build(hyprlua): package astal-menu's new deps; Super+D opens from top

- Installer: add python-pillow (map tile stitching) and networkmanager (the Network
  quad's nmcli backend) so a fresh install has a working map and network panel.
- Super+D binds explicitly to `menu-toggle.sh toggle top` so it pops in from the top.

The astal-menu config (incl. new backend/nm.py, ui/statsbar.py, etc.) already ships
via the config-updater CONFIGS list and is re-synced by sysupdate.sh; settings live
in XDG_STATE_HOME so updates don't wipe them.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XUWCXM4KhjRkwheaA3X7bP

apply-theme.sh

@@ -39,9 +39,8 @@ USER_FILES=(
     "desktopenvs/hyprland/waybar/style.css|$HOME/.config/waybar/style.css"
     "desktopenvs/hyprland/wofi/style.css|$HOME/.config/wofi/style.css"
     "desktopenvs/hyprland/walker/themes/cyberqueer.css|$HOME/.config/walker/themes/cyberqueer.css"
-    "desktopenvs/hyprland/nwg-dock-hyprland/style.css|$HOME/.config/nwg-dock-hyprland/style.css"
-    "desktopenvs/hyprland/nwg-drawer/drawer.css|$HOME/.config/nwg-drawer/drawer.css"
     "desktopenvs/hyprland/nwg-panel/menu-start.css|$HOME/.config/nwg-panel/menu-start.css"
+    "desktopenvs/hyprlua/astal-menu/style/_colors.css|$HOME/.config/astal-menu/style/_colors.css"
     "desktopenvs/hyprland/vicinae/cyberqueer.toml|$HOME/.config/vicinae/cyberqueer.toml"
     "desktopenvs/hyprland/scripts/onscreenkb.sh|$HOME/.config/scripts/onscreenkb.sh"
     "desktopenvs/hyprland/spicetify/Themes/cli-cyberqueer/color.ini|$HOME/.config/spicetify/Themes/cli-cyberqueer/color.ini"

desktopenvs/hyprlua/astal-menu/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc

desktopenvs/hyprlua/astal-menu/README.md

@@ -0,0 +1,60 @@
+# astal-menu
+
+A touch-friendly GTK4 popup control centre for the hyprlua desktop, replacing
+`nwg-dock` and `nwg-drawer`. Triggered from the EWW top bar (or `Super+D`).
+
+Layout: a **2×2 quad grid** of feature modules over a full-width **application
+drawer**. Any quad can expand to overlay the other three; the drawer can expand to
+the bottom of the screen. A single margined root box letterboxes the menu identically
+in every state.
+
+## Stack
+
+- **Frontend:** Python + PyGObject + **GTK4**, as a `wlr-layer-shell` surface
+  (`gtk4-layer-shell`). Chosen over Lua because lgi/Astal-Lua only support GTK3.
+- **Location map:** a static OSM image stitched from tiles (`backend/staticmap.py`,
+  Pillow). libshumate does not paint tiles in this environment (the official
+  `shumate-demo` shows the same blank map), though tile downloads work — hence the
+  static fallback.
+- **Services:** Astal GObject libraries via introspection — `AstalNetwork`,
+  `AstalBluetooth`, `AstalApps` — plus our own IP-geolocation singleton.
+- **Backends:** Python/Bash scripts in `backend/` (JSON on stdout), run async via
+  `Gio.Subprocess` so nothing blocks the UI.
+- **Theme:** `style/_colors.css` (`@define-color`, generated from
+  `~/Dotfiles/colors.conf` by `apply-theme.sh`) + `style/style.css`.
+
+## Running
+
+`main.py` is single-instance. The autostart launches a hidden resident daemon;
+verbs are forwarded over D-Bus:
+
+    scripts/astal-menu-start.sh          # resident daemon (hidden); sets LD_PRELOAD
+    scripts/menu-toggle.sh               # --toggle
+    scripts/menu-toggle.sh appdrawer     # open with the app drawer expanded
+
+`astal-menu-start.sh` must `LD_PRELOAD` libgtk4-layer-shell (it loads after
+libwayland under PyGObject otherwise).
+
+## Adding a module
+
+1. Create `modules/<name>.py` exposing a top-level `SPEC = ModuleSpec(...)` whose
+   `build(ctx)` returns a `ModuleInstance(compact=…, expanded=…, …)`.
+   - `compact` shows in the 2×2 cell; a distinct `expanded` widget enables the
+     expand button (they must be separate instances — GTK widgets have one parent).
+   - Declare per-feature toggles via `features=[Feature("id", "Label", default)]`;
+     read them with `ctx.feature("id")`. A disabled quad never calls `build()`.
+   - Shared state (network, bluetooth, location) is on `ctx.services`.
+2. Append its `SPEC` to `ALL_SPECS` in `registry.py`. Nothing else changes.
+
+## Files
+
+    main.py          app + single-instance IPC        window.py    layer-shell + letterbox
+    registry.py      module list (extension seam)      settings.py  JSON toggles/order
+    module_base.py   ModuleSpec / ModuleInstance / ModuleContext
+    appservices.py   shared Astal services + location
+    ui/              quadcard, quadgrid, appdrawer
+    modules/         location, weather, bluetooth, network
+    services/        location (geolocation singleton)
+    lib/             ansi (SGR→TextTag), proc (async subprocess)
+    backend/         geolocate.py, weather.sh, network.sh
+    style/           _colors.css, style.css

desktopenvs/hyprlua/astal-menu/appservices.py

@@ -0,0 +1,35 @@
+"""Lazily-built shared services handed to every module via ModuleContext.
+
+Astal's GObject service libraries (AstalNetwork, AstalBluetooth) are consumed here
+through GObject-introspection; modules connect to their `notify::` signals instead
+of polling. The location service is our own singleton.
+"""
+
+from __future__ import annotations
+
+import gi
+
+gi.require_version("AstalNetwork", "0.1")
+gi.require_version("AstalBluetooth", "0.1")
+from gi.repository import AstalBluetooth, AstalNetwork  # noqa: E402
+
+from services.location import get_location_service
+
+
+class Services:
+    def __init__(self) -> None:
+        self._network = None
+        self._bluetooth = None
+        self.location = get_location_service()
+
+    @property
+    def network(self):
+        if self._network is None:
+            self._network = AstalNetwork.Network.get_default()
+        return self._network
+
+    @property
+    def bluetooth(self):
+        if self._bluetooth is None:
+            self._bluetooth = AstalBluetooth.Bluetooth.get_default()
+        return self._bluetooth

desktopenvs/hyprlua/astal-menu/backend/geolocate.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""IP geolocation, cached with a TTL.
+
+Discovers the public IP by tracerouting to 1.1.1.1 and taking the first
+globally-routable hop (the ISP egress nearest the user), then resolves that IP to a
+location through a public geolocation API. Falls back to locating this host's own
+public IP when traceroute is unavailable or yields no public hop.
+
+Prints JSON: {lat, lon, city, country, ip, source}. Diagnostics go to stderr,
+non-zero exit on total failure. Used by services/location.py (and runnable
+standalone for testing).
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+import urllib.request
+from pathlib import Path
+
+CACHE = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "astal-menu" / "location.json"
+TTL = 1800  # seconds
+
+TARGET = "1.1.1.1"
+_IPV4 = re.compile(r"\b(\d{1,3}(?:\.\d{1,3}){3})\b")
+
+# Geolocation providers. Each builds a URL for a given IP; an empty IP asks the
+# provider to resolve the caller's own public address (the self-IP fallback).
+PROVIDERS = [
+    ("ip-api",
+     lambda ip: f"http://ip-api.com/json/{ip}?fields=lat,lon,city,country,query",
+     lambda d: {"lat": d["lat"], "lon": d["lon"], "city": d.get("city"),
+                "country": d.get("country"), "ip": d.get("query")}),
+    ("ipapi.co",
+     lambda ip: f"https://ipapi.co/{ip}/json/" if ip else "https://ipapi.co/json/",
+     lambda d: {"lat": d["latitude"], "lon": d["longitude"], "city": d.get("city"),
+                "country": d.get("country_name"), "ip": d.get("ip")}),
+    ("ipinfo",
+     lambda ip: f"https://ipinfo.io/{ip}/json" if ip else "https://ipinfo.io/json",
+     lambda d: {"lat": float(d["loc"].split(",")[0]), "lon": float(d["loc"].split(",")[1]),
+                "city": d.get("city"), "country": d.get("country"), "ip": d.get("ip")}),
+]
+
+
+def _cached() -> dict | None:
+    try:
+        blob = json.loads(CACHE.read_text())
+        if time.time() - blob.get("_ts", 0) < TTL:
+            return blob["data"]
+    except (FileNotFoundError, json.JSONDecodeError, KeyError):
+        pass
+    return None
+
+
+def _store(data: dict) -> None:
+    CACHE.parent.mkdir(parents=True, exist_ok=True)
+    CACHE.write_text(json.dumps({"_ts": time.time(), "data": data}))
+
+
+def _public_hop_ip() -> str | None:
+    """First globally-routable hop on the path to 1.1.1.1 — i.e. the ISP egress
+    closest to the user. The private/CGNAT hops before it and the anycast target
+    itself (Cloudflare, useless for locating the user) are skipped."""
+    try:
+        proc = subprocess.run(
+            ["traceroute", "-n", "-q", "1", "-w", "2", "-m", "12", TARGET],
+            capture_output=True, text=True, timeout=40,
+        )
+    except (FileNotFoundError, subprocess.SubprocessError) as exc:
+        print(f"traceroute: {exc}", file=sys.stderr)
+        return None
+    for line in proc.stdout.splitlines():
+        if line.lower().startswith("traceroute to"):
+            continue  # header line names the target; not a hop
+        for ip in _IPV4.findall(line):
+            if ip == TARGET:
+                continue
+            try:
+                if ipaddress.ip_address(ip).is_global:
+                    return ip
+            except ValueError:
+                continue
+    return None
+
+
+def _fetch(url: str) -> dict:
+    req = urllib.request.Request(url, headers={"User-Agent": "astal-menu/1.0"})
+    with urllib.request.urlopen(req, timeout=8) as resp:
+        return json.loads(resp.read().decode())
+
+
+def main() -> int:
+    if "--no-cache" not in sys.argv:
+        hit = _cached()
+        if hit:
+            print(json.dumps(hit))
+            return 0
+
+    hop = _public_hop_ip()
+    # Try the traced public hop first, then fall back to our own public IP.
+    candidates = ([hop] if hop else []) + [""]
+    for ip in candidates:
+        for name, url_of, parse in PROVIDERS:
+            try:
+                data = parse(_fetch(url_of(ip)))
+                if data.get("lat") is None or data.get("lon") is None:
+                    raise ValueError("no coordinates")
+                data["source"] = f"{name} via {ip}" if ip else name
+                _store(data)
+                print(json.dumps(data))
+                return 0
+            except Exception as exc:  # noqa: BLE001 — try the next provider/candidate
+                print(f"{name}({ip or 'self'}): {exc}", file=sys.stderr)
+    print("all geolocation attempts failed", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

desktopenvs/hyprlua/astal-menu/backend/network.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Networking backend for the astal-menu Network quad.
+# Each subcommand prints JSON (or plain text for pubip) to stdout. Wi-Fi listing and
+# state come from AstalNetwork in the UI; this covers the rest (ip/routes/ports,
+# public IP, wifi connect via nmcli, and the manual/DHCP switch).
+set -euo pipefail
+
+active_conn() {
+    # First active connection on a real device (wifi/ethernet).
+    nmcli -t -g NAME,TYPE,DEVICE connection show --active 2>/dev/null \
+        | awk -F: '$2 ~ /wireless|ethernet/ {print $1; exit}'
+}
+
+cmd="${1:-}"; shift || true
+case "$cmd" in
+    ip)
+        ip -j addr show 2>/dev/null || echo '[]'
+        ;;
+    routes)
+        ip -j route show 2>/dev/null || echo '[]'
+        ;;
+    ports)
+        # Listening TCP/UDP sockets -> JSON array.
+        ss -tulnH 2>/dev/null | awk '
+            BEGIN { print "["; sep="" }
+            { printf "%s{\"proto\":\"%s\",\"local\":\"%s\"}", sep, $1, $5; sep="," }
+            END { print "]" }'
+        ;;
+    pubip)
+        curl -sf --max-time 8 https://ifconfig.co 2>/dev/null \
+            || curl -sf --max-time 8 https://api.ipify.org 2>/dev/null \
+            || echo "unavailable"
+        ;;
+    wifi-connect)
+        ssid="${1:-}"; pass="${2:-}"
+        if [[ -n "$pass" ]]; then
+            nmcli dev wifi connect "$ssid" password "$pass"
+        else
+            nmcli dev wifi connect "$ssid"
+        fi
+        ;;
+    wifi-disconnect)
+        con="$(active_conn)"
+        [[ -n "$con" ]] && nmcli connection down "$con"
+        ;;
+    set-manual)
+        con="${4:-$(active_conn)}"; addr="${1:-}"; gw="${2:-}"; dns="${3:-}"
+        [[ -z "$con" ]] && { echo "no active connection" >&2; exit 1; }
+        nmcli connection modify "$con" ipv4.method manual \
+            ipv4.addresses "$addr" ipv4.gateway "$gw" ipv4.dns "$dns"
+        nmcli connection up "$con"
+        ;;
+    set-dhcp)
+        con="${1:-$(active_conn)}"
+        [[ -z "$con" ]] && { echo "no active connection" >&2; exit 1; }
+        nmcli connection modify "$con" ipv4.method auto
+        nmcli connection up "$con"
+        ;;
+    active-conn)
+        active_conn
+        ;;
+    *)
+        echo "usage: network.sh {ip|routes|ports|pubip|wifi-connect|wifi-disconnect|set-manual|set-dhcp|active-conn}" >&2
+        exit 2
+        ;;
+esac

desktopenvs/hyprlua/astal-menu/backend/nm.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""NetworkManager backend for the Network quad's expanded settings.
+
+Every subcommand prints JSON to stdout ({"ok": bool, ...} for mutations) and
+diagnostics to stderr. Reads use `nmcli -g` (raw, unescaped single fields) and
+`ip -j`; writes go through `nmcli connection modify/up`, so persistence and polkit
+auth are handled by NetworkManager. Kept as one script so the UI has a single,
+stable contract (see modules/network.py).
+
+  adapters                              list manageable devices + their connection
+  ipconfig <con>                        ipv4/ipv6 method/addresses/gateway/dns
+  set-ip <con> ipv4|ipv6 <method> [addr_cidr] [gateway] [dns_space_sep]
+  routes                                kernel routing table (read-only)
+  vlans                                 configured VLAN connections
+  vlan-add <parent_dev> <id> [name]     create + bring up a VLAN
+  vlan-del <name>                       delete a VLAN connection
+  vlan-up  <name>                       activate a VLAN connection
+  dns                                   effective DNS servers per device
+  set-dns  <con> ipv4|ipv6 <servers_space_sep> <yes|no ignore-auto>
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+
+
+def _run(argv: list[str], timeout: int = 20) -> tuple[bool, str, str]:
+    try:
+        p = subprocess.run(argv, capture_output=True, text=True, timeout=timeout)
+    except (FileNotFoundError, subprocess.SubprocessError) as exc:
+        return False, "", str(exc)
+    return p.returncode == 0, p.stdout, p.stderr
+
+
+def _get(field: str, con: str) -> str:
+    ok, out, _ = _run(["nmcli", "-g", field, "connection", "show", con])
+    return out.strip() if ok else ""
+
+
+def _list(field: str, con: str) -> list[str]:
+    raw = _get(field, con)
+    return [v.strip() for v in raw.replace(",", " ").split() if v.strip()]
+
+
+def _emit(obj) -> int:
+    print(json.dumps(obj))
+    return 0
+
+
+def _ok(ok: bool, err: str = "") -> int:
+    print(json.dumps({"ok": bool(ok), "error": err.strip()}))
+    return 0 if ok else 1
+
+
+# -- reads -----------------------------------------------------------------
+def adapters() -> int:
+    ok, out, _ = _run(["nmcli", "-t", "-f", "DEVICE,TYPE,STATE,CONNECTION", "device"])
+    rows = []
+    if ok:
+        for line in out.splitlines():
+            # DEVICE may contain escaped colons (bt MACs); split from the right on
+            # the three trailing fields we know are colon-free-ish.
+            parts = line.split(":")
+            if len(parts) < 4:
+                continue
+            connection = parts[-1]
+            state = parts[-2]
+            typ = parts[-3]
+            device = ":".join(parts[:-3]).replace("\\:", ":")
+            if typ not in ("ethernet", "wifi"):
+                continue
+            rows.append({"device": device, "type": typ, "state": state,
+                         "connection": connection.replace("\\:", ":")})
+    return _emit(rows)
+
+
+def ipconfig(con: str) -> int:
+    def family(fam: str) -> dict:
+        return {
+            "method": _get(f"{fam}.method", con) or "auto",
+            "addresses": _list(f"{fam}.addresses", con),
+            "gateway": _get(f"{fam}.gateway", con),
+            "dns": _list(f"{fam}.dns", con),
+            "ignore_auto_dns": _get(f"{fam}.ignore-auto-dns", con) == "yes",
+        }
+    return _emit({"connection": con, "ipv4": family("ipv4"), "ipv6": family("ipv6")})
+
+
+def routes() -> int:
+    ok, out, err = _run(["ip", "-j", "route", "show"])
+    if not ok:
+        return _emit([])
+    try:
+        return _emit(json.loads(out))
+    except json.JSONDecodeError:
+        return _emit([])
+
+
+def vlans() -> int:
+    ok, out, _ = _run(["nmcli", "-t", "-f", "NAME,TYPE,DEVICE,ACTIVE", "connection", "show"])
+    rows = []
+    if ok:
+        for line in out.splitlines():
+            parts = line.rsplit(":", 3)
+            if len(parts) < 4 or parts[1] != "vlan":
+                continue
+            name, _typ, device, active = parts
+            rows.append({"name": name, "device": device, "active": active == "yes"})
+    return _emit(rows)
+
+
+def dns() -> int:
+    """Effective DNS servers, per device, from `nmcli device show`."""
+    ok, out, _ = _run(["nmcli", "-t", "-f",
+                       "GENERAL.DEVICE,IP4.DNS,IP6.DNS", "device", "show"])
+    devices: dict[str, dict] = {}
+    cur = None
+    if ok:
+        for line in out.splitlines():
+            if ":" not in line:
+                continue
+            key, _, val = line.partition(":")
+            val = val.strip()
+            if key == "GENERAL.DEVICE":
+                cur = val
+                devices.setdefault(cur, {"device": cur, "servers": []})
+            elif cur and key.startswith(("IP4.DNS", "IP6.DNS")) and val:
+                devices[cur]["servers"].append(val)
+    return _emit([d for d in devices.values() if d["servers"]])
+
+
+# -- writes ----------------------------------------------------------------
+def set_ip(con: str, fam: str, method: str, addr: str = "",
+           gateway: str = "", dns: str = "") -> int:
+    if fam not in ("ipv4", "ipv6"):
+        return _ok(False, "family must be ipv4 or ipv6")
+    args = ["nmcli", "connection", "modify", con, f"{fam}.method", method]
+    if method == "manual":
+        args += [f"{fam}.addresses", addr or ""]
+        args += [f"{fam}.gateway", gateway or ""]
+        if dns:
+            args += [f"{fam}.dns", dns]
+    else:  # auto: clear any manual leftovers so DHCP is clean
+        args += [f"{fam}.addresses", "", f"{fam}.gateway", ""]
+    ok, _, err = _run(args)
+    if ok:
+        ok, _, err = _run(["nmcli", "connection", "up", con])
+    return _ok(ok, err)
+
+
+def set_dns(con: str, fam: str, servers: str, ignore_auto: str) -> int:
+    if fam not in ("ipv4", "ipv6"):
+        return _ok(False, "family must be ipv4 or ipv6")
+    ok, _, err = _run(["nmcli", "connection", "modify", con,
+                       f"{fam}.dns", servers,
+                       f"{fam}.ignore-auto-dns", "yes" if ignore_auto == "yes" else "no"])
+    if ok:
+        ok, _, err = _run(["nmcli", "connection", "up", con])
+    return _ok(ok, err)
+
+
+def vlan_add(parent: str, vid: str, name: str = "") -> int:
+    name = name or f"vlan{vid}"
+    ok, _, err = _run(["nmcli", "connection", "add", "type", "vlan",
+                       "con-name", name, "dev", parent, "id", str(vid)])
+    if ok:
+        ok, _, err = _run(["nmcli", "connection", "up", name])
+    return _ok(ok, err)
+
+
+def vlan_del(name: str) -> int:
+    ok, _, err = _run(["nmcli", "connection", "delete", name])
+    return _ok(ok, err)
+
+
+def vlan_up(name: str) -> int:
+    ok, _, err = _run(["nmcli", "connection", "up", name])
+    return _ok(ok, err)
+
+
+def main(argv: list[str]) -> int:
+    if not argv:
+        print("no subcommand", file=sys.stderr)
+        return 2
+    cmd, args = argv[0], argv[1:]
+    table = {
+        "adapters": lambda: adapters(),
+        "ipconfig": lambda: ipconfig(args[0]),
+        "set-ip": lambda: set_ip(*args),
+        "routes": lambda: routes(),
+        "vlans": lambda: vlans(),
+        "vlan-add": lambda: vlan_add(*args),
+        "vlan-del": lambda: vlan_del(args[0]),
+        "vlan-up": lambda: vlan_up(args[0]),
+        "dns": lambda: dns(),
+        "set-dns": lambda: set_dns(*args),
+    }
+    fn = table.get(cmd)
+    if fn is None:
+        print(f"unknown subcommand: {cmd}", file=sys.stderr)
+        return 2
+    try:
+        return fn()
+    except TypeError as exc:
+        print(f"bad arguments for {cmd}: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

desktopenvs/hyprlua/astal-menu/backend/staticmap.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Render a static slippy-map image centred on a coordinate, with a marker.
+
+Used by the Location quad because libshumate does not render tiles in this
+environment (the official shumate-demo shows the same blank map — a library/GTK
+render bug), while plain tile downloads work fine. Stitches raster tiles into one
+PNG with Pillow and caches them. The quad re-renders this at a new centre to pan.
+
+  staticmap.py <center_lat> <center_lon> <zoom> <w> <h> <out> \
+               [style] [marker_lat] [marker_lon]
+
+  style: dark (default, CartoDB dark_matter) | satellite (Esri) | standard (OSM)
+  marker_*: where to draw the location pin; defaults to the centre. When the centre
+            is panned away, the pin clamps to the nearest edge so it stays visible.
+"""
+
+from __future__ import annotations
+
+import io
+import math
+import os
+import sys
+import urllib.request
+from pathlib import Path
+
+from PIL import Image, ImageDraw
+
+TILE = 256
+CACHE = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "astal-menu" / "tiles"
+UA = "astal-menu/1.0 (personal dotfiles)"
+BG = (26, 26, 26)
+ACCENT = (228, 0, 70)
+
+STYLES = {
+    "standard":  "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
+    "dark":      "https://a.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png",
+    "satellite": "https://server.arcgisonline.com/ArcGIS/rest/services/"
+                 "World_Imagery/MapServer/tile/{z}/{y}/{x}",
+}
+
+
+def _center_px(lat: float, lon: float, zoom: int) -> tuple[float, float]:
+    n = 2 ** zoom
+    lat_r = math.radians(lat)
+    x = (lon + 180.0) / 360.0 * n
+    y = (1.0 - math.asinh(math.tan(lat_r)) / math.pi) / 2.0 * n
+    return x * TILE, y * TILE
+
+
+def _tile(z: int, x: int, y: int, style: str) -> Image.Image | None:
+    CACHE.mkdir(parents=True, exist_ok=True)
+    fp = CACHE / f"{style}_{z}_{x}_{y}.png"
+    if fp.exists():
+        try:
+            return Image.open(fp).convert("RGB")
+        except Exception:
+            pass
+    url = STYLES[style].format(z=z, x=x, y=y)
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": UA})
+        data = urllib.request.urlopen(req, timeout=8).read()
+    except Exception as exc:
+        print(f"tile {style} {z}/{x}/{y}: {exc}", file=sys.stderr)
+        return None
+    img = Image.open(io.BytesIO(data)).convert("RGB")
+    img.save(fp)   # normalise to PNG in the cache (satellite is served as JPEG)
+    return img
+
+
+def render(lat: float, lon: float, zoom: int, w: int, h: int, out: str,
+           style: str = "dark", marker: tuple[float, float] | None = None) -> None:
+    if style not in STYLES:
+        style = "dark"
+    n = 2 ** zoom
+    cx, cy = _center_px(lat, lon, zoom)
+    left, top = cx - w / 2, cy - h / 2
+    img = Image.new("RGB", (w, h), BG)
+    x0, x1 = int(left // TILE), int((left + w) // TILE)
+    y0, y1 = int(top // TILE), int((top + h) // TILE)
+    for tx in range(x0, x1 + 1):
+        for ty in range(y0, y1 + 1):
+            if ty < 0 or ty >= n:
+                continue
+            tile = _tile(zoom, tx % n, ty, style)
+            if tile is None:
+                continue
+            img.paste(tile, (int(tx * TILE - left), int(ty * TILE - top)))
+
+    # marker at the real location (defaults to centre); clamp to the edge so it stays
+    # on-screen when the view is panned away from it.
+    mlat, mlon = marker if marker else (lat, lon)
+    mwx, mwy = _center_px(mlat, mlon, zoom)
+    r = 8
+    mx = max(r, min(w - r, mwx - left))
+    my = max(r, min(h - r, mwy - top))
+    d = ImageDraw.Draw(img)
+    d.ellipse([mx - r, my - r, mx + r, my + r], fill=ACCENT, outline=(255, 255, 255), width=2)
+
+    Path(out).parent.mkdir(parents=True, exist_ok=True)
+    img.save(out)
+
+
+if __name__ == "__main__":
+    a = sys.argv
+    style = a[7] if len(a) > 7 else "dark"
+    marker = (float(a[8]), float(a[9])) if len(a) > 9 else None
+    render(float(a[1]), float(a[2]), int(a[3]), int(a[4]), int(a[5]), a[6], style, marker)
+    print(a[6])

desktopenvs/hyprlua/astal-menu/backend/weather.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Weather backend: wttr.in with its native ANSI art (curl UA gets terminal colours).
+# Args: $1 = location (may be empty -> wttr.in geolocates the caller), $2 = query opts.
+# Prints the wttr.in body (ANSI or plain, per opts) to stdout.
+set -uo pipefail
+
+loc="${1:-}"
+# Note: ${2-0}, not ${2:-0} — the expanded view passes an *empty* opts to request
+# wttr.in's default 3-day forecast, and :- would wrongly rewrite that empty string
+# to "0" (current conditions only). Default to "0" only when no opts arg is given.
+opts="${2-0}"
+
+# URL-encode spaces in a city name.
+loc="${loc// /+}"
+
+url="https://wttr.in/${loc}?${opts}"
+# -A curl makes wttr.in return terminal (ANSI) output regardless of the real UA.
+curl -sf -A curl --max-time 10 "$url"

desktopenvs/hyprlua/astal-menu/lib/ansi.py

@@ -0,0 +1,138 @@
+"""Render ANSI/SGR-coloured terminal text (e.g. wttr.in) into a Gtk.TextView.
+
+wttr.in returns real terminal escape sequences when curled. We parse the SGR
+subset it uses (basic 8/16 colours, xterm-256, truecolor, bold, reset) and emit
+Gtk.TextTags so the CLI art keeps its colours and block-glyph alignment. This is
+deliberately reusable by any future "show me some CLI art" widget.
+"""
+
+from __future__ import annotations
+
+import re
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+from gi.repository import Gdk, Gtk  # noqa: E402
+
+_SGR = re.compile(r"\x1b\[([0-9;]*)m")
+
+# xterm 16-colour base palette (approx, tuned to the CyberQueer dark background).
+_BASE16 = [
+    (0x00, 0x00, 0x00), (0xCC, 0x24, 0x24), (0x33, 0xCC, 0x33), (0xCC, 0xCC, 0x33),
+    (0x33, 0x66, 0xCC), (0xCC, 0x33, 0xCC), (0x33, 0xCC, 0xCC), (0xD6, 0xAB, 0xAB),
+    (0x66, 0x66, 0x66), (0xF5, 0x05, 0x05), (0x55, 0xFF, 0x55), (0xFF, 0xFF, 0x55),
+    (0x55, 0x88, 0xFF), (0xE4, 0x00, 0x46), (0x55, 0xFF, 0xFF), (0xFF, 0xFF, 0xFF),
+]
+
+
+def _xterm256(n: int) -> tuple[int, int, int]:
+    if n < 16:
+        return _BASE16[n]
+    if n < 232:  # 6x6x6 colour cube
+        n -= 16
+        r, g, b = n // 36, (n // 6) % 6, n % 6
+        conv = lambda c: 55 + c * 40 if c else 0
+        return conv(r), conv(g), conv(b)
+    v = 8 + (n - 232) * 10  # grayscale ramp
+    return v, v, v
+
+
+def _rgba(rgb: tuple[int, int, int]) -> Gdk.RGBA:
+    c = Gdk.RGBA()
+    c.red, c.green, c.blue, c.alpha = rgb[0] / 255, rgb[1] / 255, rgb[2] / 255, 1.0
+    return c
+
+
+class AnsiRenderer:
+    """Owns a TextView and repaints it from ANSI text. Tags are cached by state."""
+
+    def __init__(self) -> None:
+        self.view = Gtk.TextView(
+            editable=False, cursor_visible=False, monospace=True,
+            wrap_mode=Gtk.WrapMode.NONE,
+        )
+        self.view.add_css_class("ansi-view")
+        self.buffer = self.view.get_buffer()
+        self._tag_cache: dict[tuple, Gtk.TextTag] = {}
+
+    def _tag(self, fg, bg, bold) -> Gtk.TextTag | None:
+        if fg is None and bg is None and not bold:
+            return None
+        key = (fg, bg, bold)
+        tag = self._tag_cache.get(key)
+        if tag is None:
+            tag = self.buffer.create_tag()
+            if fg is not None:
+                tag.set_property("foreground-rgba", _rgba(fg))
+            if bg is not None:
+                tag.set_property("background-rgba", _rgba(bg))
+            if bold:
+                tag.set_property("weight", 700)
+            self._tag_cache[key] = tag
+        return tag
+
+    def set_text(self, text: str) -> None:
+        self.buffer.set_text("", 0)
+        fg = bg = None
+        bold = False
+        pos = 0
+        for m in _SGR.finditer(text):
+            chunk = text[pos:m.start()]
+            if chunk:
+                self._insert(chunk, fg, bg, bold)
+            fg, bg, bold = self._apply(m.group(1), fg, bg, bold)
+            pos = m.end()
+        tail = text[pos:]
+        if tail:
+            self._insert(tail, fg, bg, bold)
+
+    def _insert(self, chunk, fg, bg, bold) -> None:
+        end = self.buffer.get_end_iter()
+        tag = self._tag(fg, bg, bold)
+        if tag is None:
+            self.buffer.insert(end, chunk)
+        else:
+            self.buffer.insert_with_tags(end, chunk, tag)
+
+    @staticmethod
+    def _apply(params: str, fg, bg, bold):
+        codes = [int(x) if x else 0 for x in params.split(";")] if params else [0]
+        i = 0
+        while i < len(codes):
+            c = codes[i]
+            if c == 0:
+                fg = bg = None
+                bold = False
+            elif c == 1:
+                bold = True
+            elif c == 22:
+                bold = False
+            elif c == 39:
+                fg = None
+            elif c == 49:
+                bg = None
+            elif 30 <= c <= 37:
+                fg = _BASE16[c - 30]
+            elif 90 <= c <= 97:
+                fg = _BASE16[c - 90 + 8]
+            elif 40 <= c <= 47:
+                bg = _BASE16[c - 40]
+            elif 100 <= c <= 107:
+                bg = _BASE16[c - 100 + 8]
+            elif c in (38, 48):
+                target = "fg" if c == 38 else "bg"
+                if i + 1 < len(codes) and codes[i + 1] == 5:
+                    val = _xterm256(codes[i + 2]) if i + 2 < len(codes) else None
+                    i += 2
+                elif i + 1 < len(codes) and codes[i + 1] == 2:
+                    val = tuple(codes[i + 2:i + 5]) if i + 4 < len(codes) else None
+                    i += 4
+                else:
+                    val = None
+                if target == "fg":
+                    fg = val
+                else:
+                    bg = val
+            i += 1
+        return fg, bg, bold

desktopenvs/hyprlua/astal-menu/lib/border.py

@@ -0,0 +1,64 @@
+"""Draw a rounded border around any widget with a Cairo DrawingArea overlay.
+
+This GTK build's renderer does not paint CSS border/background nodes on plain
+container widgets (Box/Frame) — only on buttons/entries — but it renders Cairo
+draw funcs and textures fine (the map image proves it). So module 'borders' are
+drawn explicitly here instead of via CSS.
+"""
+
+from __future__ import annotations
+
+import math
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+from gi.repository import Gtk  # noqa: E402
+
+# CyberQueer accent (matches @accent / COLOR_HIGHLIGHT in colors.conf).
+ACCENT = (0xE4 / 255, 0x00 / 255, 0x46 / 255)
+BG = (0x1A / 255, 0x1A / 255, 0x1A / 255)
+
+
+def _rounded_rect(cr, x, y, w, h, r) -> None:
+    r = min(r, w / 2, h / 2)
+    cr.new_sub_path()
+    cr.arc(x + w - r, y + r, r, -math.pi / 2, 0)
+    cr.arc(x + w - r, y + h - r, r, 0, math.pi / 2)
+    cr.arc(x + r, y + h - r, r, math.pi / 2, math.pi)
+    cr.arc(x + r, y + r, r, math.pi, 3 * math.pi / 2)
+    cr.close_path()
+
+
+def _make_draw(border: int, radius: int, color, fill_bg: bool):
+    def draw(_area, cr, w, h, *_a) -> None:
+        inset = border / 2
+        _rounded_rect(cr, inset, inset, w - border, h - border, radius)
+        if fill_bg:
+            cr.set_source_rgb(*BG)
+            cr.fill_preserve()
+        cr.set_source_rgb(*color)
+        cr.set_line_width(border)
+        cr.stroke()
+    return draw
+
+
+def bordered(child: Gtk.Widget, border: int = 3, radius: int = 16,
+             color=ACCENT, fill_bg: bool = False) -> Gtk.Overlay:
+    """Wrap child in an overlay whose background is a drawn rounded border.
+
+    The DrawingArea is the overlay's main child (drawn first, behind); the content
+    is an overlay child on top and drives the size. A small margin keeps the content
+    clear of the drawn border ring.
+    """
+    overlay = Gtk.Overlay()
+    area = Gtk.DrawingArea()
+    area.set_draw_func(_make_draw(border, radius, color, fill_bg))
+    overlay.set_child(area)               # background: the border ring
+    child.set_margin_start(border + 4)
+    child.set_margin_end(border + 4)
+    child.set_margin_top(border + 4)
+    child.set_margin_bottom(border + 4)
+    overlay.add_overlay(child)            # content on top
+    overlay.set_measure_overlay(child, True)  # size the overlay to the content
+    return overlay

desktopenvs/hyprlua/astal-menu/lib/proc.py

@@ -0,0 +1,100 @@
+"""Subprocess helpers built on Gio so nothing blocks the GTK main loop.
+
+The whole backend contract (see backend/*.sh, backend/geolocate.py) is: a command
+prints JSON (or plain text) to stdout, diagnostics to stderr, non-zero exit on
+failure. These helpers run such commands asynchronously and hand the parsed result
+back on the main thread.
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+from typing import Callable, Sequence
+
+import gi
+
+gi.require_version("Gio", "2.0")
+from gi.repository import Gio, GLib  # noqa: E402
+
+
+def _as_argv(cmd: Sequence[str] | str) -> list[str]:
+    return shlex.split(cmd) if isinstance(cmd, str) else list(cmd)
+
+
+def run_text(cmd: Sequence[str] | str, cb: Callable[[bool, str, str], None]) -> None:
+    """Run cmd, call cb(ok, stdout, stderr) on the main thread when done."""
+    try:
+        proc = Gio.Subprocess.new(
+            _as_argv(cmd),
+            Gio.SubprocessFlags.STDOUT_PIPE | Gio.SubprocessFlags.STDERR_PIPE,
+        )
+    except GLib.Error as err:
+        GLib.idle_add(cb, False, "", str(err))
+        return
+
+    def _done(p: Gio.Subprocess, res: Gio.AsyncResult) -> None:
+        try:
+            _, out, errout = p.communicate_utf8_finish(res)
+        except GLib.Error as err:
+            cb(False, "", str(err))
+            return
+        cb(p.get_successful(), out or "", errout or "")
+
+    proc.communicate_utf8_async(None, None, _done)
+
+
+def run_json(cmd: Sequence[str] | str, cb: Callable[[bool, object], None]) -> None:
+    """Run cmd expecting JSON on stdout; call cb(ok, data)."""
+
+    def _text(ok: bool, out: str, err: str) -> None:
+        if not ok or not out.strip():
+            cb(False, err.strip() or "no output")
+            return
+        try:
+            cb(True, json.loads(out))
+        except json.JSONDecodeError as exc:
+            cb(False, f"bad json: {exc}")
+
+    run_text(cmd, _text)
+
+
+class Poller:
+    """Repeatedly run a command (or callable) on an interval, main-thread callback.
+
+    Used for lightweight state that has no change signal (open ports, public IP,
+    weather refresh). Modules that back onto an Astal GObject service should prefer
+    connecting to that service's `notify::` signals instead of polling.
+    """
+
+    def __init__(self, interval_s: float, cmd: Sequence[str] | str, cb, json_mode: bool = False):
+        self.interval_s = interval_s
+        self.cmd = cmd
+        self.cb = cb
+        self.json_mode = json_mode
+        self._source_id: int | None = None
+        self._stopped = False
+
+    def start(self) -> "Poller":
+        self._stopped = False
+        self._tick()
+        self._source_id = GLib.timeout_add_seconds(int(self.interval_s), self._tick)
+        return self
+
+    def _tick(self) -> bool:
+        if self._stopped:
+            return GLib.SOURCE_REMOVE
+        if self.json_mode:
+            run_json(self.cmd, lambda ok, data: None if self._stopped else self.cb(ok, data))
+        else:
+            run_text(self.cmd, lambda ok, out, err: None if self._stopped else self.cb(ok, out, err))
+        return GLib.SOURCE_CONTINUE
+
+    def refresh_now(self) -> None:
+        self._tick()
+
+    def stop(self) -> None:
+        self._stopped = True
+        if self._source_id is not None:
+            GLib.source_remove(self._source_id)
+            self._source_id = None

desktopenvs/hyprlua/astal-menu/main.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""astal-menu — a touch-friendly GTK4 popup control centre (Location, Weather,
+Bluetooth, Network) plus an application drawer, replacing nwg-dock/nwg-drawer.
+
+Single-instance: the first launch builds the (hidden) window and holds. Later
+invocations forward their arguments to it over D-Bus, so `main.py --toggle`
+toggles the running instance without spawning a new process.
+
+  main.py            run the resident instance (stays hidden until toggled)
+  main.py --toggle   toggle visibility
+  main.py --show     show     |  --hide  hide  |  --appdrawer  show with drawer open
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# astal-menu-start.sh LD_PRELOADs libgtk4-layer-shell so it loads before
+# libwayland-client (a load-ordering requirement of the layer-shell library). That
+# only matters at *this* process's exec: the library is already resident now, so the
+# variable is never read again. Drop it here so the GUI apps we launch via
+# AstalApps.launch() (and the backend subprocesses) don't inherit it — Firefox, for
+# one, aborts at startup with libgtk4-layer-shell preloaded.
+os.environ.pop("LD_PRELOAD", None)
+
+# Make sibling modules importable no matter the CWD.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import gi  # noqa: E402
+
+gi.require_version("Gtk", "4.0")
+from gi.repository import Gio, GLib, Gtk  # noqa: E402
+
+import theme  # noqa: E402
+from appservices import Services  # noqa: E402
+from paths import APP_ID, ensure_dirs  # noqa: E402
+from settings import Settings  # noqa: E402
+from window import MenuWindow  # noqa: E402
+
+
+class AstalMenuApp(Gtk.Application):
+    def __init__(self) -> None:
+        super().__init__(application_id=APP_ID,
+                         flags=Gio.ApplicationFlags.HANDLES_COMMAND_LINE)
+        self.window: MenuWindow | None = None
+
+    def do_startup(self) -> None:
+        Gtk.Application.do_startup(self)
+        ensure_dirs()
+        theme.load_css()
+        settings = Settings()
+        services = Services()
+        self.window = MenuWindow(self, settings, services)
+        self.hold()  # stay alive with no visible window
+
+    def do_command_line(self, cmdline: Gio.ApplicationCommandLine) -> int:
+        args = list(cmdline.get_arguments()[1:])
+        # Optional "--side top|bottom|left|right": the menu slides in from and pins to
+        # that monitor edge. Applied before the verb so the surface maps animated.
+        side = None
+        if "--side" in args:
+            i = args.index("--side")
+            if i + 1 < len(args):
+                side = args[i + 1]
+            del args[i:i + 2]
+        # No args = start (or keep) the resident instance hidden. Only explicit
+        # verbs change visibility, so the autostart launch never pops the menu.
+        action = args[0] if args else "--daemon"
+        if self.window is None:
+            return 0
+        if side:
+            self.window.set_side(side)
+        if action == "--show":
+            self.window.show_menu()
+        elif action == "--hide":
+            self.window.hide_menu()
+        elif action == "--appdrawer":
+            self.window.show_menu(focus_appdrawer=True)
+        elif action == "--toggle":
+            self.window.toggle()
+        # --daemon and anything else: no-op (stay as-is)
+        return 0
+
+    def do_activate(self) -> None:
+        # Resident instance: nothing to do on plain activate.
+        pass
+
+
+def main() -> int:
+    GLib.set_prgname("astal-menu")
+    return AstalMenuApp().run(sys.argv)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

desktopenvs/hyprlua/astal-menu/module_base.py

@@ -0,0 +1,73 @@
+"""The contract every quad module implements.
+
+Adding a module = drop a file in modules/ that defines a top-level `SPEC`
+(a ModuleSpec), then append its import to registry.py. Nothing else needs to
+change: enable/disable, feature toggles, the card chrome, and the expand/collapse
+plumbing are all provided generically.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+from gi.repository import Gtk  # noqa: E402
+
+
+@dataclass
+class Feature:
+    """A per-quad on/off switch surfaced in the card's settings popover."""
+    id: str
+    label: str
+    default: bool = True
+
+
+@dataclass
+class ModuleInstance:
+    """What a module's build() returns."""
+    compact: Gtk.Widget                       # shown in the 2x2 cell
+    expanded: Optional[Gtk.Widget] = None     # shown when the quad is expanded
+    scroll_expanded: bool = True              # wrap the expanded view in a scroller
+    on_show: Optional[Callable[[], None]] = None
+    on_hide: Optional[Callable[[], None]] = None
+    destroy: Optional[Callable[[], None]] = None
+
+
+@dataclass
+class ModuleSpec:
+    id: str
+    title: str
+    icon: str                                 # nerd-font glyph
+    build: Callable[["ModuleContext"], ModuleInstance]
+    default_enabled: bool = True
+    features: list[Feature] = field(default_factory=list)
+
+
+class ModuleContext:
+    """Handed to a module's build(). Scopes settings to the module and exposes the
+    expand/collapse requests so a module can drive the layout without knowing it."""
+
+    def __init__(self, spec: ModuleSpec, settings, services,
+                 request_expand: Callable[[str], None],
+                 request_collapse: Callable[[], None]):
+        self.spec = spec
+        self.settings = settings
+        self.services = services
+        self._request_expand = request_expand
+        self._request_collapse = request_collapse
+
+    def expand(self) -> None:
+        self._request_expand(self.spec.id)
+
+    def collapse(self) -> None:
+        self._request_collapse()
+
+    # feature toggles, scoped to this module
+    def feature(self, feature_id: str, default: bool = True) -> bool:
+        return self.settings.feature(self.spec.id, feature_id, default)
+
+    def on_settings_changed(self, cb: Callable[[], None]) -> None:
+        self.settings.subscribe(cb)

desktopenvs/hyprlua/astal-menu/modules/bluetooth.py

@@ -0,0 +1,292 @@
+"""Bluetooth quad: powered by AstalBluetooth (bluez wrapper).
+
+Discovery, connect, disconnect and a local connection history (bluez keeps none, so
+we record successful connects in ~/.cache/astal-menu/bt-history.json). 'discovery'
+and 'history' are per-quad feature toggles.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+from gi.repository import GLib, Gtk  # noqa: E402
+
+from lib.proc import run_text
+from module_base import Feature, ModuleContext, ModuleInstance, ModuleSpec
+from paths import CACHE_DIR
+
+_HISTORY = CACHE_DIR / "bt-history.json"
+
+
+def _load_history() -> list[dict]:
+    try:
+        return json.loads(_HISTORY.read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        return []
+
+
+def _record_history(address: str, name: str) -> None:
+    hist = [h for h in _load_history() if h.get("address") != address]
+    hist.insert(0, {"address": address, "name": name, "ts": int(time.time())})
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    _HISTORY.write_text(json.dumps(hist[:50], indent=2))
+
+
+class _BluetoothView(Gtk.Box):
+    def __init__(self, ctx: ModuleContext, full: bool):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL, spacing=8)
+        self.add_css_class("bt-view")
+        self.ctx = ctx
+        self.full = full
+        self.bt = ctx.services.bluetooth
+        self._recorded: set[str] = set()
+        self._hooked: set[str] = set()    # devices whose state signals we've wired
+        self._pending: set[str] = set()   # addresses with an in-flight connect
+        self._failed: set[str] = set()    # addresses whose last connect failed
+
+        self.append(self._build_header())
+
+        self._list = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=4)
+        self._list.add_css_class("bt-list")
+        if full:
+            scroller = Gtk.ScrolledWindow(vexpand=True,
+                                          hscrollbar_policy=Gtk.PolicyType.NEVER)
+            scroller.set_child(self._list)
+            self.append(scroller)
+        else:
+            self.append(self._list)
+
+        if self.bt is not None:
+            self.bt.connect("notify::devices", lambda *_: self._refresh())
+            self.bt.connect("notify::is-powered", lambda *_: self._refresh())
+        self._refresh()
+
+    def _adapter(self):
+        return self.bt.get_adapter() if self.bt else None
+
+    def _build_header(self) -> Gtk.Widget:
+        header = Gtk.CenterBox()
+        header.add_css_class("bt-header")
+        left = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
+        left.append(Gtk.Label(label="Power"))
+        self._power = Gtk.Switch(active=bool(self.bt and self.bt.get_is_powered()),
+                                 valign=Gtk.Align.CENTER)
+        self._power.connect("state-set", self._on_power)
+        left.append(self._power)
+        header.set_start_widget(left)
+
+        if self.full and self.ctx.feature("discovery", True):
+            self._scan = Gtk.ToggleButton(label="  Scan")
+            self._scan.add_css_class("quad-action")
+            self._scan.connect("toggled", self._on_scan)
+            header.set_end_widget(self._scan)
+        return header
+
+    def _on_power(self, _sw, value: bool) -> bool:
+        ad = self._adapter()
+        if value:
+            # The adapter is frequently rfkill soft-blocked at boot; while blocked,
+            # AstalBluetooth.set_powered(True) is a silent no-op. Unblock first, then
+            # power on (bluez usually auto-powers on unblock, so set_powered is a
+            # belt-and-suspenders follow-up).
+            run_text(["rfkill", "unblock", "bluetooth"],
+                     lambda *_a: ad.set_powered(True) if ad else None)
+        elif ad:
+            ad.set_powered(False)
+        return False
+
+    def _on_scan(self, btn: Gtk.ToggleButton) -> None:
+        ad = self._adapter()
+        if not ad:
+            return
+        if btn.get_active():
+            ad.start_discovery()
+        else:
+            ad.stop_discovery()
+
+    # -- device list -------------------------------------------------------
+    def _refresh(self) -> None:
+        child = self._list.get_first_child()
+        while child:
+            self._list.remove(child)
+            child = self._list.get_first_child()
+        if not self.bt:
+            self._list.append(Gtk.Label(label="No Bluetooth adapter"))
+            return
+
+        devices = list(self.bt.get_devices())
+        devices.sort(key=lambda d: (not d.get_connected(), not d.get_paired(),
+                                    (d.get_name() or d.get_address() or "").lower()))
+        if not self.full:
+            devices = [d for d in devices if d.get_connected() or d.get_paired()][:4]
+        for dev in devices:
+            self._hook_device(dev)
+            self._list.append(self._device_row(dev))
+
+        if self.full and self.ctx.feature("history", True):
+            self._list.append(self._history_section())
+
+    def _hook_device(self, dev) -> None:
+        # React to a device's own state changes (adapter-level notify::devices doesn't
+        # fire for per-device connect/disconnect). Hook once each.
+        key = dev.get_address() or ""
+        if key in self._hooked:
+            return
+        self._hooked.add(key)
+        for sig in ("notify::connected", "notify::connecting", "notify::paired"):
+            dev.connect(sig, lambda *_a, d=dev: self._on_device_state(d))
+
+    def _on_device_state(self, dev) -> None:
+        addr = dev.get_address() or ""
+        if dev.get_connected():
+            self._pending.discard(addr)
+            self._failed.discard(addr)
+            if self.ctx.feature("history", True):
+                self._maybe_record(dev, force=True)
+        elif addr in self._pending and not dev.get_connecting():
+            # bluez stopped trying without establishing a link → the connect failed
+            self._pending.discard(addr)
+            self._failed.add(addr)
+        self._refresh()
+
+    def _device_row(self, dev) -> Gtk.Widget:
+        row = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=10)
+        row.add_css_class("bt-row")
+        addr = dev.get_address() or ""
+        icon = Gtk.Image.new_from_icon_name((dev.get_icon() or "bluetooth") + "-symbolic")
+        row.append(icon)
+        name = dev.get_name() or addr or "Unknown"
+
+        connected = dev.get_connected()
+        connecting = dev.get_connecting() or addr in self._pending
+        failed = addr in self._failed
+
+        lbl = Gtk.Label(label=name, xalign=0.0, hexpand=True)
+        row.append(lbl)
+
+        status = ("connected" if connected else "connecting…" if connecting else
+                  "failed" if failed else "paired" if dev.get_paired() else "")
+        if status:
+            tag = Gtk.Label(label=status)
+            tag.add_css_class("bt-status")
+            if failed:
+                tag.add_css_class("bt-failed")
+            row.append(tag)
+
+        actions = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=6)
+        if connecting:
+            spinner = Gtk.Spinner(valign=Gtk.Align.CENTER)
+            spinner.start()
+            actions.append(spinner)
+            actions.append(self._act("Cancel", lambda: self._cancel(dev)))
+        else:
+            if dev.get_paired():
+                actions.append(self._act("Forget", lambda: self._forget(dev)))
+            if connected:
+                actions.append(self._act("Disconnect",
+                                         lambda: dev.disconnect_device(None, self._noop)))
+            else:
+                actions.append(self._act("Retry" if failed else "Connect",
+                                         lambda: self._start_connect(dev)))
+        row.append(actions)
+
+        if connected and self.ctx.feature("history", True):
+            self._maybe_record(dev)
+        return row
+
+    @staticmethod
+    def _act(label: str, cb) -> Gtk.Button:
+        b = Gtk.Button(label=label, valign=Gtk.Align.CENTER)
+        b.add_css_class("quad-action")
+        b.connect("clicked", lambda *_a: cb())
+        return b
+
+    # -- connect / cancel / forget ----------------------------------------
+    def _start_connect(self, dev) -> None:
+        addr = dev.get_address() or ""
+        self._failed.discard(addr)
+        self._pending.add(addr)
+
+        def done(d, res):
+            try:
+                d.connect_device_finish(res)
+            except Exception:
+                a = d.get_address() or ""
+                if not d.get_connected():
+                    self._pending.discard(a)
+                    self._failed.add(a)
+                    self._refresh()
+        dev.connect_device(None, done)
+        # Backstop: some failures never resolve the async call, so time out.
+        GLib.timeout_add_seconds(25, lambda: self._connect_timeout(addr))
+        self._refresh()
+
+    def _connect_timeout(self, addr: str) -> bool:
+        if addr in self._pending:
+            self._pending.discard(addr)
+            self._failed.add(addr)
+            self._refresh()
+        return GLib.SOURCE_REMOVE
+
+    def _cancel(self, dev) -> None:
+        addr = dev.get_address() or ""
+        self._pending.discard(addr)
+        dev.disconnect_device(None, self._noop)  # abort the in-flight attempt
+        self._refresh()
+
+    def _forget(self, dev) -> None:
+        ad = self._adapter()
+        addr = dev.get_address() or ""
+        self._pending.discard(addr)
+        self._failed.discard(addr)
+        self._hooked.discard(addr)
+        if ad:
+            ad.remove_device(dev)  # fires notify::devices → refresh
+        self._refresh()
+
+    def _maybe_record(self, dev, force: bool = False) -> None:
+        addr = dev.get_address() or ""
+        if not addr or (addr in self._recorded and not force):
+            return
+        self._recorded.add(addr)
+        _record_history(addr, dev.get_name() or addr)
+
+    @staticmethod
+    def _noop(obj, res) -> None:
+        try:
+            obj.disconnect_device_finish(res)
+        except Exception:
+            pass
+
+    def _history_section(self) -> Gtk.Widget:
+        box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=4)
+        box.add_css_class("bt-history")
+        box.append(Gtk.Separator())
+        box.append(Gtk.Label(label="History", xalign=0.0))
+        for h in _load_history()[:8]:
+            when = time.strftime("%d.%m %H:%M", time.localtime(h.get("ts", 0)))
+            box.append(Gtk.Label(label=f"{h.get('name', '?')}  ·  {when}", xalign=0.0))
+        return box
+
+
+def build(ctx: ModuleContext) -> ModuleInstance:
+    # Feature toggles (discovery/history) rebuild the whole card via QuadCard, so
+    # both views are recreated with the current features — no partial refresh here.
+    compact = _BluetoothView(ctx, full=False)
+    expanded = _BluetoothView(ctx, full=True)
+    return ModuleInstance(compact=compact, expanded=expanded)
+
+
+SPEC = ModuleSpec(
+    id="bluetooth",
+    title="Bluetooth",
+    icon="",  # nf-fa-bluetooth
+    build=build,
+    default_enabled=True,
+    features=[Feature("discovery", "Device discovery", True),
+              Feature("history", "Connection history", True)],
+)

desktopenvs/hyprlua/astal-menu/modules/location.py

@@ -0,0 +1,182 @@
+"""Location quad: a slippy-map image centred on the device's IP-geolocated position,
+with a marker. Drag to pan, scroll to zoom, double-click to recentre.
+
+The position comes from the shared LocationService (backend/geolocate.py), which
+traceroutes to 1.1.1.1, takes the first public hop (the ISP egress) and resolves it
+through a public geolocation API. The "Locate via IP" feature toggle gates that
+lookup entirely; when off, this quad shows a placeholder instead. "Satellite view"
+switches the tiles between the dark night map and Esri satellite imagery.
+
+We render a static map (backend/staticmap.py) rather than an interactive libshumate
+map: Shumate does not paint tiles in this environment (the official shumate-demo
+shows the same blank map), while tile downloads themselves work fine — so panning is
+done by re-rendering at a new centre. The Weather quad consumes the same service.
+"""
+
+from __future__ import annotations
+
+import math
+import sys
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+from gi.repository import Gdk, GLib, Gtk  # noqa: E402
+
+from lib.proc import run_text
+from module_base import Feature, ModuleContext, ModuleInstance, ModuleSpec
+from paths import BACKEND_DIR, CACHE_DIR
+
+_SCRIPT = str(BACKEND_DIR / "staticmap.py")
+_TILE = 256
+
+
+def _center_px(lat: float, lon: float, zoom: int) -> tuple[float, float]:
+    n = 2 ** zoom
+    y = (1.0 - math.asinh(math.tan(math.radians(lat))) / math.pi) / 2.0 * n
+    x = (lon + 180.0) / 360.0 * n
+    return x * _TILE, y * _TILE
+
+
+def _px_latlon(px: float, py: float, zoom: int) -> tuple[float, float]:
+    n = 2 ** zoom
+    lon = px / (_TILE * n) * 360.0 - 180.0
+    lat = math.degrees(math.atan(math.sinh(math.pi * (1.0 - 2.0 * py / (_TILE * n)))))
+    return lat, lon
+
+
+class _MapView(Gtk.Box):
+    def __init__(self, ctx: ModuleContext, zoom: int, size: tuple[int, int],
+                 tag: str, show_info: bool):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL)
+        self.add_css_class("map-view")
+        self.ctx = ctx
+        self.zoom = zoom
+        self.size = size
+        self._out = str(CACHE_DIR / f"map_{tag}.png")
+        self._loc: tuple[float, float] | None = None    # geolocated position (marker)
+        self._view: tuple[float, float] | None = None    # current view centre
+        self._drag_from: tuple[float, float] | None = None
+        self._render_pending = False
+
+        self.picture = Gtk.Picture(content_fit=Gtk.ContentFit.COVER, vexpand=True)
+        self.picture.add_css_class("map-picture")
+        self.append(self.picture)
+
+        self._info = None
+        if show_info:
+            self._info = Gtk.Label(label="Locating…", xalign=0.0)
+            self._info.add_css_class("map-info")
+            self.append(self._info)
+
+        self._wire_gestures()
+        ctx.services.location.subscribe(self._on_location)
+
+    def _style(self) -> str:
+        return "satellite" if self.ctx.feature("satellite", False) else "dark"
+
+    # -- data / render -----------------------------------------------------
+    def _on_location(self, data: dict) -> None:
+        self._loc = (data["lat"], data["lon"])
+        self._view = (data["lat"], data["lon"])   # recentre on a fresh fix
+        self._render()
+        if self._info is not None:
+            city = data.get("city") or "Unknown"
+            country = data.get("country") or ""
+            self._info.set_text(f"{city}, {country}  ·  {data['lat']:.3f}, {data['lon']:.3f}"
+                                f"   ·   drag to pan · scroll to zoom · double-click to recentre")
+
+    def _render(self) -> None:
+        if self._view is None:
+            return
+        vlat, vlon = self._view
+        mlat, mlon = self._loc or self._view
+        w, h = self.size
+        run_text([sys.executable, _SCRIPT, str(vlat), str(vlon), str(self.zoom),
+                  str(w), str(h), self._out, self._style(), str(mlat), str(mlon)],
+                 self._on_rendered)
+
+    def _schedule_render(self) -> None:
+        # coalesce the flood of drag/scroll updates into ~11 renders/sec
+        if self._render_pending:
+            return
+        self._render_pending = True
+
+        def go() -> bool:
+            self._render_pending = False
+            self._render()
+            return GLib.SOURCE_REMOVE
+        GLib.timeout_add(90, go)
+
+    def _on_rendered(self, ok: bool, out: str, err: str) -> None:
+        if not ok:
+            return
+        # load a fresh texture; set_filename would ignore an unchanged path on re-pan
+        try:
+            self.picture.set_paintable(Gdk.Texture.new_from_filename(self._out))
+        except GLib.Error:
+            self.picture.set_filename(self._out)
+
+    # -- gestures: drag to pan, scroll to zoom, double-click to recentre ----
+    def _wire_gestures(self) -> None:
+        drag = Gtk.GestureDrag()
+        drag.connect("drag-begin", lambda *_a: setattr(self, "_drag_from", self._view))
+        drag.connect("drag-update", self._on_drag)
+        self.picture.add_controller(drag)
+
+        scroll = Gtk.EventControllerScroll(
+            flags=Gtk.EventControllerScrollFlags.VERTICAL)
+        scroll.connect("scroll", self._on_scroll)
+        self.picture.add_controller(scroll)
+
+        click = Gtk.GestureClick()
+        click.connect("pressed", self._on_click)
+        self.picture.add_controller(click)
+
+    def _on_drag(self, _gesture, ox: float, oy: float) -> None:
+        if self._drag_from is None:
+            return
+        cx, cy = _center_px(self._drag_from[0], self._drag_from[1], self.zoom)
+        # drag right → the view centre moves left (map content follows the cursor)
+        self._view = _px_latlon(cx - ox, cy - oy, self.zoom)
+        self._schedule_render()
+
+    def _on_scroll(self, _controller, _dx: float, dy: float) -> bool:
+        self.zoom = max(3, min(18, self.zoom + (1 if dy < 0 else -1)))
+        self._schedule_render()
+        return True
+
+    def _on_click(self, _gesture, n_press: int, _x: float, _y: float) -> None:
+        if n_press >= 2 and self._loc is not None:
+            self._view = self._loc
+            self._schedule_render()
+
+
+def _placeholder() -> Gtk.Widget:
+    box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=8,
+                  valign=Gtk.Align.CENTER, halign=Gtk.Align.CENTER)
+    box.add_css_class("map-view")
+    box.append(Gtk.Label(label="IP location is off"))
+    return box
+
+
+def build(ctx: ModuleContext) -> ModuleInstance:
+    # "Locate via IP" gates geolocation entirely: when off we neither traceroute nor
+    # hit any geolocation API, and just show a placeholder. Toggling it rebuilds the
+    # card (via QuadCard), so flipping it back on re-triggers the lookup.
+    if not ctx.feature("ip_locate", True):
+        return ModuleInstance(compact=_placeholder(), expanded=None)
+    ctx.services.location.get()  # kick off geolocation (traceroute → API) if not started
+    compact = _MapView(ctx, zoom=12, size=(620, 150), tag="compact", show_info=False)
+    expanded = _MapView(ctx, zoom=13, size=(1100, 620), tag="expanded", show_info=True)
+    return ModuleInstance(compact=compact, expanded=expanded, scroll_expanded=False)
+
+
+SPEC = ModuleSpec(
+    id="location",
+    title="Location",
+    icon="",  # nf-fa-map_marker
+    build=build,
+    features=[Feature("ip_locate", "Locate via IP", True),
+              Feature("satellite", "Satellite view", False)],
+)

desktopenvs/hyprlua/astal-menu/modules/network.py

@@ -0,0 +1,529 @@
+"""Network quad.
+
+Compact: Wi-Fi enable + primary connection/IP (AstalNetwork + backend/network.sh).
+Expanded: a small NetworkManager control panel over backend/nm.py, as four tabs —
+  Adapters : each device foldout with editable IPv4/IPv6 (DHCP toggle, address,
+             subnet-mask <-> CIDR, gateway); applied via `nmcli connection modify/up`
+  Routes   : the kernel routing table (read-only; editing kernel routes needs root)
+  VLAN     : list / create / activate / delete VLAN connections
+  DNS      : effective servers per device + a per-connection override table
+Every tab is an independently toggle-able feature.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import sys
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+from gi.repository import Gtk  # noqa: E402
+
+from lib.proc import run_json
+from module_base import Feature, ModuleContext, ModuleInstance, ModuleSpec
+from paths import BACKEND_DIR
+
+_NET = str(BACKEND_DIR / "network.sh")
+_NM = str(BACKEND_DIR / "nm.py")
+
+
+def _nm(args: list[str], cb) -> None:
+    """Run a backend/nm.py subcommand expecting JSON on stdout."""
+    run_json([sys.executable, _NM, *args], cb)
+
+
+def _primary_ip(data) -> str:
+    if not isinstance(data, list):
+        return "—"
+    for iface in data:
+        if iface.get("ifname") == "lo":
+            continue
+        for a in iface.get("addr_info", []):
+            if a.get("family") == "inet":
+                return f"{a['local']}/{a.get('prefixlen', '')} ({iface.get('ifname')})"
+    return "—"
+
+
+# -- subnet mask <-> CIDR prefix ------------------------------------------
+def _mask_to_prefix(mask: str) -> int | None:
+    try:
+        return ipaddress.IPv4Network(f"0.0.0.0/{mask.strip()}").prefixlen
+    except (ipaddress.NetmaskValueError, ValueError):
+        return None
+
+
+def _prefix_to_mask(prefix: int) -> str:
+    return str(ipaddress.IPv4Network(f"0.0.0.0/{prefix}").netmask)
+
+
+class _Compact(Gtk.Box):
+    def __init__(self, ctx: ModuleContext):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL, spacing=8)
+        self.add_css_class("net-view")
+        self.ctx = ctx
+        self.net = ctx.services.network
+
+        row = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
+        self._primary = Gtk.Label(label="…", xalign=0.0, hexpand=True)
+        row.append(Gtk.Label(label=""))  # nf wifi
+        row.append(self._primary)
+        wifi = self.net.get_wifi() if self.net else None
+        self._wifi_switch = Gtk.Switch(active=bool(wifi and wifi.get_enabled()),
+                                       valign=Gtk.Align.CENTER)
+        self._wifi_switch.set_tooltip_text("Wi-Fi")
+        self._wifi_switch.connect("state-set", self._on_wifi_toggle)
+        row.append(self._wifi_switch)
+        self.append(row)
+
+        self._ip = Gtk.Label(label="", xalign=0.0)
+        self._ip.add_css_class("net-ip")
+        self.append(self._ip)
+
+        if self.net:
+            self.net.connect("notify::primary", lambda *_: self.refresh())
+            if wifi:
+                wifi.connect("notify::ssid", lambda *_: self.refresh())
+        self.refresh()
+
+    def _on_wifi_toggle(self, _sw, value: bool) -> bool:
+        wifi = self.net.get_wifi() if self.net else None
+        if wifi:
+            wifi.set_enabled(value)
+        return False
+
+    def refresh(self) -> None:
+        wifi = self.net.get_wifi() if self.net else None
+        if wifi and wifi.get_active_access_point():
+            self._primary.set_text(f"{wifi.get_ssid() or '?'}  ·  {wifi.get_strength()}%")
+        elif self.net and self.net.get_wired() and self.net.get_wired().get_internet():
+            self._primary.set_text("Wired")
+        else:
+            self._primary.set_text("Disconnected")
+        run_json([_NET, "ip"], lambda ok, d: self._ip.set_text(_primary_ip(d) if ok else "—"))
+
+
+# -- shared little widgets -------------------------------------------------
+def _clear(box: Gtk.Box) -> None:
+    child = box.get_first_child()
+    while child:
+        box.remove(child)
+        child = box.get_first_child()
+
+
+def _field(placeholder: str, text: str = "") -> Gtk.Entry:
+    e = Gtk.Entry(placeholder_text=placeholder, text=text, hexpand=True)
+    e.add_css_class("net-entry")
+    return e
+
+
+def _labeled(label: str, widget: Gtk.Widget) -> Gtk.Widget:
+    row = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
+    lbl = Gtk.Label(label=label, xalign=0.0)
+    lbl.set_size_request(90, -1)
+    row.append(lbl)
+    row.append(widget)
+    return row
+
+
+def _pill(label: str, cb) -> Gtk.Button:
+    b = Gtk.Button(label=label)
+    b.add_css_class("quad-action")
+    b.connect("clicked", lambda *_: cb())
+    return b
+
+
+# -- IPv4 / IPv6 editor for one connection --------------------------------
+class _IPSection(Gtk.Box):
+    """One address family's editor. IPv4 exposes a linked subnet-mask/CIDR pair;
+    IPv6 exposes a prefix-length field. Fields are only sensitive in Manual mode."""
+
+    def __init__(self, con: str, family: str, fam_data: dict, on_result):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL, spacing=6)
+        self.con = con
+        self.family = family
+        self._on_result = on_result
+        self.add_css_class("net-view")
+
+        title = "IPv4" if family == "ipv4" else "IPv6"
+        head = Gtk.CenterBox()
+        head.set_start_widget(Gtk.Label(label=title, xalign=0.0))
+        auto = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
+        auto.append(Gtk.Label(label="Automatic"))
+        self._dhcp = Gtk.Switch(active=(fam_data.get("method", "auto") != "manual"),
+                                valign=Gtk.Align.CENTER)
+        self._dhcp.connect("state-set", self._on_mode)
+        auto.append(self._dhcp)
+        head.set_end_widget(auto)
+        self.append(head)
+
+        addr, prefix = self._split(fam_data.get("addresses", []))
+        self._addr = _field("Address", addr)
+        self._gw = _field("Gateway", fam_data.get("gateway", ""))
+
+        self._fields = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6)
+        self._fields.append(_labeled("Address", self._addr))
+        if family == "ipv4":
+            self._guard = False
+            self._mask = _field("255.255.255.0", _prefix_to_mask(prefix) if prefix else "")
+            self._cidr = _field("/24", f"/{prefix}" if prefix else "")
+            self._cidr.set_size_request(70, -1)
+            self._mask.connect("changed", self._sync_from_mask)
+            self._cidr.connect("changed", self._sync_from_cidr)
+            mask_row = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
+            mask_row.append(self._mask)
+            mask_row.append(self._cidr)
+            self._fields.append(_labeled("Netmask", mask_row))
+        else:
+            self._prefix = _field("64", str(prefix) if prefix else "")
+            self._fields.append(_labeled("Prefix", self._prefix))
+        self._fields.append(_labeled("Gateway", self._gw))
+        apply = Gtk.Button(label=f"Apply {title}")
+        apply.add_css_class("enable-btn")
+        apply.connect("clicked", lambda *_: self._apply())
+        self._fields.append(apply)
+        self.append(self._fields)
+
+        self._set_manual_enabled(not self._dhcp.get_active())
+
+    def _set_manual_enabled(self, on: bool) -> None:
+        # The reset GTK theme doesn't dim insensitive widgets, so fade the manual
+        # fields explicitly when DHCP/Automatic is active.
+        self._fields.set_sensitive(on)
+        self._fields.set_opacity(1.0 if on else 0.45)
+
+    @staticmethod
+    def _split(addresses: list[str]) -> tuple[str, int | None]:
+        if not addresses:
+            return "", None
+        addr, _, prefix = addresses[0].partition("/")
+        try:
+            return addr, int(prefix)
+        except ValueError:
+            return addr, None
+
+    def _on_mode(self, _sw, auto: bool) -> bool:
+        self._set_manual_enabled(not auto)
+        return False
+
+    # keep the dotted mask and /CIDR fields in lock-step (IPv4 only)
+    def _sync_from_mask(self, _e) -> None:
+        if self._guard:
+            return
+        p = _mask_to_prefix(self._mask.get_text())
+        if p is not None:
+            self._guard = True
+            self._cidr.set_text(f"/{p}")
+            self._guard = False
+
+    def _sync_from_cidr(self, _e) -> None:
+        if self._guard:
+            return
+        raw = self._cidr.get_text().lstrip("/").strip()
+        if raw.isdigit() and 0 <= int(raw) <= 32:
+            self._guard = True
+            self._mask.set_text(_prefix_to_mask(int(raw)))
+            self._guard = False
+
+    def _prefixlen(self) -> str:
+        if self.family == "ipv4":
+            raw = self._cidr.get_text().lstrip("/").strip()
+            if raw.isdigit():
+                return raw
+            p = _mask_to_prefix(self._mask.get_text())
+            return str(p) if p is not None else ""
+        return self._prefix.get_text().strip()
+
+    def _apply(self) -> None:
+        if self._dhcp.get_active():
+            args = ["set-ip", self.con, self.family, "auto"]
+        else:
+            addr, plen = self._addr.get_text().strip(), self._prefixlen()
+            cidr = f"{addr}/{plen}" if addr and plen else addr
+            args = ["set-ip", self.con, self.family, "manual",
+                    cidr, self._gw.get_text().strip(), ""]
+        _nm(args, lambda ok, d: self._on_result(
+            ok and isinstance(d, dict) and d.get("ok"),
+            (d.get("error") if isinstance(d, dict) else "") or ""))
+
+
+class _AdaptersPage(Gtk.Box):
+    def __init__(self):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL, spacing=6)
+        self._status = Gtk.Label(xalign=0.0)
+        self._status.add_css_class("net-ip")
+        self._status.set_visible(False)
+        self.append(self._status)
+        self._list = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=8)
+        scroller = Gtk.ScrolledWindow(vexpand=True, hscrollbar_policy=Gtk.PolicyType.NEVER)
+        scroller.set_child(self._list)
+        self.append(scroller)
+        self._reload()
+
+    def _reload(self) -> None:
+        _nm(["adapters"], self._populate)
+
+    def _populate(self, ok: bool, adapters) -> None:
+        _clear(self._list)
+        if not ok or not isinstance(adapters, list) or not adapters:
+            self._list.append(Gtk.Label(label="No manageable adapters", xalign=0.0))
+            return
+        for a in adapters:
+            self._list.append(self._adapter_row(a))
+
+    def _adapter_row(self, a: dict) -> Gtk.Widget:
+        icon = "" if a.get("type") == "wifi" else ""  # nf wifi / ethernet
+        exp = Gtk.Expander(
+            label=f"{icon}  {a['device']}  ·  {a.get('connection') or '—'}  [{a.get('state')}]")
+        exp.add_css_class("net-adapter")
+        body = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=10)
+        body.set_margin_top(8)
+        con = a.get("connection")
+        if not con:
+            body.append(Gtk.Label(label="No connection profile", xalign=0.0))
+        else:
+            loading = Gtk.Label(label="Loading…", xalign=0.0)
+            body.append(loading)
+            _nm(["ipconfig", con], lambda ok, d, b=body, l=loading, c=con:
+                self._fill(ok, d, b, l, c))
+        exp.set_child(body)
+        return exp
+
+    def _fill(self, ok, data, body, loading, con) -> None:
+        body.remove(loading)
+        if not ok or not isinstance(data, dict):
+            body.append(Gtk.Label(label="Could not read config", xalign=0.0))
+            return
+        result = Gtk.Label(xalign=0.0)
+        result.set_visible(False)
+
+        def on_result(good: bool, err: str) -> None:
+            result.set_text("Applied" if good else f"Failed: {err or 'error'}")
+            result.set_visible(True)
+
+        body.append(_IPSection(con, "ipv4", data.get("ipv4", {}), on_result))
+        body.append(Gtk.Separator())
+        body.append(_IPSection(con, "ipv6", data.get("ipv6", {}), on_result))
+        body.append(result)
+
+
+class _RoutesPage(Gtk.Box):
+    def __init__(self):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL, spacing=4)
+        header = Gtk.CenterBox()
+        header.set_start_widget(Gtk.Label(label="Kernel routing table", xalign=0.0))
+        header.set_end_widget(_pill("  Refresh", self._reload))
+        self.append(header)
+        self._list = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=2)
+        scroller = Gtk.ScrolledWindow(vexpand=True, hscrollbar_policy=Gtk.PolicyType.NEVER)
+        scroller.set_child(self._list)
+        self.append(scroller)
+        self._reload()
+
+    def _reload(self) -> None:
+        _nm(["routes"], self._populate)
+
+    def _populate(self, ok: bool, routes) -> None:
+        _clear(self._list)
+        if not ok or not isinstance(routes, list) or not routes:
+            self._list.append(Gtk.Label(label="No routes", xalign=0.0))
+            return
+        for r in routes:
+            self._list.append(Gtk.Label(label=self._fmt(r), xalign=0.0,
+                                        selectable=True, wrap=True))
+
+    @staticmethod
+    def _fmt(r: dict) -> str:
+        dst = r.get("dst", "?")
+        via = f" via {r['gateway']}" if r.get("gateway") else ""
+        dev = f" dev {r['dev']}" if r.get("dev") else ""
+        metric = f"  metric {r['metric']}" if r.get("metric") is not None else ""
+        proto = f"  ({r['proto']})" if r.get("proto") else ""
+        return f"{dst}{via}{dev}{metric}{proto}"
+
+
+class _VlanPage(Gtk.Box):
+    def __init__(self):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL, spacing=8)
+        self._adapters: list[dict] = []
+
+        add = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=6)
+        self._parent = Gtk.DropDown.new_from_strings(["…"])
+        self._vid = _field("VLAN ID")
+        self._vid.set_size_request(90, -1)
+        add.append(self._parent)
+        add.append(self._vid)
+        add.append(_pill("Add", self._add))
+        self.append(_labeled("New VLAN", add))
+
+        self._status = Gtk.Label(xalign=0.0)
+        self._status.add_css_class("net-ip")
+        self._status.set_visible(False)
+        self.append(self._status)
+
+        self._list = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=4)
+        scroller = Gtk.ScrolledWindow(vexpand=True, hscrollbar_policy=Gtk.PolicyType.NEVER)
+        scroller.set_child(self._list)
+        self.append(scroller)
+
+        _nm(["adapters"], self._set_adapters)
+        self._reload()
+
+    def _set_adapters(self, ok, adapters) -> None:
+        self._adapters = adapters if ok and isinstance(adapters, list) else []
+        names = [a["device"] for a in self._adapters] or ["(no devices)"]
+        self._parent.set_model(Gtk.StringList.new(names))
+
+    def _reload(self) -> None:
+        _nm(["vlans"], self._populate)
+
+    def _populate(self, ok, vlans) -> None:
+        _clear(self._list)
+        if not ok or not isinstance(vlans, list) or not vlans:
+            self._list.append(Gtk.Label(label="No VLANs configured", xalign=0.0))
+            return
+        for v in vlans:
+            self._list.append(self._vlan_row(v))
+
+    def _vlan_row(self, v: dict) -> Gtk.Widget:
+        row = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
+        row.add_css_class("net-row")
+        state = "active" if v.get("active") else "inactive"
+        row.append(Gtk.Label(label=f"{v['name']}  ·  {v.get('device') or '—'}  [{state}]",
+                              xalign=0.0, hexpand=True))
+        if not v.get("active"):
+            row.append(_pill("Up", lambda n=v["name"]: self._act("vlan-up", n)))
+        row.append(_pill("Delete", lambda n=v["name"]: self._act("vlan-del", n)))
+        return row
+
+    def _add(self) -> None:
+        idx = self._parent.get_selected()
+        vid = self._vid.get_text().strip()
+        if idx < 0 or idx >= len(self._adapters) or not vid.isdigit():
+            self._flash("Pick a parent device and numeric VLAN ID")
+            return
+        parent = self._adapters[idx]["device"]
+        _nm(["vlan-add", parent, vid], self._after_write)
+
+    def _act(self, cmd: str, name: str) -> None:
+        _nm([cmd, name], self._after_write)
+
+    def _after_write(self, ok, d) -> None:
+        good = ok and isinstance(d, dict) and d.get("ok")
+        self._flash("Done" if good else
+                    f"Failed: {(d.get('error') if isinstance(d, dict) else '') or 'error'}")
+        self._reload()
+
+    def _flash(self, msg: str) -> None:
+        self._status.set_text(msg)
+        self._status.set_visible(True)
+
+
+class _DnsPage(Gtk.Box):
+    def __init__(self):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL, spacing=8)
+        self._adapters: list[dict] = []
+
+        self.append(Gtk.Label(label="Effective servers", xalign=0.0))
+        self._effective = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=2)
+        self.append(self._effective)
+
+        self.append(Gtk.Separator())
+        self.append(Gtk.Label(label="Override", xalign=0.0))
+        self._conn = Gtk.DropDown.new_from_strings(["…"])
+        self.append(_labeled("Connection", self._conn))
+        self._servers = _field("1.1.1.1 8.8.8.8")
+        self.append(_labeled("Servers", self._servers))
+        ignore = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
+        ignore.append(Gtk.Label(label="Ignore automatic", hexpand=True, xalign=0.0))
+        self._ignore = Gtk.Switch(active=True, valign=Gtk.Align.CENTER)
+        ignore.append(self._ignore)
+        self.append(ignore)
+        self.append(_pill("Apply DNS", self._apply))
+        self._status = Gtk.Label(xalign=0.0)
+        self._status.add_css_class("net-ip")
+        self._status.set_visible(False)
+        self.append(self._status)
+
+        _nm(["adapters"], self._set_adapters)
+        _nm(["dns"], self._show_effective)
+
+    def _set_adapters(self, ok, adapters) -> None:
+        self._adapters = [a for a in (adapters or []) if a.get("connection")] \
+            if ok and isinstance(adapters, list) else []
+        names = [f"{a['connection']} ({a['device']})" for a in self._adapters] or ["(none)"]
+        self._conn.set_model(Gtk.StringList.new(names))
+
+    def _show_effective(self, ok, data) -> None:
+        _clear(self._effective)
+        if not ok or not isinstance(data, list) or not data:
+            self._effective.append(Gtk.Label(label="—", xalign=0.0))
+            return
+        for d in data:
+            self._effective.append(Gtk.Label(
+                label=f"{d['device']}:  {', '.join(d.get('servers', []))}",
+                xalign=0.0, selectable=True))
+
+    def _apply(self) -> None:
+        idx = self._conn.get_selected()
+        if idx < 0 or idx >= len(self._adapters):
+            self._flash("Pick a connection")
+            return
+        con = self._adapters[idx]["connection"]
+        servers = self._servers.get_text().strip()
+        ign = "yes" if self._ignore.get_active() else "no"
+        _nm(["set-dns", con, "ipv4", servers, ign], self._after)
+
+    def _after(self, ok, d) -> None:
+        good = ok and isinstance(d, dict) and d.get("ok")
+        self._flash("Applied" if good else
+                    f"Failed: {(d.get('error') if isinstance(d, dict) else '') or 'error'}")
+        _nm(["dns"], self._show_effective)
+
+    def _flash(self, msg: str) -> None:
+        self._status.set_text(msg)
+        self._status.set_visible(True)
+
+
+class _Expanded(Gtk.Box):
+    def __init__(self, ctx: ModuleContext):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL, spacing=8)
+        self.add_css_class("net-view")
+        self.ctx = ctx
+
+        self.stack = Gtk.Stack(vexpand=True)
+        switcher = Gtk.StackSwitcher(stack=self.stack)
+        switcher.add_css_class("net-switcher")
+        self.append(switcher)
+        self.append(self.stack)
+
+        f = ctx.feature
+        if f("adapters", True):
+            self.stack.add_titled(_AdaptersPage(), "adapters", "Adapters")
+        if f("routes", True):
+            self.stack.add_titled(_RoutesPage(), "routes", "Routes")
+        if f("vlan", True):
+            self.stack.add_titled(_VlanPage(), "vlan", "VLAN")
+        if f("dns", True):
+            self.stack.add_titled(_DnsPage(), "dns", "DNS")
+
+
+def build(ctx: ModuleContext) -> ModuleInstance:
+    # Feature toggles rebuild the whole card via QuadCard, so _Expanded is recreated
+    # with the enabled tabs — no in-place page rebuild needed here.
+    compact = _Compact(ctx)
+    expanded = _Expanded(ctx)
+    return ModuleInstance(compact=compact, expanded=expanded)
+
+
+SPEC = ModuleSpec(
+    id="network",
+    title="Network",
+    icon="",  # nf-md-lan
+    build=build,
+    default_enabled=True,
+    features=[Feature("adapters", "Adapters", True),
+              Feature("routes", "Routes", True),
+              Feature("vlan", "VLAN", True),
+              Feature("dns", "DNS", True)],
+)

desktopenvs/hyprlua/astal-menu/modules/weather.py

@@ -0,0 +1,72 @@
+"""Weather quad: wttr.in rendered with its original ANSI/CLI art (via AnsiRenderer).
+
+Reuses the shared LocationService for the city; if none is known yet, wttr.in
+geolocates the caller's IP itself, so the widget still works standalone. The
+'ascii_art' feature toggle swaps the art for a compact one-line text summary.
+"""
+
+from __future__ import annotations
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+from gi.repository import Gtk  # noqa: E402
+
+from lib.ansi import AnsiRenderer
+from lib.proc import run_text
+from module_base import Feature, ModuleContext, ModuleInstance, ModuleSpec
+from paths import BACKEND_DIR
+
+_SCRIPT = str(BACKEND_DIR / "weather.sh")
+
+
+class _WeatherView(Gtk.Box):
+    def __init__(self, ctx: ModuleContext, opts: str):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL)
+        self.add_css_class("weather-view")
+        self.ctx = ctx
+        self.opts = opts
+        self._loc = ""
+
+        self.renderer = AnsiRenderer()
+        self.append(self.renderer.view)
+        self._status = Gtk.Label(label="Loading weather…")
+        self._status.add_css_class("weather-status")
+        self.append(self._status)
+
+        ctx.services.location.subscribe(self._on_location)
+        self.refresh()
+
+    def _on_location(self, data: dict) -> None:
+        self._loc = data.get("city") or ""
+        self.refresh()
+
+    def refresh(self) -> None:
+        art = self.ctx.feature("ascii_art", True)
+        opts = self.opts if art else "format=%l:+%c+%t,+%w"
+        run_text([_SCRIPT, self._loc, opts], self._on_result)
+
+    def _on_result(self, ok: bool, out: str, err: str) -> None:
+        if ok and out.strip() and "<html" not in out.lower():
+            self.renderer.set_text(out.rstrip("\n"))
+            self._status.set_visible(False)
+        else:
+            self._status.set_text("Weather unavailable")
+            self._status.set_visible(True)
+
+
+def build(ctx: ModuleContext) -> ModuleInstance:
+    # The ascii_art toggle rebuilds the whole card via QuadCard, so both views are
+    # recreated and re-fetch with the current format — no partial refresh here.
+    compact = _WeatherView(ctx, opts="0")        # current conditions only
+    expanded = _WeatherView(ctx, opts="")        # full 3-day forecast
+    return ModuleInstance(compact=compact, expanded=expanded)
+
+
+SPEC = ModuleSpec(
+    id="weather",
+    title="Weather",
+    icon="",  # nf-weather
+    build=build,
+    features=[Feature("ascii_art", "CLI art", True)],
+)

desktopenvs/hyprlua/astal-menu/paths.py

@@ -0,0 +1,27 @@
+"""Shared filesystem locations. Works whether run from the repo or ~/.config."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent
+BACKEND_DIR = BASE_DIR / "backend"
+STYLE_DIR = BASE_DIR / "style"
+
+CONFIG_DIR = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "astal-menu"
+CACHE_DIR = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "astal-menu"
+# User settings live under XDG_STATE_HOME, NOT CONFIG_DIR: the config-updater does
+# `rm -rf ~/.config/astal-menu` on every deploy, which would wipe pinned favourites
+# and quad toggles. The state dir is never touched by config sync.
+STATE_DIR = Path(os.environ.get("XDG_STATE_HOME", Path.home() / ".local" / "state")) / "astal-menu"
+
+SETTINGS_FILE = STATE_DIR / "settings.json"
+
+APP_ID = "eu.abdelbaki.astalmenu"
+
+
+def ensure_dirs() -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    STATE_DIR.mkdir(parents=True, exist_ok=True)

desktopenvs/hyprlua/astal-menu/registry.py

@@ -0,0 +1,29 @@
+"""The module registry — the single place that lists available quads in order.
+
+To add a new module: create modules/<name>.py exposing a top-level `SPEC`
+(ModuleSpec), then import it and append its SPEC here. The first four *enabled*
+specs fill the 2x2 grid; extra specs are kept for future paginated layouts.
+"""
+
+from __future__ import annotations
+
+from modules import bluetooth, location, network, weather
+from module_base import ModuleSpec
+
+ALL_SPECS: list[ModuleSpec] = [
+    location.SPEC,
+    weather.SPEC,
+    bluetooth.SPEC,
+    network.SPEC,
+]
+
+
+def ordered_specs(settings) -> list[ModuleSpec]:
+    """Return specs in the user's saved order, unknown/new ones appended."""
+    order = settings.order()
+    if not order:
+        return list(ALL_SPECS)
+    by_id = {s.id: s for s in ALL_SPECS}
+    result = [by_id[i] for i in order if i in by_id]
+    result += [s for s in ALL_SPECS if s.id not in order]
+    return result

desktopenvs/hyprlua/astal-menu/services/location.py

@@ -0,0 +1,55 @@
+"""Shared geolocation singleton.
+
+Runs backend/geolocate.py (IP geolocation, cached) exactly once and notifies
+subscribers. Both the Location map and the Weather widget subscribe, so there is a
+single source of truth for "where am I" and only one network lookup.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Callable, Optional
+
+from lib.proc import run_json
+from paths import BACKEND_DIR
+
+
+class LocationService:
+    def __init__(self) -> None:
+        self.data: Optional[dict] = None
+        self._subs: list[Callable[[dict], None]] = []
+        self._inflight = False
+
+    def subscribe(self, cb: Callable[[dict], None]) -> None:
+        self._subs.append(cb)
+        if self.data is not None:
+            cb(self.data)
+
+    def get(self) -> Optional[dict]:
+        if self.data is None and not self._inflight:
+            self.refresh()
+        return self.data
+
+    def refresh(self) -> None:
+        if self._inflight:
+            return
+        self._inflight = True
+        argv = [sys.executable, str(BACKEND_DIR / "geolocate.py")]
+        run_json(argv, self._on_result)
+
+    def _on_result(self, ok: bool, data) -> None:
+        self._inflight = False
+        if ok and isinstance(data, dict) and "lat" in data:
+            self.data = data
+            for cb in list(self._subs):
+                cb(data)
+
+
+_instance: LocationService | None = None
+
+
+def get_location_service() -> LocationService:
+    global _instance
+    if _instance is None:
+        _instance = LocationService()
+    return _instance

desktopenvs/hyprlua/astal-menu/settings.py

@@ -0,0 +1,83 @@
+"""Persisted user settings: which quads are enabled, per-module feature toggles,
+and quad ordering. Single JSON file, read at startup, written on every change.
+
+Modules never import this directly for their own feature flags; they receive a
+scoped view via ctx.feature(...) so the persistence format stays centralised.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Callable
+
+from paths import CONFIG_DIR, SETTINGS_FILE, ensure_dirs
+
+
+class Settings:
+    def __init__(self) -> None:
+        self._data: dict = {"quads": {}, "features": {}, "order": None, "favorites": []}
+        self._listeners: list[Callable[[], None]] = []
+        self.load()
+
+    # -- persistence -------------------------------------------------------
+    def load(self) -> None:
+        path = SETTINGS_FILE
+        if not path.exists():
+            # one-time migration from the old CONFIG_DIR location (pre state-dir)
+            legacy = CONFIG_DIR / "settings.json"
+            if legacy.exists():
+                path = legacy
+        try:
+            self._data.update(json.loads(path.read_text()))
+        except (FileNotFoundError, json.JSONDecodeError):
+            pass
+
+    def save(self) -> None:
+        ensure_dirs()
+        SETTINGS_FILE.write_text(json.dumps(self._data, indent=2))
+        for cb in list(self._listeners):
+            cb()
+
+    def subscribe(self, cb: Callable[[], None]) -> None:
+        self._listeners.append(cb)
+
+    # -- quad enable/disable ----------------------------------------------
+    def quad_enabled(self, module_id: str, default: bool = True) -> bool:
+        return bool(self._data["quads"].get(module_id, default))
+
+    def set_quad_enabled(self, module_id: str, value: bool) -> None:
+        self._data["quads"][module_id] = bool(value)
+        self.save()
+
+    # -- per-module feature toggles ---------------------------------------
+    def feature(self, module_id: str, feature_id: str, default: bool = True) -> bool:
+        return bool(self._data["features"].get(module_id, {}).get(feature_id, default))
+
+    def set_feature(self, module_id: str, feature_id: str, value: bool) -> None:
+        self._data["features"].setdefault(module_id, {})[feature_id] = bool(value)
+        self.save()
+
+    # -- favorites ---------------------------------------------------------
+    def favorites(self) -> list[str]:
+        return list(self._data.get("favorites", []))
+
+    def is_favorite(self, entry: str) -> bool:
+        return entry in self._data.get("favorites", [])
+
+    def toggle_favorite(self, entry: str) -> None:
+        if not entry:
+            return
+        favs = self._data.setdefault("favorites", [])
+        if entry in favs:
+            favs.remove(entry)
+        else:
+            favs.append(entry)
+        self.save()
+
+    # -- ordering ----------------------------------------------------------
+    def order(self) -> list[str] | None:
+        return self._data.get("order")
+
+    def set_order(self, order: list[str]) -> None:
+        self._data["order"] = order
+        self.save()

desktopenvs/hyprlua/astal-menu/style/_colors.css

@@ -0,0 +1,8 @@
+/* Generated from ~/Dotfiles/colors.conf by apply-theme.sh — do not hand-edit the
+ * hex values; edit colors.conf and re-run apply-theme.sh. (Kept in sync via the
+ * sed pipeline in USER_FILES; these defaults are the CyberQueer palette.) */
+@define-color text   #D6ABAB;
+@define-color bg     #1A1A1A;
+@define-color accent #E40046;
+@define-color violet #5018DD;
+@define-color danger #F50505;

desktopenvs/hyprlua/astal-menu/style/style.css

@@ -0,0 +1,261 @@
+/* astal-menu — CyberQueer theme. Colours come from _colors.css (@text/@bg/@accent/
+ * @violet/@danger). Mirrors the existing bar idiom: Agave Nerd Font Mono, 3px
+ * borders, ~25px pill radii. Touch-friendly hit targets throughout. */
+
+* {
+  font-family: "Agave Nerd Font Mono", monospace;
+  font-size: 13pt;
+}
+
+/* ---- window / letterbox --------------------------------------------- */
+/* The CyberQueer GTK theme paints `* { background-color: #1a1a1a }` on EVERY node,
+ * which fills the gaps between modules with a solid slab. Each module carries its
+ * own drawn (Cairo) card background via bordered(fill_bg=True), so blank the
+ * structural container nodes here to let the desktop show between the floating
+ * modules. `drawingarea` is the bordered() ring canvas — transparent so only its
+ * Cairo-drawn rounded fill shows, not a full-bleed square. */
+window,
+window.background,
+.menu-window,
+#menu-window,
+.panel,
+#panel-root,
+overlay,
+revealer,
+grid,
+scrolledwindow,
+viewport,
+drawingarea {
+  background: transparent;
+  background-color: transparent;
+}
+
+#backdrop {
+  background: alpha(black, 0.25);
+}
+
+/* Letterbox margins are set in code (window.py) as a fraction of the monitor so
+ * the inset scales per display; this box just carries the panel background. */
+
+/* ---- quad grid + cards ---------------------------------------------- */
+.quad-grid.dimmed {
+  opacity: 0.15;
+}
+
+/* bouncy pop when a quad expands (added in ui/quadgrid.py on expand) */
+@keyframes quad-pop {
+  0%   { transform: scale(0.82); opacity: 0.4; }
+  55%  { transform: scale(1.05); opacity: 1; }
+  78%  { transform: scale(0.985); }
+  100% { transform: scale(1.0); }
+}
+.quad-pop { animation: quad-pop 300ms ease-out; }
+
+/* bouncy pop-expand for the app drawer (added in ui/appdrawer.py on expand) */
+@keyframes drawer-pop {
+  0%   { transform: scale(0.90); opacity: 0.45; }
+  60%  { transform: scale(1.025); opacity: 1; }
+  82%  { transform: scale(0.995); }
+  100% { transform: scale(1.0); }
+}
+.drawer-pop { animation: drawer-pop 280ms ease-out; }
+
+.quad-card { min-height: 100px; }
+.section-title { color: @text; font-weight: bold; opacity: 0.85; }
+
+/* The single module border + background is drawn with Cairo by bordered(fill_bg=True)
+ * (see lib/border.py); the CSS border/background here would render a second,
+ * concentric ring now that the app stylesheet sits above the theme, so only keep
+ * the inner content padding. */
+.quad-card,
+.quad-expanded,
+.appdrawer,
+.taskbar,
+.favorites {
+  padding: 8px 12px;
+}
+
+.quad-header,
+.appdrawer-header,
+.expanded-header {
+  margin-bottom: 8px;
+}
+
+.quad-title { color: @text; font-weight: bold; }
+.quad-icon  { color: @accent; font-size: 15pt; }
+
+/* minimalist system-stats line (top of the panel) */
+.statsbar { padding: 1px 8px; }
+.statsbar .stat-icon  { color: @accent; font-size: 11pt; }
+.statsbar .stat-value { color: @text; font-size: 10pt; }
+
+.quad-body { color: @text; }
+
+/* pill action buttons */
+.quad-action,
+.enable-btn {
+  color: @text;
+  background: @bg;
+  border: 3px solid @violet;
+  border-radius: 25px;
+  padding: 1px 14px;   /* tight vertically so pills don't waste vertical space */
+  min-height: 22px;
+  min-width: 22px;
+}
+.quad-action:hover,
+.enable-btn:hover { border-color: @accent; color: @accent; }
+.quad-action:active,
+button:checked.quad-action { background: @accent; color: @bg; border-color: @accent; }
+
+/* A MenuButton (the settings cog) wraps an inner `button` node that would render a
+ * second ring inside the outer .quad-action pill — flatten it so only one border
+ * shows. */
+.quad-action > button {
+  border: none;
+  background: transparent;
+  padding: 0;
+  min-width: 0;
+  min-height: 0;
+}
+
+.quad-disabled { color: @text; opacity: 0.7; }
+.enable-btn { border-color: @accent; }
+
+/* settings popover */
+.quad-settings { background: @bg; border: 3px solid @violet; border-radius: 16px; padding: 10px; }
+.switch-row { min-height: 36px; }
+
+.expanded-header .quad-title { font-size: 14pt; }
+
+/* ---- appdrawer ------------------------------------------------------ */
+.appdrawer-search {
+  border: 3px solid @violet;
+  border-radius: 25px;
+  padding: 8px 14px;
+  margin-bottom: 8px;
+  color: @text;
+  background: @bg;
+}
+.appdrawer-search:focus-within { border-color: @accent; }
+
+.app-tile {
+  background: transparent;
+  border: 2px solid transparent;
+  border-radius: 16px;
+  padding: 10px 6px;
+  min-width: 92px;
+}
+.app-tile:hover { border-color: @accent; background: alpha(@violet, 0.18); }
+.app-tile label { color: @text; font-size: 10pt; }
+.fav-star { color: @accent; font-size: 13pt; margin: 2px 4px; }
+
+/* ---- favourites row (top of drawer) --------------------------------- */
+.favorites-row { padding: 4px 0; }
+.fav-tile {
+  background: @bg;
+  border: 2px solid @violet;
+  border-radius: 16px;
+  padding: 6px 12px;
+  min-height: 40px;
+}
+.fav-tile:hover { border-color: @accent; }
+.fav-tile label { color: @text; font-size: 11pt; }
+
+/* ---- taskbar (open windows) ----------------------------------------- */
+.taskbar-row { padding: 4px 0; }
+.task-tile {
+  background: transparent;
+  border: 2px solid transparent;
+  border-radius: 14px;
+  padding: 6px 10px;
+  min-height: 44px;
+  min-width: 44px;
+}
+.task-tile:hover { border-color: @accent; background: alpha(@violet, 0.18); }
+.task-badge {
+  color: @bg; background: @accent;
+  border-radius: 10px; padding: 0 6px; font-size: 9pt;
+}
+.task-popover { background: @bg; border: 3px solid @violet; border-radius: 14px; padding: 6px; }
+.task-window { color: @text; background: transparent; border-radius: 10px; padding: 6px 12px; }
+.task-window:hover { color: @accent; }
+
+/* ---- location map --------------------------------------------------- */
+.map-view { border-radius: 14px; }
+.map-info { color: @text; padding: 6px 2px 0 2px; font-size: 11pt; }
+.map-marker { color: @accent; }
+
+/* ---- weather -------------------------------------------------------- */
+.ansi-view,
+.ansi-view text {
+  background: @bg;
+  color: @text;
+  font-family: "Agave Nerd Font Mono", monospace;
+  font-size: 11pt;
+  padding: 4px;
+}
+.weather-status { color: @text; opacity: 0.7; }
+
+/* ---- bluetooth / network shared rows -------------------------------- */
+.bt-row,
+.net-row {
+  padding: 4px 6px;
+  border-radius: 12px;
+  min-height: 30px;
+}
+.bt-row:hover,
+.net-row:hover { background: alpha(@violet, 0.15); }
+.bt-status { color: @accent; font-size: 10pt; }
+.bt-status.bt-failed { color: @danger; }
+.bt-history label,
+.net-ip { color: @text; opacity: 0.85; font-size: 11pt; }
+
+.net-switcher { margin-bottom: 8px; }
+.net-adapter { padding: 4px 0; }
+.net-adapter > box { padding-left: 6px; }
+.net-entry {
+  border: 2px solid @violet;
+  border-radius: 12px;
+  padding: 6px 10px;
+  color: @text;
+  background: @bg;
+}
+.net-entry:focus-within { border-color: @accent; }
+.pubip { color: @accent; font-size: 15pt; }
+
+/* switches: fixed pill with a bordered round knob (the reset theme leaves them
+ * shapeless otherwise) */
+switch {
+  min-width: 48px;
+  min-height: 26px;
+  border: 2px solid @violet;
+  border-radius: 15px;
+  background: @bg;
+  padding: 0;
+}
+switch:checked { background: @accent; border-color: @accent; }
+switch > slider {
+  min-width: 18px;
+  min-height: 18px;
+  margin: 2px;
+  border-radius: 50%;
+  border: 1px solid @violet;
+  background: @text;
+}
+switch:checked > slider { border-color: @accent; }
+scrollbar slider { background: @violet; border-radius: 8px; min-width: 6px; }
+scrollbar slider:hover { background: @accent; }
+
+/* module frames — Gtk.Frame paints borders reliably where boxes do not */
+.module-frame { border: 3px solid @accent; border-radius: 16px; background: @bg; }
+.module-frame > box { padding: 10px 12px; }
+
+/* floating panel + close button */
+.panel { padding: 2px; }
+.close-btn {
+  color: @text; background: @bg;
+  border: none; border-radius: 20px;
+  min-width: 34px; min-height: 34px;
+  margin: 16px 20px;   /* keep it clear of the module's drawn border */
+}
+.close-btn:hover { background: @accent; color: @bg; }

desktopenvs/hyprlua/astal-menu/theme.py

@@ -0,0 +1,35 @@
+"""Load the two stylesheets as ordered CSS providers.
+
+_colors.css (generated from ~/Dotfiles/colors.conf by apply-theme.sh) defines the
+five CyberQueer @define-color names; style.css consumes them. They are loaded as
+two separate providers rather than via @import, because GTK4 resolves @import
+paths unreliably.
+
+Priority is USER+1, not APPLICATION: the CyberQueer GTK theme is installed as
+~/.config/gtk-4.0/gtk.css (a symlink), which GTK4 loads at PRIORITY_USER (800) —
+above APPLICATION (600). Its aggressive `* { background-color: #1a1a1a }` would
+otherwise beat our rules (e.g. the transparent structural containers that let the
+modules float), so we must sit just above the user-level theme.
+"""
+
+from __future__ import annotations
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+from gi.repository import Gdk, Gtk  # noqa: E402
+
+from paths import STYLE_DIR
+
+
+def load_css() -> None:
+    display = Gdk.Display.get_default()
+    for name in ("_colors.css", "style.css"):
+        path = STYLE_DIR / name
+        if not path.exists():
+            continue
+        provider = Gtk.CssProvider()
+        provider.load_from_path(str(path))
+        Gtk.StyleContext.add_provider_for_display(
+            display, provider, Gtk.STYLE_PROVIDER_PRIORITY_USER + 1
+        )

desktopenvs/hyprlua/astal-menu/ui/appdrawer.py

@@ -0,0 +1,175 @@
+"""Section 5: the full-width application drawer that replaces nwg-drawer.
+
+Top to bottom: a favourites row (full-width module), then search, then a FlowBox of
+all apps. Collapsed it is a bottom strip; expanded it fills down to the bottom.
+Right-click / long-press an app tile to pin or unpin it from favourites.
+"""
+
+from __future__ import annotations
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+gi.require_version("AstalApps", "0.1")
+from gi.repository import AstalApps, GLib, Gtk  # noqa: E402
+
+from ui.favorites import Favorites, add_pin_gestures
+
+_STRIP_HEIGHT = 150  # collapsed grid height (logical px)
+
+
+class AppDrawer(Gtk.Box):
+    def __init__(self, settings, on_launch, on_toggle_expand):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL, spacing=8)
+        self.add_css_class("appdrawer")
+        self.settings = settings
+        self._on_launch = on_launch
+        self._on_toggle_expand = on_toggle_expand
+        self._apps = AstalApps.Apps()
+        self._expanded = False
+
+        self.favorites = Favorites(settings, on_launch)
+        self.append(self.favorites)
+        self.append(Gtk.Separator())
+
+        self.append(self._build_header())
+
+        self._search = Gtk.SearchEntry(placeholder_text="Search applications")
+        self._search.add_css_class("appdrawer-search")
+        self._search.connect("search-changed", self._on_search)
+        self.append(self._search)
+
+        self._flow = Gtk.FlowBox(
+            selection_mode=Gtk.SelectionMode.NONE, homogeneous=True,
+            min_children_per_line=4, max_children_per_line=12,
+            row_spacing=8, column_spacing=8,
+            valign=Gtk.Align.START)  # keep rows their natural height (no stretch)
+        self._flow.add_css_class("appdrawer-flow")
+        self._flow.connect("child-activated", self._on_child_activated)
+
+        self._scroll = Gtk.ScrolledWindow(
+            hscrollbar_policy=Gtk.PolicyType.NEVER, vexpand=True)
+        self._scroll.set_propagate_natural_height(False)
+        self._scroll.set_child(self._flow)
+        self.append(self._scroll)
+
+        self._apply_mode()
+        self._populate(self._sorted_all())
+        # re-render tiles when favourites change so the pinned star stays in sync
+        settings.subscribe(self._on_settings_changed)
+
+    def _on_settings_changed(self) -> None:
+        # Deferred so we never rebuild the FlowBox from inside a tile's own gesture.
+        GLib.idle_add(lambda: (self._on_search(self._search), False)[1])
+
+    def _build_header(self) -> Gtk.Widget:
+        header = Gtk.CenterBox()
+        header.add_css_class("appdrawer-header")
+        title = Gtk.Label(label="Applications", xalign=0.0)
+        title.add_css_class("section-title")
+        header.set_start_widget(title)
+        self._expand_btn = Gtk.Button(label="")  # nf-fa-expand (uniform with quad expand)
+        self._expand_btn.add_css_class("quad-action")
+        self._expand_btn.set_tooltip_text("Expand")
+        self._expand_btn.connect("clicked", lambda *_: self._toggle_expand())
+        header.set_end_widget(self._expand_btn)
+        return header
+
+    # -- expansion ---------------------------------------------------------
+    def _apply_mode(self) -> None:
+        if self._expanded:
+            self.set_vexpand(True)
+            self._scroll.set_min_content_height(_STRIP_HEIGHT)
+            self._scroll.set_max_content_height(100000)
+            self._expand_btn.set_label("")   # nf-fa-compress
+        else:
+            self.set_vexpand(False)
+            self._scroll.set_min_content_height(_STRIP_HEIGHT)
+            self._scroll.set_max_content_height(_STRIP_HEIGHT)
+            self._expand_btn.set_label("")   # nf-fa-expand
+
+    def _pop(self) -> None:
+        # bouncy scale pop on the app grid when the drawer expands; cleared after the
+        # animation so a re-layout (tiles loading) can't restart it into a loop.
+        self._scroll.add_css_class("drawer-pop")
+        GLib.timeout_add(320, self._clear_pop)
+
+    def _clear_pop(self) -> bool:
+        self._scroll.remove_css_class("drawer-pop")
+        return GLib.SOURCE_REMOVE
+
+    def _toggle_expand(self) -> None:
+        self._expanded = not self._expanded
+        self._apply_mode()
+        if self._expanded:
+            self._pop()
+        self._on_toggle_expand(self._expanded)
+
+    def set_expanded(self, value: bool) -> None:
+        if value != self._expanded:
+            self._toggle_expand()
+
+    # -- data --------------------------------------------------------------
+    def _sorted_all(self) -> list:
+        apps = list(self._apps.get_list())
+        apps.sort(key=lambda a: (-a.get_frequency(), a.get_name().lower()))
+        return apps
+
+    def _on_search(self, entry: Gtk.SearchEntry) -> None:
+        text = entry.get_text().strip()
+        results = self._apps.fuzzy_query(text) if text else self._sorted_all()
+        self._populate(results)
+
+    def _populate(self, apps: list) -> None:
+        child = self._flow.get_first_child()
+        while child:
+            self._flow.remove(child)
+            child = self._flow.get_first_child()
+        for app in apps:
+            self._flow.append(self._app_button(app))
+
+    def _app_button(self, app) -> Gtk.Widget:
+        btn = Gtk.Button(valign=Gtk.Align.START)
+        btn.add_css_class("app-tile")
+        btn.app = app
+        overlay = Gtk.Overlay()
+        content = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6)
+        icon = Gtk.Image.new_from_icon_name(app.get_icon_name() or "application-x-executable")
+        icon.set_pixel_size(48)
+        label = Gtk.Label(label=app.get_name(), ellipsize=3, max_width_chars=12,
+                          justify=Gtk.Justification.CENTER)
+        content.append(icon)
+        content.append(label)
+        overlay.set_child(content)
+        # a star marks pinned apps (visible only when favourited)
+        star = Gtk.Label(label="★")
+        star.add_css_class("fav-star")
+        star.set_halign(Gtk.Align.END)
+        star.set_valign(Gtk.Align.START)
+        star.set_visible(self.settings.is_favorite(app.get_entry()))
+        overlay.add_overlay(star)
+        btn.set_child(overlay)
+        btn.connect("clicked", lambda *_: self._launch(app))
+        add_pin_gestures(btn, lambda: self._toggle_fav(app))
+        return btn
+
+    def _toggle_fav(self, app) -> None:
+        self.settings.toggle_favorite(app.get_entry())
+
+    def _on_child_activated(self, _flow, child) -> None:
+        btn = child.get_child()
+        if btn and getattr(btn, "app", None):
+            self._launch(btn.app)
+
+    def _launch(self, app) -> None:
+        try:
+            app.launch()
+        except Exception:
+            pass
+        self._on_launch()
+
+    def on_show(self) -> None:
+        self._search.set_text("")
+        self._populate(self._sorted_all())
+        self.favorites.refresh()
+        self._search.grab_focus()

desktopenvs/hyprlua/astal-menu/ui/favorites.py

@@ -0,0 +1,106 @@
+"""Full-width favourites row at the top of the app drawer.
+
+Shows pinned apps (settings["favorites"], a list of .desktop entry ids). If nothing
+is pinned yet it falls back to the most-frequently-launched apps. Pin/unpin from the
+drawer grid via right-click / long-press.
+"""
+
+from __future__ import annotations
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+gi.require_version("AstalApps", "0.1")
+from gi.repository import AstalApps, Gtk  # noqa: E402
+
+
+def add_pin_gestures(widget: Gtk.Widget, on_toggle) -> None:
+    """Wire right-click and long-press on `widget` to pin/unpin.
+
+    Uses the CAPTURE phase and claims the sequence so the gesture fires reliably on a
+    Gtk.Button (whose own primary-click gesture would otherwise swallow it) and does
+    not also trigger the button's launch action."""
+    def fire(gesture, *_a) -> None:
+        on_toggle()
+        gesture.set_state(Gtk.EventSequenceState.CLAIMED)
+
+    rclick = Gtk.GestureClick(button=3)
+    rclick.set_propagation_phase(Gtk.PropagationPhase.CAPTURE)
+    rclick.connect("pressed", fire)
+    widget.add_controller(rclick)
+
+    longpress = Gtk.GestureLongPress()
+    longpress.set_touch_only(False)
+    longpress.set_propagation_phase(Gtk.PropagationPhase.CAPTURE)
+    longpress.connect("pressed", fire)
+    widget.add_controller(longpress)
+
+
+class Favorites(Gtk.Box):
+    def __init__(self, settings, on_launch):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL)
+        self.add_css_class("favorites")
+        self.settings = settings
+        self._on_launch = on_launch
+        self._apps = AstalApps.Apps()
+
+        title = Gtk.Label(label="Favorites", xalign=0.0)
+        title.add_css_class("section-title")
+        self.append(title)
+
+        self._row = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
+        self._row.add_css_class("favorites-row")
+        scroller = Gtk.ScrolledWindow(
+            vscrollbar_policy=Gtk.PolicyType.NEVER,
+            hscrollbar_policy=Gtk.PolicyType.AUTOMATIC)
+        scroller.set_child(self._row)
+        self.append(scroller)
+
+        settings.subscribe(self.refresh)
+        self.refresh()
+
+    def _by_entry(self) -> dict:
+        return {a.get_entry(): a for a in self._apps.get_list() if a.get_entry()}
+
+    def _resolve(self) -> list:
+        by_entry = self._by_entry()
+        entries = self.settings.favorites()
+        if entries:
+            return [by_entry[e] for e in entries if e in by_entry]
+        # fallback: most-used apps
+        apps = sorted(self._apps.get_list(), key=lambda a: -a.get_frequency())
+        return [a for a in apps if a.get_frequency() > 0][:8]
+
+    def refresh(self) -> None:
+        child = self._row.get_first_child()
+        while child:
+            self._row.remove(child)
+            child = self._row.get_first_child()
+        apps = self._resolve()
+        if not apps:
+            self._row.append(Gtk.Label(label="Right-click an app below to pin it",
+                                       xalign=0.0))
+            return
+        for app in apps:
+            self._row.append(self._tile(app))
+
+    def _tile(self, app) -> Gtk.Widget:
+        btn = Gtk.Button()
+        btn.add_css_class("fav-tile")
+        content = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
+        icon = Gtk.Image.new_from_icon_name(app.get_icon_name() or "application-x-executable")
+        icon.set_pixel_size(28)
+        content.append(icon)
+        content.append(Gtk.Label(label=app.get_name(), ellipsize=3, max_width_chars=14))
+        btn.set_child(content)
+        btn.connect("clicked", lambda *_a: self._launch(app))
+        # right-click / long-press unpins
+        add_pin_gestures(btn, lambda: self.settings.toggle_favorite(app.get_entry()))
+        return btn
+
+    def _launch(self, app) -> None:
+        try:
+            app.launch()
+        except Exception:
+            pass
+        self._on_launch()

desktopenvs/hyprlua/astal-menu/ui/quadcard.py

@@ -0,0 +1,158 @@
+"""Generic chrome around any module: a header (icon, title, expand, settings) and
+a body that is either the module's compact widget or an 'enable me' placeholder.
+
+A disabled quad never calls the module's build(), so a disabled Bluetooth/Network
+quad spawns no backend work at all.
+"""
+
+from __future__ import annotations
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+from gi.repository import Gtk  # noqa: E402
+
+from module_base import ModuleContext, ModuleInstance, ModuleSpec
+
+
+class QuadCard(Gtk.Box):
+    def __init__(self, spec: ModuleSpec, settings, services,
+                 request_expand, request_collapse):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL)
+        self.add_css_class("quad-card")
+        self.spec = spec
+        self.settings = settings
+        self.services = services
+        self.ctx = ModuleContext(spec, settings, services, request_expand, request_collapse)
+        self.instance: ModuleInstance | None = None
+
+        self._header = self._build_header()
+        self.append(self._header)
+
+        self._body_holder = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
+        self._body_holder.add_css_class("quad-body")
+        self._body_holder.set_vexpand(True)
+        self.append(self._body_holder)
+
+        self._features: dict[str, bool] = {}
+        self._rebuild_body()
+
+    # -- header ------------------------------------------------------------
+    def _build_header(self) -> Gtk.Widget:
+        header = Gtk.CenterBox()
+        header.add_css_class("quad-header")
+
+        title = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
+        icon = Gtk.Label(label=self.spec.icon)
+        icon.add_css_class("quad-icon")
+        name = Gtk.Label(label=self.spec.title, xalign=0.0)
+        name.add_css_class("quad-title")
+        title.append(icon)
+        title.append(name)
+        header.set_start_widget(title)
+
+        actions = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=4)
+        self._expand_btn = Gtk.Button(label="")  # nf-fa-expand
+        self._expand_btn.add_css_class("quad-action")
+        self._expand_btn.set_tooltip_text("Expand")
+        self._expand_btn.connect("clicked", lambda *_: self.ctx.expand())
+        actions.append(self._build_settings_button())
+        actions.append(self._expand_btn)
+        header.set_end_widget(actions)
+        return header
+
+    def _build_settings_button(self) -> Gtk.Widget:
+        btn = Gtk.MenuButton(label="")  # nf-fa-cog
+        btn.add_css_class("quad-action")
+        btn.set_tooltip_text("Settings")
+        pop = Gtk.Popover()
+        pop.add_css_class("quad-settings")
+        box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6)
+
+        box.append(self._switch_row("Enabled", self.settings.quad_enabled(
+            self.spec.id, self.spec.default_enabled),
+            lambda v: self.settings.set_quad_enabled(self.spec.id, v)))
+
+        for feat in self.spec.features:
+            box.append(Gtk.Separator())
+            box.append(self._switch_row(
+                feat.label, self.settings.feature(self.spec.id, feat.id, feat.default),
+                lambda v, fid=feat.id: self.settings.set_feature(self.spec.id, fid, v)))
+
+        pop.set_child(box)
+        btn.set_popover(pop)
+        return btn
+
+    @staticmethod
+    def _switch_row(label: str, value: bool, on_change) -> Gtk.Widget:
+        row = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=12)
+        row.add_css_class("switch-row")
+        lbl = Gtk.Label(label=label, xalign=0.0, hexpand=True)
+        sw = Gtk.Switch(active=value, valign=Gtk.Align.CENTER)
+        sw.connect("state-set", lambda _sw, v: (on_change(v), False)[1])
+        row.append(lbl)
+        row.append(sw)
+        return row
+
+    # -- body --------------------------------------------------------------
+    def _clear_body(self) -> None:
+        if self.instance and self.instance.destroy:
+            self.instance.destroy()
+        self.instance = None
+        child = self._body_holder.get_first_child()
+        while child:
+            self._body_holder.remove(child)
+            child = self._body_holder.get_first_child()
+
+    def _rebuild_body(self) -> None:
+        self._clear_body()
+        self._features = self._feature_snapshot()
+        enabled = self.settings.quad_enabled(self.spec.id, self.spec.default_enabled)
+        if enabled:
+            inst = self.spec.build(self.ctx)
+            self.instance = inst
+            self._body_holder.append(inst.compact)
+            self._expand_btn.set_sensitive(inst.expanded is not None)
+        else:
+            self._expand_btn.set_sensitive(False)
+            self._body_holder.append(self._disabled_placeholder())
+
+    def _feature_snapshot(self) -> dict[str, bool]:
+        return {f.id: self.settings.feature(self.spec.id, f.id, f.default)
+                for f in self.spec.features}
+
+    def _disabled_placeholder(self) -> Gtk.Widget:
+        box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=10,
+                      valign=Gtk.Align.CENTER, halign=Gtk.Align.CENTER)
+        box.add_css_class("quad-disabled")
+        box.append(Gtk.Label(label=f"{self.spec.title} is off"))
+        btn = Gtk.Button(label="Enable")
+        btn.add_css_class("enable-btn")
+        btn.connect("clicked",
+                    lambda *_: self.settings.set_quad_enabled(self.spec.id, True))
+        box.append(btn)
+        return box
+
+    # -- lifecycle ---------------------------------------------------------
+    def on_settings_changed(self) -> None:
+        """Called by the grid when settings.json changes; rebuild if this quad's
+        enablement flipped or any of its feature toggles changed, so every switch in
+        the settings popover takes effect live (the popover is only reachable while
+        the grid is collapsed, so no expanded view is ever reparented mid-rebuild)."""
+        enabled = self.settings.quad_enabled(self.spec.id, self.spec.default_enabled)
+        has_module = self.instance is not None
+        features_changed = enabled and self._feature_snapshot() != self._features
+        if enabled != has_module or features_changed:
+            self._rebuild_body()
+
+    @property
+    def expanded_widget(self) -> Gtk.Widget | None:
+        return self.instance.expanded if self.instance else None
+
+    def on_show(self) -> None:
+        if self.instance and self.instance.on_show:
+            self.instance.on_show()
+
+    def on_hide(self) -> None:
+        if self.instance and self.instance.on_hide:
+            self.instance.on_hide()

desktopenvs/hyprlua/astal-menu/ui/quadgrid.py

@@ -0,0 +1,148 @@
+"""The 2x2 quad region and its expand-over-the-others behaviour.
+
+A Gtk.Overlay stacks two things in the same space:
+  * base   : a 2x2 Gtk.Grid of QuadCards
+  * overlay: a Revealer that, when a quad expands, fills the whole region (the full
+             content width, covering all four cells) with that module's expanded
+             view wrapped in a small header carrying a collapse button.
+
+Because the overlay fills the region exactly, the expanded quad is as wide as the
+appdrawer below it, and the outer letterbox margins (applied further up the tree)
+are untouched — so letterboxing stays identical in every state.
+"""
+
+from __future__ import annotations
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+from gi.repository import GLib, Gtk  # noqa: E402
+
+from lib.border import bordered
+from module_base import ModuleSpec
+from ui.quadcard import QuadCard
+
+
+class QuadGrid(Gtk.Overlay):
+    def __init__(self, specs: list[ModuleSpec], settings, services):
+        super().__init__()
+        self.add_css_class("quad-region")
+        self.set_vexpand(True)
+        self.settings = settings
+        self._expanded_id: str | None = None
+
+        self.grid = Gtk.Grid(column_homogeneous=True, row_homogeneous=True,
+                             column_spacing=10, row_spacing=10)
+        self.grid.add_css_class("quad-grid")
+        self.set_child(self.grid)
+
+        self.cards: dict[str, QuadCard] = {}
+        for index, spec in enumerate(specs[:4]):
+            card = QuadCard(spec, settings, services,
+                            self.request_expand, self.request_collapse)
+            self.cards[spec.id] = card
+            self.grid.attach(bordered(card, radius=16, fill_bg=True),
+                             index % 2, index // 2, 1, 1)
+
+        # overlay used for the expanded quad
+        self._expand_reveal = Gtk.Revealer(
+            transition_type=Gtk.RevealerTransitionType.CROSSFADE,
+            transition_duration=180, reveal_child=False)
+        self._expand_reveal.set_halign(Gtk.Align.FILL)
+        self._expand_reveal.set_valign(Gtk.Align.FILL)
+        self._expand_holder = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
+        self._expand_holder.add_css_class("quad-expanded")
+        self._expand_card = bordered(self._expand_holder, radius=16, fill_bg=True)
+        self._expand_reveal.set_child(self._expand_card)
+        self.add_overlay(self._expand_reveal)
+        # The overlay's holder is opaque; keep the whole overlay hidden unless a quad
+        # is actually expanded, otherwise it paints over the 2x2 grid.
+        self._expand_reveal.set_visible(False)
+
+        settings.subscribe(self._on_settings_changed)
+
+    # -- expansion ---------------------------------------------------------
+    def request_expand(self, module_id: str) -> None:
+        card = self.cards.get(module_id)
+        if not card or card.instance is None or card.instance.expanded is None:
+            return
+        # A module opts into expansion by supplying a distinct expanded widget
+        # (a separate instance), so no reparenting of the compact cell is needed.
+        content = card.instance.expanded
+        # reparent content into the expanded holder
+        self._clear_expand_holder()
+        self._expand_reveal.set_visible(True)
+        self._expand_holder.append(self._expanded_header(card.spec.title))
+        if card.instance.scroll_expanded:
+            wrap = Gtk.ScrolledWindow(vexpand=True,
+                                      hscrollbar_policy=Gtk.PolicyType.NEVER)
+            wrap.set_child(content)
+            self._expand_holder.append(wrap)
+        else:
+            content.set_vexpand(True)
+            self._expand_holder.append(content)
+        self._expanded_id = module_id
+        self._expand_reveal.set_reveal_child(True)
+        # bouncy scale pop (CSS @keyframes). Keep the class only for the animation's
+        # duration, then drop it: while it's applied, any re-layout of the card (module
+        # content streaming in, the grid updating underneath) restarts the transform
+        # animation, which made the pop loop forever.
+        self._expand_card.add_css_class("quad-pop")
+        GLib.timeout_add(340, self._clear_pop)
+        self.grid.add_css_class("dimmed")
+        card.on_show()
+
+    def _clear_pop(self) -> bool:
+        self._expand_card.remove_css_class("quad-pop")
+        return GLib.SOURCE_REMOVE
+
+    def request_collapse(self) -> None:
+        self._expand_reveal.set_reveal_child(False)
+        self._expand_reveal.set_visible(False)
+        self._expand_card.remove_css_class("quad-pop")  # reset so the pop replays
+        self._expanded_id = None
+        self.grid.remove_css_class("dimmed")
+        # Drop the reference to the reparented widget so the card can reuse it.
+        self._clear_expand_holder()
+
+    def _clear_expand_holder(self) -> None:
+        child = self._expand_holder.get_first_child()
+        while child:
+            # detach any ScrolledWindow's child so it survives for the card
+            if isinstance(child, Gtk.ScrolledWindow):
+                inner = child.get_child()
+                if inner:
+                    child.set_child(None)
+            self._expand_holder.remove(child)
+            child = self._expand_holder.get_first_child()
+
+    def _expanded_header(self, title: str) -> Gtk.Widget:
+        header = Gtk.CenterBox()
+        header.add_css_class("expanded-header")
+        back = Gtk.Button(label="  Back")  # nf arrow
+        back.add_css_class("quad-action")
+        back.connect("clicked", lambda *_: self.request_collapse())
+        header.set_start_widget(back)
+        lbl = Gtk.Label(label=title)
+        lbl.add_css_class("quad-title")
+        header.set_center_widget(lbl)
+        return header
+
+    @property
+    def is_expanded(self) -> bool:
+        return self._expanded_id is not None
+
+    # -- lifecycle ---------------------------------------------------------
+    def _on_settings_changed(self) -> None:
+        for card in self.cards.values():
+            card.on_settings_changed()
+
+    def on_show(self) -> None:
+        for card in self.cards.values():
+            card.on_show()
+
+    def on_hide(self) -> None:
+        if self.is_expanded:
+            self.request_collapse()
+        for card in self.cards.values():
+            card.on_hide()

desktopenvs/hyprlua/astal-menu/ui/statsbar.py

@@ -0,0 +1,133 @@
+"""A minimalist system-stats line for the top of the panel.
+
+CPU / RAM / GPU / disk utilisation plus network up/down rate, refreshed on a timer.
+Everything is read straight from /proc and /sys on the main thread — these are local
+file reads that take microseconds, so no subprocess or worker thread is needed.
+"""
+
+from __future__ import annotations
+
+import glob
+import os
+import time
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+from gi.repository import GLib, Gtk  # noqa: E402
+
+_GPU_FILES = glob.glob("/sys/class/drm/card*/device/gpu_busy_percent")
+_NET_SKIP = ("lo", "docker", "veth", "br-", "virbr", "tun", "tap")
+
+
+def _human(rate: float) -> str:
+    for unit in ("B", "K", "M", "G"):
+        if rate < 1024 or unit == "G":
+            return f"{rate:4.1f}{unit}"
+        rate /= 1024
+    return f"{rate:4.1f}G"
+
+
+class Statsbar(Gtk.Box):
+    def __init__(self):
+        super().__init__(orientation=Gtk.Orientation.HORIZONTAL, spacing=18,
+                         halign=Gtk.Align.CENTER)
+        self.add_css_class("statsbar")
+
+        # short text labels rather than nerd glyphs (some don't exist in the font and
+        # render as tofu); keeps the line legible on any theme.
+        self._cpu = self._cell("CPU")
+        self._ram = self._cell("MEM")
+        self._gpu = self._cell("GPU")
+        self._disk = self._cell("DISK")
+        self._down = self._cell("↓")
+        self._up = self._cell("↑")
+
+        self._prev_cpu: tuple[int, int] | None = None
+        self._prev_net: tuple[int, int] | None = None
+        self._prev_t: float | None = None
+
+        self._refresh()
+        self._source = GLib.timeout_add_seconds(2, self._tick)
+
+    def _cell(self, icon: str) -> Gtk.Label:
+        box = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=6)
+        ic = Gtk.Label(label=icon)
+        ic.add_css_class("stat-icon")
+        val = Gtk.Label(label="…")
+        val.add_css_class("stat-value")
+        box.append(ic)
+        box.append(val)
+        self.append(box)
+        return val
+
+    def _tick(self) -> bool:
+        self._refresh()
+        return GLib.SOURCE_CONTINUE
+
+    # -- readers -----------------------------------------------------------
+    @staticmethod
+    def _cpu_pct(prev) -> tuple[float, tuple[int, int]]:
+        parts = [int(x) for x in open("/proc/stat").readline().split()[1:]]
+        idle = parts[3] + parts[4]           # idle + iowait
+        total = sum(parts)
+        if prev is None:
+            return 0.0, (total, idle)
+        dt, di = total - prev[0], idle - prev[1]
+        pct = (1 - di / dt) * 100 if dt > 0 else 0.0
+        return max(0.0, min(100.0, pct)), (total, idle)
+
+    @staticmethod
+    def _ram_pct() -> float:
+        mem = {}
+        for line in open("/proc/meminfo"):
+            k, _, v = line.partition(":")
+            mem[k] = int(v.split()[0])
+            if len(mem) > 4 and "MemAvailable" in mem:
+                break
+        total, avail = mem.get("MemTotal", 1), mem.get("MemAvailable", 0)
+        return (1 - avail / total) * 100
+
+    @staticmethod
+    def _gpu_pct() -> float:
+        best = 0
+        for f in _GPU_FILES:
+            try:
+                best = max(best, int(open(f).read().strip()))
+            except (OSError, ValueError):
+                pass
+        return float(best)
+
+    @staticmethod
+    def _disk_pct() -> float:
+        s = os.statvfs("/")
+        return (1 - s.f_bfree / s.f_blocks) * 100 if s.f_blocks else 0.0
+
+    @staticmethod
+    def _net_bytes() -> tuple[int, int]:
+        rx = tx = 0
+        with open("/proc/net/dev") as fh:
+            for line in fh.readlines()[2:]:
+                name, _, rest = line.partition(":")
+                name = name.strip()
+                if name.startswith(_NET_SKIP):
+                    continue
+                cols = rest.split()
+                rx += int(cols[0])
+                tx += int(cols[8])
+        return rx, tx
+
+    def _refresh(self) -> None:
+        cpu, self._prev_cpu = self._cpu_pct(self._prev_cpu)
+        self._cpu.set_text(f"{cpu:2.0f}%")
+        self._ram.set_text(f"{self._ram_pct():2.0f}%")
+        self._gpu.set_text(f"{self._gpu_pct():2.0f}%")
+        self._disk.set_text(f"{self._disk_pct():2.0f}%")
+
+        now = time.monotonic()
+        rx, tx = self._net_bytes()
+        if self._prev_net is not None and self._prev_t is not None and now > self._prev_t:
+            dt = now - self._prev_t
+            self._down.set_text(_human((rx - self._prev_net[0]) / dt) + "/s")
+            self._up.set_text(_human((tx - self._prev_net[1]) / dt) + "/s")
+        self._prev_net, self._prev_t = (rx, tx), now

desktopenvs/hyprlua/astal-menu/ui/taskbar.py

@@ -0,0 +1,119 @@
+"""Full-width taskbar strip: jump to any open window.
+
+Reads open windows from `hyprctl clients -j`, groups them by app (class). A group
+with a single window focuses it directly; a group with several windows opens a
+pop-out list so you can pick a specific instance. The strip scrolls sideways when
+many apps are open. Focusing a window closes the menu.
+"""
+
+from __future__ import annotations
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+gi.require_version("AstalApps", "0.1")
+from gi.repository import AstalApps, Gtk  # noqa: E402
+
+from lib.proc import run_json, run_text
+
+
+class Taskbar(Gtk.Box):
+    def __init__(self, on_activate):
+        super().__init__(orientation=Gtk.Orientation.VERTICAL)
+        self.add_css_class("taskbar")
+        self._on_activate = on_activate
+        self._apps = AstalApps.Apps()
+        self._wm_index = self._build_wm_index()
+
+        header = Gtk.Label(label="Open windows", xalign=0.0)
+        header.add_css_class("section-title")
+        self.append(header)
+
+        self._row = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
+        self._row.add_css_class("taskbar-row")
+        scroller = Gtk.ScrolledWindow(
+            vscrollbar_policy=Gtk.PolicyType.NEVER,
+            hscrollbar_policy=Gtk.PolicyType.AUTOMATIC)
+        scroller.set_child(self._row)
+        self.append(scroller)
+
+    def _build_wm_index(self) -> dict:
+        idx = {}
+        for app in self._apps.get_list():
+            for key in (app.get_wm_class(), app.get_executable(), app.get_name()):
+                if key:
+                    idx.setdefault(key.lower(), app)
+        return idx
+
+    def _icon_for(self, cls: str) -> str:
+        app = self._wm_index.get((cls or "").lower())
+        if app and app.get_icon_name():
+            return app.get_icon_name()
+        return (cls or "application-x-executable").lower()
+
+    # -- populate ----------------------------------------------------------
+    def refresh(self) -> None:
+        run_json(["hyprctl", "clients", "-j"], self._on_clients)
+
+    def _on_clients(self, ok: bool, data) -> None:
+        child = self._row.get_first_child()
+        while child:
+            self._row.remove(child)
+            child = self._row.get_first_child()
+        if not ok or not isinstance(data, list):
+            self._row.append(Gtk.Label(label="no window data"))
+            return
+        groups: dict[str, list] = {}
+        for w in data:
+            if not w.get("mapped", True) or not w.get("class"):
+                continue
+            groups.setdefault(w["class"], []).append(w)
+        if not groups:
+            self._row.append(Gtk.Label(label="No open windows"))
+            return
+        for cls, wins in sorted(groups.items()):
+            self._row.append(self._group_button(cls, wins))
+
+    def _group_button(self, cls: str, wins: list) -> Gtk.Widget:
+        icon = Gtk.Image.new_from_icon_name(self._icon_for(cls))
+        icon.set_pixel_size(32)
+        if len(wins) == 1:
+            btn = Gtk.Button()
+            btn.add_css_class("task-tile")
+            btn.set_child(icon)
+            btn.set_tooltip_text(wins[0].get("title") or cls)
+            btn.connect("clicked", lambda *_a, w=wins[0]: self._focus(w))
+            return btn
+        # multiple windows -> pop-out list of specific instances
+        btn = Gtk.MenuButton()
+        btn.add_css_class("task-tile")
+        box = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=6)
+        box.append(icon)
+        badge = Gtk.Label(label=str(len(wins)))
+        badge.add_css_class("task-badge")
+        box.append(badge)
+        btn.set_child(box)
+        btn.set_tooltip_text(f"{cls} ({len(wins)})")
+        pop = Gtk.Popover()
+        pop.add_css_class("task-popover")
+        plist = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=4)
+        for w in wins:
+            item = Gtk.Button(label=w.get("title") or cls)
+            item.add_css_class("task-window")
+            item.connect("clicked", lambda *_a, ww=w: (pop.popdown(), self._focus(ww)))
+            plist.append(item)
+        pop.set_child(plist)
+        btn.set_popover(pop)
+        return btn
+
+    def _focus(self, w) -> None:
+        addr = w.get("address")
+        if addr:
+            # This is a hyprlua (Lua-configured Hyprland) setup: `hyprctl dispatch`
+            # evaluates its argument as Lua, so the native `focuswindow address:…`
+            # syntax is a Lua error. Use the hyprlua focus dispatcher, which also
+            # switches to the window's workspace.
+            run_text(["hyprctl", "dispatch",
+                      f'hl.dsp.focus({{ window = "address:{addr}" }})'],
+                     lambda *_a: None)
+        self._on_activate()

desktopenvs/hyprlua/astal-menu/window.py

@@ -0,0 +1,193 @@
+"""The popup: a content-sized floating layer-shell panel anchored top-centre.
+
+Earlier this was a full-monitor overlay with a dim backdrop, but that blocks the
+whole screen — the invisible full-screen surface intercepts every click. Instead the
+window now sizes to its own content and only occupies that area, leaving the rest of
+the screen usable. It is dismissed with the launcher toggle, Esc, or the ✕ button
+(there is no click-outside-to-close, since that would require a blocking full-screen
+surface).
+
+  Gtk.Window (layer TOP, anchored TOP → horizontally centred, height = content)
+    └ Gtk.Overlay
+        main : #panel-root (Taskbar / QuadGrid / AppDrawer, each drawn-bordered)
+        over : ✕ close button (top-right)
+
+Expanding the app drawer additionally anchors the BOTTOM edge so the panel stretches
+down and the drawer fills to the bottom; collapsing removes that anchor.
+"""
+
+from __future__ import annotations
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+gi.require_version("Gdk", "4.0")
+gi.require_version("Gtk4LayerShell", "1.0")
+from gi.repository import Gdk, GLib, Gtk  # noqa: E402
+from gi.repository import Gtk4LayerShell as LayerShell  # noqa: E402
+
+from appservices import Services
+from lib.border import bordered
+from registry import ordered_specs
+from ui.appdrawer import AppDrawer
+from ui.quadgrid import QuadGrid
+from ui.statsbar import Statsbar
+from ui.taskbar import Taskbar
+
+PANEL_WIDTH_FRACTION = 0.5   # of the monitor width...
+MAX_PANEL_WIDTH = 1100       # ...clamped to this
+EDGE_MARGIN = 28             # gap from the anchored edge
+BOTTOM_MARGIN = 34           # gap from the far edge when the drawer is expanded
+SIDES = ("top", "bottom", "left", "right")
+
+
+class MenuWindow(Gtk.ApplicationWindow):
+    def __init__(self, app, settings, services: Services):
+        super().__init__(application=app)
+        self.set_name("menu-window")
+        self.add_css_class("menu-window")
+        self.settings = settings
+        self.services = services
+        self._drawer_expanded = False
+        self._side = "top"
+
+        self._init_layer_shell()
+
+        self.root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=8)
+        self.root.set_name("panel-root")
+        self.root.add_css_class("panel")
+
+        # minimalist system-stats line (full-width, very top)
+        self.statsbar = Statsbar()
+        self.statsbar_reveal = Gtk.Revealer(
+            transition_type=Gtk.RevealerTransitionType.SLIDE_DOWN,
+            transition_duration=160, reveal_child=True)
+        self.statsbar_reveal.set_child(bordered(self.statsbar, border=2, radius=12, fill_bg=True))
+        self.root.append(self.statsbar_reveal)
+
+        # taskbar (full-width, top)
+        self.taskbar = Taskbar(on_activate=self.hide_menu)
+        self.taskbar_reveal = Gtk.Revealer(
+            transition_type=Gtk.RevealerTransitionType.SLIDE_DOWN,
+            transition_duration=160, reveal_child=True)
+        self.taskbar_reveal.set_child(bordered(self.taskbar, fill_bg=True))
+        self.root.append(self.taskbar_reveal)
+
+        # quads
+        specs = list(ordered_specs(settings))
+        self.grid = QuadGrid(specs, settings, services)
+        self.quad_reveal = Gtk.Revealer(
+            transition_type=Gtk.RevealerTransitionType.SLIDE_UP,
+            transition_duration=200, reveal_child=True)
+        self.quad_reveal.set_child(self.grid)
+        self.root.append(self.quad_reveal)
+
+        # appdrawer
+        self.appdrawer = AppDrawer(settings, on_launch=self.hide_menu,
+                                   on_toggle_expand=self._on_appdrawer_expand)
+        self.appdrawer_wrap = bordered(self.appdrawer, fill_bg=True)
+        self.appdrawer_wrap.set_valign(Gtk.Align.FILL)
+        self.root.append(self.appdrawer_wrap)
+
+        overlay = Gtk.Overlay()
+        overlay.set_child(self.root)
+        close = Gtk.Button(label="✕")
+        close.add_css_class("close-btn")
+        close.set_halign(Gtk.Align.END)
+        close.set_valign(Gtk.Align.START)
+        close.connect("clicked", lambda *_: self.hide_menu())
+        overlay.add_overlay(close)
+        self.set_child(overlay)
+
+        key = Gtk.EventControllerKey()
+        key.connect("key-pressed", self._on_key)
+        self.add_controller(key)
+
+        self.connect("map", lambda *_: self._apply_size())
+        self.set_visible(False)
+
+    # -- layer shell / size -----------------------------------------------
+    def _init_layer_shell(self) -> None:
+        LayerShell.init_for_window(self)
+        LayerShell.set_layer(self, LayerShell.Layer.TOP)
+        LayerShell.set_namespace(self, "astal-menu")
+        LayerShell.set_keyboard_mode(self, LayerShell.KeyboardMode.ON_DEMAND)
+        self._apply_anchor()
+
+    def set_side(self, side: str) -> None:
+        """Anchor the panel to the given monitor edge ('top'|'bottom'|'left'|'right').
+        The compositor's layer 'slide' animation then slides it in from that edge, and
+        the panel sits flush against it. Set before showing so the map animates."""
+        if side in SIDES:
+            self._side = side
+            self._apply_anchor()
+
+    def _apply_anchor(self) -> None:
+        """Pin the panel to its side edge; while the drawer is expanded, also pin the
+        perpendicular edges so it fills the screen height."""
+        E = LayerShell.Edge
+        for edge in (E.TOP, E.BOTTOM, E.LEFT, E.RIGHT):
+            LayerShell.set_anchor(self, edge, False)
+            LayerShell.set_margin(self, edge, 0)
+        primary = {"top": E.TOP, "bottom": E.BOTTOM, "left": E.LEFT, "right": E.RIGHT}[self._side]
+        LayerShell.set_anchor(self, primary, True)
+        LayerShell.set_margin(self, primary, EDGE_MARGIN)
+        if self._drawer_expanded:
+            # fill vertically so the expanded drawer reaches top and bottom
+            for edge in (E.TOP, E.BOTTOM):
+                LayerShell.set_anchor(self, edge, True)
+                if edge != primary:
+                    LayerShell.set_margin(self, edge, BOTTOM_MARGIN)
+
+    def _monitor_width(self) -> int:
+        display = Gdk.Display.get_default()
+        surface = self.get_surface()
+        mon = display.get_monitor_at_surface(surface) if surface is not None else None
+        if mon is None:
+            monitors = display.get_monitors()
+            mon = monitors.get_item(0) if monitors.get_n_items() else None
+        return mon.get_geometry().width if mon is not None else 1920
+
+    def _apply_size(self) -> None:
+        width = min(int(self._monitor_width() * PANEL_WIDTH_FRACTION), MAX_PANEL_WIDTH)
+        self.root.set_size_request(width, -1)
+
+    # -- appdrawer expansion ----------------------------------------------
+    def _on_appdrawer_expand(self, expanded: bool) -> None:
+        self._drawer_expanded = expanded
+        self._apply_anchor()
+        # Hide (not just un-reveal) the stats/taskbar/quads so they reserve zero space
+        # and the drawer fills the whole panel.
+        for rev in (self.statsbar_reveal, self.quad_reveal, self.taskbar_reveal):
+            rev.set_reveal_child(not expanded)
+            rev.set_visible(not expanded)
+        self.appdrawer_wrap.set_vexpand(expanded)
+
+    # -- visibility --------------------------------------------------------
+    def show_menu(self, focus_appdrawer: bool = False) -> None:
+        self.appdrawer.set_expanded(False)
+        self.taskbar.refresh()
+        self.grid.on_show()
+        self.appdrawer.on_show()
+        self.set_visible(True)
+        self.present()
+        GLib.timeout_add(30, lambda: (self._apply_size(), False)[1])
+        if focus_appdrawer:
+            self.appdrawer.set_expanded(True)
+
+    def hide_menu(self) -> None:
+        self.grid.on_hide()
+        self.appdrawer.set_expanded(False)
+        self.set_visible(False)
+
+    def toggle(self, focus_appdrawer: bool = False) -> None:
+        if self.get_visible():
+            self.hide_menu()
+        else:
+            self.show_menu(focus_appdrawer)
+
+    def _on_key(self, _c, keyval, _kc, _state) -> bool:
+        if keyval == Gdk.KEY_Escape:
+            self.hide_menu()
+            return True
+        return False

desktopenvs/hyprlua/config-updater/updater.conf

@@ -11,14 +11,13 @@ SOURCE_BASE = ~/Dotfiles/desktopenvs/hyprlua
 
 # ── deployed as ~/.config/<name> ─────────────────────────────────────────────
 config alacritty
+config astal-menu
 config btop
 config dunst
 config gtk-3.0
 config hypr except usr
 config kitty
 config mimeapps.list
-config nwg-dock-hyprland
-config nwg-drawer
 config nwg-panel
 config scripts
 config ulauncher

desktopenvs/hyprlua/eww-nobattery/eww.scss

@@ -102,3 +102,12 @@ menuitem {
 menuitem:hover {
   color: #E40046;
 }
+
+// astal-menu launcher button — accent-coloured icon, highlight on hover
+.menu-launcher {
+  color: #E40046;
+  font-size: 15pt;
+}
+.menu-launcher:hover {
+  color: #5018dd;
+}

desktopenvs/hyprlua/eww-nobattery/eww.yuck

@@ -20,8 +20,10 @@
 
 (defwidget winsworks [monitor]
 	(box :orientation "h" :space-evenly false :halign "start"
+		; astal-menu launcher — opens the popup control centre / app drawer
+		(button :class "music menu-launcher" :onclick "~/.config/scripts/menu-toggle.sh" {""})
 		(workspaceWidget :monitor monitor)
-		(button :onclick "~/Dotfiles/desktopenvs/hyprland/scripts/drawer.sh" :class "music" {" ${activewindow}"})
+		(button :onclick "~/.config/scripts/menu-toggle.sh" :class "music" {" ${activewindow}"})
         	)
 )
 

desktopenvs/hyprlua/eww-touch/eww.yuck

@@ -26,7 +26,7 @@
 	(box :orientation "h" :space-evenly false :halign "start"
 		(osk)
 		(box :class "music" {"${battery}"})
-		(button :onclick "~/.config/scripts/drawer.sh" :class "icon-btn" :valign "center" :width 26 :height 26 {""})
+		(button :onclick "~/.config/scripts/menu-toggle.sh" :class "icon-btn" :valign "center" :width 26 :height 26 {""})
 		(metric :label "󰓃 "
 		:value volume
 		:onchange "pactl set-sink-volume @DEFAULT_SINK@ {}%"

desktopenvs/hyprlua/eww/eww.scss

@@ -102,3 +102,12 @@ menuitem {
 menuitem:hover {
   color: #E40046;
 }
+
+// astal-menu launcher button — accent-coloured icon, highlight on hover
+.menu-launcher {
+  color: #E40046;
+  font-size: 15pt;
+}
+.menu-launcher:hover {
+  color: #5018dd;
+}

desktopenvs/hyprlua/eww/eww.yuck

@@ -54,12 +54,14 @@
 ; :halign "start" — left-aligns the content within the centerbox left cell.
 (defwidget winsworks [monitor]
 	(box :orientation "h" :space-evenly false :halign "start"
+		; astal-menu launcher — opens the popup control centre / app drawer
+		(button :class "music menu-launcher" :onclick "~/.config/scripts/menu-toggle.sh" {""})
 		; Battery percentage badge — styled as a pill with class "music"
 		(box :class "music" {"${battery}"})
 		; Workspace dots — one button per active workspace on this monitor
 		(workspaceWidget :monitor monitor)
 		; Active window title — clicking opens the application drawer
-		(button :onclick "~/Dotfiles/desktopenvs/hyprland/scripts/drawer.sh" :class "music" {" ${activewindow}"})
+		(button :onclick "~/.config/scripts/menu-toggle.sh" :class "music" {" ${activewindow}"})
         	)
 )
 

desktopenvs/hyprlua/hypr/hyprland.lua

@@ -207,6 +207,13 @@ hl.animation({ leaf = "fade",             enabled = true, speed = 7,  bezier = "
 -- from regular workspace transitions which use horizontal slides by default.
 hl.animation({ leaf = "specialWorkspace", enabled = true, speed = 10, bezier = "default",  style = "slidevert" })
 
+-- Layer-shell surfaces (the astal-menu control centre, notifications, the bar) slide
+-- in from their anchored edge with the bouncy myBezier curve, so opening the menu
+-- reads as a springy slide-down rather than a plain fade. (A per-namespace layerrule
+-- was tried but this hyprlua build doesn't honour its animation timing; the global
+-- `layers` leaf does.)
+hl.animation({ leaf = "layers",           enabled = true, speed = 5,  bezier = "myBezier", style = "slide" })
+
 --------------
 ---- DEVICE ---
 --------------

desktopenvs/hyprlua/hypr/usr/autostart.lua

@@ -16,12 +16,16 @@ hl.on("hyprland.start", function()
     hl.exec_cmd("[workspace special:magic silent] kitty")
     hl.exec_cmd("hyprctl setcursor Nordzy-cursors-lefthand 50")
     hl.exec_cmd("hyprpaper")
-    hl.exec_cmd("nwg-dock-hyprland -c ~/.config/scripts/drawer.sh -mt 50 -i 25 -r -s style.css -p right")
+    hl.exec_cmd("bash ~/Dotfiles/desktopenvs/hyprlua/scripts/astal-menu-start.sh")
     hl.exec_cmd("blueman-applet")
     hl.exec_cmd("blueman-tray")
     hl.exec_cmd("hypridle")
-    hl.exec_cmd("bash ~/Dotfiles/desktopenvs/hyprlua/scripts/presence-detect.sh")
+    -- hl.exec_cmd("bash ~/Dotfiles/desktopenvs/hyprlua/scripts/presence-detect.sh")
     hl.exec_cmd("chamel")
     hl.exec_cmd("ydotoold")
     hl.exec_cmd("opendeck")
+
+    -- Reload once everything has spawned so layer-shell clients (bar, astal-menu)
+    -- pick up the final monitor/config state.
+    hl.exec_cmd("sleep 1 && hyprctl reload")
 end)

desktopenvs/hyprlua/hypr/usr/binds.lua

@@ -209,15 +209,11 @@ hl.bind(mainMod .. " + SHIFT + ALT + k",     hl.dsp.group.move_window("u"))
 hl.bind(mainMod .. " + SHIFT + ALT + j",     hl.dsp.group.move_window("d"))
 
 --------------------
----- NWG-DOCK ------
+---- ASTAL-MENU ----
 --------------------
 
-hl.bind(mainMod .. " + SHIFT + W", hl.dsp.exec_cmd("killall nwg-dock-hyprland; nwg-dock-hyprland -c ~/.config/scripts/drawer.sh -mt 50 -i 25 -r -s style.css -p left"))
-hl.bind(mainMod .. " + SHIFT + E", hl.dsp.exec_cmd("killall nwg-dock-hyprland; nwg-dock-hyprland -c ~/.config/scripts/drawer.sh -mt 50 -i 25 -r -s style.css -p right"))
-hl.bind(mainMod .. " + SHIFT + S", hl.dsp.exec_cmd("killall nwg-dock-hyprland; nwg-dock-hyprland -c ~/.config/scripts/drawer.sh -mt 50 -i 25 -r -s style.css -p top"))
-hl.bind(mainMod .. " + SHIFT + D", hl.dsp.exec_cmd("killall nwg-dock-hyprland; nwg-dock-hyprland -c ~/.config/scripts/drawer.sh -mt 50 -i 25 -r -s style.css -p bottom"))
-hl.bind(mainMod .. " + D",         hl.dsp.exec_cmd("killall nwg-dock-hyprland || nwg-dock-hyprland -c ~/.config/scripts/drawer.sh -mt 50 -i 25 -r -s style.css -p bottom"), { release = true })
-hl.bind(mainMod .. " + SHIFT + A", hl.dsp.exec_cmd("~/.config/scripts/drawer.sh"))
+hl.bind(mainMod .. " + D",         hl.dsp.exec_cmd("~/.config/scripts/menu-toggle.sh toggle top"), { release = true })
+hl.bind(mainMod .. " + SHIFT + A", hl.dsp.exec_cmd("~/.config/scripts/menu-toggle.sh appdrawer"))
 
 --------------------
 ---- SCREENSHOT ----

desktopenvs/hyprlua/scripts/astal-menu-start.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Resident launcher for the astal-menu GTK4 popup control centre.
+#
+# gtk4-layer-shell must be loaded before libwayland-client; when the shell is used
+# through PyGObject that ordering isn't guaranteed, so we LD_PRELOAD it (the library
+# itself documents this workaround). main.py drops LD_PRELOAD from its environment
+# right after startup so the apps it launches don't inherit it (Firefox, for one,
+# crashes with libgtk4-layer-shell preloaded). Starts the daemon hidden — it shows
+# only when menu-toggle.sh forwards a --toggle/--show/--appdrawer verb.
+
+APP="${HOME}/.config/astal-menu/main.py"
+SO="$(ldconfig -p 2>/dev/null | awk '/libgtk4-layer-shell\.so/ {print $NF; exit}')"
+if [[ -n "${SO:-}" ]]; then
+    export LD_PRELOAD="${SO}${LD_PRELOAD:+:${LD_PRELOAD}}"
+fi
+
+exec python3 "$APP" "$@"

desktopenvs/hyprlua/scripts/menu-toggle.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Toggle the astal-menu popup (or open it to a section). Forwards a verb to the
+# resident daemon over D-Bus; if the daemon isn't running yet, starts it first.
+# (No `set -e`: a non-zero `grep`/`busctl` in the wait loop is expected and must
+# not abort the script before it forwards the verb.)
+#
+#   menu-toggle.sh                 -> --toggle (top, the default)
+#   menu-toggle.sh appdrawer       -> open with the app drawer expanded
+#   menu-toggle.sh left            -> toggle, sliding in from / pinned to the left
+#   menu-toggle.sh toggle right    -> same, explicit verb
+#   menu-toggle.sh appdrawer bottom
+#
+# Verbs: (toggle) | show | hide | appdrawer.  Sides: top | bottom | left | right.
+
+BUS="eu.abdelbaki.astalmenu"
+APP="${HOME}/.config/astal-menu/main.py"
+
+verb="${1:-}"; side="${2:-}"
+# allow the side to be given as the sole argument (verb defaults to toggle)
+case "$verb" in
+    top|bottom|left|right) side="$verb"; verb="" ;;
+esac
+
+case "$verb" in
+    appdrawer) VERB="--appdrawer" ;;
+    show)      VERB="--show" ;;
+    hide)      VERB="--hide" ;;
+    *)         VERB="--toggle" ;;
+esac
+
+case "$side" in
+    top|bottom|left|right) SIDE=(--side "$side") ;;
+    *)                     SIDE=() ;;
+esac
+
+registered() { busctl --user list 2>/dev/null | grep -q "$BUS"; }
+
+if ! registered; then
+    "${HOME}/.config/scripts/astal-menu-start.sh" >/dev/null 2>&1 &
+    for _ in $(seq 1 25); do
+        if registered; then break; fi
+        sleep 0.2
+    done
+fi
+
+# If it still didn't register, this invocation just becomes the primary instance
+# (Gio single-instance handles the routing either way).
+exec python3 "$APP" "$VERB" "${SIDE[@]}"

setup/modules/Desktop-Environments/hyprlua.sh

@@ -71,11 +71,19 @@ HYPRLUA_PACKAGES=(
     kitty                 # GPU-accelerated terminal (default in this setup)
     dunst                 # lightweight, scriptable notification daemon
 
-    nwg-dock-hyprland     # dock/taskbar with Hyprland workspace awareness
-    nwg-drawer            # grid application drawer / launcher
-    nwg-menu              # GTK application menu for the panel button
     nwg-look              # GTK/cursor/icon theme picker for wlroots sessions
 
+    # astal-menu popup control centre (replaces nwg-dock + nwg-drawer)
+    python-gobject        # PyGObject: GTK4 + Astal libs from Python
+    python-pillow         # Pillow: stitches the map tiles into the Location image
+    gtk4                  # GTK4 toolkit (the menu's frontend)
+    gtk4-layer-shell      # wlr-layer-shell for GTK4 (the popup surface)
+    libshumate            # GTK4 OpenStreetMap widget (Location quad)
+    networkmanager        # nmcli backend for the Network quad (adapters/routes/vlan/dns)
+    bluez-utils           # bluetoothctl + bluez CLI (Bluetooth quad fallbacks)
+    iproute2 curl jq      # ip/ss, HTTP fetches, JSON (Network/Weather backends)
+    traceroute            # path trace to 1.1.1.1 for the Location quad's IP geolocation
+
     # Build toolchain required for EWW (Rust) and AUR package compilation
     python cmake meson cpio pkgconf ruby-pkg-config
 
@@ -194,10 +202,13 @@ rustup default stable
 #   wofi-calc           — inline calculator inside wofi
 #   bri                 — brightness control helper for bar widgets
 #   chamel              — colour-palette / theme switcher
+#   libastal-*-git      — Astal GObject service libraries consumed by astal-menu
+#                         (io, apps, network, bluetooth) via PyGObject
 yay -Syu --answerdiff None --answerclean All --noconfirm --needed \
     hyprland-workspaces vicinae-bin bluetuith wvkbd iwmenu pinta \
     walker-bin ulauncher bzmenu udiskie \
-    wofi-calc bri chamel 
+    wofi-calc bri chamel \
+    libastal-io-git libastal-apps-git libastal-network-git libastal-bluetooth-git
 # hyprmoncfg if custom script no worky
 
 # ---------------------------------------------------------------------------
@@ -335,7 +346,7 @@ log "Copying configs..."
 
 # Deploy each config directory from the hyprlua Dotfiles source.
 # The wipe-then-copy pattern ensures no stale files from older installs remain.
-CONFIGS=(kitty mimeapps.list vicinae walker ulauncher hypr xfce4 wofi dunst alacritty nwg-dock-hyprland nwg-drawer nwg-panel scripts btop gtk-3.0)
+CONFIGS=(kitty mimeapps.list vicinae walker ulauncher hypr xfce4 wofi dunst alacritty astal-menu nwg-panel scripts btop gtk-3.0)
 for cfg in "${CONFIGS[@]}"; do
     rm -rf ~/.config/"$cfg"
     cp -r ~/Dotfiles/desktopenvs/hyprlua/"$cfg" ~/.config/