AsteroidOS Watchface Playground

A web-based IDE for creating, previewing, and exporting AsteroidOS watchfaces — right in your browser.

---

Quick Start

Run with Podman (recommended)

podman build -t watchface-playground .
podman run -p 8080:8080 watchface-playground

Then open http://localhost:8080 in your browser.

Run with Docker

docker build -t watchface-playground .
docker run -p 8080:8080 watchface-playground

Run locally (development)

No build step required — this is vanilla HTML/CSS/JS with ES modules.

# Python 3
python3 -m http.server 8080

# Or Node.js (npx)
npx serve .

Then open http://localhost:8080.

Note: ES modules require a real HTTP server (not file://). CDN resources (ACE editor, JSZip, Google Fonts) need internet access.

---

Features

• Live QML preview — Edit QML and see the watchface render in a circular bezel instantly
• Multi-file editor — Tabbed ACE editor with QML/JS/JSON/SVG/CSS syntax highlighting
• Simulator controls — Adjust time, battery, charging, notifications, alarm, steps, heart rate
• 12h/24h mode — Toggle between time formats with live preview
• ZIP import/export — Import existing watchface archives; export with correct AsteroidOS directory structure
• Font browser — Browse all AsteroidOS-compatible fonts with live preview
• Alignment guides — Crosshair, concentric circle grid, zoom in/out
• Dark/light theme — Persisted across sessions
• Persistent state — Open files restored from localStorage

---

Architecture

index.html          — SPA shell, modals, HTML structure
css/styles.css      — All styles (CSS custom properties, responsive grid)
js/
  app.js            — Main controller, file system, toolbar wiring
  editor.js         — ACE editor wrapper, multi-tab management
  simulator.js      — Simulator state, animation loop, DOM controls
  archive.js        — JSZip import/export
  fonts.js          — Font browser modal, Google Fonts loader
  alignment.js      — Overlay canvas guides, zoom control
examples/
  digital-thoreau-simplify/
    digital-thoreau-simplify.qml   — Example watchface
fonts/
  README.md         — Font documentation
Containerfile       — Multi-stage Podman/Docker build
nginx.conf          — nginx configuration (port 8080, gzip, SPA routing)

---

Creating a Watchface

A watchface is a QML file targeting a 360×360 canvas. Minimal example:

import QtQuick 2.9
import org.asteroid.controls 1.0

Item {
    width: 360; height: 360

    Rectangle { anchors.fill: parent; color: "black" }

    Text {
        anchors.centerIn: parent
        text: wallClock.time.toLocaleTimeString(Qt.locale(), "HH:mm")
        font.family: "Raleway"
        font.pixelSize: 72
        color: "white"
        horizontalAlignment: Text.AlignHCenter
    }
}

Available Context Variables

Variable	Type	Description
wallClock.time	Date	Current time
use12H.value	bool	12-hour format active
batteryChargePercentage.charge	int	Battery 0–100
alarmController.enabled	bool	Alarm set
notifCount	int	Notification count
stepCount	int	Step count
heartRate	int	Heart rate BPM

Qt Date Format Tokens

Token	Meaning
HH	24h hours, zero-padded
hh	12h hours, zero-padded
mm	Minutes, zero-padded
ss	Seconds, zero-padded
AP	AM/PM uppercase
ddd	Short weekday (Mon)
dddd	Full weekday (Monday)
d	Day of month
MMM	Short month (Jan)

---

Deploying to a Watch

1. Click Export ZIP to download the archive
2. The ZIP contains the correct AsteroidOS directory structure:

   watchface-name/usr/share/asteroid-launcher/watchfaces/watchface-name.qml
   

3. Sideload via scp or ADB to your watch
4. See the AsteroidOS watchface guide for full instructions

---

License

This project is licensed under the GNU General Public License v3.0.
See LICENSE and LICENSES.md for details.

All dependencies are GPL-3.0 compatible — see LICENSES.md for the full inventory.