project-away 0.1.1__py3-none-any.whl

away/__init__.py

@@ -0,0 +1,4 @@
+"""Project Away: hands-free PC control (gestures, dictation, speaker gating, Wi-Fi CSI)."""
+
+__version__ = "0.1.1"
+__all__ = ["__version__"]

away/__main__.py

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

away/actions.py

@@ -0,0 +1,329 @@
+"""Action mapping and dispatch.
+
+The gesture state machine only *detects* (``click``, ``drag_start``, ``scroll``...).
+:class:`Dispatcher` maps each detected event to a trigger (``pinch``,
+``pinch_hold``, ``two_finger_scroll``...), looks the trigger up in the active
+profile of :class:`~away.bindings.BindingsConfig` and hands the resulting
+:class:`~away.bindings.Action` to :class:`ActionExecutor`, which talks to the
+mouse/keyboard backend, launches apps, or calls the app's hooks for
+dictation, mic, voice-mode and pause actions.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+import time
+import webbrowser
+from collections.abc import Callable
+from typing import Any
+
+from away.bindings import NONE, Action, BindingsConfig, normalize_phrase
+from away.control.keys import parse_combo, to_pynput_hotkey
+from away.control.mouse import MouseController
+from away.hands.gestures import GestureEvent, GestureStateMachine
+
+# detected gesture event -> trigger name (``move`` depends on its anchor)
+EVENT_TRIGGER = {
+    "click": "pinch",
+    "double_click": "double_pinch",
+    "drag_start": "pinch_hold",
+    "drag_end": "pinch_hold",
+    "scroll": "two_finger_scroll",
+    "clutch": "open_palm",
+    "swipe_left": "swipe_left",
+    "swipe_right": "swipe_right",
+    "push": "push",  # multi-camera depth: hand pushed toward the screen
+    "dwell": "dwell",  # cursor rested in place (hands.dwell)
+}
+PINCH_CLICK_EVENTS = ("click", "double_click", "drag_start")
+SCROLL_STEP = 3.0  # wheel notches for mouse:scroll_up / scroll_down
+URL_PREFIXES = ("http://", "https://", "mailto:", "file://", "ftp://")
+HOOK_KINDS = ("dictation", "mic", "voice", "pause")
+
+Hook = Callable[[str, dict[str, Any]], None]
+
+
+def event_trigger(ev: GestureEvent) -> str | None:
+    if ev.kind == "move":
+        return "pinch_hold" if ev.data.get("anchor") == "pinch" else "point"
+    if ev.kind == "custom":
+        name = ev.data.get("name")
+        return str(name) if name else None
+    return EVENT_TRIGGER.get(ev.kind)
+
+
+def _default_launch(argv: list[str]) -> None:  # pragma: no cover - starts a process
+    subprocess.Popen(argv, start_new_session=True)
+
+
+def _default_shell(cmd: str) -> None:  # pragma: no cover - starts a process
+    subprocess.Popen(cmd, shell=True, start_new_session=True)
+
+
+class ActionExecutor:
+    """Runs one :class:`Action`. Launch/shell/URL openers are injectable for tests."""
+
+    def __init__(
+        self,
+        mouse: MouseController,
+        allow_shell: bool = False,
+        hooks: dict[str, Hook] | None = None,
+        launcher: Callable[[list[str]], None] = _default_launch,
+        shell_runner: Callable[[str], None] = _default_shell,
+        url_opener: Callable[[str], Any] = webbrowser.open,
+    ) -> None:
+        self.mouse = mouse
+        self.allow_shell = allow_shell
+        self.hooks: dict[str, Hook] = dict(hooks or {})
+        self.launcher = launcher
+        self.shell_runner = shell_runner
+        self.url_opener = url_opener
+        self.log: list[str] = []  # human-readable record of what ran / was refused
+        self.errors: list[tuple[str, BaseException]] = []
+
+    @property
+    def backend(self) -> Any:
+        return self.mouse.backend
+
+    def run(self, action: Action, data: dict[str, Any] | None = None, *, extra_click_only: bool = False) -> bool:
+        """Execute ``action``; returns False if nothing ran (none, refused, missing hook, error)."""
+        if action.kind == "none":
+            return False
+        try:
+            return self._run(action, data or {}, extra_click_only)
+        except Exception as exc:  # an action must never take down the pipeline
+            self.errors.append((str(action), exc))
+            self.log.append(f"error {action}: {exc}")
+            return False
+
+    def _run(self, a: Action, data: dict[str, Any], extra_click_only: bool) -> bool:
+        b = self.backend
+        if a.kind == "mouse":
+            if a.arg == "click":
+                b.click(1)
+            elif a.arg == "double_click":
+                b.click(1 if extra_click_only else 2)
+            elif a.arg in ("right_click", "middle_click"):
+                btn = a.arg.split("_")[0]
+                if hasattr(b, "click_button"):
+                    b.click_button(btn, 1)
+                else:
+                    self.log.append(f"backend cannot {a.arg}")
+                    return False
+            elif a.arg in ("scroll_up", "scroll_down"):
+                b.scroll(SCROLL_STEP if a.arg == "scroll_up" else -SCROLL_STEP)
+            else:  # move/drag/scroll are continuous; the Dispatcher routes those
+                return False
+        elif a.kind == "key":
+            keys = parse_combo(a.arg)
+            if len(keys) == 1:
+                b.key(keys[0])
+            elif hasattr(b, "hotkey"):
+                b.hotkey(keys)
+            else:
+                self.log.append(f"backend cannot press combo {a.arg}")
+                return False
+        elif a.kind == "type":
+            if hasattr(b, "type_text"):
+                b.type_text(a.arg)
+            else:
+                return False
+        elif a.kind == "launch":
+            if a.arg.lower().startswith(URL_PREFIXES):
+                self.url_opener(a.arg)
+            else:
+                self.launcher(shlex.split(a.arg, posix=os.name != "nt"))
+        elif a.kind == "shell":
+            if not self.allow_shell:
+                self.log.append(f"refused {a}: bindings.allow_shell is false")
+                return False
+            self.shell_runner(a.arg)
+        elif a.kind in HOOK_KINDS:
+            hook = self.hooks.get(a.kind)
+            if hook is None:
+                self.log.append(f"no handler for {a}")
+                return False
+            hook(a.arg, data)
+        else:
+            return False
+        self.log.append(f"ran {a}")
+        return True
+
+
+class Dispatcher:
+    """Maps detected events and named triggers to actions under the active profile."""
+
+    def __init__(
+        self,
+        bindings: BindingsConfig,
+        executor: ActionExecutor,
+        gestures: GestureStateMachine | None = None,
+        active_app: Callable[[], str | None] | None = None,
+        paused: Callable[[], bool] = lambda: False,
+        app_poll: float = 0.5,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.bindings = bindings
+        self.executor = executor
+        self.gestures = gestures
+        self.active_app = active_app
+        self.paused = paused
+        self.app_poll = app_poll
+        self.clock = clock
+        self._profile = bindings.profile_for_app(None)
+        self._app_checked = -1e9
+        self.last_app: str | None = None
+        self._last_fire: dict[str, float] = {}
+        self.fired: list[tuple[str, str]] = []  # (trigger_id, action) history for the GUI/tests
+        self.on_fire: Callable[[str, Action], None] | None = None
+        self.sync()
+
+    # ------------------------------------------------------------ profile
+    @property
+    def profile(self) -> str:
+        now = self.clock()
+        if self.active_app is not None and now - self._app_checked >= self.app_poll:
+            self._app_checked = now
+            try:
+                self.last_app = self.active_app()
+            except Exception:
+                self.last_app = None
+            name = self.bindings.profile_for_app(self.last_app)
+            if name != self._profile:
+                self._profile = name
+                self.sync()
+        elif self.active_app is None:
+            name = self.bindings.profile_for_app(None)
+            if name != self._profile:
+                self._profile = name
+                self.sync()
+        return self._profile
+
+    def set_bindings(self, bindings: BindingsConfig) -> None:
+        self.bindings = bindings
+        self.executor.allow_shell = bindings.allow_shell
+        self._app_checked = -1e9
+        self._profile = bindings.profile_for_app(self.last_app)
+        self.sync()
+
+    def sync(self) -> None:
+        """Push mapping-dependent switches into the detector (open palm pauses only if bound to pause:toggle)."""
+        if self.gestures is not None:
+            act = self.bindings.resolve("gestures", "open_palm", self._profile)
+            self.gestures.clutch_pauses = act == Action("pause", "toggle")
+
+    def resolve(self, category: str, trigger: str) -> Action:
+        return self.bindings.resolve(category, trigger, self.profile)
+
+    # ------------------------------------------------------------ gestures
+    def on_gesture(self, ev: GestureEvent) -> Action:
+        mouse = self.executor.mouse
+        if ev.kind == "hand_lost":
+            mouse.handle(ev)
+            return NONE
+        trig = event_trigger(ev)
+        if trig is None:
+            return NONE
+        act = self.resolve("gestures", trig)
+        if ev.kind == "drag_end":
+            mouse.handle(ev)  # always release a held button
+            return act
+        if self.paused() and act.kind != "pause":
+            return NONE
+        if ev.kind in PINCH_CLICK_EVENTS and act.kind == "mouse":
+            mouse.steady(ev.t)  # steady click: land where the cursor was before the pinch began
+        cont = {"point": "move", "pinch_hold": "drag", "two_finger_scroll": "scroll"}.get(trig)
+        if cont is not None and act == Action("mouse", cont):
+            if ev.kind in ("move", "drag_start", "scroll"):
+                mouse.handle(ev)
+                self._record(f"gesture:{trig}", act, quiet=ev.kind != "drag_start")
+            return act
+        if ev.kind == "move":
+            return NONE  # a non-drag action on pinch_hold fires once on drag_start, not every frame
+        if trig in ("two_finger_scroll",) or ev.kind == "custom":
+            last = self._last_fire.get(trig, -1e9)
+            if ev.t - last < self.bindings.discrete_cooldown:
+                return NONE
+            self._last_fire[trig] = ev.t
+        extra_only = False
+        if trig == "double_pinch" and act == Action("mouse", "double_click"):
+            # the first tap of a double pinch already produced a left click when pinch -> mouse:click
+            extra_only = self.resolve("gestures", "pinch") == Action("mouse", "click")
+        if self.executor.run(act, dict(ev.data), extra_click_only=extra_only):
+            self._record(f"gesture:{trig}", act)
+        return act
+
+    # ------------------------------------------------------------ other sources
+    def trigger(self, category: str, name: str, data: dict[str, Any] | None = None) -> Action:
+        """Fire a voice/face/hotkey trigger by name. Returns the action (``none`` if unbound or paused)."""
+        if category == "voice":
+            name = normalize_phrase(name)
+        act = self.resolve(category, name)
+        if self.paused() and act.kind == "mouse":
+            return NONE
+        if self.executor.run(act, dict(data or {})):
+            prefix = {"voice": "voice", "face": "face", "hotkeys": "hotkey", "gestures": "gesture"}[category]
+            self._record(f"{prefix}:{name}", act)
+            return act
+        return NONE if act.kind == "none" else act
+
+    def _record(self, trig: str, act: Action, quiet: bool = False) -> None:
+        if quiet:
+            return
+        self.fired.append((trig, str(act)))
+        del self.fired[:-200]
+        if self.on_fire is not None:
+            self.on_fire(trig, act)
+
+
+class CustomGestureDetector:
+    """Fires a custom gesture when the temporal model's probability for it rises above ``min_conf``.
+
+    Rising-edge + cooldown so one performance fires once.
+    """
+
+    def __init__(self, names: list[str], min_conf: float = 0.7, cooldown: float = 1.0, release: float = 0.4) -> None:
+        self.names = list(names)
+        self.min_conf = min_conf
+        self.release = release
+        self.cooldown = cooldown
+        self._armed = dict.fromkeys(self.names, True)
+        self._last = dict.fromkeys(self.names, -1e9)
+
+    def update(self, t: float, probs: dict[str, float] | None) -> list[str]:
+        if not probs:
+            return []
+        out = []
+        for n in self.names:
+            p = float(probs.get(n, 0.0))
+            if p < self.release:
+                self._armed[n] = True
+            elif p >= self.min_conf and self._armed[n] and t - self._last[n] >= self.cooldown:
+                self._armed[n] = False
+                self._last[n] = t
+                out.append(n)
+        return out
+
+
+def hotkey_slots(voice_cfg: Any) -> dict[str, str]:
+    """Named hotkey slot -> key combo, from the voice config."""
+    return {"ptt": str(voice_cfg.hotkey), "mute": str(voice_cfg.mute_hotkey)}
+
+
+def hotkey_map(bindings: BindingsConfig, voice_cfg: Any, profile: str = "default") -> dict[str, str]:
+    """pynput GlobalHotKeys combo -> hotkey trigger name for every bound, non-``none`` hotkey.
+
+    In ``push_to_talk`` mode the ``ptt`` slot is handled by the hold-key listener instead.
+    """
+    slots = hotkey_slots(voice_cfg)
+    out: dict[str, str] = {}
+    for name, act in bindings.effective(profile)["hotkeys"].items():
+        if act.kind == "none":
+            continue
+        if name == "ptt" and getattr(voice_cfg, "mode", "") == "push_to_talk":
+            continue
+        combo = slots.get(name, name)
+        out[to_pynput_hotkey(combo)] = name
+    return out

away/app/__init__.py

@@ -0,0 +1 @@
+

away/app/autopause.py

@@ -0,0 +1,119 @@
+"""Auto-pause gesture control while the physical mouse or keyboard is in use.
+
+:class:`ManualInputGuard` is pure logic with an injectable clock. The app feeds it
+events from pynput listeners; Away's own synthetic input is reported through
+:class:`GuardedBackend` so it is not mistaken for the user (an OS listener sees
+both). Idea from Tracky Mouse (MIT), implementation is original.
+"""
+
+from __future__ import annotations
+
+import math
+import time
+from collections.abc import Callable
+from typing import Any
+
+
+class ManualInputGuard:
+    def __init__(
+        self,
+        idle_ms: float = 1500.0,
+        clock: Callable[[], float] = time.monotonic,
+        synthetic_window_s: float = 0.08,
+        key_window_s: float = 0.5,
+        tol_px: float = 3.0,
+    ) -> None:
+        self.idle_s = idle_ms / 1000.0
+        self.clock = clock
+        self.synthetic_window_s = synthetic_window_s
+        self.key_window_s = key_window_s
+        self.tol_px = tol_px
+        self.enabled = True
+        self._until = -1e9
+        self._synth_pos: tuple[float, float] | None = None
+        self._synth_t = -1e9
+        self._synth_key_t = -1e9
+
+    # Away's own output --------------------------------------------------------
+    def note_synthetic_move(self, x: float, y: float) -> None:
+        self._synth_pos, self._synth_t = (x, y), self.clock()
+
+    def note_synthetic_key(self) -> None:
+        self._synth_key_t = self.clock()
+
+    # the user's input -----------------------------------------------------------
+    def on_mouse_move(self, x: float, y: float) -> bool:
+        now = self.clock()
+        if self._synth_pos is not None and (
+            now - self._synth_t <= self.synthetic_window_s or math.dist((x, y), self._synth_pos) <= self.tol_px
+        ):
+            return False
+        return self._manual(now)
+
+    def on_click(self) -> bool:
+        now = self.clock()
+        if now - self._synth_t <= self.synthetic_window_s or now - self._synth_key_t <= self.key_window_s:
+            return False
+        return self._manual(now)
+
+    def on_key(self) -> bool:
+        now = self.clock()
+        if now - self._synth_key_t <= self.key_window_s:
+            return False
+        return self._manual(now)
+
+    def _manual(self, now: float) -> bool:
+        if not self.enabled:
+            return False
+        self._until = now + self.idle_s
+        return True
+
+    @property
+    def active(self) -> bool:
+        """True while gesture control should stay paused."""
+        return self.enabled and self.clock() < self._until
+
+
+class GuardedBackend:
+    """Wraps a mouse backend and tells the guard about every synthetic event it sends."""
+
+    def __init__(self, backend: Any, guard: ManualInputGuard) -> None:
+        self._b = backend
+        self._g = guard
+
+    def move(self, x: int, y: int) -> None:
+        self._g.note_synthetic_move(x, y)
+        self._b.move(x, y)
+
+    def __getattr__(self, name: str) -> Any:
+        attr = getattr(self._b, name)
+        if callable(attr) and name in (
+            "click",
+            "press",
+            "release",
+            "scroll",
+            "key",
+            "click_button",
+            "hotkey",
+            "type_text",
+        ):
+
+            def wrapped(*a: Any, **k: Any) -> Any:
+                if name in ("key", "hotkey", "type_text"):
+                    self._g.note_synthetic_key()
+                else:
+                    self._g._synth_t = self._g.clock()
+                return attr(*a, **k)
+
+            return wrapped
+        return attr
+
+
+def start_listeners(guard: ManualInputGuard) -> list[Any]:  # pragma: no cover - needs a desktop session
+    from pynput import keyboard, mouse
+
+    ml = mouse.Listener(on_move=lambda x, y: guard.on_mouse_move(x, y), on_click=lambda *a: guard.on_click())
+    kl = keyboard.Listener(on_press=lambda _k: guard.on_key())
+    ml.start()
+    kl.start()
+    return [ml, kl]

away/app/autostart.py

@@ -0,0 +1,83 @@
+"""Start-at-login integration per OS (user level, no admin rights)."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+LABEL = "com.fernandogarzaaa.projectaway"
+RUN_KEY = r"Software\Microsoft\Windows\CurrentVersion\Run"
+
+
+def launch_command() -> list[str]:
+    if getattr(sys, "frozen", False):  # PyInstaller bundle
+        # inside an AppImage sys.executable is a temporary mount; $APPIMAGE is the file the user keeps
+        return [os.environ.get("APPIMAGE") or sys.executable, "tray"]
+    return [sys.executable, "-m", "away", "tray"]
+
+
+def linux_desktop_file(home: Path) -> Path:
+    base = Path(os.environ.get("XDG_CONFIG_HOME") or home / ".config")
+    return base / "autostart" / "project-away.desktop"
+
+
+def mac_plist(home: Path) -> Path:
+    return home / "Library" / "LaunchAgents" / f"{LABEL}.plist"
+
+
+def desktop_entry(cmd: list[str]) -> str:
+    exec_line = " ".join(f'"{c}"' if " " in c else c for c in cmd)
+    return (
+        "[Desktop Entry]\nType=Application\nName=Project Away\n"
+        f"Exec={exec_line}\nX-GNOME-Autostart-enabled=true\nNoDisplay=false\n"
+        "Comment=Hands-free PC control\n"
+    )
+
+
+def plist(cmd: list[str]) -> str:
+    args = "\n".join(f"    <string>{c}</string>" for c in cmd)
+    return (
+        '<?xml version="1.0" encoding="UTF-8"?>\n'
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n'
+        '<plist version="1.0"><dict>\n'
+        f"  <key>Label</key><string>{LABEL}</string>\n"
+        f"  <key>ProgramArguments</key><array>\n{args}\n  </array>\n"
+        "  <key>RunAtLoad</key><true/>\n"
+        "</dict></plist>\n"
+    )
+
+
+def enable(platform: str | None = None, home: Path | None = None, cmd: list[str] | None = None) -> str:
+    plat = platform or sys.platform
+    home = home or Path.home()
+    cmd = cmd or launch_command()
+    if plat.startswith("win"):  # pragma: no cover - needs Windows
+        import winreg  # type: ignore[import-not-found,unused-ignore]
+
+        with winreg.OpenKey(winreg.HKEY_CURRENT_USER, RUN_KEY, 0, winreg.KEY_SET_VALUE) as k:
+            winreg.SetValueEx(k, "ProjectAway", 0, winreg.REG_SZ, " ".join(f'"{c}"' for c in cmd))
+        return "HKCU\\" + RUN_KEY + "\\ProjectAway"
+    path = mac_plist(home) if plat == "darwin" else linux_desktop_file(home)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(plist(cmd) if plat == "darwin" else desktop_entry(cmd))
+    return str(path)
+
+
+def disable(platform: str | None = None, home: Path | None = None) -> bool:
+    plat = platform or sys.platform
+    home = home or Path.home()
+    if plat.startswith("win"):  # pragma: no cover - needs Windows
+        import winreg  # type: ignore[import-not-found,unused-ignore]
+
+        try:
+            with winreg.OpenKey(winreg.HKEY_CURRENT_USER, RUN_KEY, 0, winreg.KEY_SET_VALUE) as k:
+                winreg.DeleteValue(k, "ProjectAway")
+            return True
+        except FileNotFoundError:
+            return False
+    path = mac_plist(home) if plat == "darwin" else linux_desktop_file(home)
+    if path.exists():
+        path.unlink()
+        return True
+    return False

away/app/cursor_overlay.py

@@ -0,0 +1,110 @@
+"""At-cursor feedback ring (tkinter): pinch progress, drag, paused, dwell, hand lost.
+
+:func:`ring_spec` is pure (tested). :func:`run_cursor_overlay` polls a state
+function (``Pipeline.cursor_state``) about 30 times a second and draws a small
+ring next to the cursor in a borderless, always-on-top window. On Windows the
+window is made click-through; elsewhere it sits offset from the hotspot so it
+never covers what you click. Idea from Tracky Mouse's dwell/gesture overlay (MIT);
+implementation is original.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+from collections.abc import Callable
+from typing import Any
+
+COLORS = {
+    "idle": "#7CFC9A",
+    "pinch": "#FFD54F",
+    "drag": "#4FC3F7",
+    "paused": "#9E9E9E",
+    "dwell": "#CE93D8",
+    "hand_lost": "#9E9E9E",
+    "click": "#FFFFFF",
+}
+SIZE = 34  # window size in px
+OFFSET = (18, 18)  # from the cursor hotspot (keeps the ring out from under the pointer)
+
+
+def ring_spec(state: dict[str, Any]) -> dict[str, Any]:
+    """What to draw: ``{"color", "extent", "filled", "visible", "width"}``; ``extent`` in degrees (0..360)."""
+    s = str(state.get("state", "idle"))
+    pinch = float(state.get("pinch", 0.0) or 0.0)
+    dwell = float(state.get("dwell", 0.0) or 0.0)
+    if s == "paused":
+        return {"color": COLORS["paused"], "extent": 360.0, "filled": False, "visible": True, "width": 2}
+    if s == "hand_lost":
+        return {"color": COLORS["hand_lost"], "extent": 360.0, "filled": False, "visible": True, "width": 1}
+    if s == "drag":
+        return {"color": COLORS["drag"], "extent": 360.0, "filled": True, "visible": True, "width": 4}
+    if s == "dwell":
+        return {"color": COLORS["dwell"], "extent": 360.0 * dwell, "filled": False, "visible": True, "width": 4}
+    if s == "pinch":
+        return {"color": COLORS["pinch"], "extent": 360.0, "filled": True, "visible": True, "width": 4}
+    # idle: the ring fills as the pinch closes, invisible when the hand is relaxed
+    return {"color": COLORS["idle"], "extent": 360.0 * pinch, "filled": False, "visible": pinch > 0.05, "width": 3}
+
+
+def _click_through(root: Any) -> None:  # pragma: no cover - Windows only
+    if not sys.platform.startswith("win"):
+        return
+    import ctypes
+
+    hwnd = ctypes.windll.user32.GetParent(root.winfo_id())
+    style = ctypes.windll.user32.GetWindowLongW(hwnd, -20)  # GWL_EXSTYLE
+    ctypes.windll.user32.SetWindowLongW(hwnd, -20, style | 0x00080000 | 0x00000020)  # LAYERED | TRANSPARENT
+
+
+def run_cursor_overlay(state_fn: Callable[[], dict[str, Any]], status_bus: Any = None) -> None:  # pragma: no cover
+    import tkinter as tk
+
+    key = "#010203"
+    root = tk.Tk()
+    root.overrideredirect(True)
+    root.attributes("-topmost", True)
+    try:
+        root.attributes("-transparentcolor", key)  # Windows
+    except tk.TclError:
+        with contextlib.suppress(tk.TclError):
+            root.attributes("-alpha", 0.85)  # X11/macOS: no colour keying; a slightly see-through square
+    cv = tk.Canvas(root, width=SIZE, height=SIZE, bg=key, highlightthickness=0)
+    cv.pack()
+    root.update_idletasks()
+    _click_through(root)
+    if status_bus is not None:
+        from away.app.overlay import status_text
+
+        top = tk.Toplevel(root)
+        top.overrideredirect(True)
+        top.attributes("-topmost", True)
+        top.geometry("+20+20")
+        label = tk.Label(top, text="Project Away", bg="#111", fg="#7CFC9A", padx=10, pady=4)
+        label.pack()
+        status_bus.subscribe("*", lambda ev: (s := status_text(ev)) and label.after(0, label.config, {"text": s}))
+
+    def tick() -> None:
+        try:
+            st = state_fn()
+        except Exception:
+            st = {"state": "hand_lost"}
+        spec = ring_spec(st)
+        cv.delete("all")
+        if spec["visible"]:
+            pad = spec["width"] + 1
+            box = (pad, pad, SIZE - pad, SIZE - pad)
+            if spec["filled"]:
+                cv.create_oval(*box, outline=spec["color"], width=spec["width"], fill=spec["color"])
+            elif spec["extent"] >= 359.9:
+                cv.create_oval(*box, outline=spec["color"], width=spec["width"])
+            elif spec["extent"] > 0:
+                cv.create_arc(
+                    *box, start=90, extent=-spec["extent"], style="arc", outline=spec["color"], width=spec["width"]
+                )
+        x, y = int(st.get("x", 0)), int(st.get("y", 0))
+        root.geometry(f"{SIZE}x{SIZE}+{x + OFFSET[0]}+{y + OFFSET[1]}")
+        root.after(33, tick)
+
+    tick()
+    root.mainloop()