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.