Metadata-Version: 2.4
Name: luvatrix
Version: 0.1.2
Summary: Luvatrix runtime and plotting toolkit
Author: Luvatrix contributors
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/0202alcc/luvatrix
Project-URL: Repository, https://github.com/0202alcc/luvatrix
Project-URL: Issues, https://github.com/0202alcc/luvatrix/issues
Keywords: apps,runtime,rendering,ui,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: <3.15,>=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.4.2
Requires-Dist: Pillow>=10.3.0
Provides-Extra: desktop
Requires-Dist: torch>=2.4.0; extra == "desktop"
Provides-Extra: macos
Requires-Dist: torch>=2.4.0; extra == "macos"
Requires-Dist: pyobjc-core>=12.1; extra == "macos"
Requires-Dist: pyobjc-framework-cocoa>=12.1; extra == "macos"
Requires-Dist: pyobjc-framework-quartz>=12.1; extra == "macos"
Requires-Dist: pyobjc-framework-Metal>=12.1; extra == "macos"
Provides-Extra: ios
Requires-Dist: pyobjc-framework-cocoa>=12.1; extra == "ios"
Requires-Dist: pyobjc-framework-quartz>=12.1; extra == "ios"
Requires-Dist: pyobjc-framework-Metal>=12.1; extra == "ios"
Provides-Extra: vulkan
Requires-Dist: vulkan>=1.3.275.1; extra == "vulkan"
Provides-Extra: web
Provides-Extra: android
Provides-Extra: dev
Requires-Dist: matplotlib>=3.10.8; extra == "dev"
Dynamic: license-file

# Luvatrix

Luvatrix is a Python app protocol and rendering runtime for building custom apps
that can run headless, on macOS, as static browser-side web apps, and through
scaffolded native Android/iOS projects.

## Install

Base install:

```bash
pip install luvatrix
```

Optional platform/runtime extras:

```bash
pip install "luvatrix[macos]"
pip install "luvatrix[vulkan]"
pip install "luvatrix[macos,vulkan]"
pip install "luvatrix[web]"
pip install "luvatrix[android]"
pip install "luvatrix[ios]"
```

The base package intentionally includes common raster/data dependencies
(`numpy` and `Pillow`). Platform-specific renderers still live behind extras.

## Create An External App

Create a standalone app outside this repository:

```bash
luvatrix init-app my_app
cd my_app
luvatrix validate-app . --render headless
luvatrix run-app . --render headless --ticks 1
```

Build and serve a browser-side app:

```bash
luvatrix build-web . --out dist/web
luvatrix serve-web .
```

Run with macOS rendering:

```bash
pip install "luvatrix[macos,vulkan]"
luvatrix validate-app . --render macos
luvatrix run-app . --render macos
```

## Native Scaffolds

Native Android and iOS projects are app-owned. Scaffold them into your app
repository when you need native targets:

```bash
luvatrix init-native . --target android --out android
luvatrix init-native . --target ios --out ios
```

Then run with the app-owned native project:

```bash
luvatrix run-app . --render android-emulator --native-project android
luvatrix run-app . --render ios-simulator --native-project ios
```

Native prerequisites:

- Android: Android SDK, ADB, Gradle/Android Gradle Plugin support, and a
  configured emulator or device.
- iOS: Xcode, xcodegen, signing for physical devices, and the iOS Python support
  assets prepared by the scaffold's `ios/scripts/setup_ios.sh`.
- Vulkan on macOS: the Python `vulkan` binding plus a native Vulkan SDK/loader
  such as Vulkan SDK or MoltenVK.

## App Layout

A minimal Luvatrix app is just:

```text
my_app/
├── app.toml
└── app_main.py
```

`app.toml` declares the app id, protocol version, entrypoint, capabilities,
platform support, display metadata, and render preferences. The Python
entrypoint returns an object compatible with `init(ctx)`, `loop(ctx, dt)`, and
`stop(ctx)`, or a subclass of `luvatrix.app.App`.

Public app-developer API:

```python
from luvatrix.app import App, AppContext, validate_app_install
```

See `docs/app_protocol.md` in the repository for the detailed protocol contract.
