pixdial 0.1.0__py3-none-any.whl

pixdial/__init__.py

@@ -0,0 +1,4 @@
+"""pixdial: a Python SDK and CLI for hardware screens on Linux."""
+
+NAME = "pixdial"  # the project's name at run time: plugin entry-point groups, config and state folders, messages
+__version__ = "0.1.0"

pixdial/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

pixdial/cli.py

@@ -0,0 +1,146 @@
+"""The command line. Exit codes: 0 done, 1 a check or a search came up short, 2 a usage or config error."""
+
+from __future__ import annotations
+
+import argparse
+import signal
+import sys
+import threading
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import NAME, __version__, demo, doctor, plugins
+from . import config as cfg
+from .designs import BUILTIN as DESIGNS
+from .designs import THEMES, Design
+from .devices import BUILTIN as DEVICES
+from .devices import Device
+from .gallery import Demo, gallery
+from .runtime import ROTATE, Report
+from .sources import BUILTIN as SOURCES
+from .sources import Source
+
+OK, SHORT, USAGE = 0, 1, 2
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        return int(args.command(args))
+    except cfg.ConfigError as error:
+        print(f"{NAME}: {args.config or cfg.config_path()}: {error}", file=sys.stderr)
+        return USAGE
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog=NAME, description="A Python SDK and CLI for hardware screens on Linux.")
+    p.add_argument("--version", action="version", version=f"{NAME} {__version__}")
+    p.add_argument("--config", type=Path, help=f"the config file (default {cfg.config_path()})")
+    sub = p.add_subparsers(required=True, metavar="COMMAND")
+
+    run_ = sub.add_parser("run", help="show the designs on the panels until stopped")
+    run_.set_defaults(command=run)
+
+    show_ = sub.add_parser("show", help="pick the designs a running `run` shows; alone, the current ones")
+    show_.add_argument("specs", nargs="*", metavar="DESIGN", help=f"one per panel (name or name:theme), or {ROTATE}")
+    show_.set_defaults(command=show)
+
+    list_ = sub.add_parser("list", help="the designs, themes, sources and devices")
+    list_.set_defaults(command=list_all)
+
+    devices_ = sub.add_parser("devices", help="the panels attached now")
+    devices_.set_defaults(command=devices)
+
+    render_ = sub.add_parser("render", help="designs as PNG files from demo readings, without hardware")
+    render_.add_argument("specs", nargs="*", metavar="DESIGN", help="name or name:theme (default: every design)")
+    render_.add_argument("--state", default="busy", choices=demo.STATES, help="the demo readings (default busy)")
+    render_.add_argument("--scale", type=int, default=1, choices=(1, 2, 3, 4), help="1 is the panel's 400 px")
+    render_.add_argument("--out", type=Path, default=Path(), help="the folder to write to (default here)")
+    render_.add_argument("--gallery", type=Path, metavar="DIR", help="every design, sheets and gallery.html, to DIR")
+    render_.set_defaults(command=render)
+
+    doctor_ = sub.add_parser("doctor", help="check the config, panels, permissions and sources")
+    doctor_.set_defaults(command=check)
+    return p
+
+
+def run(args: argparse.Namespace) -> int:
+    runner = cfg.runner(cfg.load(args.config), Report())
+    stop = threading.Event()
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        signal.signal(sig, lambda *_: stop.set())
+    runner.run(stop)
+    return OK
+
+
+def show(args: argparse.Namespace) -> int:
+    config = cfg.load(args.config)
+    layout = cfg.layout(config, cfg.catalog(config))
+    if args.specs:
+        try:
+            layout.save(args.specs)
+        except ValueError as error:
+            print(f"{NAME}: {error}; the panels keep {' '.join(layout.load())}", file=sys.stderr)
+            return USAGE
+    print(" ".join(layout.load()))
+    return OK
+
+
+def list_all(args: argparse.Namespace) -> int:
+    config = cfg.load(args.config)
+    designs, broken = plugins.available("designs", Design, DESIGNS)
+    print("designs:")
+    for name, cls in designs.items():
+        print(f"  {name:10} {cls.shows}{f' (animated, {cls.fps} frames/s)' if cls.fps else ''}")
+    print(f"themes: {', '.join(THEMES)} (name:theme; {config.theme} is the default)")
+    for kind, base, builtin in (("sources", Source, SOURCES), ("devices", Device, DEVICES)):
+        found, more = plugins.available(kind, base, builtin)
+        print(f"{kind}: {', '.join(found)}")
+        broken |= more
+    for name, why in broken.items():
+        print(f"broken plugin {name}: {why}", file=sys.stderr)
+    return OK
+
+
+def devices(args: argparse.Namespace) -> int:
+    panels = {device.id: name for name, device in cfg.devices(cfg.load(args.config))}
+    found = 0
+    for kind, cls in plugins.available("devices", Device, DEVICES)[0].items():
+        for panel in cls.discover():
+            found += 1
+            access = "ok" if panel.access else "no access (`doctor` says how to fix it)"
+            where = f"panel {panels[panel.id]!r}" if panel.id in panels else "not in the config"
+            print(f"{kind}  {panel.id}  {panel.where}  {access}  {where}")
+    if not found:
+        print("no panels attached", file=sys.stderr)
+    return OK if found else SHORT
+
+
+def render(args: argparse.Namespace) -> int:
+    config = cfg.load(args.config)
+    catalog = cfg.catalog(config)
+    if args.gallery:
+        gallery(args.gallery, catalog, config.readings)
+        print(args.gallery / "gallery.html")
+        return OK
+    specs = args.specs or list(catalog.designs)
+    for spec in specs:
+        try:
+            catalog.check(spec)
+        except ValueError as error:
+            print(f"{NAME}: {error}", file=sys.stderr)
+            return USAGE
+    args.out.mkdir(parents=True, exist_ok=True)
+    for spec in specs:
+        path = args.out / f"{spec.replace(':', '-')}-{args.state}@{args.scale}x.png"
+        Demo(catalog.make(spec, args.scale), args.state, config.readings).render().save(path)
+        print(path)
+    return OK
+
+
+def check(args: argparse.Namespace) -> int:
+    problems = 0
+    for c in doctor.checks(args.config):
+        problems += not c.ok
+        print(f"{'ok' if c.ok else 'FAIL':4}  {c.what:16} {c.detail}", flush=True)
+    return OK if not problems else SHORT

pixdial/config.py

@@ -0,0 +1,229 @@
+"""The config file (TOML, under XDG_CONFIG_HOME), checked with errors that say where, and what it builds.
+
+A ConfigError's message says where in the file; the caller adds which file.
+"""
+
+from __future__ import annotations
+
+import inspect
+import itertools
+import os
+import tomllib
+from collections import Counter
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import NAME, plugins
+from .designs import BUILTIN as DESIGNS
+from .designs import THEMES, Design
+from .devices import BUILTIN as DEVICES
+from .devices import Device
+from .readings import Meta
+from .runtime import Catalog, Feed, Layout, Report, Runner, Sampler, Screen
+from .sources import BUILTIN as SOURCES
+from .sources import Source
+
+
+class ConfigError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Entry:
+    """A [[panels]] or [[sources]] table: its kind (a device or source name, or "module:Class") and the rest of its
+    keys, which go to that class as options."""
+
+    kind: str
+    options: Mapping[str, Any]
+    name: str  # in log lines: the panel's name, or the source's kind (numbered when it comes twice)
+
+
+DEFAULT_SOURCES = (
+    Entry("cpu", {}, "cpu"),
+    Entry("rapl", {}, "rapl"),
+    Entry("nvml", {}, "nvml"),
+    Entry("hwmon", {"readings": {"cpu_c": ["k10temp/Tctl", "coretemp/Package id 0"]}}, "hwmon"),
+)
+
+
+@dataclass(frozen=True)
+class Config:
+    path: Path
+    theme: str = "warm"
+    layout: tuple[str, ...] = ()  # the designs top to bottom, or ("rotate",); empty: the first designs
+    rotate_every: float = 60.0
+    rotation: tuple[str, ...] = ()  # empty: every design
+    panels: tuple[Entry, ...] = ()
+    sources: tuple[Entry, ...] = DEFAULT_SOURCES
+    readings: Mapping[str, Meta] = field(default_factory=dict)
+
+
+def config_path() -> Path:
+    return Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / NAME / "config.toml"
+
+
+def state_path() -> Path:
+    """Where `show` keeps the layout for `run`."""
+    return Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local" / "state") / NAME / "layout"
+
+
+def load(path: Path | None = None) -> Config:
+    """The config at path, or at the default place; the defaults where there is no file at the default place."""
+    file = path or config_path()
+    try:
+        data = tomllib.loads(file.read_text())
+    except FileNotFoundError:
+        if path is not None:
+            raise ConfigError("no such file") from None
+        data = {}
+    except (OSError, tomllib.TOMLDecodeError) as error:
+        raise ConfigError(str(error)) from error
+    return parse(data, file)
+
+
+def parse(data: Mapping[str, Any], path: Path) -> Config:
+    known(data, "", "theme", "layout", "rotate_every", "rotation", "panels", "sources", "readings")
+    layout = get(data, "layout", (str, list), [])
+    every = get(data, "rotate_every", (int, float), 60.0)
+    if every <= 0:
+        raise ConfigError(f"rotate_every: must be above 0, not {every}")
+    panels = [panel(table, i) for i, table in enumerate(get(data, "panels", list, []))]
+    if dupes := [n for n, count in Counter(p.name for p in panels).items() if count > 1]:
+        raise ConfigError(f"panels: two panels named {dupes[0]!r}")
+    sources = [entry(table, f"sources[{i}]", "type") for i, table in enumerate(get(data, "sources", list, []))]
+    return Config(
+        path=path,
+        theme=get(data, "theme", str, "warm"),
+        layout=tuple(strings([layout] if isinstance(layout, str) else layout, "layout")),
+        rotate_every=float(every),
+        rotation=tuple(strings(get(data, "rotation", list, []), "rotation")),
+        panels=tuple(panels),
+        sources=tuple(numbered(sources)) if "sources" in data else DEFAULT_SOURCES,
+        readings={key: meta(table, f"readings.{key}") for key, table in get(data, "readings", dict, {}).items()},
+    )
+
+
+def panel(table: Any, i: int) -> Entry:
+    """A panel: its device (slv3 unless it says), its name (its number unless it says), the device's options."""
+    where = f"panels[{i}]"
+    e = entry(table, where, "device", "slv3")
+    name = get(e.options, "name", str, str(i + 1), where)
+    return Entry(e.kind, {k: v for k, v in e.options.items() if k != "name"}, name)
+
+
+def entry(table: Any, where: str, kind_key: str, default: str | None = None) -> Entry:
+    if not isinstance(table, dict):
+        raise ConfigError(f"{where}: must be a table")
+    kind = get(table, kind_key, str, default, where)
+    if kind is None:
+        raise ConfigError(f"{where}: needs {kind_key}")
+    return Entry(kind, {k: v for k, v in table.items() if k != kind_key}, kind)
+
+
+def numbered(entries: Sequence[Entry]) -> list[Entry]:
+    """Sources named by their kind, numbered where a kind comes more than once."""
+    counts = Counter(e.kind for e in entries)
+    seen: Counter[str] = Counter()
+    out = []
+    for e in entries:
+        seen[e.kind] += 1
+        out.append(Entry(e.kind, e.options, f"{e.kind} {seen[e.kind]}" if counts[e.kind] > 1 else e.kind))
+    return out
+
+
+def meta(table: Any, where: str) -> Meta:
+    if not isinstance(table, dict):
+        raise ConfigError(f"{where}: must be a table")
+    known(table, where, "max", "warn", "label")
+    return Meta(
+        max=get(table, "max", (int, float), None, where),
+        warn=get(table, "warn", (int, float), None, where),
+        label=get(table, "label", str, None, where),
+    )
+
+
+def known(table: Mapping[str, Any], where: str, *keys: str) -> None:
+    for key in table:
+        if key not in keys:
+            raise ConfigError(f"{where + ': ' if where else ''}unknown key {key!r} (known: {', '.join(keys)})")
+
+
+KINDS = {str: "text", int: "a number", float: "a number", list: "a list", dict: "a table"}
+
+
+def get(table: Mapping[str, Any], key: str, kind: type | tuple[type, ...], default: Any, where: str = "") -> Any:
+    """table[key] if it is of that kind (TOML's true and false are not numbers), else default if it is missing."""
+    value = table.get(key, default)
+    if value is not default and (not isinstance(value, kind) or isinstance(value, bool)):
+        kinds = kind if isinstance(kind, tuple) else (kind,)
+        wanted = " or ".join(dict.fromkeys(KINDS[k] for k in kinds))
+        raise ConfigError(f"{where + '.' if where else ''}{key}: must be {wanted}, not {value!r}")
+    return value
+
+
+def strings(values: list[Any], where: str) -> list[str]:
+    if not all(isinstance(v, str) for v in values):
+        raise ConfigError(f"{where}: must be a list of names")
+    return values
+
+
+# ---------------------------------------------------------------- what it builds
+
+
+def catalog(config: Config) -> Catalog:
+    if config.theme not in THEMES:
+        raise ConfigError(f"theme: no theme {config.theme!r} (themes: {', '.join(THEMES)})")
+    designs, _ = plugins.available("designs", Design, DESIGNS)
+    return Catalog(designs, THEMES, config.theme)
+
+
+def layout(config: Config, catalog: Catalog) -> Layout:
+    names = list(catalog.designs)
+    rotation = config.rotation or tuple(names)
+    for name in rotation:
+        if name not in catalog.designs:
+            raise ConfigError(f"rotation: no design {name!r}")
+    default = config.layout or tuple(itertools.islice(itertools.cycle(names), len(config.panels)))
+    try:
+        return Layout(catalog, len(config.panels), state_path(), default, rotation, config.rotate_every)
+    except ValueError as error:
+        raise ConfigError(f"layout: {error}") from None
+
+
+def devices(config: Config) -> list[tuple[str, Device]]:
+    return [(e.name, build("devices", Device, DEVICES, e, f"panels[{i}]")) for i, e in enumerate(config.panels)]
+
+
+def sources(config: Config) -> list[tuple[str, Source]]:
+    return [(e.name, build("sources", Source, SOURCES, e, f"sources[{i}]")) for i, e in enumerate(config.sources)]
+
+
+def build[C](kind: str, base: type[C], builtin: Mapping[str, type[C]], e: Entry, where: str) -> C:
+    """The class an entry names, made with its options."""
+    try:
+        cls = plugins.resolve(kind, base, builtin, e.kind)
+    except plugins.PluginError as error:
+        raise ConfigError(f"{where}: {error}") from None
+    params = inspect.signature(cls).parameters.values()
+    takes = [p.name for p in params if p.kind in (p.POSITIONAL_OR_KEYWORD, p.KEYWORD_ONLY)]
+    if (unknown := [k for k in e.options if k not in takes]) and all(p.kind != p.VAR_KEYWORD for p in params):
+        raise ConfigError(f"{where}: {e.kind} takes no {unknown[0]!r} (it takes {', '.join(takes) or 'nothing'})")
+    if needed := [p.name for p in params if p.name in takes and p.default is p.empty and p.name not in e.options]:
+        raise ConfigError(f"{where}: {e.kind} needs {', '.join(needed)}")
+    try:
+        return cls(**e.options)
+    except (TypeError, ValueError) as error:
+        raise ConfigError(f"{where}: {error}") from None
+
+
+def runner(config: Config, report: Report) -> Runner:
+    """Everything `run` needs, checked before anything opens."""
+    if not config.panels:
+        raise ConfigError(f"no [[panels]] (`{NAME} devices` lists the panels attached)")
+    found = catalog(config)
+    plan = layout(config, found)
+    screens = [Screen(name, device, report) for name, device in devices(config)]
+    feed = Feed(config.readings, {spec for cls in found.designs.values() for spec in cls.trails})
+    return Runner(screens, Sampler(sources(config), report), feed, found, plan, report)

pixdial/data/60-pixdial.rules

@@ -0,0 +1,5 @@
+# Lets the user logged in at the machine use Lian Li UNI FAN SL V3 Wireless LCD panels (USB 1cbe:0005) without root.
+# Install: sudo cp 60-pixdial.rules /etc/udev/rules.d/ && sudo udevadm control --reload && sudo udevadm trigger
+# On a machine nobody logs in to locally, give a group access instead: replace TAG+="uaccess" with
+# GROUP="<group>", MODE="0660" and add the user to that group.
+SUBSYSTEM=="usb", ATTRS{idVendor}=="1cbe", ATTRS{idProduct}=="0005", TAG+="uaccess"

pixdial/data/pixdial.service

@@ -0,0 +1,16 @@
+# A systemd user unit for `pixdial run`. Install:
+#   mkdir -p ~/.config/systemd/user && cp pixdial.service ~/.config/systemd/user/
+#   systemctl --user daemon-reload && systemctl --user enable --now pixdial
+# ExecStart assumes `uv tool install` or `pipx install` (~/.local/bin); point it at your pixdial otherwise.
+# To keep it running while you are logged out: loginctl enable-linger
+[Unit]
+Description=pixdial: live dashboards on the fans' LCD panels
+
+[Service]
+ExecStart=%h/.local/bin/pixdial run
+Restart=always
+RestartSec=10
+Nice=10
+
+[Install]
+WantedBy=default.target

pixdial/demo.py

@@ -0,0 +1,69 @@
+"""Made-up readings of a busy workstation, for rendering designs without hardware (previews, the gallery, tests).
+
+States: idle; busy (a build and a GPU job, the CPU near its limit, three agent sessions working); waiting (an agent
+session waiting for you); full (everything at its limit); missing (no readings at all). The machine reports the limits
+a real one would (an NVML power limit and slowdown point, a PSU's temperature crit).
+"""
+
+from __future__ import annotations
+
+import datetime
+import math
+
+import numpy as np
+
+from .readings import Reading
+
+STATES = ("idle", "busy", "waiting", "full", "missing")
+START = datetime.datetime(2026, 11, 4, 21, 42).timestamp()  # the clock shows 21:42
+
+
+def readings(state: str, t: float) -> dict[str, Reading]:
+    """The readings at second t of a state."""
+    if state == "missing":
+        return {}
+    rng = np.random.default_rng(int(t * 10) + STATES.index(state))
+    wave = math.sin(t / 9)
+    if state == "idle":
+        threads = np.clip(rng.gamma(1.2, 1.5, 48), 0, 100)
+        cpu_w, cpu_c = 41 + 2 * wave, 34 + wave
+        gpu_w, gpu_c, use = 10.5 + wave, 31, 0
+        pins = [0.38, 0.41, 0.36, 0.40, 0.37, 0.39]
+        psu_c, fan, quota, working, waiting = 33, 0, 89.8, 0, False
+    elif state == "busy":
+        threads = np.clip(rng.normal(55 + 25 * math.sin(t / 7), 22, 48), 0, 100)
+        cpu_w, cpu_c = 230 + 60 * wave, 93 + 2 * wave
+        gpu_w, gpu_c, use = 455 + 40 * math.sin(t / 5), 71, 98
+        pins = [7.4, 7.1, 7.6, 7.3, 6.9, 7.5]
+        psu_c, fan, quota, working, waiting = 46, 640, 58, 3, False
+    elif state == "waiting":
+        threads = np.clip(rng.normal(16, 9, 48), 0, 100)
+        cpu_w, cpu_c = 92 + 8 * wave, 57 + wave
+        gpu_w, gpu_c, use = 120 + 10 * wave, 47, 31
+        pins = [1.8, 1.7, 1.9, 1.8, 1.6, 1.8]
+        psu_c, fan, quota, working, waiting = 39, 0, 31, 1, True
+    else:  # full
+        threads = np.full(48, 100.0)
+        cpu_w, cpu_c = 352 + 3 * wave, 95
+        gpu_w, gpu_c, use = 600, 93, 100
+        pins = [9.0, 8.7, 9.3, 9.1, 8.6, 9.0]
+        psu_c, fan, quota, working, waiting = 52, 980, 12.4, 3, True
+    psu_w = 60 + cpu_w * 1.08 + gpu_w * 1.04 + (240 * max(0, math.sin(t / 15)) if state == "busy" else 0)
+    return {
+        "cpu_load": Reading(float(np.mean(threads)), "%"),
+        "threads": Reading(threads, "%"),
+        "cpu_c": Reading(cpu_c, "°C"),
+        "cpu_w": Reading(cpu_w, "W"),
+        "gpu_w": Reading(gpu_w, "W", max=600),
+        "gpu_c": Reading(gpu_c, "°C", max=93),
+        "gpu_use": Reading(use, "%"),
+        "pins": Reading(np.array(pins), "A"),
+        "pin_total": Reading(sum(pins) * 0.98, "A"),
+        "pin_balance": Reading(min(pins) / max(pins) * 0.97),
+        "psu_w": Reading(psu_w, "W"),
+        "psu_c": Reading(psu_c, "°C", max=70),
+        "psu_fan": Reading(fan, "rpm"),
+        "quota": Reading(quota, "%"),
+        "working": Reading(working),
+        "waiting": Reading(waiting),
+    }

pixdial/designs/__init__.py

@@ -0,0 +1,57 @@
+"""Designs: pure renders from a snapshot of readings to a 400 x 400 picture, with no I/O.
+
+What a design needs to draw is importable from here; see the README's "Writing a design".
+"""
+
+from ..readings import Snapshot, TrailSpec
+from .agents import Quota
+from .base import DEFAULT_MAX, Design, fmt, joined, limit, rnd
+from .clock import Clock
+from .colour import LOAD, THEMES, Scale, Theme, current, lerp, share, solid, temperature
+from .cpu import Crown, Grid, Minimal, Orb, Radar
+from .frame import DASH, Frame, Pixels, Still, add, disc, glow_disc, paint, with_text
+from .geometry import MID, SIZE, Kit, Ring, on_circle
+from .gpu import Gpu, Pins, Twin
+from .motion import Eased
+from .power import Flow, History, Psu
+from .thermals import Thermals
+
+BUILTIN: dict[str, type[Design]] = {
+    d.name: d for d in (Crown, Gpu, Psu, Pins, Flow, Quota, History, Twin, Clock, Minimal, Thermals, Orb, Radar, Grid)
+}
+
+__all__ = [
+    "BUILTIN",
+    "DASH",
+    "DEFAULT_MAX",
+    "LOAD",
+    "MID",
+    "SIZE",
+    "THEMES",
+    "Design",
+    "Eased",
+    "Frame",
+    "Kit",
+    "Pixels",
+    "Ring",
+    "Scale",
+    "Snapshot",
+    "Still",
+    "Theme",
+    "TrailSpec",
+    "add",
+    "current",
+    "disc",
+    "fmt",
+    "glow_disc",
+    "joined",
+    "lerp",
+    "limit",
+    "on_circle",
+    "paint",
+    "rnd",
+    "share",
+    "solid",
+    "temperature",
+    "with_text",
+]

pixdial/designs/agents.py

@@ -0,0 +1,83 @@
+"""Designs for coding agents: a pool's quota, sessions working, a session waiting for you."""
+
+from __future__ import annotations
+
+import colorsys
+import math
+from collections.abc import Hashable
+
+from ..readings import Snapshot
+from .base import Design, rnd
+from .colour import NEEDS_YOU, QUOTA_RGB, Theme, lerp
+from .frame import Pixels, Still, disc, glow_disc
+from .geometry import on_circle
+from .motion import Eased
+
+
+def agents(r: Snapshot) -> tuple[int, bool]:
+    """(sessions working, whether one waits for you): none while the agents' readings are missing."""
+    return r.count("working"), r.flag("waiting")
+
+
+def pulse(now: float) -> float:
+    """A wait's pulse, 0-1, every 1.4 s."""
+    return 0.5 + 0.5 * math.cos(now * 2 * math.pi / 1.4)
+
+
+def sessions(n: int) -> str:
+    return f"{n} AGENT{'S' if n > 1 else ''}"
+
+
+class Quota(Design):
+    name = "quota"
+    shows = "An agent pool's quota left, agent sessions working, a wait for you"
+    about = (
+        "The agents' quota as a big coral fuel gauge, one dot per working session circling inside it, and the "
+        "whole screen pulsing magenta while a session waits for you."
+    )
+    fps = 20
+    previews = ("busy", "idle", "waiting")
+
+    working: int  # set by update(), with waiting and title
+    waiting: bool
+    title: str
+
+    def __init__(self, theme: Theme, scale: int = 1) -> None:
+        super().__init__(theme, scale)
+        self.quota = Eased(0.5, tau=0.4)
+        self.spin = self.pulse = 0.0
+
+    def update(self, r: Snapshot, now: float, dt: float) -> tuple[Hashable, Hashable | None]:
+        self.quota.step(r.number("quota"), dt)
+        self.title = r.label("quota") or "QUOTA"
+        self.working, self.waiting = working, waiting = agents(r)
+        self.spin = (self.spin + dt * 40) % 360
+        self.pulse = pulse(now) if waiting else 0.0
+        still = rnd(self.quota.value, 2), working, waiting, round(self.pulse * 10)
+        return still, self.animating(now) if working else None
+
+    def still(self) -> Still:
+        waiting, q = self.waiting, self.quota.get()
+        accent = lerp(self.theme.track, NEEDS_YOU, 0.35 + 0.65 * self.pulse) if waiting else QUOTA_RGB
+        f = self.frame(accent if waiting or q is not None else None, 0.12 if waiting else 0.07)
+        ring = self.kit.ring(166, 190)
+        f.paint(ring, ring.arc(1.0), self.theme.track, glow=0)
+        if q is not None:
+            f.paint(ring, ring.arc(q / 100), accent)
+        self.label(f, self.title)
+        f.number(246, q, "%", glow=QUOTA_RGB)
+        if waiting:
+            self.line(f, "NEEDS YOU", rgb=lerp(self.theme.dim, NEEDS_YOU, 0.4 + 0.6 * self.pulse), size=30, spacing=2)
+        elif self.working:
+            self.line(f, sessions(self.working), size=30, spacing=2)
+        else:
+            self.line(f, "WEEK LEFT", rgb=self.theme.dim, size=30, spacing=2)
+        return f.finish()
+
+    def moving(self, px: Pixels, now: float) -> None:
+        n = self.working
+        for i in range(min(n, 8)):
+            x, y = on_circle(146, self.spin + i * 360 / n)
+            r, g, b = (255 * c for c in colorsys.hsv_to_rgb((self.spin / 360 + i / n) % 1, 0.7, 1))
+            glow_disc(px, self.kit, x, y, 9, (r, g, b), 0.35)
+            disc(px, self.kit, x, y, 5.5, (r, g, b))