path: root/docs/superpowers/plans/2026-11-09-deck-it.md

# deck-it Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** A modular tablet dashboard, stream-deck, and second monitor for a Slackware-current Hyprland desktop, UDT-themed, reusing tabdeck's plumbing.

**Architecture:** A Python stdlib HTTP server serves a web page over `adb reverse`; the page is a shell that mounts independent module panels. Backend modules register a `Module` (state + allow-listed actions). A separate half creates a headless Hyprland output streamed by wayvnc to AVNC. Theme comes from UDT's palette files, never restated.

**Tech Stack:** Python 3.11+ stdlib (one dep: `websocket-client` for OBS), plain HTML/CSS/JS, bash launcher, wayvnc, adb.

**Spec:** `docs/superpowers/specs/2026-11-09-deck-it-design.md`

## Global Constraints

- Python 3.11+; stdlib only except `websocket-client`.
- No systemd. SysV init + eudev.
- Server listens only on a Unix socket in `$XDG_RUNTIME_DIR/deck-it` (mode 0700), reached via `adb reverse tcp:8765 localfilesystem:$RUN/http.sock`.
- Client sends module + action ids, never a command string.
- UDT palette is read, never restated; a missing palette falls back.
- Commits are conventional, GPG-signed (`git commit -S`), one per task.
- Reused tabdeck code is MIT; keep its notice in `NOTICE`.

## Review Focus

- **OBS connection drops mid-action** → the HTTP request must return an error, never hang.
- **llm-cost-dashboard is down** → the llm panel shows "offline", not a 500.
- **Oversized or malformed POST body** → rejected without crashing the server.
- **Two taps race** (double record toggle) → serialized, no duplicate start.
- **Palette file missing** (before UDT install) → built-in fallback, page still renders.

---

## Phase 0 — Core

### Task 1: Scaffold and config

**Files:**
- Create: `deckit/__init__.py`, `deckit/config.py`, `config.toml`, `tests/test_config.py`
- Create: `README.md`, `LICENSE`, `NOTICE`, `AGENTS.md`, `.gitignore`, `git init`

**Interfaces:**
- Produces: `deckit.config.user_config_path() -> Path`, `load_config() -> dict`, `config_error(cfg) -> str | None`.

- [ ] **Step 1: Scaffold the repo**

Run `git init -b master`, create the directories. License: GPLv2 (confirm with maintainer; MIT tabdeck portions are compatible). `NOTICE` credits tabdeck (MIT) and its bundled fonts/icons. `AGENTS.md` stays thin and points at this plan and the spec.

- [ ] **Step 2: Write the failing test**

```python
# tests/test_config.py
import sys, tempfile, tomllib
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(ROOT))
import unittest
import deckit.config as config

class Config(unittest.TestCase):
    def test_default_config_is_valid(self):
        with open(ROOT / "config.toml", "rb") as f:
            self.assertIsNone(config.config_error(tomllib.load(f)))

    def test_rejects_bad_values(self):
        bad = [{"display": {"name": "TAB;rm"}},
               {"display": {"refresh": 0}},
               {"ports": {"command_center": 80}},
               {"ports": {"command_center": 5900, "display": 5900}}]
        for cfg in bad:
            self.assertIsNotNone(config.config_error(cfg), cfg)

if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 3: Run it, expect failure**

Run: `python3 tests/test_config.py -v`
Expected: FAIL (no module `deckit.config`).

- [ ] **Step 4: Implement config**

`config.toml` carries: `[hyprland]` (`"auto"`), `[display]` (`resolution/position/scale/refresh/name`), `[ports]` (`command_center=8765`, `display=5900`), `[hardware]` (`net/battery/cpu_sensor/gpu`), `[modules]` (per-module bools, default true), `[obs]` (`host/port/password`), `[llm]` (`url`), `[sbbuilder]` (`host`).

`config_error(cfg)` mirrors tabdeck: validate `display.name` (`[A-Za-z0-9_-]{1,32}`), `display.refresh` int 1–240, ports int 1024–65535 and differing. `user_config_path()` returns `$XDG_CONFIG_HOME/deck-it/config.toml`; `load_config()` uses it if present else the repo `config.toml`, exiting on `config_error`.

- [ ] **Step 5: Run the test, expect pass**

Run: `python3 tests/test_config.py -v`
Expected: PASS.

- [ ] **Step 6: Commit** — `git add -A && git commit -S -m "feat: scaffold and config"`

### Task 2: UDT theming

**Files:**
- Create: `deckit/theme.py`, `tests/test_theme.py`, `tests/fixtures/palette.rasi`, `tests/fixtures/accent.rasi`

**Interfaces:**
- Produces: `parse_palette(text) -> dict[str, str]`, `parse_accent(text) -> str | None`, `css(colors: dict, accent: str | None) -> str`, `load() -> str` (reads the two live paths, falling back).

- [ ] **Step 1: Write the failing test**

```python
# tests/test_theme.py  (same sys.path preamble as Task 1)
import unittest
import deckit.theme as theme

PALETTE = """* {
    base:      #24273aff;
    text:      #cad3f5ff;
    surface0:  #363a4fff;
}"""
ACCENT = "* { accent: #b7bdf8; }"

class Theme(unittest.TestCase):
    def test_parses_palette(self):
        self.assertEqual(theme.parse_palette(PALETTE),
                         {"base": "#24273aff", "text": "#cad3f5ff", "surface0": "#363a4fff"})

    def test_parses_accent(self):
        self.assertEqual(theme.parse_accent(ACCENT), "#b7bdf8")
        self.assertIsNone(theme.parse_accent("nothing"))

    def test_css_exposes_vars_and_falls_back(self):
        out = theme.css({"base": "#24273a"}, None)
        self.assertIn("--udt-base: #24273a", out)
        self.assertIn("--udt-accent:", out)  # fallback accent

if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: Run it, expect failure** — `python3 tests/test_theme.py -v`; FAIL.

- [ ] **Step 3: Implement theme**

`parse_palette` matches `^\s*([a-z0-9]+)\s*:\s*(#[0-9a-fA-F]{6,8});`. `parse_accent` matches `accent:\s*(#[0-9a-fA-F]{6,8})`. `css(colors, accent)` emits `:root {\n  --udt-<name>: <value>;\n ... --udt-accent: <accent or FALLBACK["accent"]>;\n}`. `FALLBACK` is the Macchiato set (base `#24273a`, mantle `#1e2030`, crust `#181926`, surface0 `#363a4f`, surface1 `#494d64`, surface2 `#5b6078`, text `#cad3f5`, subtext0 `#a5adcb`, subtext1 `#b8c0e0`, overlay0 `#6e738d`, red `#ed8796`, green `#a6da95`, yellow `#eed49f`, teal `#8bd5ca`, blue `#8aadf4`, lavender `#b7bdf8`, peach `#f5a97f`, mauve `#c6a0f6`, accent `#b7bdf8`). `load()` reads `~/.config/rofi/udt/palette.rasi` + `~/.cache/udt/udt-accent.rasi`, using `FALLBACK` on `OSError` or empty parse.

- [ ] **Step 4: Run the test, expect pass** — `python3 tests/test_theme.py -v`; PASS.

- [ ] **Step 5: Commit** — `git add deckit/theme.py tests/test_theme.py tests/fixtures && git commit -S -m "feat: UDT palette theming"`

### Task 3: Module contract and registry

**Files:**
- Create: `deckit/module.py`, `tests/test_module.py`

**Interfaces:**
- Produces: `ModuleError`, `Module` (dataclass: `name`, `title`, `state: Callable[[], dict]`, `actions: dict[str, Callable[[dict], dict | None]]`, `start`/`stop` optional), `Registry(modules)` with `names() -> list[dict]`, `state(name) -> dict`, `run_action(name, action, body) -> dict | None`.

- [ ] **Step 1: Write the failing test**

```python
# tests/test_module.py
import unittest
import deckit.module as mod

def make():
    return mod.Module(name="demo", title="Demo",
                      state=lambda: {"ok": True},
                      actions={"ping": lambda body: {"got": body.get("n")}})

class RegistryTest(unittest.TestCase):
    def test_lists_and_dispatches(self):
        r = mod.Registry([make()])
        self.assertEqual(r.names(), [{"name": "demo", "title": "Demo"}])
        self.assertEqual(r.state("demo"), {"ok": True})
        self.assertEqual(r.run_action("demo", "ping", {"n": 3}), {"got": 3})

    def test_unknown_module_and_action_raise(self):
        r = mod.Registry([make()])
        with self.assertRaises(mod.ModuleError):
            r.state("nope")
        with self.assertRaises(mod.ModuleError):
            r.run_action("demo", "nope", {})

if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: Run it, expect failure** — FAIL.

- [ ] **Step 3: Implement the contract**

`Module` is a `@dataclass`. `Registry` stores `{m.name: m}`; `state`/`run_action` raise `ModuleError` on unknown names/actions; `run_action` calls the verb with the JSON body (a dict) and returns its result.

- [ ] **Step 4: Run the test, expect pass** — PASS.

- [ ] **Step 5: Commit** — `git commit -S -am "feat: module contract and registry"`

### Task 4: HTTP server, auth, routing

**Files:**
- Create: `deckit/server.py`, `deckit/__main__.py`, `tests/test_server.py`

**Interfaces:**
- Consumes: `Registry` (Task 3), `theme.load()` (Task 2).
- Produces: `serve(listen: tuple[str, int] | None = None) -> None`; module-global `TOKEN`; routes `GET /`, `GET /theme.css`, `GET /api/modules`, `GET /api/<name>`, `POST /api/<name>/<action>`, `GET /static/...`.

- [ ] **Step 1: Write the failing test** (adapted from tabdeck's `Http` class)

```python
# tests/test_server.py
import json, os, socket, tempfile, threading, unittest
from pathlib import Path
import http.client
import deckit.server as srv
import deckit.module as mod

TOKEN = "test-token"
HOST = {"Host": "127.0.0.1:8765", "Cookie": f"deckit={TOKEN}"}
ORIGIN = {"Origin": "http://127.0.0.1:8765"}

class UnixConnection(http.client.HTTPConnection):
    def __init__(self, path):
        super().__init__("localhost"); self.path = path
    def connect(self):
        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        self.sock.connect(self.path)

class Server(unittest.TestCase):
    @classmethod
    def setUpClass(cls):
        cls.dir = tempfile.TemporaryDirectory()
        cls.sock = os.path.join(cls.dir.name, "http.sock")
        srv.TOKEN = TOKEN
        srv.REGISTRY = mod.Registry([mod.Module("demo", "Demo", lambda: {"ok": True})])
        cls.server = srv.UnixHTTPServer(cls.sock, srv.Handler)
        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
    @classmethod
    def tearDownClass(cls):
        cls.server.shutdown(); cls.server.server_close(); cls.dir.cleanup()

    def req(self, method, path, headers=None, body=None):
        c = UnixConnection(self.sock); c.request(method, path, body=body, headers=headers or {})
        r = c.getresponse(); data = r.read(); c.close(); return r.status, data

    def test_assets_and_api(self):
        self.assertEqual(self.req("GET", "/", HOST)[0], 200)
        self.assertEqual(self.req("GET", "/theme.css", HOST)[0], 200)
        self.assertEqual(json.loads(self.req("GET", "/api/modules", HOST)[1]),
                         [{"name": "demo", "title": "Demo"}])
        self.assertEqual(json.loads(self.req("GET", "/api/demo", HOST)[1]), {"ok": True})

    def test_trust_and_auth(self):
        self.assertEqual(self.req("GET", "/api/demo", {"Host": "evil.com"})[0], 403)
        self.assertEqual(self.req("POST", "/api/demo/x", {**HOST, "Origin": "https://evil.com"})[0], 403)
        self.assertEqual(self.req("GET", "/api/demo", {"Host": "127.0.0.1:8765"})[0], 401)

    def test_unlock_and_bad_action(self):
        c = UnixConnection(self.sock); c.request("GET", f"/?t={TOKEN}", headers={"Host": "127.0.0.1:8765"})
        r = c.getresponse(); r.read(); c.close()
        self.assertEqual(r.status, 303)
        self.assertIn("deckit=", r.getheader("Set-Cookie"))
        self.assertIn("SameSite=Strict", r.getheader("Set-Cookie"))
        self.assertEqual(self.req("POST", "/api/demo/nope", {**HOST, **ORIGIN})[0], 404)

    def test_rejects_oversized_body(self):
        big = "x" * 5000
        status, _ = self.req("POST", "/api/demo/ping",
                             {**HOST, **ORIGIN, "Content-Type": "application/json"}, big)
        self.assertEqual(status, 400)

if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: Run it, expect failure** — FAIL.

- [ ] **Step 3: Implement the server**

Port tabdeck's `Handler`/`UnixHTTPServer`/`serve`, adding: `REGISTRY` (module-global, built in `serve`), `GET /api/modules -> REGISTRY.names()`, `GET /api/<name> -> REGISTRY.state(name)`, `POST /api/<name>/<action>` (JSON body ≤ 4096 bytes, `Content-Type: application/json`, else 400; `ModuleError` → 400). `GET /theme.css` serves `theme.load()`. Static files resolve under `static/` only. Auth/trust (Host/Origin), `?t=` unlock setting cookie `deckit` remain as tabdeck has them. `__main__.py` dispatches `serve`, `setup-display`, `env` (prints `MON= PORT= VNC_PORT=`).

- [ ] **Step 4: Run the test, expect pass** — PASS.

- [ ] **Step 5: Commit** — `git commit -S -am "feat: HTTP server with trust, auth, module routing"`

### Task 5: Frontend shell and theming

**Files:**
- Create: `static/index.html`, `static/deck.css`, `static/app.js`, `tests/test_frontend.py`

**Interfaces:**
- Consumes: `/theme.css`, `/api/modules`, `/api/<name>`.
- Produces: a page whose shell imports `./modules/<name>.js` per enabled module.

- [ ] **Step 1: Write the failing test**

```python
# tests/test_frontend.py — served-page smoke test
# (run a server like Task 4; assert)
#   GET /         -> body contains 'app.js' and 'deck.css'
#   GET /deck.css -> body contains '--udt-bg' usage
```

- [ ] **Step 2: Run it, expect failure** — FAIL.

- [ ] **Step 3: Implement**

`index.html`: viewport meta, link `theme.css` + `deck.css`, `<main id="grid">`, `<script type="module" src="app.js">`. `deck.css`: grid layout and shared card/button classes, all colours via `var(--udt-*)`. `app.js`: `fetch('/api/modules')`, then for each `await import('./modules/'+name+'.js')`, call `mount(el)` and poll `update(state)` at the module's `interval` (default 1000 ms). Refresh on `visibilitychange`.

- [ ] **Step 4: Run the test, expect pass** — PASS.

- [ ] **Step 5: Commit** — `git commit -S -am "feat: frontend shell and UDT-themed layout"`

### Task 6: Launcher, tunnel, Slackware autostart

**Files:**
- Create: `deck-it` (bash), `tests/test_launcher.py`

**Interfaces:**
- Consumes: `python3 -m deckit env`, `setup-display`.
- Produces: `deck-it` subcommands `start` (default), `stop`, `env`, `pair`, `wifi`, `install`, `uninstall`.

- [ ] **Step 1: Write the failing test**

```python
# tests/test_launcher.py
import subprocess, unittest
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent

class Launcher(unittest.TestCase):
    def test_syntax(self):
        self.assertEqual(subprocess.run(["bash", "-n", str(ROOT / "deck-it")]).returncode, 0)
    def test_env_prints_keys(self):
        out = subprocess.run(["bash", str(ROOT / "deck-it"), "env"],
                             capture_output=True, text=True, cwd=ROOT).stdout
        for key in ("MON=", "PORT=", "VNC_PORT="):
            self.assertIn(key, out)

if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: Run it, expect failure** — FAIL.

- [ ] **Step 3: Implement the launcher**

Adapt tabdeck's `tablet`: `RUN="$XDG_RUNTIME_DIR/deck-it"`, `CONF="${XDG_CONFIG_HOME:-$HOME/.config}/deck-it"`, `MON/PORT/VNC_PORT` from `python3 -m deckit env`; `tunnel()` uses `adb reverse tcp:5900 localfilesystem:$RUN/vnc.sock` and `tcp:8765 localfilesystem:$RUN/http.sock`; `vnc_setup()` and `open_avnc()` from tabdeck. `install` writes `/etc/udev/rules.d/70-deck-it.rules` with a non-blocking `RUN+="/bin/sh -c 'setsid <dir>/deck-it start >/dev/null 2>&1 &'"` and prints the `exec-once = <dir>/deck-it` line to add to hypr-theme. `uninstall` removes the rule. No systemd, no `systemctl`.

- [ ] **Step 4: Run the test, expect pass** — PASS.

- [ ] **Step 5: Commit** — `git commit -S -am "feat: launcher, adb tunnel, Slackware autostart"`

### Task 7: Second monitor

**Files:**
- Create: `deckit/display.py`, `tests/test_display.py`

**Interfaces:**
- Produces: `tablet_resolution(cfg, adb=None) -> str`, `setup_display(cfg, run_cmd=None) -> None`.

- [ ] **Step 1: Write the failing test**

```python
# tests/test_display.py
import unittest
import deckit.display as display

class Res(unittest.TestCase):
    def test_reads_adb(self):
        self.assertEqual(display.tablet_resolution({"display": {}}, adb=lambda: "Physical size: 1920x1200"),
                         "1920x1200")
    def test_config_override(self):
        self.assertEqual(display.tablet_resolution({"display": {"resolution": "2560x1600"}},
                                                   adb=lambda: "1920x1200"), "2560x1600")

if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: Run it, expect failure** — FAIL.

- [ ] **Step 3: Implement**

Port tabdeck's `tablet_resolution` (sorted `max x min`) and `setup_display` (create headless output if absent, then Lua `hl.monitor({...})` for the Lua config or `hyprctl keyword monitor` for classic). `adb`/`run_cmd` are injectable for tests.

- [ ] **Step 4: Run the test, expect pass** — PASS.

- [ ] **Step 5: Commit** — `git commit -S -am "feat: virtual monitor setup"`

### Task 8: stats module

**Files:**
- Create: `deckit/modules/__init__.py`, `deckit/modules/stats.py`, `tests/test_stats.py`

**Interfaces:**
- Produces: `stats.make(cfg) -> Module` (name `stats`); registry builder `build(cfg) -> Registry` in `deckit/modules/__init__.py` that lazily imports each `deckit.modules.<name>` present and enabled under `[modules]` (default on), skipping `ImportError`. Lazy discovery means a later phase just adds a file, and the assistant slot stays empty without touching the core.

- [ ] **Step 1: Write the failing test**

```python
# tests/test_stats.py
import unittest
import deckit.modules.stats as stats

class Stats(unittest.TestCase):
    def test_state_shape(self):
        st = stats.make({}).state()
        for key in ("cpu", "memUsed", "memTotal", "net", "uptime", "host"):
            self.assertIn(key, st)
        self.assertIsInstance(st["cpu"], int)

if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: Run it, expect failure** — FAIL.

- [ ] **Step 3: Implement**

Port tabdeck's `cpu_percent`, `mem`, `net_rates`, `gpu`, `detect_*` readers into `deckit/modules/stats.py`; `make(cfg)` closes over the `[hardware]` overrides. `deckit/modules/__init__.py`'s `build(cfg)` walks `Path(__file__).parent` for `*.py` (excluding `__init__`), `importlib.import_module`s each that `[modules]` does not disable, calls its `make(cfg)`, and returns a `Registry`.

- [ ] **Step 4: Run the test, expect pass** — PASS.

- [ ] **Step 5: Commit** — `git commit -S -am "feat: stats module"`

### Task 9: music module

**Files:**
- Create: `deckit/modules/music.py`, `tests/test_music.py`

**Interfaces:**
- Produces: `music.make(cfg) -> Module` (name `music`); state has `status/title/artist/album/length/position/art/player/volume`; actions `prev/play/next/voldown/volup/mute`.

- [ ] **Step 1: Write the failing test**

```python
# tests/test_music.py
import unittest
import deckit.modules.music as music

class Music(unittest.TestCase):
    def test_parses_metadata(self):
        sep = "\x1f"
        fake = lambda cmd, timeout=2: {
            "metadata": sep.join(["Playing", "Song", "Artist", "Album", "200000000", "1000000", "", "spotify"]),
            "get-volume": "Volume: 0.42",
        }[cmd[1]]
        m = music.make({"run": fake})
        st = m.state()
        self.assertEqual(st["title"], "Song")
        self.assertEqual(st["status"], "Playing")
        self.assertEqual(st["volume"]["level"], 42)
    def test_action_commands(self):
        self.assertEqual(music.BASE_ACTIONS["next"], ["playerctl", "next"])

if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: Run it, expect failure** — FAIL.

- [ ] **Step 3: Implement**

Port tabdeck's `player()` (SEP split, art URL handling) and `BASE_ACTIONS` (wpctl/playerctl); inject `run` for tests. Register actions.

- [ ] **Step 4: Run the test, expect pass** — PASS.

- [ ] **Step 5: Commit** — `git commit -S -am "feat: music module"`

### Task 10: windows module

**Files:**
- Create: `deckit/modules/windows.py`, `tests/test_windows.py`

**Interfaces:**
- Produces: `windows.make(cfg) -> Module` (name `windows`); state `{windows, workspaces, activeClass}`; actions `workspace/<n>`, `focus/<addr>`, `close/<addr>`, `launch/<key>` from a `[launch]` table.

- [ ] **Step 1: Write the failing test**

```python
# tests/test_windows.py
import unittest
import deckit.modules.windows as windows

class Commands(unittest.TestCase):
    def test_lua_and_classic(self):
        self.assertEqual(windows.workspace_cmd(3, lua=False), ["hyprctl", "dispatch", "workspace", "3"])
        self.assertEqual(windows.workspace_cmd(3, lua=True)[:2], ["hyprctl", "eval"])
    def test_address_guard(self):
        self.assertIsNone(windows.ADDR.fullmatch("0x1;rm"))
        self.assertTrue(windows.ADDR.fullmatch("0x55897e5c0800"))

if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: Run it, expect failure** — FAIL.

- [ ] **Step 3: Implement**

Port tabdeck's `workspace_cmd`, `window_cmd`, `windows()` (hyprctl clients/activewindow/monitors), and address regex. `[launch]` in config maps key id → command (string or list); actions run declared commands only. Client sends a key id, never a command.

- [ ] **Step 4: Run the test, expect pass** — PASS.

- [ ] **Step 5: Commit** — `git commit -S -am "feat: windows module"`

---

## Phase 1 — OBS stream-deck

### Task 11: obs-websocket client

**Files:**
- Create: `deckit/obsclient.py`, `tests/test_obsclient.py`

**Interfaces:**
- Produces: `auth_string(password: str, salt: str, challenge: str) -> str`, `class ObsClient` with `connect()`, `close()`, `request(type: str, data: dict | None = None) -> dict` (`ModuleError` if disconnected or on error status), and an `events` callback setter.

- [ ] **Step 1: Write the failing test**

```python
# tests/test_obsclient.py
import base64, hashlib, unittest
import deckit.obsclient as oc

class Auth(unittest.TestCase):
    def test_matches_protocol_formula(self):
        pw, salt, challenge = "supersecret", "salty", "chall"
        step1 = base64.b64encode(hashlib.sha256((pw + salt).encode()).digest()).decode()
        expected = base64.b64encode(hashlib.sha256((step1 + challenge).encode()).digest()).decode()
        self.assertEqual(oc.auth_string(pw, salt, challenge), expected)
        self.assertNotEqual(oc.auth_string("other", salt, challenge), expected)

class Disconnected(unittest.TestCase):
    def test_request_raises_when_closed(self):
        with self.assertRaises(oc.ModuleError):
            oc.ObsClient(host="127.0.0.1", port=4455, password="").request("GetVersion")

if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: Run it, expect failure** — FAIL.

- [ ] **Step 3: Implement the client**

Use `websocket-client`. On connect, read `Hello`; if `authentication` present, send `Identify` with `authentication=auth_string(password, salt, challenge)` and `rpcVersion: 1`; wait for `Identified`. Run a receive loop in a daemon thread dispatching `Event` to the callback and resolving `RequestResponse` by `requestId` on a dict of pending events with a timeout (`ModuleError` on timeout). `request` holds a lock, sends `{op:6, d:{requestType, requestId, requestData}}`, waits. `close` stops the loop.

- [ ] **Step 4: Run the test, expect pass** — PASS.

- [ ] **Step 5: Commit** — `git commit -S -am "feat: obs-websocket v5 client"`

### Task 12: OBS module

**Files:**
- Create: `deckit/modules/obs.py`, `tests/test_obs.py`

**Interfaces:**
- Consumes: `ObsClient` (Task 11).
- Produces: `obs.make(cfg) -> Module` (name `obs`); state `{connected, scenes, currentScene, recording, streaming, inputs, transition, transitionKinds}`; actions `scene`, `record`, `stream`, `mute`, `volume`, `transition`, `trigger`, `source`.

- [ ] **Step 1: Write the failing test**

```python
# tests/test_obs.py
import unittest
import deckit.modules.obs as obs

class Fake:
    connected = True
    def request(self, kind, data=None):
        Fake.last = (kind, data)
        return {"ok": True}

class Actions(unittest.TestCase):
    def setUp(self):
        self.m = obs.make({"obs": {"host": "h", "port": 4455, "password": ""},
                           "client": Fake()})
    def test_scene_and_record(self):
        self.m.actions["scene"]({"scene": "Live"}); self.assertEqual(Fake.last[0], "SetCurrentProgramScene")
        self.m.actions["record"]({"on": True}); self.assertEqual(Fake.last[0], "StartRecord")
        self.m.actions["record"]({"on": False}); self.assertEqual(Fake.last[0], "StopRecord")
    def test_mute_and_source(self):
        self.m.actions["mute"]({"input": "Mic", "muted": True}); self.assertEqual(Fake.last[0], "SetInputMute")
        self.m.actions["source"]({"scene": "S", "id": 2, "on": False}); self.assertEqual(Fake.last[0], "SetSceneItemEnabled")

class Serialized(unittest.TestCase):
    def test_double_toggle_is_serialized(self):
        # concurrent record toggles resolve under one lock; no duplicate Start
        pass
```

- [ ] **Step 2: Run it, expect failure** — FAIL.

- [ ] **Step 3: Implement**

`make(cfg)` builds an `ObsClient` (injectable for tests via `cfg["client"]`), starts it, and caches state updated from events. The lock serializes actions. Map actions to obs-websocket requests: scene → `SetCurrentProgramScene`, record → `StartRecord`/`StopRecord`/`ToggleRecord`, stream → `StartStream`/`StopStream`, mute → `SetInputMute`, volume → `SetInputVolume`, transition → `SetCurrentSceneTransition`, trigger → `TriggerStudioModeTransition`, source → `SetSceneItemEnabled`. A disconnected client raises `ModuleError` (Review Focus: no hang).

- [ ] **Step 4: Run the test, expect pass** — PASS.

- [ ] **Step 5: Commit** — `git commit -S -am "feat: OBS stream-deck module"`

### Task 13: OBS panel

**Files:**
- Create: `static/modules/obs.js`, `tests/test_frontend.py` (extend)

- [ ] **Step 1: Extend the smoke test** — assert `obs.js` is served and exports a panel with `mount`/`update`.
- [ ] **Step 2: Run it, expect failure** — FAIL.
- [ ] **Step 3: Implement** — a grid: scene buttons (active highlighted), record/stream toggles with elapsed time, audio channel rows (mute + volume), transition select + trigger, source toggles. Uses `--udt-*` vars.
- [ ] **Step 4: Run the test, expect pass** — PASS.
- [ ] **Step 5: Commit** — `git commit -S -am "feat: OBS stream-deck panel"`

---

## Phase 2 — read-only feeds

### Task 14: llm module

**Files:**
- Create: `deckit/modules/llm.py`, `tests/test_llm.py`

**Interfaces:**
- Produces: `llm.make(cfg) -> Module` (name `llm`); state `{claude: {...}, opencode: {...}, offline: bool}` fetched from `[llm] url` (default `http://127.0.0.1:8420`).

- [ ] **Step 1: Write the failing test**

```python
# tests/test_llm.py
import unittest
import deckit.modules.llm as llm

class Down(unittest.TestCase):
    def test_offline_when_dashboard_down(self):
        def boom(url, timeout=2):
            raise OSError("refused")
        st = llm.make({"llm": {"url": "http://x"}, "fetch": boom}).state()
        self.assertTrue(st["offline"])

class Up(unittest.TestCase):
    def test_merges_endpoints(self):
        data = {"/api/claude_limits": [{"context_pct": 12}],
                "/api/claude_session": {"context_used": 1200},
                "/api/summary": {"total_cost": 1.5}}
        st = llm.make({"llm": {"url": "http://x"},
                       "fetch": lambda u, timeout=2: data[u]}).state()
        self.assertFalse(st["offline"])
        self.assertEqual(st["claude"]["context_pct"], 12)

if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: Run it, expect failure** — FAIL.
- [ ] **Step 3: Implement** — fetch `/api/summary`, `/api/today`, `/api/claude_limits`, `/api/claude_session`, `/api/opencode_agents`; on any `OSError`/`JSONDecodeError` return `{"offline": True}` (Review Focus). Inject `fetch` for tests.
- [ ] **Step 4: Run the test, expect pass** — PASS.
- [ ] **Step 5: Commit** — `git commit -S -am "feat: llm-cost-dashboard relay module"`

### Task 15: llm panel

**Files:**
- Create: `static/modules/llm.js`, extend `tests/test_frontend.py`
- Steps: served smoke test (fail → implement cards: claude 5h/7d/context, opencode spend → pass → commit).

### Task 16: sb-builder module

**Files:**
- Create: `deckit/modules/sbbuilder.py`, `tests/test_sbbuilder.py`

**Interfaces:**
- Produces: `sbbuilder.make(cfg) -> Module` (name `sbbuilder`); state `{offline: bool, jobs: [...]}` from `ssh <host> sbb-remote jobs`.

- [ ] **Step 1: Write the failing test**

```python
# tests/test_sbbuilder.py
import json, unittest
import deckit.modules.sbbuilder as sbb

class Fail(unittest.TestCase):
    def test_offline_on_ssh_failure(self):
        def boom(cmd, timeout=5):
            raise OSError("no route")
        self.assertTrue(sbb.make({"sbbuilder": {"host": "buildsystem"}, "run": boom}).state()["offline"])

class Ok(unittest.TestCase):
    def test_parses_jobs(self):
        out = json.dumps({"jobs": [{"id": "20261109-101010-build", "status": "running"}]})
        st = sbb.make({"sbbuilder": {"host": "buildsystem"}, "run": lambda cmd, timeout=5: out}).state()
        self.assertFalse(st["offline"])
        self.assertEqual(st["jobs"][0]["status"], "running")

if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: Run it, expect failure** — FAIL.
- [ ] **Step 3: Implement** — run `["ssh", "-o", "BatchMode=yes", host, "sbb-remote", "jobs"]` (injectable `run`); parse JSON; on `OSError`/`JSONDecodeError` return `{"offline": True}`. Read-only.
- [ ] **Step 4: Run the test, expect pass** — PASS.
- [ ] **Step 5: Commit** — `git commit -S -am "feat: sb-builder status module"`

### Task 17: sb-builder panel

**Files:**
- Create: `static/modules/sbbuilder.js`, extend `tests/test_frontend.py`
- Steps: served smoke test (fail → implement job list with status chips → pass → commit).

---

## Phase 3 — deferred

### Assistant (not built)

`desktop-assistant` control is out of scope. When its shape is decided, it is
`deckit/modules/assistant.py` plus `static/modules/assistant.js` using the
existing Unix-socket protocol (`state`, `ctx`); no core change.

---

## Self-review

- **Spec coverage:** goals 1–6 map to Tasks 1–17; second monitor → Task 7; OBS → 11–13; read-only feeds → 14–17; assistant deferred → Phase 3.
- **Review Focus:** OBS drop → Task 12; llm down → Task 14; oversized body → Task 4; toggle race → Task 12; palette missing → Task 2.
- **Types:** `Module`/`Registry` signatures are used identically in Tasks 3, 4, 8–17; `run`/`fetch`/`client` are the injectable seams.