AGENTS.md

Operational guide for AI agents working on this repository.

Remote machine

The plugin runs on jozz (vini@jozz). SSH access is pre-configured; no password needed.

ssh vini@jozz "some command"

Deploy cycle

After editing any file under plugin/, commit, push, then run on jozz:

git push && ssh vini@jozz "bash -s" <<'EOF'
git -C "$HOME/skeledance" pull
cp -r "$HOME/skeledance/plugin/." "$HOME/.local/share/plasma/wallpapers/com.vini.dancingcharacter/"
export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
qdbus6 org.kde.plasmashell /PlasmaShell org.kde.PlasmaShell.refreshCurrentShell 2>&1
echo "done"
EOF

The qdbus6 call hot-reloads QML. For HTML/CSS/JS changes the page reloads automatically. If visuals look wrong after deploy, wait a few seconds — WebEngine takes a moment to reinitialize.

Services on jozz

music-light

Reads the current track via playerctl, extracts the dominant album color, and exposes it over HTTP.

# Status
ssh vini@jozz "systemctl --user status music-light.service"

# Restart (needed after updating luz-musica.py)
ssh vini@jozz "systemctl --user restart music-light.service"

# Logs
ssh vini@jozz "journalctl --user -u music-light.service -n 30 --no-pager"

Endpoints (all on 127.0.0.1:8765):

Path	Description
`GET /current`	Returns `{"art_url": "...", "rgb": [r, g, b]}` for the playing track
`GET /art?t=`	Proxies the album art image bytes (use query string for cache-busting)

CORS: Access-Control-Allow-Origin: * is set on all responses. Required because dancer.html is loaded from file://.

Deploying changes to luz-musica.py: scp the file, then restart the service. The repo at ~/music-light on jozz may be behind; always scp directly.

scp /home/ltadeu6/Projetos/Codigo/music-light/luz-musica.py vini@jozz:~/music-light/luz-musica.py
ssh vini@jozz "systemctl --user restart music-light.service"

cava-server

Started automatically by the wallpaper via cava-start.sh on load. Reads CAVA audio bars from stdin and streams them as SSE on 127.0.0.1:5555.

# Check if running
ssh vini@jozz "pgrep -a python | grep cava"

# Restart manually if bars stop animating
ssh vini@jozz "bash ~/.local/share/plasma/wallpapers/com.vini.dancingcharacter/contents/ui/cava-start.sh &"

Debugging JS errors

Add a onJavaScriptConsoleMessage handler to main.qml to capture JS errors to a file:

onJavaScriptConsoleMessage: function(level, message, lineNumber, sourceID) {
    var logDs = Qt.createQmlObject('import org.kde.plasma.plasma5support as P5S; P5S.DataSource { engine: "executable" }', webView)
    logDs.connectSource("echo '[skeledance] " + message.replace(/'/g, '') + " :" + lineNumber + "' >> /tmp/skeledance_console.log")
}

Then read on jozz: ssh vini@jozz "cat /tmp/skeledance_console.log".

Remove the handler after debugging — it creates a new QmlObject per message and causes performance issues.

Known WebEngine constraints

fetch() to http:// works from file:// pages when localContentCanAccessRemoteUrls: true is set in QML.
<img src="http://..."> also works with localContentCanAccessRemoteUrls: true, but the server must include Access-Control-Allow-Origin: *.
CSS background-image: url('http://...') is blocked — use <img> or fetch()+blob URL instead.
img.src with file:/// paths works when localContentCanAccessFileUrls: true is set.

3.4 KiB Raw Blame History