diff options
Diffstat (limited to 'AGENTS.md')
| -rw-r--r-- | AGENTS.md | 65 |
1 files changed, 53 insertions, 12 deletions
@@ -1,14 +1,55 @@ # AGENTS.md -Guidance for agents working in this repository. - -Read the design (`docs/superpowers/specs/2026-11-09-deck-it-design.md`) and the -implementation plan (`docs/superpowers/plans/2026-11-09-deck-it.md`) first. The -plan is the authority for interfaces and test values. - -- Python 3.11+, standard library only except `websocket-client` for OBS. -- Run the suite with `python3 -m unittest discover -s tests`. -- Each module is `deckit/modules/<name>.py` exporting `make(cfg) -> Module`; the - registry discovers files lazily, so a new module is a new file. -- The server listens only on a Unix socket; `adb reverse` exposes it. -- UDT's palette is read, never restated. +Guidance for AI coding agents working in this repository. + +## What this is + +`deck-it` turns an Android tablet into a second monitor, a stream-deck and an +always-on control surface for a Slackware Hyprland desktop. The PC serves a web +page on a Unix socket and exposes it to the tablet with `adb reverse`; `wayvnc` +streams a headless output to AVNC. Python 3.11+ standard library, plus +`websocket-client` for obs-websocket. Plain HTML/CSS/JS frontend, bash launcher. +Keep the server dependency-free apart from that one package. + +## How it fits together + +- `deckit/server.py` is the stdlib HTTP server: it listens on + `$XDG_RUNTIME_DIR/deck-it/http.sock`, serves `static/`, `/theme.css`, + `/icons/<name>.svg` and `/api/<module>[/<action>]`. +- A module is `deckit/modules/<name>.py` exporting `make(cfg) -> Module`; the + registry discovers files lazily. `state()` is read, `actions` are + allow-listed, and the client sends ids, never commands. +- The page shell (`static/app.js`) builds tabs from each panel's `tab` property, + mounts panels and polls `/api/<module>`. +- `deckit/theme.py` reads UDT's palette (`~/.config/rofi/udt/palette.rasi`) and + `~/.cache/udt/udt-border.lua`; the frontend uses only those CSS variables. +- Launcher icons follow the icon theme Keystone sets (`gsettings + org.gnome.desktop.interface icon-theme`); window icons resolve through the + `.desktop` `Icon`/`StartupWMClass` mapping. +- `deckit/display.py` creates the headless output, centres it under the first + monitor for `position = "auto-below"`, and paints it with the first monitor's + swaybg image. +- The launcher (`deck-it`) handles USB and Wi-Fi (`pair`/`wifi`), the tunnels, + wayvnc and AVNC. `adb mdns` may be unsupported; `deck-it wifi <ip:port>` takes + an explicit address. + +## Conventions + +- New behaviour goes in a module under `deckit/modules/`, not in the server. +- Panels keep their scoped wrapper class (`.music`, `.sbb`, `.llm`, `.windows`) + because the CSS is scoped to it. +- Hyprland Lua: a dispatcher must be wrapped in `hl.dispatch(...)` to execute. + `hyprctl eval` alone only builds the dispatcher object. +- No personal data in code, docs, tests or commits; use placeholders. + +## Testing + + python3 -m unittest discover -s tests + +`node --check` any changed JS file. The real hardware paths (wayvnc, adb, OBS, +the tablet) are manual. + +## Repo facts + +- License: GPLv2 only (`LICENSE`, header in each source file). +- Work directly on master. |