pythonnative
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 54 additions & 0 deletions b/‎.github/workflows/ci.yml‎
Lines changed: 54 additions & 0 deletions
diff --git a/‎.github/workflows/e2e.yml‎
Lines changed: 20 additions & 10 deletions b/‎.github/workflows/e2e.yml‎
Lines changed: 20 additions & 10 deletions
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 18 additions & 4 deletions b/‎CONTRIBUTING.md‎
Lines changed: 18 additions & 4 deletions
diff --git a/‎README.md‎
Lines changed: 2 additions & 2 deletions b/‎README.md‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎docs/api/bridge.md‎
Lines changed: 48 additions & 0 deletions b/‎docs/api/bridge.md‎
Lines changed: 48 additions & 0 deletions
diff --git a/‎docs/api/hosts.md‎
Lines changed: 8 additions & 12 deletions b/‎docs/api/hosts.md‎
Lines changed: 8 additions & 12 deletions
diff --git a/‎docs/api/native_modules.md‎
Lines changed: 24 additions & 3 deletions b/‎docs/api/native_modules.md‎
Lines changed: 24 additions & 3 deletions
@@ -43,3 +43,57 @@ jobs:
 
       - name: Run tests
         run: uv run pytest -q
+
+  # The Swift half of the rendering core: decoders, component managers,
+  # gestures, and module promises run under XCTest on a simulator.
+  native-ios:
+    runs-on: macos-14
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Runner images ship different simulator sets, and xcodebuild
+      # silently falls back to "My Mac" (where UIKit doesn't exist) when
+      # a named destination is missing, so resolve an available iPhone
+      # simulator by UDID instead of hardcoding a model name.
+      - name: Run PythonNativeKit tests
+        working-directory: src/pythonnative/templates/ios_template/PythonNativeKit
+        run: |
+          set -o pipefail
+          UDID="$(xcrun simctl list devices available -j | python3 -c '
+          import json, sys
+          data = json.load(sys.stdin)["devices"]
+          phones = [
+              d for runtime, devices in sorted(data.items()) if "iOS" in runtime
+              for d in devices if d.get("isAvailable") and d["name"].startswith("iPhone")
+          ]
+          if not phones:
+              sys.exit("no available iPhone simulator on this runner")
+          print(phones[-1]["udid"])
+          ')"
+          echo "Using simulator $UDID"
+          xcodebuild test \
+            -scheme PythonNativeKit \
+            -destination "platform=iOS Simulator,id=$UDID" \
+            -derivedDataPath "$RUNNER_TEMP/pnkit" \
+            -quiet
+
+  # The Kotlin half has no Chaquopy dependency, so plain JUnit covers it.
+  native-android:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Java 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Run pythonnative module tests
+        working-directory: src/pythonnative/templates/android_template
+        run: ./gradlew :pythonnative:testDebugUnitTest --no-daemon
@@ -127,28 +127,36 @@ jobs:
     runs-on: macos-15
     # Budget for the worst case: ~8 min build/boot plus two full suite
     # attempts (run-e2e.sh retries the whole suite once after a driver
-    # flake) at up to ~20 min each on a slow runner. 40 was enough for
-    # a clean pass but cut the retry off mid-suite.
+    # flake). The test step gets its own, shorter timeout so a hung
+    # attempt still leaves time for the debug-output upload below;
+    # a job-level timeout kills the runner before that step can run.
     timeout-minutes: 55
     # iOS simulators are stable for the full suite (unlike the Android
     # emulator; see the e2e-android note), so this split is purely a
     # speed optimization: the iOS Maestro run is ~22 minutes and is the
-    # critical path for the whole E2E workflow. Sharding it across three
+    # critical path for the whole E2E workflow. Sharding it across
     # simulators (same balanced groups as Android) runs them in parallel
     # and roughly halves wall-clock time. macOS minutes are free on this
     # public repo, so the extra per-shard build/boot overhead is fine.
+    # Shards are sized so a single attempt is ~10-12 minutes of driving:
+    # ``components`` alone was ~21 minutes per attempt on a hosted
+    # runner, so one retry (build + two attempts) overran the job budget.
     # ``fail-fast: false`` so one shard's failure still lets the others
     # report.
     strategy:
       fail-fast: false
       matrix:
         include:
-          - name: components
-            suites: components
-          - name: hooks-nav-gestures
-            suites: hooks navigation gestures
-          - name: layout-styling-anim-misc
-            suites: layout styling animations misc
+          - name: components-a
+            suites: components-a
+          - name: components-b
+            suites: components-b
+          - name: hooks
+            suites: hooks
+          - name: nav-gestures-layout-styling
+            suites: navigation gestures layout styling
+          - name: anim-misc
+            suites: animations misc
 
     name: e2e-ios (${{ matrix.name }})
 
@@ -175,13 +183,15 @@ jobs:
           echo "$HOME/.maestro/bin" >> $GITHUB_PATH
 
       - name: Build and run E2E tests
+        timeout-minutes: 48
         run: uv run ./scripts/run-e2e.sh ios ${{ matrix.suites }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       # Maestro writes per-flow debug output (command log, view-hierarchy
       # dumps, failure screenshots) under ~/.maestro/tests. Surface it when
-      # a shard fails so CI-only failures are diagnosable without guesswork.
+      # a shard fails (or hits the step timeout above) so CI-only failures
+      # are diagnosable without guesswork.
       - name: Upload Maestro debug output
         if: failure()
         uses: actions/upload-artifact@v4
 
@@ -63,8 +63,12 @@ Unsolicited pull requests for issues that are already assigned or already have a
 
 - `src/pythonnative/`: installable library and CLI
   - `pythonnative/`: core cross‑platform UI components and utilities
+  - `bridge/`: JSON codec and per-platform transports into the native rendering core
   - `cli/`: `pn` command
+  - `project/`: config loading, template configuration, native plugin staging, and the builder behind `pn`
   - `templates/`: Android/iOS project templates (bundled with the package)
+    - `ios_template/PythonNativeKit/`: Swift package with the iOS rendering core (component managers, gestures, animations, native modules) and its XCTest target
+    - `android_template/pythonnative/`: Gradle library module with the Android rendering core and its JUnit target
 - `tests/`: unit tests for the library, plus the Maestro E2E suite
   - `e2e/`: the comprehensive E2E suite (see [E2E tests](#e2e-tests-maestro) below and `tests/e2e/AGENTS.md`)
 - `examples/`: runnable example apps
@@ -77,7 +81,8 @@ Unsolicited pull requests for issues that are already assigned or already have a
 
 - Style: Black; lint: Ruff; typing where useful. Keep APIs stable.
 - Prefer explicit, descriptive names; keep platform abstractions clean.
-- Add/extend tests under `tests/` for new behavior.
+- Python never imports platform code. Everything that touches `UIView` or `android.view.View` lives in Swift (`PythonNativeKit`) or Kotlin (the `pythonnative` Gradle module) and is reached through `pythonnative.bridge`; see `docs/concepts/bridge.md` for the protocol. Bump `PROTOCOL_VERSION` on both sides when the wire format changes.
+- Add/extend tests under `tests/` for new behavior. Native changes get XCTest / JUnit coverage next to the code they touch.
 - Don't commit generated artifacts or large binaries; templates live under `src/pythonnative/templates/`.
 - Docstrings: Google style throughout. Ruff is configured with the Google
   convention (`pydocstyle.convention = "google"`) and enforces the `D` rule
@@ -94,6 +99,10 @@ uv run pytest -q                # run tests
 uv run ruff check .             # lint
 uv run black src examples tests # format
 uv run --group docs mkdocs serve # preview the docs site locally
+
+# native rendering core (macOS with Xcode for the Swift package; JDK 17 for Gradle)
+(cd src/pythonnative/templates/ios_template/PythonNativeKit && xcodebuild test -scheme PythonNativeKit -destination 'platform=iOS Simulator,name=iPhone 15 Pro')
+(cd src/pythonnative/templates/android_template && ./gradlew :pythonnative:testDebugUnitTest)
 ```
 
 ## Conventional Commits
@@ -132,24 +141,27 @@ Recommended scopes (choose the smallest, most accurate unit; prefer module/direc
 - Module/directory scopes:
   - `alerts`: imperative Alert/Picker helpers (`alerts.py`)
   - `animated`: Animated namespace and animation primitives (`animated.py`)
+  - `bootstrap`: on-device runtime start-up called by the templates (`bootstrap.py`)
+  - `bridge`: wire codec, transports, handshake, and native-to-Python callback (`bridge/`)
   - `cli`: CLI tool and `pn` command (`src/pythonnative/cli/`)
   - `component`: the `@component` decorator, `Component`, and `memo` (`component.py`)
   - `components`: declarative element-creating functions (`components/`)
   - `element`: Element descriptor class (`element.py`)
   - `events`: tag-based event routing between native views and Python callbacks (`events.py`)
   - `gestures`: gesture descriptors and the pure-Python recognition arbiter (`gestures.py`)
   - `hooks`: hooks and contexts (`hooks.py`)
-  - `hosts`: screen hosts, native lifecycle bridge, and render scheduling (`hosts/`)
+  - `hosts`: screen hosts, lifecycle forwarding, and render scheduling (`hosts/`)
   - `hot_reload`: file watcher and module reloader (`hot_reload.py`)
   - `layout`: pure-Python flexbox engine (`layout.py`)
   - `mutations`: batched mutation ops between reconciler and native backends (`mutations.py`)
-  - `native_modules`: native API modules for device capabilities (`native_modules/`)
-  - `native_views`: platform-specific native view creation and updates (`native_views/`)
+  - `native_modules`: native module registry, Python facades, and desktop implementations (`native_modules/`)
+  - `native_views`: view registry protocol, bridge backend, and desktop handlers (`native_views/`)
   - `navigation`: navigation state, container, navigators, hooks, and linking (`navigation/`)
   - `net`: awaitable HTTP client (`net.py`)
   - `package`: `src/pythonnative/__init__.py` exports and package boundary
   - `platform`: `Platform.OS`/`Platform.select` and version detection (`platform.py`)
   - `platform_metrics`: platform-reported metrics like safe-area insets and bar heights (`platform_metrics.py`)
+  - `project`: `pythonnative.toml` config, template configurators, plugin staging, and the builder (`project/`)
   - `reconciler`: virtual view tree diffing, boundaries, and the layout pass (`reconciler/`)
   - `runtime`: framework-wide asyncio loop and thread-safe future helpers (`runtime.py`)
   - `sdk`: public extension SDK for custom native components (`sdk/`)
@@ -167,6 +179,8 @@ Recommended scopes (choose the smallest, most accurate unit; prefer module/direc
   - `repo`: repository metadata and top‑level files (`README.md`, `CONTRIBUTING.md`, `.gitignore`, licenses)
   - `scripts`: developer scripts under `scripts/` (e.g., `check.sh`)
   - `templates`: Android/iOS project templates under `src/pythonnative/templates/`
+  - `kit`: the Swift rendering core (`templates/ios_template/PythonNativeKit/`)
+  - `runtime-android`: the Kotlin rendering core (`templates/android_template/pythonnative/`)
   - `tests`: unit/integration/E2E tests under `tests/`
   - `workflows`: CI pipelines under `.github/workflows/`
 
 
@@ -26,7 +26,7 @@
 
 ## Overview
 
-PythonNative is a cross-platform toolkit for building native Android and iOS apps in Python. It provides a **declarative, React-like component model** with hooks and automatic reconciliation, powered by Chaquopy on Android and rubicon-objc on iOS. Write function components with `use_state`, `use_effect`, and friends, just like React, and let PythonNative handle creating and updating native views.
+PythonNative is a cross-platform toolkit for building native Android and iOS apps in Python. It provides a **declarative, React-like component model** with hooks and automatic reconciliation on top of a **native rendering core** written in Swift and Kotlin. Write function components with `use_state`, `use_effect`, and friends, just like React, and let PythonNative handle creating and updating native views.
 
 ## Features
 
@@ -42,7 +42,7 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Native-driven animations:** The `Animated` API (timing / spring / decay / loop / stagger, awaitable or fire-and-forget) hands animations to Core Animation and `ViewPropertyAnimator` whenever possible, so no Python code runs per frame; a pure-Python ticker covers the rest. `interpolate`, arithmetic operators on animated nodes, `Animated.event` scroll binding, and `diff_clamp` cover the scroll-driven patterns (collapsing headers, parallax) that define native feel.
 - **Native gesture system:** Attach `Tap`, `LongPress`, `Pan`, `Swipe`, `Fling`, `Pinch`, and `Rotation` recognizers to any view via the `gestures=` prop, backed by `UIGestureRecognizer` on iOS and a unit-testable pure-Python arbiter on Android and desktop. Compose them with `Race`, `Exclusive`, and `Simultaneous` for cross-gesture arbitration (single vs. double tap, drag vs. long press).
 - **Virtualized lists:** `FlatList` / `SectionList` window their rows in Python over the platform scroll view: uniform, exact, or measured variable heights, grids, headers/footers, infinite scroll, and an imperative scroll controller, identical on every platform.
-- **Direct native bindings:** Python calls platform APIs directly through Chaquopy and rubicon-objc, with no JavaScript bridge.
+- **Native rendering core:** each commit is one serialized transaction applied by Swift and Kotlin component managers, the same shape as React Native's Fabric. Device APIs are native modules registered by name (TurboModules-style), callable from thin Python facades.
 - **Custom-component SDK:** Wrap any platform widget as a first-class element with type-checked props via `pythonnative.sdk` (`Props`, `@native_component`, `element_factory`). Plugins distributed on PyPI auto-register through the `pythonnative.handlers` entry-point group.
 - **CLI scaffolding:** `pn init` creates a ready-to-run project; `pn run android` and `pn run ios` build and launch your app.
 - **Instant desktop preview:** `pn preview` renders your app in a native desktop window via Tkinter with Fast Refresh on every save: iterate on layout, state, and navigation in milliseconds without booting a simulator or device. The reconciler, hooks, layout engine, and navigation are the same code that ships to the phone.
 
@@ -0,0 +1,48 @@
+# Bridge
+
+The Python half of the [native bridge](../concepts/bridge.md): JSON
+codec, per-platform transports, protocol handshake, main-queue posting,
+and the single callback native uses to reach Python. App code never
+calls this module directly; the
+[`BridgeBackend`][pythonnative.native_views.bridge_backend.BridgeBackend],
+[`BridgeModule`][pythonnative.native_modules.registry.BridgeModule], and
+[`NativeScreenHost`][pythonnative.hosts.native.NativeScreenHost] do.
+
+::: pythonnative.bridge
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+      members_order: source
+      filters: ["!^_"]
+
+## Codec
+
+::: pythonnative.bridge.codec
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+      members_order: source
+      filters: ["!^_"]
+
+## Fake transport (tests)
+
+::: pythonnative.bridge.fake
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+      members_order: source
+      filters: ["!^_"]
+
+## Bootstrap
+
+::: pythonnative.bootstrap
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+      members_order: source
+      filters: ["!^_"]
+
+## Next steps
+
+- Wire format and native contracts: [The native bridge](../concepts/bridge.md).
+- Bundling native plugins: [Configuration](../guides/configuration.md#plugins).
@@ -7,9 +7,12 @@ pause, back press, destroy) to navigators and effects. It's also the
 [`Stack.Navigator`][pythonnative.create_stack_navigator] talks to when
 it pushes real native screens.
 
-The bundled Android (`ScreenFragment`) and iOS (`ViewController`)
-templates create a host via [`create_screen`][pythonnative.create_screen]
-and never need to be edited by app code. The desktop preview uses
+The bundled Android (`PNScreenFragment`) and iOS (`PNViewController`)
+templates create a host through the `Host` native module's `create`
+event and never need to be edited by app code; one
+[`NativeScreenHost`][pythonnative.hosts.native.NativeScreenHost] class
+serves both platforms because every platform-specific step goes over
+the [bridge](../concepts/bridge.md). The desktop preview uses
 [`DesktopScreenHost`][pythonnative.hosts.desktop.DesktopScreenHost].
 
 ::: pythonnative.hosts
@@ -30,18 +33,11 @@ and never need to be edited by app code. The desktop preview uses
 
 ## Platform hosts
 
-::: pythonnative.hosts.android
+::: pythonnative.hosts.native
     options:
       show_root_heading: false
       show_root_toc_entry: false
-      members: ["AndroidScreenHost"]
-      filters: ["!^_"]
-
-::: pythonnative.hosts.ios
-    options:
-      show_root_heading: false
-      show_root_toc_entry: false
-      members: ["IOSScreenHost"]
+      members_order: source
       filters: ["!^_"]
 
 ::: pythonnative.hosts.desktop
 
@@ -3,16 +3,36 @@
 Cross-platform wrappers around device APIs that are not part of the
 view tree: camera, GPS, file I/O, notifications, clipboard, share
 sheet, deep links, permissions, connectivity, secure storage, battery,
-haptics, and biometrics. Each module is implemented twice (once per
-platform) and dispatches at runtime based on the `IS_ANDROID` and
-`IS_IOS` flags from `pythonnative.utils`, with a safe desktop fallback.
+haptics, and biometrics. Each module is a Swift and a Kotlin class
+registered by name in the native runtime; the Python classes below are
+facades that call them through
+[`native_module`][pythonnative.native_modules.registry.native_module],
+with a Python implementation registered for the desktop and tests.
 
 Both synchronous and coroutine APIs exist (chosen to match the
 platform call). For the call-site patterns, the reactive
 `use_app_state` / `use_net_info` hooks, and the runtime coroutines are
 scheduled on, see the [Native modules guide](../guides/native-modules.md)
 and the [Async + data guide](../guides/async.md).
 
+## Registry
+
+::: pythonnative.native_modules.registry
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+      members_order: source
+      filters: ["!^_"]
+
+## Desktop implementations
+
+::: pythonnative.native_modules.desktop
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+      members_order: source
+      filters: ["!^_"]
+
 ## Camera
 
 ::: pythonnative.native_modules.camera
@@ -142,3 +162,4 @@ and the [Async + data guide](../guides/async.md).
 ## Next steps
 
 - See guidance and permission setup in [Native modules guide](../guides/native-modules.md).
+- Write your own: [Native modules guide](../guides/native-modules.md#writing-your-own-native-module).