# 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.

```bash
ssh vini@jozz "some command"
```

## Deploy cycle

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

```bash
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.

```bash
# 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.

```bash
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`.

```bash
# 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:

```qml
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.