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

pythonnative/navigation.py

@@ -25,7 +25,7 @@ Stack navigators rendered as the root of an app host (i.e. the parent
 own handle) talk to the platform via that host's ``_push`` / ``_pop``
 methods, so the back stack matches what UIKit / AndroidX maintain.
 Nested stacks (e.g. a stack inside a tab) fall back to in-Python
-state — there is no second native navigation controller to push
+state; there's no second native navigation controller to push
 onto in that case.
 
 Example:
@@ -66,7 +66,7 @@ from .hooks import (
 
 # Defaults to True: components rendered outside any declarative
 # navigator (e.g. the root component of a screen pushed via the host's
-# native nav stack) are by definition focused — the host's own
+# native nav stack) are by definition focused; the host's own
 # ``on_resume`` / ``on_pause`` lifecycle drives the focus state for
 # those. Declarative navigators override this provider on the active
 # subtree (always True today; reserved for future inactive-screen
@@ -152,7 +152,7 @@ class _DeclarativeNavHandle:
 
     When ``parent`` is the host's own ``NavigationHandle`` (root
     Stack), ``navigate`` / ``go_back`` / ``reset`` drive the native
-    navigation controller and the in-Python stack is bypassed — the
+    navigation controller and the in-Python stack is bypassed; the
     OS owns the back-stack source of truth.
 
     When ``parent`` is another declarative handle (nested navigator),
@@ -212,7 +212,7 @@ class _DeclarativeNavHandle:
           untouched because the native controller is the source of
           truth.
         - **Nested stack / tab / drawer**: ``set_stack`` is called with
-          the new route — the parent reconciler re-renders the active
+          the new route; the parent reconciler re-renders the active
           screen subtree in place.
         - **Unknown route**: forwarded to ``parent`` if one exists,
           otherwise raises ``ValueError``.

pythonnative/net.py

@@ -4,7 +4,7 @@ A small, dependency-free coroutine wrapper around
 :mod:`urllib.request`. Operates on bytes internally and exposes a
 :class:`Response` with `text()`, `json()`, and `bytes` accessors.
 
-The implementation is deliberately minimal — it covers the
+The implementation is deliberately minimal; it covers the
 "call a JSON API" path that's overwhelmingly the use case for mobile
 apps. For streaming, multipart uploads, or HTTP/2, integrate
 ``httpx`` / ``aiohttp`` directly; this module won't try to compete.
@@ -161,7 +161,7 @@ async def fetch(
         TimeoutError: If the request doesn't complete within
             ``timeout`` seconds.
         OSError: For network errors (DNS failure, connection refused,
-            etc.) — re-raised from ``urllib``.
+            etc.), re-raised from ``urllib``.
 
     Example:
         ```python
@@ -223,7 +223,7 @@ def _dispatch_request(request: urllib.request.Request, timeout: float) -> Respon
                 content=content,
             )
     except urllib.error.HTTPError as exc:
-        # HTTPError is itself a response object — propagate the body
+        # HTTPError is itself a response object; propagate the body
         # so callers can inspect it before deciding to raise.
         body = exc.read() if hasattr(exc, "read") else b""
         return Response(

pythonnative/platform.py

@@ -102,7 +102,7 @@ class Platform:
         """Pick the value matching the current platform.
 
         Looks up ``spec[Platform.OS]``, then falls back to
-        ``spec["native"]`` (matches iOS and Android — *not* desktop,
+        ``spec["native"]`` (matches iOS and Android, *not* desktop,
         which is a development surface), then to ``spec["default"]``,
         then to the explicit ``default`` argument.
 

pythonnative/platform_metrics.py

@@ -16,7 +16,7 @@ that state to size themselves correctly:
 Rather than threading those values through every
 [`measure_intrinsic`][pythonnative.native_views.base.ViewHandler.measure_intrinsic]
 call signature, the screen host writes them here and handlers read
-them on demand. Values are in **dp on Android** and **pt on iOS** —
+them on demand. Values are in **dp on Android** and **pt on iOS**,
 i.e., the same "layout units" the layout engine uses on each
 platform, so handlers can add them to other layout-unit values
 without further conversion. On iOS the screen host consumes the top
@@ -88,7 +88,7 @@ def subscribe(callback: Callable[[], None]) -> Callable[[], None]:
 
     Returns an unsubscribe function. Hooks pass a state setter so a
     component re-renders whenever the platform reports a new value.
-    Threadsafe — multiple subscribers may register/unregister
+    Threadsafe: multiple subscribers may register/unregister
     concurrently.
     """
     with _subscribers_lock:
@@ -138,7 +138,7 @@ def set_safe_area_insets(top: float, left: float, bottom: float, right: float) -
 def get_safe_area_insets() -> SafeAreaInsets:
     """Return the current safe-area insets.
 
-    The default value is ``(0, 0, 0, 0)`` — handlers should still
+    The default value is ``(0, 0, 0, 0)``; handlers should still
     function correctly on a desktop / unit-test environment where no
     screen host has published insets.
     """
@@ -217,7 +217,7 @@ def reset_keyboard_height() -> None:
 # trust ``UITabBar.sizeThatFits_`` (it has historically returned 0 in
 # some configurations) and the screen host deliberately extends the
 # root view past the bottom safe area so the bar reaches the home
-# indicator — both pieces conspire to require a single source of
+# indicator; both pieces conspire to require a single source of
 # truth for the height formula.
 #
 # Android intentionally has no equivalent: ``BottomNavigationView``
@@ -240,7 +240,7 @@ def ios_tab_bar_height() -> float:
     Equal to ``IOS_TAB_BAR_BASE_HEIGHT_PT + safe_area_insets.bottom``
     so the bar reaches the home indicator. The iOS screen host
     deliberately extends the root view past the bottom safe area for
-    this very reason — the tab bar absorbs the inset and UIKit
+    this very reason; the tab bar absorbs the inset and UIKit
     renders the pill with internal padding for the home indicator.
     Used by ``pythonnative.native_views.ios.TabBarHandler``; exposed
     here so the formula is testable without importing the iOS

pythonnative/preview.py

@@ -1,4 +1,4 @@
-"""Desktop preview runtime — the engine behind ``pn preview``.
+"""Desktop preview runtime, the engine behind ``pn preview``.
 
 ``pn preview`` renders a PythonNative app in a real OS window using the
 Tkinter backend ([`pythonnative.native_views.desktop`][pythonnative.native_views.desktop]),
@@ -43,6 +43,36 @@ _POLL_INTERVAL_MS = 16
 _WATCH_INTERVAL_S = 0.4
 
 
+def _publish_desktop_color_scheme() -> None:
+    """Publish the host OS appearance so `use_color_scheme` works in preview.
+
+    ``PN_COLOR_SCHEME=light|dark`` forces a value (handy for testing
+    both appearances); otherwise macOS is asked via ``defaults read``
+    (the key only exists when dark mode is on). Other platforms default
+    to light.
+    """
+    from . import appearance
+
+    forced = os.environ.get("PN_COLOR_SCHEME")
+    if forced in ("light", "dark"):
+        appearance.set_system_color_scheme(forced)
+        return
+    if sys.platform == "darwin":
+        import subprocess
+
+        try:
+            result = subprocess.run(
+                ["defaults", "read", "-g", "AppleInterfaceStyle"],
+                capture_output=True,
+                text=True,
+                timeout=2,
+            )
+            is_dark = result.returncode == 0 and result.stdout.strip() == "Dark"
+            appearance.set_system_color_scheme("dark" if is_dark else "light")
+        except Exception:
+            pass
+
+
 class DesktopApp:
     """Navigation-stack controller for the desktop preview window.
 
@@ -50,7 +80,7 @@ class DesktopApp:
     [`screen`][pythonnative.screen] host as the ``native_instance`` so
     hosts can drive navigation (``push_screen`` / ``pop_screen`` /
     ``reset_to_root``), report the viewport size, and set the window
-    title — mirroring the role a ``UIViewController`` / ``Activity``
+    title, mirroring the role a ``UIViewController`` / ``Activity``
     plays on device.
     """
 
@@ -359,6 +389,7 @@ def run_preview(
         )
 
     root_dir, watched = _resolve_paths(component_path, project_root, watch_dir)
+    _publish_desktop_color_scheme()
 
     root = tk.Tk()
     root.title(title)
@@ -424,7 +455,7 @@ def run_preview(
 
     root.protocol("WM_DELETE_WINDOW", _on_close)
     root.after(_POLL_INTERVAL_MS, _poll)
-    print(f"[pn preview] {component_path} — {int(width)}x{int(height)}", file=sys.stderr)
+    print(f"[pn preview] {component_path} ({int(width)}x{int(height)})", file=sys.stderr)
     try:
         root.mainloop()
     except KeyboardInterrupt:

pythonnative/project/builder.py

@@ -3,7 +3,7 @@
 The [`Builder`][pythonnative.project.builder.Builder] ties the pieces
 together: it stages the bundled native template, runs the platform
 [`configurators`][pythonnative.project.android], invokes the native
-toolchains (Gradle / Xcode), and—on iOS—embeds the CPython runtime into
+toolchains (Gradle / Xcode), and, on iOS, embeds the CPython runtime into
 the built app.
 
 All shell-outs go through a small

pythonnative/project/config.py

@@ -113,7 +113,7 @@ class IOSSigning:
     """iOS code-signing / export configuration (``[ios.signing]``).
 
     Attributes:
-        export_method: How the archive is exported — one of
+        export_method: How the archive is exported, one of
             ``development``, ``ad-hoc``, ``app-store``, ``enterprise``.
         provisioning_profile: Optional provisioning profile name or UUID
             for manual signing.
@@ -321,15 +321,7 @@ class AppConfig:
         root = Path(project_root) if project_root is not None else Path.cwd()
         config_path = root / CONFIG_FILENAME
         if not config_path.is_file():
-            legacy = root / "pythonnative.json"
-            hint = ""
-            if legacy.is_file():
-                hint = (
-                    "\nFound a legacy 'pythonnative.json'. PythonNative now uses "
-                    "'pythonnative.toml'.\nRun 'pn init --force' to scaffold one, then "
-                    "port your settings over."
-                )
-            raise ConfigError(f"No {CONFIG_FILENAME} found in {root}.{hint}")
+            raise ConfigError(f"No {CONFIG_FILENAME} found in {root}.")
         try:
             with open(config_path, "rb") as handle:
                 data = _toml.load(handle)
@@ -590,7 +582,7 @@ def render_default_toml(*, name: str, app_id: str, python_version: str = "3.11")
     """
     display = name.replace("_", " ").replace("-", " ").strip().title() or name
     return f"""# PythonNative project configuration.
-# Docs: https://docs.pythonnative.com/guide/configuration/
+# Docs: https://pythonnative.com/guides/configuration/
 
 [app]
 id = "{app_id}"
@@ -604,7 +596,7 @@ entry_point = "app/main.py"
 
 # Declare the device capabilities your app needs. A string becomes the
 # iOS permission prompt text; `true` uses a sensible default.
-# See: https://docs.pythonnative.com/guide/permissions/
+# See: https://pythonnative.com/guides/permissions/
 [permissions]
 # camera = "Scan receipts with your camera."
 # location_when_in_use = "Show nearby stores."

pythonnative/project/doctor.py

@@ -1,7 +1,7 @@
 """Environment diagnostics for ``pn doctor``.
 
 Inspects the local toolchain and the project's ``pythonnative.toml`` and
-reports what's ready and what's missing for building on each platform —
+reports what's ready and what's missing for building on each platform,
 analogous to ``flutter doctor`` / ``npx react-native doctor``. The checks
 are deliberately read-only and fast; they shell out only to ask tools for
 their versions.
@@ -44,7 +44,7 @@ class CheckResult:
     def format(self) -> str:
         """Return a single aligned line for terminal output."""
         symbol = _SYMBOLS.get(self.level, "[?]")
-        suffix = f" — {self.detail}" if self.detail else ""
+        suffix = f": {self.detail}" if self.detail else ""
         return f"  {symbol} {self.name}{suffix}"
 
 

pythonnative/project/icons.py

@@ -77,7 +77,7 @@ def _circular(img: "object") -> "object":
 def generate_ios_icons(source: Path, appiconset_dir: Path) -> bool:
     """Generate a single-size iOS ``AppIcon.appiconset``.
 
-    Writes ``icon-1024.png`` (a flattened, opaque 1024x1024 image — the
+    Writes ``icon-1024.png`` (a flattened, opaque 1024x1024 image; the
     App Store rejects icons with alpha) and a ``Contents.json`` that
     declares it as the universal iOS app icon. Xcode derives every other
     size at build time.

pythonnative/project/ios.py

@@ -3,7 +3,7 @@
 Adapts the bundled ``ios_template`` Xcode project to a specific
 [`AppConfig`][pythonnative.project.config.AppConfig]. Unlike Android, the
 iOS bundle identifier, version, team, and deployment target are *not*
-baked into files — they're passed to ``xcodebuild`` as build-setting
+baked into files; they're passed to ``xcodebuild`` as build-setting
 overrides (see [`build_settings`][pythonnative.project.ios.build_settings]),
 which avoids fragile ``project.pbxproj`` edits. This module owns the
 parts that must live on disk:

pythonnative/project/permissions.py

@@ -23,7 +23,7 @@ artifacts it requires:
 A capability's value may be either a string (used verbatim as the iOS
 usage description) or ``true`` (use the capability's
 [`default_reason`][pythonnative.project.permissions.Capability]). A value
-of ``false`` disables the capability — useful for switching one off
+of ``false`` disables the capability, useful for switching one off
 without deleting the line.
 
 The catalog is the single source of truth shared by the iOS and Android
@@ -284,7 +284,7 @@ def resolve_permissions(
     """Resolve a declared capability map into native permission artifacts.
 
     Args:
-        permissions: The ``[permissions]`` table — capability key to a
+        permissions: The ``[permissions]`` table, capability key to a
             reason string or boolean. ``false``/``None`` values are
             skipped (capability disabled).
         extra_android_permissions: Additional raw Android permission

pythonnative/project/runtime_assets.py

@@ -9,8 +9,8 @@ paths the [`ios`][pythonnative.project.ios] configurator needs:
 ``Python.xcframework``, the simulator ``Python.framework``, the standard
 library, and the simulator headers/static lib.
 
-Android doesn't need any of this — Chaquopy ships its own CPython via
-Gradle — so there's no Android equivalent here.
+Android doesn't need any of this: Chaquopy ships its own CPython via
+Gradle, so there's no Android equivalent here.
 """
 
 from __future__ import annotations
@@ -238,7 +238,7 @@ def prepare_ios_runtime(
         try:
             return _locate_runtime(extract_root, python_version)
         except RuntimeError:
-            # Stale/partial extraction — re-extract below.
+            # Stale/partial extraction: re-extract below.
             pass
 
     url = resolve_asset_url(python_version, preferred_name=preferred_name)

pythonnative/reconciler.py

@@ -9,7 +9,7 @@ The diff phase is *pure*: it never touches the native layer. Each pass
 appends ops (`pythonnative.mutations`) to a transaction list, and the
 commit applies them through a single
 ``backend.apply_mutations(ops)`` call. Event callbacks never cross into
-the native layer at all — they live in the Python-side
+the native layer at all; they live in the Python-side
 [`EventRegistry`][pythonnative.events.EventRegistry], keyed by tag, so
 re-renders that only produce fresh closures cost nothing natively.
 
@@ -66,7 +66,7 @@ def _shallow_equal_props(old: dict, new: dict) -> bool:
 
     Used by [`memo`][pythonnative.memo] to skip re-rendering when none
     of a component's props changed identity. Callables only count as
-    equal if they're the *same object* — fresh closures always invalidate
+    equal if they're the *same object*; fresh closures always invalidate
     the memo (matching React's behavior; pair with
     [`use_callback`][pythonnative.use_callback] when stability matters).
     """
@@ -173,7 +173,7 @@ class VNode:
         # node's props change, so unchanged leaves skip native
         # ``measure_intrinsic`` calls entirely.
         self._measure_cache: Optional[Tuple[float, float, float, float]] = None
-        # Last frame sent to the native side — frames that don't change
+        # Last frame sent to the native side; frames that don't change
         # are skipped (frame diffing).
         self._last_frame: Optional[Tuple[float, float, float, float]] = None
         # Cached LayoutNode reused across passes while the subtree is
@@ -444,8 +444,8 @@ class Reconciler:
         Unlike a full reconcile from the root, a local update starts in
         the *middle* of the tree, so the context stack of every
         ``__Provider__`` ancestor must be re-established before the body
-        runs (otherwise [`use_context`][pythonnative.use_context] — and
-        therefore [`use_navigation`][pythonnative.use_navigation] — would
+        runs (otherwise [`use_context`][pythonnative.use_context], and
+        therefore [`use_navigation`][pythonnative.use_navigation], would
         read the context default instead of the provided value). Nested
         providers *inside* this subtree are pushed/popped normally by the
         recursive reconcile beneath us.
@@ -939,7 +939,7 @@ class Reconciler:
             node.hook_state.cleanup_all_effects()
             # Break the back-references so the unmounted component's hook
             # state (and the closures it captured) can be freed by plain
-            # refcounting — important on iOS, where the cyclic GC is
+            # refcounting, important on iOS, where the cyclic GC is
             # disabled.
             node.hook_state._vnode = None
             node.hook_state._reconciler = None
@@ -983,7 +983,7 @@ class Reconciler:
 
         Event callables never appear here (they live in the event
         registry), so listener identity churn produces no native
-        traffic — only the ``_pn_events`` name set is compared.
+        traffic; only the ``_pn_events`` name set is compared.
         """
         changed = {}
         for key, new_val in new.items():
@@ -1056,7 +1056,7 @@ class Reconciler:
         """Whether ``changed`` props can alter the node's layout.
 
         Content-sized leaves re-measure on *any* prop change (text,
-        font, image source — almost everything affects their intrinsic
+        font, image source: almost everything affects their intrinsic
         size). Containers only care about the layout style keys.
         """
         if type_name in cls._INTRINSIC_TYPES:
@@ -1110,7 +1110,7 @@ class Reconciler:
         )
         viewport.dirty = True
         calculate_layout(viewport, viewport_w, viewport_h)
-        # Skip set_frame for the root itself — descendants are
+        # Skip set_frame for the root itself; descendants are
         # positioned relative to the root's local origin, which is
         # what they want regardless of where the host placed the
         # root in the screen.

pythonnative/runtime.py

@@ -2,7 +2,8 @@
 
 PythonNative runs a single, framework-wide ``asyncio`` event loop on
 a dedicated daemon thread. Every awaitable surface in the framework
-— the async hooks
+schedules its work on this loop via
+[`run_async`][pythonnative.runtime.run_async]: the async hooks
 ([`use_async_effect`][pythonnative.hooks.use_async_effect],
 [`use_query`][pythonnative.hooks.use_query],
 [`use_mutation`][pythonnative.hooks.use_mutation]), the
@@ -12,8 +13,7 @@ native modules
 ([`Camera`][pythonnative.native_modules.camera.Camera] /
 [`Location`][pythonnative.native_modules.location.Location] /
 [`Notifications`][pythonnative.native_modules.notifications.Notifications]),
-and awaited animations — schedules its work on this loop via
-[`run_async`][pythonnative.runtime.run_async].
+and awaited animations.
 
 The reconciler is **not** asyncio-aware; it still runs synchronously on
 the platform main thread. Coroutines that want to mutate component
@@ -66,7 +66,7 @@ _lock = threading.Lock()
 # ======================================================================
 #
 # By default ``threading.Thread`` lands at a low QoS class on Apple
-# platforms, which iOS subjects to wake-up coalescing — the asyncio
+# platforms, which iOS subjects to wake-up coalescing; the asyncio
 # loop only gets ~2 timeslices per second (~500ms granularity). Bumping
 # the thread to ``QOS_CLASS_USER_INTERACTIVE`` is *necessary* for it to
 # be treated as foreground work, but on the simulator it's not
@@ -85,7 +85,7 @@ def _apply_apple_thread_qos() -> None:
     No-op on other platforms or if the symbol can't be loaded. Must be
     called from inside the target thread (the underlying syscall is
     ``pthread_set_qos_class_self_np``). Empirically ``USER_INTERACTIVE``
-    is required on iOS — anything lower triggers wake-up coalescing on
+    is required on iOS; anything lower triggers wake-up coalescing on
     the background asyncio thread, which adds ~500ms latency to every
     cross-thread dispatch.
     """
@@ -151,7 +151,7 @@ def _shutdown_for_tests() -> None:
     Cancels every pending task, stops the loop, joins the thread, and
     clears the module-level state so the next call to
     [`get_loop`][pythonnative.runtime.get_loop] starts a fresh loop.
-    Production code should not call this — the loop is a daemon and
+    Production code should not call this; the loop is a daemon and
     will be torn down with the process.
     """
     global _loop, _thread
@@ -316,7 +316,7 @@ def call_on_main_thread(fn: Callable[[], None]) -> None:
 
     - **iOS**: dispatches ``fn`` onto the main dispatch queue via
       ``libdispatch.dispatch_async_f`` (called through
-      :class:`ctypes.PyDLL` to keep the GIL held — see the
+      :class:`ctypes.PyDLL` to keep the GIL held; see the
       ``_ios_call_on_main`` comment block for why this matters).
     - **Android**: posts a ``Runnable`` to
       ``Handler(Looper.getMainLooper())``.
@@ -469,7 +469,7 @@ def _ios_call_on_main(fn: Callable[[], None]) -> None:
         _main_next_id += 1
         key = _main_next_id
         _main_pending[key] = fn
-    # dispatch_async_f(queue, context, work) — non-blocking; just
+    # dispatch_async_f(queue, context, work): non-blocking; just
     # enqueues the work onto the main queue and returns.
     assert _dispatch_async_f_c is not None
     _dispatch_async_f_c(_dispatch_main_q_ptr, key, _main_trampoline_c)

pythonnative/screen.py

@@ -186,7 +186,7 @@ def _init_host_common(host: Any, component_path: str, component_func: Any) -> No
     host._hot_reload_manifest_path = None
     host._hot_reload_last_version = None
     host._layout_listener = None  # retained on Android to prevent GC
-    # Focus state — drives ``use_focus_effect``. Starts focused because
+    # Focus state: drives ``use_focus_effect``. Starts focused because
     # a host is only created when the screen is being presented; the
     # platform lifecycle hooks (``on_resume`` / ``on_pause``) flip this
     # when the user navigates to / from another screen.
@@ -276,14 +276,14 @@ def _on_create(host: Any) -> None:
     # Android the FragmentManager destroys and recreates a screen's
     # view every time the user pops back to it, and the platform
     # template calls ``screen.on_create()`` again from
-    # ``onViewCreated`` — but the Python screen object (and therefore
+    # ``onViewCreated``, but the Python screen object (and therefore
     # the reconciler, hook state, focus subscribers, etc.) persists
     # across that. Re-running the full mount path here would reset
     # use_state, clobber use_focus_effect subscriptions, and break
     # navigation handles held by existing components, which is why
     # the focus counter never advanced past ``1`` before this guard.
     # If we're already mounted, just re-attach the existing root view
-    # to the (newly created) native container — ``on_resume`` will
+    # to the (newly created) native container; ``on_resume`` will
     # fire the focus subscribers separately.
     if host._reconciler is not None and host._root_native_view is not None:
         host._attach_root(host._root_native_view)
@@ -678,6 +678,65 @@ if IS_ANDROID:
                 bottom_px / density,
                 right_px / density,
             )
+            # IME (soft keyboard) insets: API 30+ exposes them through
+            # the typed getInsets API. The keyboard overlaps the system
+            # navigation bar, so the visible keyboard height is the IME
+            # inset minus the permanent bottom bar inset. Older API
+            # levels don't report IME insets here; those devices rely
+            # on ``adjustResize`` shrinking the window (the viewport
+            # push handles the layout) and the height stays 0.
+            try:
+                ime = insets_obj.getInsets(Type.ime())
+                ime_px = max(0, int(ime.bottom) - bottom_px)
+                platform_metrics.set_keyboard_height(ime_px / density)
+            except Exception:
+                pass
+        except Exception:
+            pass
+
+    def _android_publish_color_scheme(activity: Any) -> None:
+        """Read the system night mode from the activity and publish it.
+
+        Android delivers appearance changes as a configuration change,
+        which recreates the activity by default, so publishing on
+        ``on_create`` / ``on_resume`` covers both the initial value and
+        subsequent flips.
+        """
+        try:
+            from . import appearance
+
+            Configuration = jclass("android.content.res.Configuration")
+            ui_mode = int(activity.getResources().getConfiguration().uiMode)
+            night = ui_mode & int(Configuration.UI_MODE_NIGHT_MASK)
+            is_dark = night == int(Configuration.UI_MODE_NIGHT_YES)
+            appearance.set_system_color_scheme("dark" if is_dark else "light")
+        except Exception:
+            pass
+
+    def _android_register_insets_listener(host: Any, view: Any) -> None:
+        """Re-publish insets whenever the window's insets change.
+
+        The ``OnLayoutChangeListener`` in ``_android_register_layout_listener``
+        only fires when the container is re-measured, which covers
+        ``adjustResize`` keyboards but not inset-only changes (e.g. an
+        edge-to-edge window where the IME floats over the content).
+        ``setOnApplyWindowInsetsListener`` fires on every insets pass,
+        so keyboard show/hide reaches ``platform_metrics`` immediately.
+        """
+        try:
+            View = jclass("android.view.View")
+
+            class _PNInsetsListener(dynamic_proxy(View.OnApplyWindowInsetsListener)):  # type: ignore[misc]
+                def onApplyWindowInsets(self, v: Any, insets: Any) -> Any:
+                    try:
+                        _android_publish_window_insets(v)
+                    except Exception:
+                        pass
+                    return insets
+
+            listener = _PNInsetsListener()
+            view.setOnApplyWindowInsetsListener(listener)
+            host._insets_listener = listener  # retain to prevent GC
         except Exception:
             pass
 
@@ -728,7 +787,7 @@ if IS_ANDROID:
             # Publish insets first so the very first layout pass sees
             # them. Otherwise handlers reading insets at first paint
             # would get ``(0, 0, 0, 0)`` and re-measure once the
-            # ``OnLayoutChangeListener`` fires moments later — a
+            # ``OnLayoutChangeListener`` fires moments later, a
             # measurable flicker (~50–200 ms on a stock Pixel
             # emulator).
             _android_publish_window_insets(view)
@@ -761,12 +820,14 @@ if IS_ANDROID:
             _init_host_common(self, component_path, component_func)
 
         def on_create(self) -> None:
+            _android_publish_color_scheme(self.native_instance)
             _on_create(self)
 
         def on_start(self) -> None:
             pass
 
         def on_resume(self) -> None:
+            _android_publish_color_scheme(self.native_instance)
             _set_host_focused(self, True)
 
         def on_layout(self) -> None:
@@ -873,6 +934,7 @@ if IS_ANDROID:
 
             if container is not None:
                 _android_register_layout_listener(self, container)
+                _android_register_insets_listener(self, container)
                 _android_push_initial_viewport(self, container)
 
         def _detach_root(self, native_view: Any) -> None:
@@ -1089,7 +1151,7 @@ else:
         the concrete type varies between releases:
 
         - On rubicon-objc 0.5.x ``ptr`` is ``bytes`` (the raw 8-byte,
-          little-endian address) — ``int(ptr)`` raises ``ValueError``
+          little-endian address); ``int(ptr)`` raises ``ValueError``
           because Python tries to parse the bytes as a decimal string.
         - Older releases return a ``c_void_p`` for which ``int(ptr)``
           works.
@@ -1128,6 +1190,24 @@ else:
         except Exception:
             pass
 
+    def _ios_publish_color_scheme() -> None:
+        """Read the current UIKit interface style and publish it.
+
+        ``UITraitCollection.currentTraitCollection`` reflects the
+        active appearance; ``userInterfaceStyle`` is 1 for light and
+        2 for dark (0 = unspecified, treated as light). Called from
+        the lifecycle callbacks that fire on appearance flips
+        (``viewDidLayoutSubviews`` / ``viewDidAppear``).
+        """
+        try:
+            from . import appearance
+
+            UITraitCollection = ObjCClass("UITraitCollection")
+            style_value = int(UITraitCollection.currentTraitCollection.userInterfaceStyle)
+            appearance.set_system_color_scheme("dark" if style_value == 2 else "light")
+        except Exception:
+            pass
+
     def _ios_register_screen(vc_instance: Any, host_obj: Any) -> None:
         ptr = _objc_addr(vc_instance)
         if ptr is None:
@@ -1273,6 +1353,7 @@ else:
                     _ios_register_screen(self.native_instance, self)
 
             def on_create(self) -> None:
+                _ios_publish_color_scheme()
                 _on_create(self)
 
             def on_start(self) -> None:
@@ -1483,6 +1564,9 @@ else:
                 # insets are now valid (initial layout, rotation,
                 # multitasking, …). Re-sync the root frame and push the
                 # viewport so the layout engine matches the visible area.
+                # Appearance flips also trigger a layout pass, so the
+                # color scheme is re-published here too.
+                _ios_publish_color_scheme()
                 if self._root_native_view is None:
                     _log_pn("on_layout: no root_native_view yet, skipping")
                     return
@@ -1494,6 +1578,7 @@ else:
                 # ``viewDidAppear`` always follows ``viewDidLayoutSubviews``,
                 # but trigger one extra sync here for safety in case a
                 # template overrides the layout call without forwarding.
+                _ios_publish_color_scheme()
                 _set_host_focused(self, True)
                 if self._root_native_view is None:
                     _log_pn("on_resume: no root_native_view yet, skipping")

pythonnative/sdk/_components.py

@@ -361,7 +361,7 @@ def element_factory(name: str) -> Callable[..., Element]:
       arguments matching the registered props dataclass.
 
     If no ``props`` dataclass was registered for ``name``, kwargs flow
-    through unmodified — useful when iterating before locking down a
+    through unmodified, useful when iterating before locking down a
     prop schema.
 
     Args: