tempestroid 0.1.0__tar.gz

tempestroid-0.1.0/.gitignore

@@ -0,0 +1,73 @@
+# ─── Python ───────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+*.whl
+.installed.cfg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.cache/
+
+# ─── Editors / OS ─────────────────────────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*~
+.DS_Store
+Thumbs.db
+
+# ─── Environment / secrets ─────────────────────────────────────────────────
+.env
+.env.*
+!.env.example
+
+# ─── Trilho B: toolchain (regenerable build outputs of B0/B1) ───────────────
+# Built CPython, native wheels, staged site-packages and cloned sources.
+# Reproduce with toolchain/00_fetch_cpython.sh, 01_build_wheels.sh, 02_stage_deps.sh.
+toolchain/dist/
+toolchain/.src/
+toolchain/wheelhouse/
+
+# ─── Trilho B: android-host (Gradle / NDK build artifacts) ──────────────────
+android-host/build/
+android-host/app/build/
+android-host/app/.cxx/
+android-host/.gradle/
+android-host/.kotlin/
+android-host/local.properties
+android-host/captures/
+*.apk
+*.aab
+*.ap_
+*.dex
+
+# Keep the Gradle wrapper jar tracked (do not ignore it):
+!android-host/gradle/wrapper/gradle-wrapper.jar
+
+# MkDocs build output
+site/
+
+# `tempest build` embeds the user app here as a generated asset (phase C).
+android-host/app/src/main/assets/tempest_app.py

tempestroid-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to **tempestroid** are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-31
+
+First public release. The framework (Trilho A) is complete and the Android
+runtime (Trilho B, phases B0–B6) is validated on a real arm64 device.
+
+### Added
+
+- **Typed declarative UI core.** A frozen-Pydantic `Style` model (`Color`,
+  `Edge`, `Border`, `Transition`, and the style enums) and a widget IR
+  (`Widget`, `Text`, `Button`, `Column`, `Row`, `Container`, plus value-bearing
+  inputs and utility widgets).
+- **Renderer-agnostic reconciler** — `build → diff → patch` (`Insert` / `Remove`
+  / `Update` / `Reorder` / `Replace`).
+- **Qt desktop simulator** (`run_qt`, optional `qt` extra) with a `Style → Qt`
+  translator and an asyncio×Qt event loop via `qasync`.
+- **Async-first state runtime** (`App`) with coalesced rebuilds and **stateful
+  hot reload** (`App.swap_view`).
+- **`tempest` CLI** — `dev` (simulator + hot reload/restart cockpit), `serve`
+  (LAN code-push to a device), `spec` (typed contract as JSON), `new` (scaffold
+  a project), `build` (bundle an app into an APK), `run` (build + install +
+  logcat).
+- **Android runtime (Trilho B).** Official CPython 3.14 (PEP 738) embedded via a
+  hand-rolled JNI bridge in a Kotlin/Gradle host; native wheels (`pydantic-core`)
+  via cibuildwheel; a Jetpack Compose renderer; a LAN dev server with QR pairing;
+  and native capabilities (notifications).
+- **Conformance suite** pinning the Qt and Compose `Style` translators with
+  golden snapshots (phase D).
+
+[Unreleased]: https://github.com/mauriciobenjamin700/tempestroid/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/mauriciobenjamin700/tempestroid/releases/tag/v0.1.0

tempestroid-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mauricio Benjamin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tempestroid-0.1.0/PKG-INFO

@@ -0,0 +1,368 @@
+Metadata-Version: 2.4
+Name: tempestroid
+Version: 0.1.0
+Summary: Framework for building native Android apps in typed Python — declarative typed UI tree, Qt simulator + Compose device renderers.
+Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempestroid
+Project-URL: Documentation, https://mauriciobenjamin700.github.io/tempestroid/
+Project-URL: Repository, https://github.com/mauriciobenjamin700/tempestroid
+Project-URL: Changelog, https://github.com/mauriciobenjamin700/tempestroid/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/mauriciobenjamin700/tempestroid/issues
+Author: Mauricio Benjamin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: android,compose,cross-platform,declarative,framework,mobile,pydantic,qt,ui
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Android
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.7
+Provides-Extra: qt
+Requires-Dist: pyside6>=6.7; extra == 'qt'
+Requires-Dist: qasync>=0.27; extra == 'qt'
+Description-Content-Type: text/markdown
+
+# tempestroid
+
+> 📖 **Documentação / Docs:** site MkDocs bilíngue em [`docs/`](docs/index.md)
+> com seletor **PT-BR / EN-US** no header — rode `uv run mkdocs serve` e abra
+> <http://127.0.0.1:8000> (PT) ou <http://127.0.0.1:8000/en/> (EN). Guia do
+> usuário, arquitetura e referência da API.
+
+Build **native Android apps** in **typed Python**.
+
+You write one declarative, fully typed widget tree (a Pydantic IR). A
+**renderer-agnostic reconciler** diffs it into patches. Two leaf renderers apply
+those patches: **Qt** for the desktop simulator, **Jetpack Compose** for the
+device. The runtime is **async-first**, with an Expo-style dev loop: hot reload
+in the Qt simulator and LAN code-push to a device over QR — both shipping today.
+
+> This is a **framework, not a web service** — no FastAPI, SQLAlchemy, Redis, or
+> HTTP layering. See [`docs/plan.md`](docs/plan.md) for the full design and the
+> phase roadmap.
+
+---
+
+## Why
+
+- **Typed end to end.** Style model, widget primitives, events, and the
+  Python↔Kotlin boundary contract are all Pydantic v2 / fully typed. `pyright`
+  runs in strict mode.
+- **One tree, two targets.** The reconciler is pure data-in → patches-out. All
+  platform divergence is confined to the two `Style` translators (Qt today,
+  Compose next).
+- **Async-first.** Event handlers and lifecycle hooks may be sync or `async`;
+  Python runs on a background asyncio loop, never the UI thread.
+- **Fast inner loop.** `tempest dev` watches your file and hot-restarts the Qt
+  simulator on save — no device or emulator needed for UI work.
+
+---
+
+## How it works
+
+```text
+   view(app) ──build──▶  Node tree (IR)
+                              │
+                            diff           pure, renderer-agnostic
+                              ▼
+                          [ Patch ]        Insert / Remove / Update / Reorder / Replace
+                         ╱          ╲
+                  Qt renderer    Compose renderer
+                  (simulator)      (device, B4)
+```
+
+1. `view(app) -> Widget` builds a declarative widget tree from current state.
+2. `build` lowers it to a `Node` IR; `diff` compares old vs. new and emits a
+   minimal `Patch` list.
+3. A renderer applies patches to live widgets. State changes coalesce into one
+   rebuild per tick.
+
+---
+
+## Install
+
+```bash
+uv sync        # core + dev tooling + the Qt simulator
+```
+
+End users embedding the framework who want the simulator:
+`pip install tempestroid[qt]`. The framework **core** needs only `pydantic` —
+Qt is an optional extra.
+
+---
+
+## Quick start
+
+```python
+from dataclasses import dataclass
+
+from tempestroid import App, Button, Column, Style, Text, Widget
+from tempestroid.renderers.qt import run_qt
+
+
+@dataclass
+class CounterState:
+    value: int = 0
+
+
+def make_state() -> CounterState:
+    return CounterState()
+
+
+def view(app: App[CounterState]) -> Widget:
+    def increment() -> None:
+        app.set_state(lambda s: setattr(s, "value", s.value + 1))
+
+    return Column(
+        style=Style(gap=8.0),
+        children=[
+            Text(content=f"Count: {app.state.value}", key="label"),
+            Button(label="+", on_click=increment, key="inc"),
+        ],
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_qt(make_state(), view, title="counter"))
+```
+
+Full example with sync **and** `async` handlers:
+[`examples/counter/app.py`](examples/counter/app.py).
+
+---
+
+## Gallery
+
+A set of runnable example apps lives in [`examples/`](examples/README.md). Each
+exposes the same `make_state()` + `view(app)` contract, so it runs in the Qt
+simulator (`uv run python examples/<name>/app.py`) **and** on a device via
+code-push (`uv run tempest serve examples/<name>/app.py`) with no changes.
+
+| App | What it shows |
+|---|---|
+| [`counter`](examples/counter/app.py) | Sync + `async` handlers, the basics. |
+| [`todo`](examples/todo/app.py) | Type-to-add list — `Input` + `insert` / `remove` / `update` patches. |
+| [`calculator`](examples/calculator/app.py) | Dense nested `Row`/`Column` button grid. |
+| [`stopwatch`](examples/stopwatch/app.py) | Async loop ticking the UI via `asyncio.sleep`. |
+| [`colorpicker`](examples/colorpicker/app.py) | Dynamic `Style` updates (swatches + toggles). |
+| [`form`](examples/form/app.py) | The value-bearing inputs (`Input` / `Checkbox` / `DatePicker` / `FilePicker`) + their typed change events. |
+| [`gallery`](examples/gallery/app.py) | The expanded set — `Slider` / `Switch` / `ProgressBar` / `Spinner` / `Image` / `Icon` / `ScrollView`, secure + regex + multiline text fields, and a `Style.transition`. |
+
+The framework and the Qt simulator support the full widget set, including the
+value-bearing inputs and the utility widgets (`Slider` / `Switch` /
+`ProgressBar` / `Spinner` / `Image` / `Icon` / `ScrollView` / `TextArea`). The
+device (Compose) renderer renders `Text` / `Button` / `Column` / `Row` /
+`Container` plus the value widgets `Input` / `Checkbox` / `DatePicker` /
+`FilePicker` (with their typed change events); the remaining utility widgets stay
+empty-box on device until the Kotlin host grows the matching cases (see
+[`examples/README.md`](examples/README.md)).
+
+---
+
+## CLI
+
+```bash
+uv run tempest new MyApp                        # scaffold a new app project
+uv run python examples/counter/app.py          # run an app directly in the Qt simulator
+uv run tempest dev examples/counter/app.py     # dev loop: edit + save → hot reload (state preserved)
+uv run tempest serve examples/device_counter/app.py  # push to a device over LAN, no APK rebuild
+uv run tempest build MyApp/app.py              # bundle the app into an APK
+uv run tempest run MyApp/app.py                # build + install on a device + stream logs
+uv run tempest spec                            # print the typed contract (widgets/events) as JSON
+uv run tempest --help
+```
+
+`tempest dev` cockpit commands: `r` (hot reload, state preserved), `R` (hot
+restart, clean state), `s` (raise window), `q` (quit). Saving the file
+hot-reloads; a reload incompatible with the live state falls back to a clean
+restart. `tempest build`/`run` drive the `android-host` Gradle project + `adb`,
+so they need an Android SDK/NDK and a checkout of the host tree.
+
+| Command | Status | Notes |
+|---|---|---|
+| `tempest new <name>` | ✅ | Scaffold a runnable app project |
+| `tempest dev <app>` | ✅ | Simulator + hot reload / hot restart (needs `qt` extra) |
+| `tempest serve <app>` | ✅ | LAN code-push to a device + log relay (phase B5) |
+| `tempest spec` | ✅ | Typed widget/event contract as JSON |
+| `tempest build <app>` | ✅ | Bundle an app into an APK (needs Android SDK/NDK) |
+| `tempest run <app>` | ✅ | Build + install on a device + stream logs |
+
+---
+
+## Public API
+
+Everything below is importable from the top-level `tempestroid` package.
+
+### Style (`tempestroid.style`)
+
+Frozen Pydantic value objects, diffed by value.
+
+- **`Style`** — the style model (layout, box model, paint, typography, sizing,
+  effects, animation). Notable fields: `opacity`, `shadow`, `align_self`,
+  `letter_spacing`, `line_height`, `max_lines`, `text_overflow`, `aspect_ratio`.
+- **`Color`** — `Color.from_hex("#101418")`.
+- **`Edge`** — insets; `Edge.all(24.0)`.
+- **`Border`** (uniform) / **`SideBorder`** (per-side, e.g. a bottom divider).
+- **`Corners`** — per-corner radii for `Style.radius` (e.g. top-rounded sheets).
+- **`Shadow`** — `box-shadow` / elevation (`color` / `blur` / `offset_x` /
+  `offset_y`); Compose maps it to elevation, Qt to a `QGraphicsDropShadowEffect`.
+- **`Gradient`** + **`GradientStop`** — a linear gradient usable wherever a
+  background `Color` is (QSS `qlineargradient` / Compose `Brush`).
+- **`Transition`** — implicit animation (`duration_ms` / `curve` / `delay_ms`):
+  on rebuild the renderer tweens changed visual props instead of snapping
+  (Compose maps it to `animate*AsState`; Qt animation is renderer-imperative).
+- Enums: **`FlexDirection`**, **`JustifyContent`**, **`AlignItems`**,
+  **`TextAlign`**, **`FontWeight`**, **`FontStyle`**, **`TextDecoration`**,
+  **`TextOverflow`**, **`GradientDirection`**, **`Curve`** (easing).
+
+### Widgets (`tempestroid.widgets`)
+
+The declarative IR — bare-noun widgets.
+
+- **`Widget`** (base), **`Text`**, **`Button`**, **`Column`**, **`Row`**,
+  **`Container`**, **`ScrollView`** (scrollable container).
+- Value-bearing inputs: **`Input`** (text — with `secure` password masking +
+  reveal toggle, regex `pattern`, `keyboard` type, `max_length`), **`TextArea`**
+  (multi-line), **`Checkbox`** (boolean), **`Switch`** (boolean toggle),
+  **`Slider`** (numeric range), **`DatePicker`** (ISO date), **`FilePicker`**
+  (file selection).
+- Presentation widgets: **`Image`** (URL/asset, `fit`), **`Icon`** (named glyph),
+  **`ProgressBar`** (determinate/indeterminate), **`Spinner`** (activity).
+- Enums: **`KeyboardType`** (text/number/email/phone/url/password),
+  **`ImageFit`** (contain/cover/fill/none).
+- **`EventHandler`** — the typed handler-prop wrapper used by every handler field
+  (`on_click`, `on_change`, `on_select`); sync or `async`, zero- or one-argument.
+
+### Events (`tempestroid.widgets`) — typed boundary contract
+
+- **`Event`** (base), **`TapEvent`**, **`TextChangeEvent`** (carries `valid`
+  against the input's `pattern`), **`ToggleEvent`**, **`SlideEvent`**,
+  **`DateChangeEvent`**, **`FileSelectEvent`**.
+- **`parse_event(event_type, raw)`** — boundary gate: validates a raw payload
+  into a typed event or raises **`EventValidationError`** with structured field
+  errors. This is the Python↔Kotlin contract for the device bridge. The bridge
+  passes the validated event to handlers that accept a positional argument.
+
+### Core — IR + reconciler (`tempestroid.core`)
+
+- **`Node`**, **`Path`** — the lowered IR.
+- Patches: **`Insert`**, **`Remove`**, **`Update`**, **`Reorder`**,
+  **`Replace`**, and the **`Patch`** union.
+- **`build(widget) -> Node`**, **`diff(old, new) -> list[Patch]`**.
+- **`App[S]`** — renderer-agnostic state container: owns state, builds via
+  `view(app)`, diffs, hands patches to an `apply_patches` callback.
+
+### Introspection (`tempestroid.core`)
+
+- **`introspect()`** — full JSON contract `{"widgets": {...}, "events": {...}}`
+  (powers `tempest spec`).
+- **`widget_catalog()`**, **`event_catalog()`**.
+
+### Renderer (`tempestroid.renderers.qt`, needs `qt` extra)
+
+- **`run_qt(state, view, *, title, size)`** — run an app in the Qt simulator.
+- **`run_dev(app_path)`** — the `tempest dev` cockpit.
+
+### Compose + bridge — device side (phases B3/B4)
+
+The Python half is device-independent and tested without a phone; the JNI
+transport (B3) and the Kotlin Compose renderer (B4) are implemented in
+`android-host/` and verified on a real arm64 device.
+
+- **`to_compose(style)`** (`tempestroid.renderers.compose`) — serializable
+  `Style → Compose` spec; the second `Style` translator (pairs with `Style → Qt`).
+- **`serialize_node` / `serialize_patch`** — lower the IR/patches to JSON-able
+  dicts (handlers → path tokens, style → Compose spec).
+- **`MountMessage` / `PatchMessage` / `EventMessage`** — the wire protocol across
+  the bridge: `mount` carries the full serialized tree, `patch` an incremental
+  patch list, `event` a device→Python callback addressed by handler token.
+- **`DeviceApp`** + **`Bridge`** / **`LoopbackBridge`** — wire an `App` to a
+  device transport; the device-side analogue of `run_qt`. Events come back by
+  handler token, are validated by `parse_event`, and trigger coalesced patches.
+- **`JniBridge`** + **`run_device`** — the real on-device transport (phase B3):
+  `JniBridge` ships messages to Kotlin via the native `_tempest_host` module;
+  `run_device(state, view)` boots a `DeviceApp` on a fresh asyncio loop and
+  marshals incoming events back onto it. Imports cleanly off-device (the native
+  module is loaded lazily), so the framework still develops/tests on the desktop.
+
+### Dev server — LAN code-push (phase B5)
+
+The Expo-style on-device inner loop: edit on the dev machine, hot-restart on the
+phone without rebuilding the APK (`tempest serve <app>`).
+
+- **`DevServer`** — serves the app source (`/version`, `/app`) and relays device
+  logs (`/log`) over HTTP.
+- **`run_dev_client`** — the device poll loop: fetch on change → re-exec source →
+  hot-restart the `DeviceApp` (transport/fetch injected, so it's desktop-testable).
+- **`serve_device(url)`** — device entry point wiring the real `JniBridge` + the
+  native sink + an `urllib` fetch into `run_dev_client`.
+- **`render_qr(url)`** — ASCII QR for pairing (falls back to the plain URL).
+
+### Native capabilities (phase B6)
+
+Device-native features driven from Python as `{"kind": "native"}` commands the
+Kotlin host routes to capability modules. Verified on device.
+
+- **`notify(title, body="")`** — post a system notification from a handler.
+  The extension pattern (`native_command` envelope + a host module router) is in
+  place for further capabilities (camera, sensors, …).
+
+---
+
+## Project layout
+
+```text
+tempestroid/
+├── style.py            # Style + value objects (Color/Edge/Border/Corners/Shadow/Gradient/Transition) + enums (frozen Pydantic)
+├── widgets/            # Widget base + layout/inputs/media/indicators widgets + events.py
+├── core/               # ir.py, reconciler.py, state.py, introspection.py
+├── renderers/qt/       # renderer, Style→Qt, run_qt, simulator, dev_loop
+├── renderers/compose/  # Style→Compose translator (device renderer, Python side)
+├── bridge/             # IR/patch serialization, handler registry, DeviceApp
+└── cli/                # tempest entry point + app_loader + watcher
+
+# Trilho B (Android), outside the Python package:
+docs/research/          # web research + executable B0–B6 runbook
+toolchain/              # fetch CPython 3.14 + cibuildwheel native wheels
+android-host/           # Gradle/Kotlin host embedding official CPython via JNI
+```
+
+---
+
+## Status
+
+Track A (pure desktop CPython) is **complete: A0–A6**.
+
+| Phase | Scope | Status |
+|---|---|---|
+| A0 | Foundation: package, tooling, `tempest --help` | ✅ |
+| A1 | Style model + typed widget primitives | ✅ |
+| A2 | Reconciler: `build → diff → patch` | ✅ |
+| A3 | Qt renderer: patches → `QWidget`s, `Style → Qt` | ✅ |
+| A4 | Async event loop: asyncio ⨉ Qt (`qasync`) | ✅ |
+| A5 | `tempest dev`: watcher, hot restart, command loop | ✅ |
+| A6 | Typed event contract + introspection | ✅ |
+| B0–B6 | Android runtime: CPython 3.14 arm64, native wheels, Kotlin host, JNI bridge, Compose renderer, LAN code-push, native capabilities | ✅ |
+| C | Polish: `new`/`build`/`run` + stateful hot reload | ✅ |
+| D | Conformance golden snapshots (Qt vs Compose) | ✅ |
+
+---
+
+## Develop
+
+```bash
+uv run ruff check .
+uv run pyright          # strict mode
+uv run pytest
+```
+
+Conventions: double quotes everywhere, every parameter/return/annotation typed,
+Google-style English docstrings, absolute imports re-exported from each
+`__init__.py`. See [`CLAUDE.md`](CLAUDE.md) for the full set.