# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## What this is A KDE Plasma 6 wallpaper plugin — a dancing retrowave robot (DANCEBOT-9000) that reacts to currently playing music via `playerctl`. No build step, no dependencies to install; the plugin is deployed directly. Plugin ID: `com.vini.dancingcharacter` Install path: `~/.local/share/plasma/wallpapers/com.vini.dancingcharacter` ## Deploy / test cycle ```bash # Install (or reinstall after edits) ./install.sh # Remove ./uninstall.sh ``` After install, activate via: Right-click desktop → Configure Desktop and Wallpaper → Wallpaper Type → Dancing Character. Plasma hot-reloads QML changes when you reinstall; for HTML/CSS/JS changes you may need to switch away and back to the wallpaper type to force a reload. **Runtime requirement**: `QtWebEngine` QML module must be installed (e.g., `qml6-module-qtwebengine` on Debian/Ubuntu). `playerctl` must be running for the music ticker to show track info. ## Architecture ``` plugin/ metadata.json # KPackage/KPlugin descriptor for Plasma 6 contents/ui/ main.qml # Plasma WallpaperItem — hosts everything dancer.html # Self-contained animation (HTML + CSS + JS) starcatalog.js # Generated star data (Yale BSC) — see tools/build_catalog.py milkyway.jpg # Gaia all-sky map (ESA/Gaia/DPAC, CC BY-SA 3.0 IGO) — see tools/build_skymap.py tools/ build_catalog.py # Regenerates starcatalog.js from the Yale Bright Star Catalog build_skymap.py # Regenerates milkyway.jpg (Hammer -> plate carrée) from ESA's Gaia map ``` ### main.qml — the Plasma host - Declares a `WallpaperItem` with a full-screen `WebEngineView` pointed at `dancer.html`. - A `Plasma5Support.DataSource` with `engine: "executable"` runs `playerctl metadata` every 2 s and injects the result into the page with `webView.runJavaScript("updateMusic(...)")`. - JavaScript is enabled; local file access and local storage are on/off respectively. ### dancer.html — the visual layer Pure HTML/CSS/JS, no external dependencies. All visuals are self-contained: | Layer | Technique | |---|---| | Realistic sky (stars + Milky Way) | `