# Vela Quick App Development

A developer skill and knowledge base for building **VelaJS quick apps** for Xiaomi watches — specifically the **Xiaomi Watch S4 41mm** (466×466 round AMOLED).

This repo documents everything learned while building working third-party apps for the S4: the working toolchain, the gotchas that caused black-screen crashes, the round-screen layout math, the input-event reality (including the crown question), and the TDD harness used to test `.ux` page logic without a device.

## Contents

- **`SKILL.md`** — the main skill: workflow discipline, project structure, build toolchain, confirmed observations, round-screen layout, TDD technique, input/crown findings, and per-app notes.
- **`references/gitea-publish.md`** — how the built apps are published to self-hosted Gitea (repo creation, `.rpk` release assets, issues).
- **`references/watch-s4-session-log.md`** — chronological debugging log from the S4 dev session.
- **`references/nyan-watch-example.md`** — historical notes from early failed experiments (superseded; kept for reference).

## The apps built with this skill

| Repo | App | Package |
|---|---|---|
| `vela-sundial` | Solar-path dial watch face | `com.ilias.sundial` |
| `vela-snake` | Snake game | `com.ilias.snake` |
| `vela-calculator` | Round-screen calculator | `com.example.hellovela` |

## Key facts (tl;dr)

- **Toolchain:** `aiot-toolkit` (2.0.5), plain-JS `aiot release` with signed RPK — works on the S4. Generic `hap-toolkit` did not.
- **Critical fix:** every `.ux` page must contain `<script>export default {}</script>`; a bare/static page throws `Cannot read properties of undefined (reading 'data')` at launch.
- **Screen:** 466×466 physical → set `config.designWidth` to **466** (not the 480 default) or layout renders ~3% undersized/off-center.
- **Input:** `click`, `longpress`, `touchstart/move/end`, `swipe`, `onBackPress()`. **Crown rotation is NOT exposed** on Vela (the `crownrotationchanged` event is HarmonyOS-only).
- **Template directives:** `for="{{ v in list }}"` (with `tid`), `if`/`elif`/`else`, `show`.

This is a living document — treat it as notes with provenance, not as a spec. Claims that say "unverified" or "not confirmed" mean exactly that.