velto 0.1.0__tar.gz

velto-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Neuri
+
+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.

velto-0.1.0/NOTICE

@@ -0,0 +1,159 @@
+# Qyro CLI
+
+Copyright (c) 2020 - 2026 Neuri
+
+Qyro CLI depends on several open source libraries and external tools. This file
+describes the open source software used by, supported by, or integrated with
+Qyro CLI and the applicable license terms.
+
+Some third-party software may be used by applications generated by Qyro CLI,
+while other software is invoked externally by Qyro CLI when performing specific
+build or distribution operations. Third-party components are not necessarily
+distributed with Qyro CLI and remain subject to their respective licenses.
+
+For the complete license terms of a dependency, refer to the license provided
+by the respective project.
+
+# Qyro
+
+URL: https://github.com/Neuri-AI/qyro
+
+The Qyro CLI generates and orchestrates applications based on Qyro.
+
+Qyro is distributed under its own applicable license terms.
+See the Qyro repository for its license and third-party notices.
+
+# PyInstaller
+
+URL: https://www.pyinstaller.org
+
+Qyro CLI invokes PyInstaller to freeze Python applications into standalone
+application artifacts.
+
+PyInstaller is distributed under the GNU General Public License, version 2
+or later, with an exception that permits the distribution of applications
+generated by PyInstaller under terms selected by the application author.
+
+Qyro CLI does not link to PyInstaller as a library; it invokes PyInstaller
+as a build tool.
+
+# PySide6
+
+URL: https://doc.qt.io/qtforpython/
+
+PySide6 may be used by applications generated by Qyro CLI.
+
+PySide6 is distributed under the GNU Lesser General Public License, version 3,
+or other applicable Qt licensing terms.
+
+See the PySide6 and Qt licensing documentation for complete terms.
+
+# PyQt6
+
+URL: https://www.riverbankcomputing.com/software/pyqt/
+
+PyQt6 may be used by applications generated by Qyro CLI.
+
+PyQt6 is available under the GNU General Public License, version 3, or a
+commercial license from Riverbank Computing, subject to the applicable
+licensing terms.
+
+# PyQt5
+
+URL: https://www.riverbankcomputing.com/software/pyqt/
+
+PyQt5 may be used by applications generated by Qyro CLI.
+
+PyQt5 is available under the GNU General Public License, version 3, or a
+commercial license from Riverbank Computing, subject to the applicable
+licensing terms.
+
+# PySide2
+
+URL: https://wiki.qt.io/Qt_for_Python
+
+PySide2 may be used by applications generated by Qyro CLI.
+
+PySide2 is distributed under the GNU Lesser General Public License, version 3,
+or other applicable Qt licensing terms.
+
+See the PySide2 and Qt licensing documentation for complete terms.
+
+# Kivy
+
+URL: https://kivy.org
+
+Kivy may be used by applications generated by Qyro CLI.
+
+Kivy is distributed under the MIT License.
+
+# Tkinter
+
+URL: https://docs.python.org/3/library/tkinter.html
+
+Tkinter is part of the Python standard library and may be used by applications
+generated by Qyro CLI.
+
+Tkinter is distributed as part of Python and is subject to the applicable
+Python license terms.
+
+# External Distribution Tools
+
+Qyro CLI may require external tools for specific distribution targets.
+These tools are not bundled with or redistributed by Qyro CLI.
+
+When an operation requires one of these tools and it is not installed,
+Qyro CLI reports the missing requirement and instructs the user to install
+the corresponding tool.
+
+## create-dmg
+
+URL: https://github.com/create-dmg/create-dmg
+
+Qyro CLI may invoke create-dmg to create customized macOS disk images.
+
+create-dmg is distributed under the MIT License.
+
+## fpm
+
+URL: https://github.com/jordansissel/fpm
+
+Qyro CLI may invoke fpm to create Linux packages such as DEB, RPM,
+and Arch packages.
+
+fpm is distributed under the MIT License.
+
+## NSIS
+
+URL: https://nsis.sourceforge.io
+
+Qyro CLI may invoke NSIS to create Windows installers.
+
+NSIS is distributed under its own open source license terms.
+
+The applicable copyright and license notices for these external tools are
+provided by their respective projects.
+
+# Open Source Licensing
+
+Qyro CLI is designed to work with multiple independently licensed open source
+frameworks, libraries, and packaging tools.
+
+The licensing terms of a generated application depend on the frameworks,
+libraries, resources, and external tools included in that application.
+
+Users are responsible for reviewing and complying with the licenses applicable
+to the dependencies and components they distribute.
+
+Where a dependency requires attribution, license notices, or source code
+availability, those requirements must be satisfied in accordance with the
+dependency's license.
+
+# Third-Party Notices
+
+This NOTICE file is provided for informational and attribution purposes.
+It does not replace, modify, or supersede the license terms of any third-party
+software.
+
+For components distributed separately from Qyro CLI, consult the corresponding
+upstream project for the authoritative license text and copyright notices.

velto-0.1.0/PKG-INFO

@@ -0,0 +1,319 @@
+Metadata-Version: 2.4
+Name: velto
+Version: 0.1.0
+Summary: The public application facade for Qyro, PSX, and Pydux.
+License: MIT
+License-File: LICENSE
+License-File: NOTICE
+Author: Neuri
+Requires-Python: >=3.10,<3.13.20
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: kivy
+Provides-Extra: pyqt5
+Provides-Extra: pyqt6
+Provides-Extra: pyside2
+Provides-Extra: pyside6
+Provides-Extra: sentry
+Provides-Extra: state
+Requires-Dist: pydux-store[psx] (>=0.1.0,<1.0.0) ; extra == "state"
+Requires-Dist: qyro-engine (>=0.1.0,<1.0.0)
+Requires-Dist: qyro-engine[kivy] (>=0.1.0,<1.0.0) ; extra == "kivy"
+Requires-Dist: qyro-engine[pyqt5] (>=0.1.0,<1.0.0) ; extra == "pyqt5"
+Requires-Dist: qyro-engine[pyqt6] (>=0.1.0,<1.0.0) ; extra == "pyqt6"
+Requires-Dist: qyro-engine[pyside2] (>=0.1.0,<1.0.0) ; extra == "pyside2"
+Requires-Dist: qyro-engine[pyside6] (>=0.1.0,<1.0.0) ; extra == "pyside6"
+Requires-Dist: qyro-engine[sentry] (>=0.1.0,<1.0.0) ; extra == "sentry"
+Requires-Dist: velto-core (>=0.1.0,<1.0.0)
+Requires-Dist: velto-core[kivy] (>=0.1.0,<1.0.0) ; extra == "kivy"
+Requires-Dist: velto-core[pyqt5] (>=0.1.0,<1.0.0) ; extra == "pyqt5"
+Requires-Dist: velto-core[pyqt6] (>=0.1.0,<1.0.0) ; extra == "pyqt6"
+Requires-Dist: velto-core[pyside2] (>=0.1.0,<1.0.0) ; extra == "pyside2"
+Requires-Dist: velto-core[pyside6] (>=0.1.0,<1.0.0) ; extra == "pyside6"
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://ik.imagekit.io/kummiktgaiq/ppg/velto-logo_KcLcXCZnT.png" alt="Velto logo" width="45%" />
+</p>
+
+# Velto
+Build native applications in Python with declarative, reactive interfaces
+
+[![Python](https://img.shields.io/badge/Python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://python.org)
+[![velto Platforms Tests](https://github.com/Neuri-AI/velto/actions/workflows/matrix.yml/badge.svg)](https://github.com/Neuri-AI/velto/actions/workflows/matrix.yml)
+![GitHub Release](https://img.shields.io/github/v/release/Neuri-AI/velto?include_prereleases&display_name=release&color=stable)
+![GitHub Issues](https://img.shields.io/github/issues/Neuri-AI/velto)
+![GitHub Issues Closed](https://img.shields.io/github/issues-closed/Neuri-AI/velto?color=green)
+![GitHub forks](https://img.shields.io/github/forks/Neuri-AI/velto)
+![GitHub stars](https://img.shields.io/github/stars/Neuri-AI/velto)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Sponsor](https://img.shields.io/badge/Sponsor-Buy%20Me%20a%20Coffee-FFDD00?logo=buymeacoffee&logoColor=000000)](https://buymeacoffee.com/neuri)
+
+
+Velto is a Python framework for building native graphical applications using declarative components, reactive state, and a shared layout engine. It combines a Python-first development experience with native rendering through Qt, Tkinter, and Kivy—without requiring a web browser for the UI.
+
+
+> **Project status:** Velto 0.1.x is an early-stage release. APIs, tooling, backend parity, and mobile deployment are actively evolving. Desktop support and mobile deployment have different levels of maturity.
+
+## Highlights
+
+- **Declarative Python UI:** Describe interfaces with PSX markup.
+- **Reactive updates:** Build stateful components using hooks such as `use_state`, `use_effect`, and `use_ref`.
+- **Native backends:** Render through Qt, Tkinter, and Kivy.
+- **Styling and layout:** Use HTML-like elements, CSS-like styles, Flex, Grid, and scrolling primitives.
+- **Native integration:** Embed toolkit widgets using `Native` and extend reactive updates through adapters.
+- **Global state:** Integrate Pydux when local component state is not enough.
+- **CLI:** Use the Velto CLI for project setup, execution, and packaging workflows.
+
+## Quick start
+
+The **recommended way to create, run, and package a Velto application is through [Velto CLI](https://github.com/Neuri-AI/Velto-CLI)**. It initializes the project structure, configures the selected native framework, and provides a consistent development and release workflow.
+
+### 1. Install the CLI
+
+Use a supported Python installation (Python 3.10–3.14 is a conservative choice; compatibility depends on package versions and the selected backend). A virtual environment is recommended:
+
+```bash
+python -m venv .venv
+```
+
+Activate it on macOS or Linux:
+
+```bash
+source .venv/bin/activate
+```
+
+Or on Windows (PowerShell):
+
+```powershell
+.venv\Scripts\Activate.ps1
+```
+
+Then install the desktop tooling:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install "velto-cli[desktop]"
+```
+
+### 2. Create your application
+
+```bash
+velto init --name my-app
+```
+
+The interactive setup guides you through the available frameworks and project options. To select PySide6 explicitly:
+
+```bash
+velto init --name my-app --framework pyside6
+```
+
+Velto CLI supports desktop framework choices including **PySide6, PyQt6, PyQt5, PySide2, Kivy, and Tkinter**, subject to their platform and Python compatibility.
+
+### 3. Start developing
+
+```bash
+cd my-app
+velto start
+```
+
+Edit the generated `main.py` and other project files. For example, a simple reactive component looks like this:
+
+```python
+import sys
+from velto import VeltoContext
+from velto.ui import psx, use_state
+
+
+class CounterApp(VeltoContext):
+    def render(self):
+        count, set_count = use_state(0)
+
+        return psx("""
+            <div style="display: flex; flex-direction: column; gap: 16px; padding: 24px;">
+                <h1>Hello, Velto!</h1>
+                <p>Build reactive native interfaces with Python.</p>
+                <button on_click={() => set_count(count + 1)}>
+                    Count is {count}
+                </button>
+            </div>
+        """)
+
+
+if __name__ == "__main__":
+    sys.exit(CounterApp().run())
+```
+
+The example shows component-local reactive state. PSX updates the affected UI nodes and the selected backend renders the native widgets. Run the application using **`velto start`** from the project directory.
+
+For a complete starter project with stylesheets and assets, see [examples/hello-world](examples/hello-world).
+
+### 4. Build and distribute
+
+From the project directory, build your desktop application:
+
+```bash
+velto build
+```
+
+To produce a single executable, where supported:
+
+```bash
+velto build --onefile
+```
+
+For distribution, use the CLI's platform-aware packaging workflow:
+
+```bash
+velto bundle
+```
+
+The CLI also provides signing and release tools. See the [Velto CLI documentation](https://github.com/Neuri-AI/Velto-CLI) for packaging formats, settings, prerequisites, and platform-specific behavior.
+
+> [!NOTE]
+> Velto CLI is in alpha. Desktop development is the supported workflow; Android and iOS packaging are experimental and should not be treated as production-ready.
+
+## Architecture
+
+Velto exposes one application-facing interface while preserving clear responsibilities for each subsystem:
+
+```text
+                        Your Python application
+                                  |
+                           velto (facade)
+                                  |
+                +-----------------+----------------+
+                |                 |                |
+           Qyro Engine           PSX          Pydux (optional)
+          Runtime/lifecycle   UI + reactivity    Shared state
+                                  |
+                               Cinnamon
+                           Layout geometry
+                                  |
+                       Native renderer adapters
+                                  |
+                        Qt / Tkinter / Kivy
+```
+
+| Component | Responsibility | Repository |
+| --- | --- | --- |
+| **Velto** | Public application-facing imports | [Neuri-AI/Velto](https://github.com/Neuri-AI/Velto) |
+| **Qyro Engine** | Application lifecycle, runtime services, and resource handling | [Neuri-AI/qyro](https://github.com/Neuri-AI/qyro) |
+| **PSX / Velto Core** | Declarative markup, components, reconciliation, hooks, and native adapters | [Neuri-AI/PSX](https://github.com/Neuri-AI/PSX) |
+| **Cinnamon** | Shared geometric layout computation used by PSX | [Neuri-AI/PSX](https://github.com/Neuri-AI/PSX) |
+| **Pydux** | Optional store, reducers, selectors, and state integration | [Neuri-AI/Pydux](https://github.com/Neuri-AI/Pydux) |
+| **Velto CLI** | Project development and packaging commands | [Neuri-AI/Velto-CLI](https://github.com/Neuri-AI/Velto-CLI) |
+
+### What happens when Velto renders?
+
+1. Your `VeltoContext` provides the application entry point and lifecycle.
+2. PSX processes markup and component definitions into a virtual UI representation.
+3. Hooks and reconciliation track state changes and determine which nodes need updating.
+4. Cinnamon computes the layout geometry for the UI.
+5. The selected renderer maps the result to native toolkit widgets.
+
+The UI is **not rendered as an HTML page inside a browser**. Explicit native integrations, such as a web view embedded in an application, are available separately.
+
+## Unified public API
+
+```python
+from velto import VeltoContext
+from velto.ui import psx, component, use_state, use_effect, use_ref
+from velto.ui import Flex, Grid, GridItem, Scroll, Text, Native, native_adapter
+from velto.runtime import get_resource, is_frozen
+
+# Optional: requires `velto[state]`
+from velto.state import configure_store, create_slice, use_dispatch, use_selector
+```
+
+Velto reexports the underlying libraries' public objects rather than maintaining a separate wrapper implementation. Existing applications importing from `qyro`, `psx`, or `pydux` can continue using those APIs.
+
+See the [public API reference](docs/public-api.md) for the facade contract and integration details.
+
+## Native widget integration
+
+PSX can mount existing native widgets through the `Native` component. For reactive widget properties, use a widget-owned `update_props(self, props, changed)` method or register an adapter with `@native_adapter(WidgetType)`.
+
+```python
+from velto.ui import native_adapter
+
+@native_adapter(MyWidget)
+def update_my_widget(widget, props, changed):
+    if "value" in changed:
+        widget.set_value(props["value"])
+```
+
+```jsx
+<Native widget={MyWidget} props={{"value": current_value}} />
+```
+
+Native widget construction parameters can also be passed separately. Refer to the [native integration contract](docs/public-api.md) before using toolkit-specific APIs.
+
+## Examples
+
+Explore the working examples in this repository:
+
+| Example | Description |
+| --- | --- |
+| [Hello World](examples/hello-world) | Minimal reactive application |
+| [Dashboard](examples/dashboard) | Multi-section application layout |
+| [Pydux login screen](examples/pydux-login-screen) | Optional centralized state integration |
+| [Qt Charts](examples/qt-charts) | Native chart integration |
+| [Chromium browser](examples/chromium-browser) | Browser component embedded as a native integration |
+| [WebView app](examples/webview-app) | Web view integration |
+| [Third-party libraries](examples/third-party-libraries) | Extending applications with external UI libraries |
+
+## Platforms and compatibility
+
+Velto targets desktop applications on **Linux, Windows, and macOS**, depending on the selected backend and its available native dependencies.
+
+Android and iOS are areas of ongoing development. Mobile packaging and deployment should not yet be assumed to have the same maturity or compatibility coverage as desktop.
+
+The current repository's package manifest requires `Python >=3.10,<3.13.20`, while [docs/compatibility.md](docs/compatibility.md) describes a broader 0.1.x certification range. When choosing an installation environment, use the published package metadata and the constraints of your selected backend as the source of truth.
+
+## Development workflow
+
+The [Velto CLI](https://github.com/Neuri-AI/Velto-CLI) provides commands for generating and working with projects:
+
+```bash
+velto init
+velto start
+```
+
+CLI installation, backend selection, and build options are documented in the CLI repository. Packaging and mobile build support vary by platform and backend.
+
+To contribute to this facade repository:
+
+```bash
+git clone https://github.com/Neuri-AI/Velto.git
+cd Velto
+python -m pip install -e ".[pyside6]"
+python -m pip install pytest
+python -m pytest
+```
+
+Some integration tests may require additional backend packages or platform-specific tools.
+
+## Documentation
+
+- [Public API and native integration](docs/public-api.md)
+- [Compatibility matrix](docs/compatibility.md)
+- [PSX source and documentation](https://github.com/Neuri-AI/PSX)
+- [Qyro Engine](https://github.com/Neuri-AI/qyro)
+- [Velto CLI](https://github.com/Neuri-AI/Velto-CLI)
+- [Examples](examples)
+
+## Contributing
+
+Contributions, reproducible bug reports, and documentation improvements are welcome. Before submitting a change, review the relevant subsystem repository, provide a minimal reproduction for defects, and run the applicable test suite.
+
+Open an [issue](https://github.com/Neuri-AI/Velto/issues) for facade-level bugs or feature discussions.
+
+## License
+
+Velto is released under the [MIT License](LICENSE). Individual runtime engines, UI bindings, and other dependencies may have their own license obligations; consult [NOTICE](NOTICE) and the corresponding upstream packages.
+

velto-0.1.0/README.md

@@ -0,0 +1,280 @@
+<p align="center">
+  <img src="https://ik.imagekit.io/kummiktgaiq/ppg/velto-logo_KcLcXCZnT.png" alt="Velto logo" width="45%" />
+</p>
+
+# Velto
+Build native applications in Python with declarative, reactive interfaces
+
+[![Python](https://img.shields.io/badge/Python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://python.org)
+[![velto Platforms Tests](https://github.com/Neuri-AI/velto/actions/workflows/matrix.yml/badge.svg)](https://github.com/Neuri-AI/velto/actions/workflows/matrix.yml)
+![GitHub Release](https://img.shields.io/github/v/release/Neuri-AI/velto?include_prereleases&display_name=release&color=stable)
+![GitHub Issues](https://img.shields.io/github/issues/Neuri-AI/velto)
+![GitHub Issues Closed](https://img.shields.io/github/issues-closed/Neuri-AI/velto?color=green)
+![GitHub forks](https://img.shields.io/github/forks/Neuri-AI/velto)
+![GitHub stars](https://img.shields.io/github/stars/Neuri-AI/velto)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Sponsor](https://img.shields.io/badge/Sponsor-Buy%20Me%20a%20Coffee-FFDD00?logo=buymeacoffee&logoColor=000000)](https://buymeacoffee.com/neuri)
+
+
+Velto is a Python framework for building native graphical applications using declarative components, reactive state, and a shared layout engine. It combines a Python-first development experience with native rendering through Qt, Tkinter, and Kivy—without requiring a web browser for the UI.
+
+
+> **Project status:** Velto 0.1.x is an early-stage release. APIs, tooling, backend parity, and mobile deployment are actively evolving. Desktop support and mobile deployment have different levels of maturity.
+
+## Highlights
+
+- **Declarative Python UI:** Describe interfaces with PSX markup.
+- **Reactive updates:** Build stateful components using hooks such as `use_state`, `use_effect`, and `use_ref`.
+- **Native backends:** Render through Qt, Tkinter, and Kivy.
+- **Styling and layout:** Use HTML-like elements, CSS-like styles, Flex, Grid, and scrolling primitives.
+- **Native integration:** Embed toolkit widgets using `Native` and extend reactive updates through adapters.
+- **Global state:** Integrate Pydux when local component state is not enough.
+- **CLI:** Use the Velto CLI for project setup, execution, and packaging workflows.
+
+## Quick start
+
+The **recommended way to create, run, and package a Velto application is through [Velto CLI](https://github.com/Neuri-AI/Velto-CLI)**. It initializes the project structure, configures the selected native framework, and provides a consistent development and release workflow.
+
+### 1. Install the CLI
+
+Use a supported Python installation (Python 3.10–3.14 is a conservative choice; compatibility depends on package versions and the selected backend). A virtual environment is recommended:
+
+```bash
+python -m venv .venv
+```
+
+Activate it on macOS or Linux:
+
+```bash
+source .venv/bin/activate
+```
+
+Or on Windows (PowerShell):
+
+```powershell
+.venv\Scripts\Activate.ps1
+```
+
+Then install the desktop tooling:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install "velto-cli[desktop]"
+```
+
+### 2. Create your application
+
+```bash
+velto init --name my-app
+```
+
+The interactive setup guides you through the available frameworks and project options. To select PySide6 explicitly:
+
+```bash
+velto init --name my-app --framework pyside6
+```
+
+Velto CLI supports desktop framework choices including **PySide6, PyQt6, PyQt5, PySide2, Kivy, and Tkinter**, subject to their platform and Python compatibility.
+
+### 3. Start developing
+
+```bash
+cd my-app
+velto start
+```
+
+Edit the generated `main.py` and other project files. For example, a simple reactive component looks like this:
+
+```python
+import sys
+from velto import VeltoContext
+from velto.ui import psx, use_state
+
+
+class CounterApp(VeltoContext):
+    def render(self):
+        count, set_count = use_state(0)
+
+        return psx("""
+            <div style="display: flex; flex-direction: column; gap: 16px; padding: 24px;">
+                <h1>Hello, Velto!</h1>
+                <p>Build reactive native interfaces with Python.</p>
+                <button on_click={() => set_count(count + 1)}>
+                    Count is {count}
+                </button>
+            </div>
+        """)
+
+
+if __name__ == "__main__":
+    sys.exit(CounterApp().run())
+```
+
+The example shows component-local reactive state. PSX updates the affected UI nodes and the selected backend renders the native widgets. Run the application using **`velto start`** from the project directory.
+
+For a complete starter project with stylesheets and assets, see [examples/hello-world](examples/hello-world).
+
+### 4. Build and distribute
+
+From the project directory, build your desktop application:
+
+```bash
+velto build
+```
+
+To produce a single executable, where supported:
+
+```bash
+velto build --onefile
+```
+
+For distribution, use the CLI's platform-aware packaging workflow:
+
+```bash
+velto bundle
+```
+
+The CLI also provides signing and release tools. See the [Velto CLI documentation](https://github.com/Neuri-AI/Velto-CLI) for packaging formats, settings, prerequisites, and platform-specific behavior.
+
+> [!NOTE]
+> Velto CLI is in alpha. Desktop development is the supported workflow; Android and iOS packaging are experimental and should not be treated as production-ready.
+
+## Architecture
+
+Velto exposes one application-facing interface while preserving clear responsibilities for each subsystem:
+
+```text
+                        Your Python application
+                                  |
+                           velto (facade)
+                                  |
+                +-----------------+----------------+
+                |                 |                |
+           Qyro Engine           PSX          Pydux (optional)
+          Runtime/lifecycle   UI + reactivity    Shared state
+                                  |
+                               Cinnamon
+                           Layout geometry
+                                  |
+                       Native renderer adapters
+                                  |
+                        Qt / Tkinter / Kivy
+```
+
+| Component | Responsibility | Repository |
+| --- | --- | --- |
+| **Velto** | Public application-facing imports | [Neuri-AI/Velto](https://github.com/Neuri-AI/Velto) |
+| **Qyro Engine** | Application lifecycle, runtime services, and resource handling | [Neuri-AI/qyro](https://github.com/Neuri-AI/qyro) |
+| **PSX / Velto Core** | Declarative markup, components, reconciliation, hooks, and native adapters | [Neuri-AI/PSX](https://github.com/Neuri-AI/PSX) |
+| **Cinnamon** | Shared geometric layout computation used by PSX | [Neuri-AI/PSX](https://github.com/Neuri-AI/PSX) |
+| **Pydux** | Optional store, reducers, selectors, and state integration | [Neuri-AI/Pydux](https://github.com/Neuri-AI/Pydux) |
+| **Velto CLI** | Project development and packaging commands | [Neuri-AI/Velto-CLI](https://github.com/Neuri-AI/Velto-CLI) |
+
+### What happens when Velto renders?
+
+1. Your `VeltoContext` provides the application entry point and lifecycle.
+2. PSX processes markup and component definitions into a virtual UI representation.
+3. Hooks and reconciliation track state changes and determine which nodes need updating.
+4. Cinnamon computes the layout geometry for the UI.
+5. The selected renderer maps the result to native toolkit widgets.
+
+The UI is **not rendered as an HTML page inside a browser**. Explicit native integrations, such as a web view embedded in an application, are available separately.
+
+## Unified public API
+
+```python
+from velto import VeltoContext
+from velto.ui import psx, component, use_state, use_effect, use_ref
+from velto.ui import Flex, Grid, GridItem, Scroll, Text, Native, native_adapter
+from velto.runtime import get_resource, is_frozen
+
+# Optional: requires `velto[state]`
+from velto.state import configure_store, create_slice, use_dispatch, use_selector
+```
+
+Velto reexports the underlying libraries' public objects rather than maintaining a separate wrapper implementation. Existing applications importing from `qyro`, `psx`, or `pydux` can continue using those APIs.
+
+See the [public API reference](docs/public-api.md) for the facade contract and integration details.
+
+## Native widget integration
+
+PSX can mount existing native widgets through the `Native` component. For reactive widget properties, use a widget-owned `update_props(self, props, changed)` method or register an adapter with `@native_adapter(WidgetType)`.
+
+```python
+from velto.ui import native_adapter
+
+@native_adapter(MyWidget)
+def update_my_widget(widget, props, changed):
+    if "value" in changed:
+        widget.set_value(props["value"])
+```
+
+```jsx
+<Native widget={MyWidget} props={{"value": current_value}} />
+```
+
+Native widget construction parameters can also be passed separately. Refer to the [native integration contract](docs/public-api.md) before using toolkit-specific APIs.
+
+## Examples
+
+Explore the working examples in this repository:
+
+| Example | Description |
+| --- | --- |
+| [Hello World](examples/hello-world) | Minimal reactive application |
+| [Dashboard](examples/dashboard) | Multi-section application layout |
+| [Pydux login screen](examples/pydux-login-screen) | Optional centralized state integration |
+| [Qt Charts](examples/qt-charts) | Native chart integration |
+| [Chromium browser](examples/chromium-browser) | Browser component embedded as a native integration |
+| [WebView app](examples/webview-app) | Web view integration |
+| [Third-party libraries](examples/third-party-libraries) | Extending applications with external UI libraries |
+
+## Platforms and compatibility
+
+Velto targets desktop applications on **Linux, Windows, and macOS**, depending on the selected backend and its available native dependencies.
+
+Android and iOS are areas of ongoing development. Mobile packaging and deployment should not yet be assumed to have the same maturity or compatibility coverage as desktop.
+
+The current repository's package manifest requires `Python >=3.10,<3.13.20`, while [docs/compatibility.md](docs/compatibility.md) describes a broader 0.1.x certification range. When choosing an installation environment, use the published package metadata and the constraints of your selected backend as the source of truth.
+
+## Development workflow
+
+The [Velto CLI](https://github.com/Neuri-AI/Velto-CLI) provides commands for generating and working with projects:
+
+```bash
+velto init
+velto start
+```
+
+CLI installation, backend selection, and build options are documented in the CLI repository. Packaging and mobile build support vary by platform and backend.
+
+To contribute to this facade repository:
+
+```bash
+git clone https://github.com/Neuri-AI/Velto.git
+cd Velto
+python -m pip install -e ".[pyside6]"
+python -m pip install pytest
+python -m pytest
+```
+
+Some integration tests may require additional backend packages or platform-specific tools.
+
+## Documentation
+
+- [Public API and native integration](docs/public-api.md)
+- [Compatibility matrix](docs/compatibility.md)
+- [PSX source and documentation](https://github.com/Neuri-AI/PSX)
+- [Qyro Engine](https://github.com/Neuri-AI/qyro)
+- [Velto CLI](https://github.com/Neuri-AI/Velto-CLI)
+- [Examples](examples)
+
+## Contributing
+
+Contributions, reproducible bug reports, and documentation improvements are welcome. Before submitting a change, review the relevant subsystem repository, provide a minimal reproduction for defects, and run the applicable test suite.
+
+Open an [issue](https://github.com/Neuri-AI/Velto/issues) for facade-level bugs or feature discussions.
+
+## License
+
+Velto is released under the [MIT License](LICENSE). Individual runtime engines, UI bindings, and other dependencies may have their own license obligations; consult [NOTICE](NOTICE) and the corresponding upstream packages.

velto-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "velto"
+version = "0.1.0"
+description = "The public application facade for Qyro, PSX, and Pydux."
+readme = "README.md"
+requires-python = ">=3.10,<3.13.20"
+license = { text = "MIT" }
+authors = [
+    { name = "Neuri" },
+]
+dependencies = [
+    "qyro-engine>=0.1.0,<1.0.0",
+    "velto-core>=0.1.0,<1.0.0",
+]
+
+[project.optional-dependencies]
+state = ["pydux-store[psx]>=0.1.0,<1.0.0"]
+pyside6 = [
+    "qyro-engine[pyside6]>=0.1.0,<1.0.0",
+    "velto-core[pyside6]>=0.1.0,<1.0.0",
+]
+pyqt6 = [
+    "qyro-engine[pyqt6]>=0.1.0,<1.0.0",
+    "velto-core[pyqt6]>=0.1.0,<1.0.0",
+]
+pyqt5 = [
+    "qyro-engine[pyqt5]>=0.1.0,<1.0.0",
+    "velto-core[pyqt5]>=0.1.0,<1.0.0",
+]
+pyside2 = [
+    "qyro-engine[pyside2]>=0.1.0,<1.0.0",
+    "velto-core[pyside2]>=0.1.0,<1.0.0",
+]
+kivy = [
+    "qyro-engine[kivy]>=0.1.0,<1.0.0",
+    "velto-core[kivy]>=0.1.0,<1.0.0",
+]
+sentry = ["qyro-engine[sentry]>=0.1.0,<1.0.0"]
+
+[tool.poetry]
+packages = [{ include = "velto" }]
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.0"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

velto-0.1.0/velto/__init__.py

@@ -0,0 +1,7 @@
+"""The public entry point for Velto applications."""
+
+from qyro import VeltoContext
+
+__version__ = "0.1.0"
+
+__all__ = ["VeltoContext", "__version__"]

velto-0.1.0/velto/py.typed

@@ -0,0 +1 @@
+

velto-0.1.0/velto/runtime/__init__.py

@@ -0,0 +1,22 @@
+"""Runtime, configuration, and resource APIs supplied by Qyro."""
+
+from qyro import (
+    AppMetadata,
+    EngineContainer,
+    ExecutionMode,
+    FrameworkNotAvailableError,
+    PlatformDetector,
+    PlatformType,
+    QyroEngineError,
+    ResourceNotFoundError,
+    SettingsNotFoundError,
+    get_resource,
+    is_frozen,
+    load_build_settings,
+)
+
+__all__ = [
+    "AppMetadata", "EngineContainer", "ExecutionMode", "FrameworkNotAvailableError",
+    "PlatformDetector", "PlatformType", "QyroEngineError", "ResourceNotFoundError",
+    "SettingsNotFoundError", "get_resource", "is_frozen", "load_build_settings",
+]

velto-0.1.0/velto/state/__init__.py

@@ -0,0 +1,35 @@
+"""State-management APIs supplied by Pydux."""
+
+from pydux import (
+    Action,
+    Dispatch,
+    Middleware,
+    PyDuxDevTools,
+    PyDuxInspectorServer,
+    Reducer,
+    Selector,
+    Slice,
+    Store,
+    combine_reducers,
+    configure_store,
+    create_async_thunk,
+    create_selector,
+    create_slice,
+    create_thunk_middleware,
+    deep_equal,
+    devtools_middleware,
+    is_identical,
+    shallow_equal,
+    start_inspector,
+    StoreProvider,
+    use_dispatch,
+    use_selector,
+)
+
+__all__ = [
+    "Action", "Dispatch", "Middleware", "PyDuxDevTools", "PyDuxInspectorServer", "Reducer",
+    "Selector", "Slice", "Store", "combine_reducers", "configure_store",
+    "create_async_thunk", "create_selector", "create_slice", "create_thunk_middleware",
+    "deep_equal", "devtools_middleware", "is_identical", "shallow_equal", "start_inspector",
+    "StoreProvider", "use_dispatch", "use_selector",
+]

velto-0.1.0/velto/ui/__init__.py

@@ -0,0 +1,90 @@
+"""Declarative UI, hooks, rendering, and extension APIs supplied by PSX."""
+
+from psx import (
+    App,
+    Badge,
+    Button,
+    Checkbox,
+    ComponentAdapter,
+    ComponentDefinition,
+    ComponentRegistry,
+    Divider,
+    DuplicateKeyError,
+    Flex,
+    Fragment,
+    Grid,
+    GridItem,
+    HookOrderError,
+    Image,
+    Input,
+    InvalidChildError,
+    Link,
+    MarkupSyntaxError,
+    Native,
+    NativeOwnership,
+    NativeWidget,
+    PLUGIN_ENTRY_POINT_GROUP,
+    PSXError,
+    Plugin,
+    PluginAPI,
+    ProgressBar,
+    Radio,
+    RadioGroup,
+    Ref,
+    RendererAdapterRegistry,
+    RendererCapabilities,
+    RendererCapabilityError,
+    RendererConfigurationError,
+    Scroll,
+    Select,
+    Slider,
+    Spacer,
+    SpinBox,
+    Switch,
+    Text,
+    TextArea,
+    ThreadViolationError,
+    VNode,
+    WebView,
+    builtin_component_registry,
+    component,
+    create_element,
+    load_plugins,
+    native_widget,
+    native_adapter,
+    psx,
+    register_adapter,
+    register_component,
+    renderer_capabilities,
+    use_effect,
+    use_ref,
+    use_state,
+)
+# Pydux is an optional state integration; PSX UI must work without it.
+try:
+    from pydux import MainThreadBridge, Reactive, ReactiveBinding, connect, connect_qyro
+except ImportError as error:
+    if not (error.name == "pydux" or (error.name or "").startswith("pydux.")):
+        raise
+    # The Pydux-specific names are deliberately not exposed when absent.
+    pass
+
+__all__ = [
+    "App", "Badge", "Button", "Checkbox", "ComponentAdapter", "ComponentDefinition",
+    "ComponentRegistry", "Divider", "DuplicateKeyError", "Flex", "Fragment", "Grid",
+    "GridItem", "HookOrderError", "Image", "Input", "InvalidChildError", "Link",
+    "MainThreadBridge", "MarkupSyntaxError", "Native", "NativeOwnership", "NativeWidget",
+    "PLUGIN_ENTRY_POINT_GROUP", "PSXError", "Plugin", "PluginAPI", "ProgressBar",
+    "Radio", "RadioGroup", "Reactive",
+    "ReactiveBinding", "Ref", "RendererAdapterRegistry", "RendererCapabilities",
+    "RendererCapabilityError", "RendererConfigurationError", "Scroll", "Select", "Slider",
+    "Spacer", "SpinBox", "Switch", "Text", "TextArea", "WebView",
+    "ThreadViolationError", "VNode", "builtin_component_registry", "component", "connect",
+    "connect_qyro", "create_element", "load_plugins", "native_widget", "native_adapter", "psx",
+    "register_adapter", "register_component", "renderer_capabilities", "use_effect", "use_ref",
+    "use_state",
+]
+
+# Only publish Pydux integration symbols if the optional dependency is installed.
+_PYDUX_NAMES = ("MainThreadBridge", "Reactive", "ReactiveBinding", "connect", "connect_qyro")
+__all__ = [name for name in __all__ if name not in _PYDUX_NAMES or name in globals()]