Metadata-Version: 2.4
Name: neo-play
Version: 0.2.1
Summary: NEOPlay — chợ ứng dụng & launcher cho thiết bị NEO (ARM Linux)
Author: ThingEdu
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: PyQt6>=6.5
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-qt>=4.2; extra == "dev"

# NEOPlay

[Tiếng Việt](README.md) · **English**

App store & launcher for NEO devices (ARM Linux) — by ThingEdu.

> Like Google Play, but built for NEO. One-tap install, offline-first, curated, safe for kids.

## Table of Contents

- [Description](#description)
- [Features](#features)
- [Installation](#installation)
- [Documentation](#documentation)
- [Contributing](#contributing)

## Description

NEOPlay is the app store and launcher for the NEO family of ARM Linux devices (NEO One, NEO AI). The goal: a student opens NEOPlay → sees an app in the "New" shelf → taps *Install* → taps *Open*. Done, in exactly two taps.

Built with PyQt6, it runs on 2GB-RAM machines, works offline-first (installed apps need no network), and ships a catalog curated by hand at ThingEdu so content stays safe for kids.

## Features

- **One-tap install** — a single state button: *Install → Installing → Open*.
- **Offline-first** — the catalog is cached locally; installed apps still open with no network.
- **ThingEdu-curated catalog** — pinned `version`, scripts pointed at git tags, `sha256` verified before running (never a raw `curl | bash`).
- **Multiple install backends** — script-source (NEO App Script Convention v0) as the primary path, plus Flathub for FOSS apps.
- **Launchpad-style UI** — large rounded app icons, a light blue theme, friendly for kids.
- **Classroom mode** — fullscreen autostart + kiosk allowlist, so kids only see approved apps.

## Installation

### On a NEO device

Installs from PyPI; Qt/PyQt6 comes from the apt packages already on the image (no source build):

```bash
# normal install (icon in the menu)
curl -sSL https://raw.githubusercontent.com/ThingEdu/neo-play-catalog/main/scripts/install_on_neo.sh | bash

# boot straight into NEOPlay fullscreen
curl -sSL https://raw.githubusercontent.com/ThingEdu/neo-play-catalog/main/scripts/install_on_neo.sh | bash -s -- --autostart
```

Uninstall: append `-s -- --uninstall` to the command above.

### Classroom mode (recommended)

Install with `--autostart` and enable kiosk in `~/.config/neoplay/config.toml` on the device:

```toml
fullscreen = true

[kiosk]
enabled = true
allowlist = ["neo-code", "gcompris"]
```

The machine boots straight into NEOPlay fullscreen, kids only see approved apps, and the Esc key is disabled (with kiosk off, Esc exits fullscreen normally). Quick test on a dev machine: `NEOPLAY_FULLSCREEN=1 make run`.

### Run on a dev machine

```bash
make venv
make run
```

Pulls the live catalog from the `neo-play-catalog` repo. Needs network + a display (X11/Wayland).

## Documentation

- MVP spec: `docs/superpowers/specs/2026-06-06-neoplay-mvp-design.md`
- UI Launchpad spec: `docs/superpowers/specs/2026-06-06-neoplay-ui-launchpad-design.md`
- Boot/Fullscreen spec: `docs/superpowers/specs/2026-06-06-neoplay-boot-fullscreen-design.md`
- Plan: `docs/superpowers/plans/2026-06-06-neoplay-mvp.md`

## Contributing

### Add an app to the shelf (ThingEdu review process)

1. The app has an install script meeting **NEO App Script Convention v0** (see the spec in `docs/`).
2. Pin the script: `python tools/pin_script.py <url-pointing-at-tag-vX.Y.Z>` → copy the entry into `catalog/catalog.json`.
3. `make check` → open a PR → CI validates → on merge the app appears on every device.

### Development

```bash
make venv          # create .venv + install dev deps
make test          # full unit + UI smoke suite
make check         # validate catalog.json
```

Code contributions: branch off `main`, write tests first (TDD), get `make test` green, and open a PR that clearly describes the change.

### Packaging & release

```bash
make build         # build sdist + wheel
make dist          # clean + build + twine check
make publish       # scripts/publish.sh (TestPyPI → confirm → PyPI)
```
