Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
"""Jarvis-Orb as a native desktop overlay (Tkinter + Pillow + numpy).
History of approaches tried and why we landed on Tkinter:
- pywebview + WebView2 Canvas: WebView2 renders via DirectComposition,
so SetWindowRgn/LWA_COLORKEY have no effect → a rectangular box remained.
- PySide6 + WA_TranslucentBackground: Qt6+DWM on Windows 11 frequently
delivers only an opaque black backing buffer + a DropShadow frame
instead of real transparency. Dozens of known Qt bugs, no robust fix.
- Tkinter + wm_attributes('-transparentcolor'): uses the classic
Win32 SetLayeredWindowAttributes API with LWA_COLORKEY. Stable since
Windows 2000, independent of DWM compositor quirks. Magenta (#FF00FF)
becomes pixel-perfect transparent — Windows routes those pixels
straight through to the desktop.
Rendering pipeline:
numpy computes a 108x108 RGB buffer per frame. Radial gradients,
additive swirls, and the bright core are executed as vector operations
on the distance arrays (precomputed once in the constructor).
Hard circle edge, no alpha fade outward — otherwise pink anti-aliasing
pixels would appear at the color-key boundary. Pillow wraps the array
into a PhotoImage that Tkinter renders onto a Canvas.
Public API:
overlay = OrbOverlay(style="mascot") # the mascot pet (or a custom PNG)
overlay = OrbOverlay(style="voice_orb") # procedural weather sphere
overlay.start() # blocks until mainloop exit
overlay.show(mode="listen") # voice modes: idle/listen/speak/think
overlay.show(mode="speak")
overlay.show(mode="dictate") # dictation modes: recording ...
overlay.show(mode="dictate_transcribing") # ... and transcribing
overlay.hide()
overlay.set_level(0.42)
overlay.set_style("mascot") # runtime switch, no restart
ENV overrides:
JARVIS_ORB_STYLE=mascot|voice_orb # legacy "orb" requests are ignored
JARVIS_ORB_MASCOT_PATH=<path.png> # alternative mascot path
Standalone test:
python -m ui.orb.overlay # demo sequence (mascot)
python -m ui.orb.overlay --sticky # permanently visible (preview)
python -m ui.orb.overlay --sticky --mascot # SWG mascot, static
python -m ui.orb.overlay --sticky --voice-orb # procedural voice orb
python -m ui.orb.overlay --mic --mascot # SWG + mic-reactive
"""
from __future__ import annotations
import argparse
import logging
import math
import os
import queue
import sys
import threading
import time
import tkinter as tk
import tkinter.font as tkfont
from collections import OrderedDict
from collections.abc import Callable, Hashable
from dataclasses import dataclass, replace
from pathlib import Path
from typing import Any
import numpy as np
from PIL import Image, ImageDraw, ImageFilter, ImageTk
from dodaios.core.config import DEFAULT_CONFIG_FILE as JARVIS_TOML_PATH
from dodaios.core.win32_dpi import ensure_dpi_awareness as _ensure_dpi_awareness
from dodaios.ui.dodaiosbar.modes import ACTIVE_VOICE_MODES, MODES
from dodaios.ui.overlay_styles import LEGACY_STYLE_ALIASES, MASCOT_PET_ID, ORB_STYLES
from dodaios.ui.pets.states import ACTION_STATES, DEFAULT_PET_ID, NO_PET_ID, ONE_SHOT_STATES
from ui.orb import controls as orb_controls
from ui.orb.animations import (
ANIMATION_REGISTRY,
Animation,
ArmTransform,
Transform,
identity_arm,
identity_transform,
make_animation,
)
from ui.orb.drag_persistence import (
MascotPosition,
clamp_to_work_area,
clear_position_in_toml,
load_allow_secondary_monitor_pin,
load_position_from_toml,
resolve_placement,
save_position_to_toml,
screens_from_tk,
)
from ui.orb.notice_stack import PetNoticeStack
from ui.orb.pet_renderer import PET_TARGET_EDGE_PX, PetRenderer, dpi_ratio_for
from ui.orb.taskbar import (
MascotAnchor,
compute_mascot_position,
get_taskbar_info,
get_tray_notify_rect,
)
from ui.orb.thought_bubble import PetThoughtBubble
from ui.orb.voice_orb import VoiceOrbRenderer
#: The looks this window can wear (ONE definition, in dodaios.ui.overlay_styles):
#: ``mascot`` is the Gigi ghost, ``voice_orb`` the procedural weather sphere —
#: the desktop twin of the in-app orb. Both share this window, so both are
#: always on top and draggable to any monitor. The removed legacy procedural
#: "orb" style is coerced to the mascot.
DEFAULT_ORB_STYLE = "mascot"
@dataclass
class _DragState:
"""In-flight drag tracking. ``moved`` flips True once the threshold is crossed."""
start_root_x: int
start_root_y: int
offset_x: int # event.x_root - mascot_x at press time
offset_y: int
moved: bool = False
# 108x108 — roughly 1/3 smaller than the old 160-px size
WIN_W = 108
WIN_H = 108
#: The voice orb's window. Twice the mascot's edge, which is NOT the same as
#: twice the sphere: the sphere rests at 70 % of the window (162 px — the 50 %
#: larger sphere the maintainer asked for on 2026-08-06), and the margin that
#: leaves is where the aura lives. The corona and its outgoing waves have to be
#: drawn INSIDE this window like everything else, so the window has to be
#: bigger than the thing it draws. The mascot keeps 108: its artwork, taskbar
#: anchor and animations are all drawn for that size.
VOICE_ORB_WIN_W = 216
VOICE_ORB_WIN_H = 216
def window_size_for_style(style: str, renderer: object | None = None) -> tuple[int, int]:
"""Window size for one orb style.
The pet's size is not a constant: it comes from its sprite sheet, the
monitor's DPI and the user's ``pet_scale``, all of which the loaded
:class:`PetRenderer` knows. Before one exists the pet gets its nominal
edge, which the real size replaces the moment the pack is loaded.
"""
if style == "voice_orb":
return VOICE_ORB_WIN_W, VOICE_ORB_WIN_H
if style == "pet":
size = getattr(renderer, "size", None)
if isinstance(size, tuple) and len(size) == 2:
return max(1, int(size[0])), max(1, int(size[1]))
return PET_TARGET_EDGE_PX, PET_TARGET_EDGE_PX
return WIN_W, WIN_H
MARGIN_RIGHT = 24
MARGIN_TOP = 28
# Anchor margins fed to ui.orb.taskbar.compute_mascot_position so the mascot
# stands on the real Windows taskbar top edge (Shell_TrayWnd, read live).
TRAY_SAFE_MARGIN_PX = 14
RIGHT_EDGE_MARGIN_PX = 24
TASKBAR_OVERLAP_PX = 1
AUTOHIDE_BOTTOM_MARGIN_PX = 16
POSITION_RECHECK_MS = 1500
# Drag-and-pin threshold (manhattan distance, px). Below this we treat
# the gesture as a click (no movement, no persistence). Raised from 5 to
# 16 on 2026-05-18 (BUG-027): an over-eager 5 px threshold meant a casual
# mouse twitch during a double-click could commit a pin, which silently
# moved the orb onto a secondary monitor where the user could not see it.
DRAG_THRESHOLD_PX = 16
# Mute gesture window (ms). After one ``<Double-Button-1>`` event we wait
# this long for a second double-click; only then does the mute toggle
# actually fire. The 2026-05-17 single-double-click implementation
# muted Jarvis whenever the user clicked the freshly popped-up orb,
# silently locking the wake-loop. Two double-clicks (four clicks total)
# in under 600 ms is intentional, easy to perform when wanted, and
# practically impossible to trigger by accident on an aware-popup hit.
MUTE_GESTURE_WINDOW_MS = 600
# Comment bubble — mirrors the gigi-bubble look from the Desktop App.
BUBBLE_BG_HEX = "#0F0F0F"
BUBBLE_BORDER_HEX = "#FFE500"
BUBBLE_TEXT_HEX = "#FFF200"
BUBBLE_PADDING_X = 14
BUBBLE_PADDING_Y = 8
BUBBLE_CORNER_RADIUS = 14
BUBBLE_GAP_FROM_ORB = 6
BUBBLE_MAX_WIDTH = 240
BUBBLE_MIN_WIDTH = 60
BUBBLE_FONT_FAMILY = "Segoe UI"
BUBBLE_FONT_SIZE = 11
BUBBLE_BORDER_WIDTH = 2
BUBBLE_TAIL_W = 18
BUBBLE_TAIL_H = 10
TRANSCRIPT_BUBBLE_WIDTH = 370
TRANSCRIPT_BUBBLE_TEXT_WIDTH = 332
TRANSCRIPT_BUBBLE_FONT_SIZE = 12
TRANSCRIPT_MAX_VISIBLE_LINES = 4
# Min on-screen time so fast LISTENING→THINKING bounces are still readable.
BUBBLE_MIN_SHOW_S = 1.1
@dataclass(frozen=True)
class BubbleTheme:
"""How the speech bubble is painted for one orb style.
The bubble used to be the mascot's bubble, full stop: black body, thick
yellow border, bold yellow text — the comic look that belongs to the Gigi
ghost. Beside the procedural sphere that reads as a different program's
window sitting on the same desktop, which is exactly what the maintainer
reported (2026-08-06). So the look travels with the style instead of being
baked into the widget: the ghost keeps its bubble, the orb gets the app's
own quiet surface (``bg-background/85`` + ``border-border/50`` +
``text-muted-foreground``, flattened — a layered Tk window has no partial
alpha), and neither one has to compromise for the other.
"""
bg: str
border: str
text: str
border_width: int
#: Bold is the mascot's voice. The orb's transcript is read, not shouted.
bold: bool
#: A tail points at a character that is speaking. The orb is not a mouth,
#: and the in-app bubble it copies has no tail either.
tail: bool
corner_radius: int
#: The pet's status lines are read as narration, not speech.
italic: bool = False
#: The muted header line above a pet status ("Thinking …").
header: str = "#8A8A8A"
#: The Gigi bubble, unchanged — the ghost's own voice.
MASCOT_BUBBLE_THEME = BubbleTheme(
bg=BUBBLE_BG_HEX,
border=BUBBLE_BORDER_HEX,
text=BUBBLE_TEXT_HEX,
border_width=BUBBLE_BORDER_WIDTH,
bold=True,
tail=True,
corner_radius=BUBBLE_CORNER_RADIUS,
)
#: The app's surface, so the desktop orb and the in-app orb read as one thing.
#: The border is a shade above the app's ``--border``: in the app a shadow
#: separates the bubble from what is behind it, and a colour-keyed window
#: cannot cast one without fringing.
ORB_BUBBLE_THEME = BubbleTheme(
bg="#121212",
border="#333333",
text="#B4B4B4",
border_width=1,
bold=False,
tail=False,
corner_radius=16,
)
#: The comment bubble's look while the pet is the style: a dark pill with a
#: hairline border, a bold light title and a muted detail line, no tail and no
#: italics. ``header`` is the title colour, ``text`` the detail colour.
PET_BUBBLE_THEME = BubbleTheme(
bg="#1E1F22",
border="#3A3B40",
text="#A0A1A7",
border_width=1,
bold=False,
tail=False,
corner_radius=26,
italic=False,
header="#F3F3F3",
)
def bubble_theme_for_style(style: str) -> BubbleTheme:
"""The bubble look one orb style wears."""
if style == "voice_orb":
return ORB_BUBBLE_THEME
if style == "pet":
return PET_BUBBLE_THEME
return MASCOT_BUBBLE_THEME
#: The default linger of the pet's ``clear_status`` (its thought bubble).
PET_STATUS_LINGER_S = 1.5
PET_BUBBLE_GAP = 8
#: The notification cards are this many times the strip's width.
PET_NOTICE_WIDTH_PER_STRIP = 1.5
# Magenta color key — Tkinter renders this color pixel-perfect transparent
COLOR_KEY_HEX = "#FF00FF"
COLOR_KEY_RGB = np.array([255, 0, 255], dtype=np.uint8)
def _is_bare_thinking_label(text: str) -> bool:
"""Is ``text`` only the generic "Thinking …" label (in any interface language)?"""
try:
from ui.orb.bus_bridge import PET_CARD_LABELS # noqa: PLC0415 — lazy, optional
except Exception: # noqa: BLE001 — without the labels, words are shown as words
return False
word = text.rstrip(" .…")
return any(word == label.rstrip(" .…") for label in PET_CARD_LABELS["thinking"].values())
def key_to_alpha(img: Image.Image) -> Image.Image:
"""RGB frame → RGBA with the magenta color key mapped to full transparency.
Windows keys the magenta out natively (layered-window color key); macOS
has no color-key concept, so the Tk surface there shows RGBA frames on a
``-transparent`` root instead. Exact-match keying mirrors the Windows
contract: only pure ``COLOR_KEY_RGB`` pixels vanish.
"""
arr = np.asarray(img, dtype=np.uint8)
alpha = np.where((arr == COLOR_KEY_RGB).all(axis=-1), 0, 255).astype(np.uint8)
return Image.fromarray(np.dstack((arr, alpha)), "RGBA")
# Warn-once latch: the clear-backing pass runs on every reveal, but a missing
# pyobjc should produce ONE actionable warning, not a log storm.
_WARNED_NO_APPKIT = False
def apply_macos_clear_backing() -> None:
"""Make every NSWindow of THIS process paint a clear backing (BUG-075).
Tk 8.6 aqua turned the ``systemTransparent`` background into true
per-pixel transparency; Tk 9 (bundled by uv's python-build-standalone)
paints it as an opaque appearance color instead — the surface showed a
solid grey box around its artwork. A non-opaque window backing with a
clear background is the native, Tk-version-independent equivalent.
Runs only inside the overlay host process, whose every window wants a
clear backing. Safe post-BUG-067: Tk owns ``NSApp`` before any window
exists here. Best-effort, never raises.
"""
if sys.platform != "darwin":
return
import logging # noqa: PLC0415
orb_log = logging.getLogger("jarvis.orb")
try:
from AppKit import NSApp, NSColor # type: ignore[import-not-found] # noqa: PLC0415
except Exception: # noqa: BLE001
# Without this pass Tk 9 paints the window backing as an OPAQUE grey
# box (BUG-075) — the single most visible macOS defect. Say so loudly
# once instead of hiding the cause in a debug line.
global _WARNED_NO_APPKIT
if not _WARNED_NO_APPKIT:
_WARNED_NO_APPKIT = True
orb_log.warning(
"pyobjc (AppKit) unavailable — Tk 9 paints the mascot backing "
"as an opaque grey box. Install the [desktop-macos] extra "
"(pip install 'personal-jarvis[desktop-macos]') to fix it."
)
return
try:
wins = list(NSApp.windows())
for win in wins:
win.setOpaque_(False)
win.setBackgroundColor_(NSColor.clearColor())
win.setHasShadow_(False)
from dodaios.platform.capture_exclusion import ( # noqa: PLC0415
exclude_macos_app_windows,
)
exclude_macos_app_windows()
orb_log.debug("macOS clear-backing applied to %d window(s)", len(wins))
except Exception: # noqa: BLE001 — cosmetic; the grey box is the degrade
orb_log.warning("macOS clear-backing pass failed", exc_info=True)
_GWL_EXSTYLE = -20
_WS_EX_APPWINDOW = 0x00040000
_WS_EX_TOOLWINDOW = 0x00000080
TAU = math.tau
# Default path for the SWG/Gigi mascot. Looked up by MascotRenderer when no
# explicit path is passed in. Resolved relative to the project root.
DEFAULT_MASCOT_REL = "assets/icons/dodaios-gigi-256.png"
def _transcript_visible_line_count(text_height: int, line_height: int) -> int:
"""Return how many transcript lines should shape the bubble height."""
safe_line_height = max(1, line_height)
lines = max(1, math.ceil(max(1, text_height) / safe_line_height))
return min(TRANSCRIPT_MAX_VISIBLE_LINES, lines)
def _transcript_body_height(line_count: int, line_height: int) -> int:
visible_lines = max(1, min(TRANSCRIPT_MAX_VISIBLE_LINES, line_count))
return (BUBBLE_PADDING_Y * 2) + (max(1, line_height) * visible_lines)
def mode_energy(mode: str, t: float, ext_level: float | None) -> float:
"""Return the raw drive level (0..1) the mascot renders ``mode`` with.
The mascot has exactly one expressive channel: energy. It feeds the halo
threshold, the breathing scale and the brightness, so "what a mode looks
like" on this surface *is* the curve this function returns. Pulled out of
:meth:`MascotRenderer.render` so the per-mode contract is directly testable
without a Tk root, a PNG asset or a frame buffer.
Voice modes keep their historical behaviour to the letter: a live level
(mic or TTS loudness) always wins, and each mode has its own synthetic
fallback curve.
The two dictation modes are deliberately NOT variations of ``listen``:
* ``dictate`` — recording. The dictation session feeds the very same mic
level channel, so the live signal drives the halo exactly like the bar's
equalizer. It is clamped up from a floor, because a quiet moment while
recording must still read as "I am listening", never as a dead mascot.
* ``dictate_transcribing`` — the key is released and the mic feed has
stopped, so the last sample would otherwise freeze the mascot at whatever
loudness the user happened to end on. This mode therefore ignores the
stale level outright and runs a steady work pulse instead — the mascot's
equivalent of the bar's orbital core.
``notice`` — something the user asked for did not happen. Like
``dictate_transcribing`` it IGNORES the live level: the mascot must not
shimmer along with a microphone it is not using while it says the opposite.
It runs a low, slow breath — clearly awake (a dead-flat mascot reads as a
crashed one) and clearly not listening. On this surface the reason itself
is legible in the speech bubble, so the energy only has to avoid
contradicting it.
"""
if mode == "notice":
return max(0.0, min(1.0, 0.16 + 0.08 * math.sin(t * 1.1)))
if mode == "dictate":
live = 0.0 if ext_level is None else max(0.0, min(1.0, ext_level))
floor = 0.22 + 0.14 * math.sin(t * 1.6)
return max(0.0, min(1.0, max(live, floor)))
if mode == "dictate_transcribing":
return max(0.0, min(1.0, 0.30 + 0.16 * math.sin(t * 2.2)))
if ext_level is not None:
return max(0.0, min(1.0, ext_level))
if mode == "speak":
return 0.35 + 0.25 * math.sin(t * 1.8) + 0.1 * math.sin(t * 3.3)
if mode == "think":
return 0.2 + 0.12 * math.sin(t * 2.5)
if mode == "listen":
return 0.25 + 0.18 * math.sin(t * 1.4) + 0.08 * math.sin(t * 2.7)
return 0.0
def _resolve_mascot_path(path_str: str | None) -> Path | None:
"""Looks for the mascot PNG in the common locations.
Order: explicit path → ENV ``JARVIS_ORB_MASCOT_PATH`` → project root
(walking up from the module). Returns None when no asset is available; callers
keep the overlay invisible instead of falling back to the removed legacy orb.
"""
candidates: list[Path] = []
if path_str:
candidates.append(Path(path_str))
env_path = os.environ.get("JARVIS_ORB_MASCOT_PATH")
if env_path:
candidates.append(Path(env_path))
# Find the project root: this file lives at <root>/ui/orb/overlay.py
here = Path(__file__).resolve()
for parent in [here.parent, here.parent.parent, here.parent.parent.parent]:
candidates.append(parent / DEFAULT_MASCOT_REL)
for c in candidates:
if c.is_file():
return c
return None
def _apply_jarvis_icon_to_tk_root(root: tk.Tk) -> None:
"""Set the Jarvis taskbar/titlebar icon on this Tk root.
Thin wrapper over the canonical, cross-platform
:func:`dodaios.ui.icon_utils.apply_tk_window_icon` so the orb and the
JarvisBar share ONE implementation — the two used to drift apart, which is
how the JarvisBar regressed to the Python logo (BUG #UI-Pin-2026-05-05).
Best-effort; any failure is silent (the orb is cosmetic).
"""
try:
from dodaios.ui.icon_utils import apply_tk_window_icon
apply_tk_window_icon(root)
except Exception: # noqa: BLE001
import logging
logging.getLogger("jarvis.orb").debug(
"Tk icon setup failed; continuing without it.",
exc_info=True,
)
def _coerce_style(style: str | None) -> str:
"""Return a style this window can actually render.
Unknown values (the removed legacy ``"orb"``, a typo, a value written by a
newer build into an older ``jarvis.toml``) fall back to the mascot with one
warning rather than leaving the desktop without any overlay at all.
"""
candidate = (style or "").strip().lower()
candidate = LEGACY_STYLE_ALIASES.get(candidate, candidate)
if candidate in ORB_STYLES:
return candidate
import logging
logging.getLogger("jarvis.orb").warning(
"Unknown orb style %r — falling back to %r (known: %s).",
style,
DEFAULT_ORB_STYLE,
", ".join(ORB_STYLES),
)
return DEFAULT_ORB_STYLE
def _apply_color_key(root: tk.Tk) -> bool:
"""Make the key colour transparent on this Tk root. False = not supported.
Windows keys the magenta out natively on the layered window. On Linux the
same attribute is accepted only under a compositing window manager; under a
bare X11 session (and on Wayland) Tk raises, and the honest outcome is "no
overlay" rather than an opaque magenta square parked on the desktop. The
caller degrades; this never raises.
"""
try:
root.wm_attributes("-transparentcolor", COLOR_KEY_HEX)
root.configure(bg=COLOR_KEY_HEX)
return True
except tk.TclError:
import logging
logging.getLogger("jarvis.orb").warning(
"This desktop session does not support Tk's transparent colour key "
"(typical for Wayland or X11 without a compositor) — the on-screen "
"orb stays hidden. Voice, the tray icon and the app window are "
"unaffected; pick 'None (hidden)' as the display style to silence "
"this."
)
return False
def _hide_tk_window_from_task_switcher(root: tk.Tk) -> None:
"""Marks the orb window as a toolwindow so it doesn't count as an app."""
if sys.platform != "win32":
return
try:
import ctypes
hwnd = int(root.winfo_id())
user32 = ctypes.windll.user32
get_long = getattr(user32, "GetWindowLongPtrW", user32.GetWindowLongW)
set_long = getattr(user32, "SetWindowLongPtrW", user32.SetWindowLongW)
style = int(get_long(hwnd, _GWL_EXSTYLE))
style = (style | _WS_EX_TOOLWINDOW) & ~_WS_EX_APPWINDOW
set_long(hwnd, _GWL_EXSTYLE, style)
except Exception:
# Pure desktop cosmetics. If Win32 doesn't take effect, the orb
# stays functional and may just show up as an extra window.
return
def _exclude_tk_window_from_capture(root: tk.Tk) -> None:
"""Keep the orb / transcription bubble out of screenshots. Best-effort."""
try:
from dodaios.platform.capture_exclusion import ( # noqa: PLC0415
exclude_tk_window_from_capture,
)
exclude_tk_window_from_capture(root)
except Exception: # noqa: BLE001 — overlay must degrade, never crash
return
class MascotRenderer:
"""Renderer for the SWG/Gigi mascot.
Implements the render interface ``render(t, mode, ext_level) -> Image.Image``
used by ``OrbOverlay``.
Notable details:
- Alpha threshold (binary): antialiasing edges would create pink
fringes on magenta during compositing. For the pixel-art Gigi
style, binary alpha is a good fit anyway.
- Soft glow: a gaussian-blurred alpha-mask derivative provides a
warm halo around the mascot that pulses with ``energy``.
- Breathing scale: the mascot breathes (±3%) and scales with
energy up to ~107%. Scaling uses NEAREST — this matches the
pixel-art look and is nearly free per frame.
"""
def __init__(self, image_path: Path) -> None:
raw = Image.open(image_path).convert("RGBA")
# Once to target size; NEAREST is enough for per-frame scaling.
base = raw.resize((WIN_W, WIN_H), Image.LANCZOS)
self._base_rgba = np.asarray(base).copy() # (H,W,4) uint8
self._base_pil = base
self._image_path = image_path
# Soft glow mask from a gaussian-blurred alpha. Values 0..1.
# Radius 6 gives a clearly visible but tight halo.
alpha_only = base.split()[3]
blurred = alpha_only.filter(ImageFilter.GaussianBlur(radius=6))
self._glow_mask = np.asarray(blurred).astype(np.float32) / 255.0
# Alpha threshold for the mascot itself (binary).
self._solid_mask = np.asarray(alpha_only) >= 128
# Body-part decomposition: extract the actual arm stubs as their
# own sprites with a pivot point. This lets animations rotate the
# REAL arm instead of drawing a second one next to it.
# _arm_left_sprite, _arm_right_sprite: small RGBA images with arm + transparent.
# _arm_left_pivot, _arm_right_pivot: (x, y) in the frame coordinate system,
# the point the rotation runs around (shoulder toward the body).
# _body_no_arms_pil: mascot PIL without the arm pixels (alpha=0 there).
# _arm_left_local_pivot: pivot relative to the sprite rectangle (in sprite pixels).
decomp = self._decompose_arms(base)
self._arm_left_sprite: Image.Image = decomp["left_sprite"]
self._arm_right_sprite: Image.Image = decomp["right_sprite"]
self._arm_left_pivot: tuple[int, int] = decomp["left_pivot"]
self._arm_right_pivot: tuple[int, int] = decomp["right_pivot"]
self._arm_left_local_pivot: tuple[int, int] = decomp["left_local_pivot"]
self._arm_right_local_pivot: tuple[int, int] = decomp["right_local_pivot"]
self._body_no_arms_pil: Image.Image = decomp["body_no_arms"]
self._level: float = 0.0
# Active animations — filtered per frame (is_finished).
# A list rather than a set so FIFO order stays deterministic for
# layering (animations added earlier draw beneath later ones).
self._animations: list[Animation] = []
# Mouth-anim deadline (in render-time `t` seconds). Mouth runs only
# while `t < self._mouth_anim_until_t`. Outside that window the
# original PNG mouth shows through unchanged.
self._mouth_anim_until_t: float = -1.0
# Hard-coded arm bounding boxes (measured on the 108x108 render of
# dodaios-gigi-256.png, 2026-04-25). Heuristic detection was unreliable
# because the body outline also contains yellow pixels (clusters overlap).
# These bboxes capture ONLY the actual stub — a clean separation.
# If the asset changes: re-measure manually and update these here.
# Sprite bbox: large enough to capture the stub + all outline tips.
# Body-erase bbox: tighter, exactly on the stub — otherwise "holes"
# appear in the body at the default pose (rot=0), because the sprite
# doesn't fully fill the cleared area.
ARM_LEFT_BBOX = (10, 55, 22, 79)
ARM_LEFT_PIVOT = (20, 62)
ARM_LEFT_ERASE_BBOX = (12, 58, 21, 76)
ARM_RIGHT_BBOX = (86, 57, 99, 79)
ARM_RIGHT_PIVOT = (87, 62)
ARM_RIGHT_ERASE_BBOX = (87, 60, 98, 76)
# Mouth overlay constants. Center mirrors the SVG ellipse cx=128 cy=146 in
# the 256px source; rx/ry mirror the SVG (rx=7 ry=10), scaled to 108px:
# rx≈3 ry=1..7. Animation runs only while _mouth_anim_until_t > t.
MOUTH_CENTER = (54, 62)
MOUTH_RX = 3.2
MOUTH_RY_CLOSED = 0.6
MOUTH_RY_OPEN = 7.0
MOUTH_ERASE_RX = 5.5
MOUTH_ERASE_RY = 9.0
MOUTH_BG_COLOR = (14, 14, 14)
MOUTH_FG_COLOR = (255, 229, 0)
MOUTH_INNER_COLOR = (5, 5, 5)
MOUTH_ANIM_HZ = 1.5
MOUTH_SUPERSAMPLE = 4
@classmethod
def _decompose_arms(cls, base: Image.Image) -> dict:
"""Separates the mascot's arm stubs from the body as separate sprites.
Uses hard-coded bounding boxes (ARM_LEFT_BBOX/ARM_RIGHT_BBOX)
instead of heuristic yellow-cluster detection — the latter also
picked up the body-outline pixels and produced unclean sprites with
stray pixels that distorted the arm after rotation.
Body erase: bbox + 2px padding is set entirely to alpha=0, so the
rotated arm has a clear path (no leftover outline in the shoulder
region that would otherwise cover the raised arm).
"""
arr = np.asarray(base) # (H,W,4)
def _extract_from_bbox(
sprite_bbox: tuple[int, int, int, int],
pivot_abs: tuple[int, int],
erase_bbox: tuple[int, int, int, int],
) -> dict:
x0, y0, x1, y1 = sprite_bbox
# Sprite crop: bbox + padding for rotation headroom
pad = 3
sprite_x0 = max(0, x0 - pad)
sprite_y0 = max(0, y0 - pad)
sprite_x1 = min(arr.shape[1], x1 + 1 + pad)
sprite_y1 = min(arr.shape[0], y1 + 1 + pad)
crop = arr[sprite_y0:sprite_y1, sprite_x0:sprite_x1].copy()
# Sprite mask: keep only pixels inside sprite_bbox
local_x0 = x0 - sprite_x0
local_y0 = y0 - sprite_y0
local_x1 = x1 + 1 - sprite_x0
local_y1 = y1 + 1 - sprite_y0
mask = np.zeros(crop.shape[:2], dtype=bool)
mask[local_y0:local_y1, local_x0:local_x1] = True
crop[~mask, 3] = 0
sprite = Image.fromarray(crop, mode="RGBA")
# Body erase: tighter than sprite_bbox, exactly on the stub.
# This way the default pose (rot=0) fully fills the erase hole
# and the body looks normal at idle.
ex0, ey0, ex1, ey1 = erase_bbox
body_erase = np.zeros(arr.shape[:2], dtype=bool)
body_erase[ey0 : ey1 + 1, ex0 : ex1 + 1] = True
# Local pivot relative to the sprite crop
pivot_local = (pivot_abs[0] - sprite_x0, pivot_abs[1] - sprite_y0)
return {
"sprite": sprite,
"pivot": pivot_abs,
"local_pivot": pivot_local,
"body_erase_mask": body_erase,
}
left = _extract_from_bbox(
cls.ARM_LEFT_BBOX,
cls.ARM_LEFT_PIVOT,
cls.ARM_LEFT_ERASE_BBOX,
)
right = _extract_from_bbox(
cls.ARM_RIGHT_BBOX,
cls.ARM_RIGHT_PIVOT,
cls.ARM_RIGHT_ERASE_BBOX,
)
# Body without arms: set all pixels inside the dilated arm region
# to alpha=0 — removes both the yellow stubs and the adjacent
# outline contours that would otherwise cover the raised arm.
body_arr = arr.copy()
for entry in (left, right):
mask = entry.get("body_erase_mask")
if mask is None:
continue
body_arr[mask, 3] = 0
body_no_arms = Image.fromarray(body_arr, mode="RGBA")
return {
"left_sprite": left["sprite"],
"right_sprite": right["sprite"],
"left_pivot": left["pivot"],
"right_pivot": right["pivot"],
"left_local_pivot": left["local_pivot"],
"right_local_pivot": right["local_pivot"],
"body_no_arms": body_no_arms,
}
# ------------------------------------------------------------------
# Animation API (called by OrbOverlay, Tk main thread)
# ------------------------------------------------------------------
def add_animation(self, animation: Animation) -> None:
"""Adds a running animation. Threading: the caller ensures this
happens on the Tk main thread (OrbOverlay queues via root.after).
"""
self._animations.append(animation)
def stop_animation(self, name: str) -> int:
"""Removes all running animations with the given name.
Returns the number of stopped instances."""
before = len(self._animations)
self._animations = [a for a in self._animations if a.name != name]
return before - len(self._animations)
def clear_animations(self) -> None:
self._animations.clear()
def active_animation_names(self) -> list[str]:
return [a.name for a in self._animations]
def start_mouth_anim(self, duration_s: float, t_now: float) -> None:
"""Schedule the mouth-talk overlay to run for `duration_s` seconds."""
if duration_s <= 0:
return
self._mouth_anim_until_t = t_now + duration_s
def stop_mouth_anim(self) -> None:
"""Immediately end the mouth-talk overlay."""
self._mouth_anim_until_t = -1.0
def _overlay_mouth(self, frame: np.ndarray, t: float) -> None:
"""Replace the mouth area with a smoothly animated open/close ellipse.
Renders into a 4× super-sampled PIL buffer and LANCZOS-downscales,
so the mouth opens with sub-pixel-smooth anti-aliased edges instead
of jumping between integer pixel rows.
"""
if t >= self._mouth_anim_until_t:
return
cx, cy = self.MOUTH_CENTER
openness = 0.5 - 0.5 * math.cos(t * self.MOUTH_ANIM_HZ * TAU)
ry = self.MOUTH_RY_CLOSED + openness * (self.MOUTH_RY_OPEN - self.MOUTH_RY_CLOSED)
rx = self.MOUTH_RX
sub_pad = 4
sub_w_half = int(math.ceil(self.MOUTH_ERASE_RX)) + sub_pad
sub_h_half = int(math.ceil(self.MOUTH_ERASE_RY)) + sub_pad
x0 = max(0, cx - sub_w_half)
y0 = max(0, cy - sub_h_half)
x1 = min(frame.shape[1], cx + sub_w_half + 1)
y1 = min(frame.shape[0], cy + sub_h_half + 1)
if x1 <= x0 or y1 <= y0:
return
sub_w = x1 - x0
sub_h = y1 - y0
ss = self.MOUTH_SUPERSAMPLE
sub_pil = Image.fromarray(frame[y0:y1, x0:x1], mode="RGB")
big = sub_pil.resize((sub_w * ss, sub_h * ss), Image.NEAREST)
draw = ImageDraw.Draw(big)
big_cx = (cx - x0) * ss
big_cy = (cy - y0) * ss
erx = self.MOUTH_ERASE_RX * ss
ery = self.MOUTH_ERASE_RY * ss
draw.ellipse(
[big_cx - erx, big_cy - ery, big_cx + erx, big_cy + ery],
fill=self.MOUTH_BG_COLOR,
)
rx_b = rx * ss
ry_b = ry * ss
draw.ellipse(
[big_cx - rx_b, big_cy - ry_b, big_cx + rx_b, big_cy + ry_b],
fill=self.MOUTH_FG_COLOR,
)
if ry >= 1.6:
inner_rx = max(0.6, rx - 1.4) * ss
inner_ry = max(0.4, ry - 1.4) * ss
draw.ellipse(
[big_cx - inner_rx, big_cy - inner_ry, big_cx + inner_rx, big_cy + inner_ry],
fill=self.MOUTH_INNER_COLOR,
)
small = big.resize((sub_w, sub_h), Image.LANCZOS)
frame[y0:y1, x0:x1] = np.asarray(small)
def _aggregate_transform(self, t: float) -> Transform:
"""Folds all active animation transforms into one combined transform."""
result = identity_transform()
for anim in self._animations:
result = result.combine(anim.transform(t))
return result
def _aggregate_arm_transforms(self, t: float) -> tuple[ArmTransform, ArmTransform]:
"""Folds the left and right arm transforms from all active animations."""
left = identity_arm()
right = identity_arm()
for anim in self._animations:
left = left.combine(anim.arm_left_transform(t))
right = right.combine(anim.arm_right_transform(t))
return left, right
# ------------------------------------------------------------------
# Render pipeline
# ------------------------------------------------------------------
def render(self, t: float, mode: str, ext_level: float | None) -> Image.Image:
# Level smoothing mirrors the previous voice-reactive dynamics; the
# per-mode curve itself lives in ``mode_energy`` so it stays testable.
raw = mode_energy(mode, t, ext_level)
self._level += (raw - self._level) * 0.08
breath = 0.5 + 0.5 * math.sin(t * 0.9)
energy = max(self._level, breath * 0.1)
# --- Animation lifecycle: remove finished animations now, so their
# transforms and overlays no longer contribute a "last frame".
# Important before the aggregate_transform call.
if self._animations:
self._animations = [a for a in self._animations if not a.is_finished(t)]
anim_transform = self._aggregate_transform(t)
# Magenta background (color key → transparent)
frame = np.empty((WIN_H, WIN_W, 3), dtype=np.uint8)
frame[:] = COLOR_KEY_RGB
# --- 1. Warm halo around the mascot (gaussian-blurred alpha as mask)
# The color key is magenta — soft-blending with magenta creates pink
# fringes. So the halo is HARD: a pixel is either visible (full gold
# mix) or magenta (transparent). The threshold boundary shifts
# dynamically with energy — at high energy more of the blur gradient
# becomes visible and the halo feels "breathing/expanding".
halo_threshold = 0.55 - energy * 0.35 # 0.55 calm → 0.20 loud
halo_mask = (self._glow_mask > halo_threshold) & ~self._solid_mask
if halo_mask.any():
# Inside the halo: intensity rises with the glow_mask value
# (close to the mascot = brighter, outer edge = darker gold).
intensity = np.clip(
(self._glow_mask[halo_mask] - halo_threshold) / (1.0 - halo_threshold),
0.0,
1.0,
)
# Gold gradient: dark warm (80, 50, 0) → bright gold (255, 210, 80)
frame[halo_mask, 0] = (80 + 175 * intensity).astype(np.uint8)
frame[halo_mask, 1] = (50 + 160 * intensity).astype(np.uint8)
frame[halo_mask, 2] = (0 + 80 * intensity).astype(np.uint8)
# --- 2. PRE layer from animations (e.g. wind streaks behind the ghost)
if self._animations:
pre_layer = self._make_overlay_layer(t, which="pre")
if pre_layer is not None:
self._composite_layer(frame, pre_layer)
# --- 3. Body (without arms) + arms rendered separately with pivot rotation
# The animation transform (scale, rotation, dx/dy, brightness) is
# added/multiplied ON TOP of the breathing scale here.
breath_scale = 1.0 + 0.04 * math.sin(t * 0.9) + 0.03 * energy
total_scale = breath_scale * anim_transform.scale
sx = total_scale * anim_transform.skew_x
sy = total_scale * anim_transform.skew_y
target_w = max(16, int(round(WIN_W * sx)))
target_h = max(16, int(round(WIN_H * sy)))
body_dx = int(round(anim_transform.dx))
body_dy = int(round(anim_transform.dy))
body_rot_deg = -math.degrees(anim_transform.rotation)
brightness_factor = (1.0 + 0.08 * energy) * anim_transform.brightness
# Render the body without arms (body pixels + eyes + mouth + jagged
# base, ONLY the arm stubs are erased). This way rotated arms don't
# overlap the static stub and no "double-arm" artifacts appear.
self._composite_sprite_centered(
frame=frame,
sprite_pil=self._body_no_arms_pil,
target_w=target_w,
target_h=target_h,
rot_deg=body_rot_deg,
offset_dx=body_dx,
offset_dy=body_dy,
brightness=brightness_factor,
)
# Aggregate arm transforms from the active animations
arm_left_t, arm_right_t = self._aggregate_arm_transforms(t)
# Left arm — the pivot is the point of the stub closest to the body.
# When the body scales, the pivot scales with it (body-scale-aware).
if arm_left_t.visible:
self._composite_arm(
frame=frame,
arm_sprite=self._arm_left_sprite,
local_pivot=self._arm_left_local_pivot,
world_pivot=self._arm_left_pivot,
arm_t=arm_left_t,
body_scale_x=sx,
body_scale_y=sy,
body_offset_dx=body_dx,
body_offset_dy=body_dy,
body_rotation_rad=anim_transform.rotation,
brightness=brightness_factor,
)
if arm_right_t.visible:
self._composite_arm(
frame=frame,
arm_sprite=self._arm_right_sprite,
local_pivot=self._arm_right_local_pivot,
world_pivot=self._arm_right_pivot,
arm_t=arm_right_t,
body_scale_x=sx,
body_scale_y=sy,
body_offset_dx=body_dx,
body_offset_dy=body_dy,
body_rotation_rad=anim_transform.rotation,
brightness=brightness_factor,
)
# --- 3b. Talking-mouth overlay. Only repaints a small ellipse, only
# while a SPEAKING session is active (toggled by start/stop_mouth_anim
# from OrbBusBridge on AudioOutFirst events).
self._overlay_mouth(frame, t)
# --- 4. POST layer from animations (hand, thought bubble, Z-Z-Z…)
if self._animations:
post_layer = self._make_overlay_layer(t, which="post")
if post_layer is not None:
self._composite_layer(frame, post_layer)
return Image.fromarray(frame, mode="RGB")
# ------------------------------------------------------------------
# Overlay helpers
# ------------------------------------------------------------------
def _make_overlay_layer(self, t: float, which: str) -> Image.Image | None:
"""Asks all animations to paint their overlays into an RGBA layer.
Returns None if no animation touched the layer
(a cheap pixel check via the alpha-channel sum).
"""
layer = Image.new("RGBA", (WIN_W, WIN_H), (0, 0, 0, 0))
draw = ImageDraw.Draw(layer)
any_drawn = False
for anim in self._animations:
if which == "pre":
anim.draw_pre(draw, t)
else:
anim.draw_post(draw, t)
any_drawn = True
if not any_drawn:
return None
# Fast path: if the whole layer is empty (alpha=0) → None instead of compositing.
# We can check this without an extra walk: Pillow has getbbox().
if layer.getbbox() is None:
return None
return layer
def _composite_sprite_centered(
self,
frame: np.ndarray,
sprite_pil: Image.Image,
target_w: int,
target_h: int,
rot_deg: float,
offset_dx: int,
offset_dy: int,
brightness: float,
) -> None:
"""Scales and rotates a sprite, placing it centered + offset in the frame.
Used for the body (the whole mascot minus arms). The sprite is
scaled to target_w x target_h, then optionally rotated (around
center), then placed onto the frame using binary alpha (>= 128).
"""
if target_w == WIN_W and target_h == WIN_H and abs(rot_deg) < 0.05:
tmp = sprite_pil
else:
tmp = sprite_pil.resize((target_w, target_h), Image.NEAREST)
if abs(rot_deg) >= 0.05:
tmp = tmp.rotate(rot_deg, resample=Image.NEAREST, fillcolor=(0, 0, 0, 0))
arr = np.asarray(tmp)
ph, pw = arr.shape[:2]
cx_target = WIN_W // 2 + offset_dx
cy_target = WIN_H // 2 + offset_dy
x0 = cx_target - pw // 2
y0 = cy_target - ph // 2
self._blit_rgba_into_frame(frame, arr, x0, y0, brightness)
def _composite_arm(
self,
frame: np.ndarray,
arm_sprite: Image.Image,
local_pivot: tuple[int, int],
world_pivot: tuple[int, int],
arm_t: ArmTransform,
body_scale_x: float,
body_scale_y: float,
body_offset_dx: int,
body_offset_dy: int,
body_rotation_rad: float,
brightness: float,
) -> None:
"""Renders an arm sprite with pivot rotation around the shoulder.
Math:
1. The sprite has a local pivot (shoulder in the sprite coordinate system).
2. The world pivot is the shoulder in the frame (108x108 system).
3. The body transform (scale + body rotation around the body center)
moves the world pivot — we have to move the shoulder along with it.
4. The arm's own rotation rotates the sprite AROUND its local pivot.
5. The sprite is placed so that the local pivot lands on the
(shifted) world pivot.
PIL.rotate(center=...) rotates an image around a freely chosen point
— we use that for the pivot rotation. expand=True enlarges the
bounds so the rotated arm doesn't clip.
"""
if arm_sprite.size == (1, 1):
return # Decomposition produced an empty sprite (asset mismatch)
rot_deg_arm = -math.degrees(arm_t.rotation)
if abs(rot_deg_arm) < 0.05:
rotated = arm_sprite
new_pivot = local_pivot
else:
# Standard trick: pad the sprite into a larger canvas so the
# pivot sits exactly in the center. Then rotate with center=center —
# this behaves predictably (PIL.rotate without center, expand=False,
# rotates pixel-stably around the image midpoint).
sw, sh = arm_sprite.size
px, py = local_pivot
# How far is the pivot from the right/bottom edge?
# The new canvas must be large enough that the maximum distance
# from the pivot to any sprite corner has room in every direction
# (otherwise the rotation clips sprite pixels).
max_dist = int(math.ceil(math.hypot(max(px, sw - px), max(py, sh - py))))
canvas_size = 2 * max_dist + 4
canvas = Image.new("RGBA", (canvas_size, canvas_size), (0, 0, 0, 0))
# The sprite's pivot should land at the canvas center
paste_x = canvas_size // 2 - px
paste_y = canvas_size // 2 - py
canvas.paste(arm_sprite, (paste_x, paste_y))
# Rotation around the image midpoint — the center default applies, expand=False
rotated = canvas.rotate(rot_deg_arm, resample=Image.NEAREST, fillcolor=(0, 0, 0, 0))
# The new pivot position is the image midpoint
new_pivot = (canvas_size // 2, canvas_size // 2)
# World pivot of the shoulder, derived from the body center + the
# mascot-relative position. The unscaled world pivot is `world_pivot`
# in the 108-frame. When scaling, it must be scaled relative to the body center.
cx_body = WIN_W / 2.0
cy_body = WIN_H / 2.0
# Body-relative shoulder position (before scaling)
rel_x = world_pivot[0] - cx_body
rel_y = world_pivot[1] - cy_body
# Scale
rel_x *= body_scale_x
rel_y *= body_scale_y
# Body rotation: rotate the shoulder with the body
if abs(body_rotation_rad) >= 1e-4:
cr = math.cos(body_rotation_rad)
sr = math.sin(body_rotation_rad)
rel_x_r = rel_x * cr - rel_y * sr
rel_y_r = rel_x * sr + rel_y * cr
rel_x, rel_y = rel_x_r, rel_y_r
# World pivot after the body transform
world_pivot_x = cx_body + rel_x + body_offset_dx + arm_t.dx
world_pivot_y = cy_body + rel_y + body_offset_dy + arm_t.dy
# Place the sprite so that new_pivot lands on world_pivot
x0 = int(round(world_pivot_x - new_pivot[0]))
y0 = int(round(world_pivot_y - new_pivot[1]))
arr = np.asarray(rotated)
self._blit_rgba_into_frame(frame, arr, x0, y0, brightness)
@staticmethod
def _blit_rgba_into_frame(
frame: np.ndarray,
rgba_arr: np.ndarray,
x0: int,
y0: int,
brightness: float,
) -> None:
"""Blits an RGBA sprite at position (x0, y0) into the 108-px frame.
Binary alpha threshold (>= 128) so the color-key magenta is never
touched. Brightness multiplies the RGB values (clipped to 255).
"""
ph, pw = rgba_arr.shape[:2]
src_x0 = max(0, -x0)
src_y0 = max(0, -y0)
src_x1 = pw - max(0, (x0 + pw) - WIN_W)
src_y1 = ph - max(0, (y0 + ph) - WIN_H)
dst_x0 = max(0, x0)
dst_y0 = max(0, y0)
dst_x1 = dst_x0 + (src_x1 - src_x0)
dst_y1 = dst_y0 + (src_y1 - src_y0)
if src_x1 <= src_x0 or src_y1 <= src_y0:
return
placed = rgba_arr[src_y0:src_y1, src_x0:src_x1]
solid = placed[:, :, 3] >= 128
if not solid.any():
return
rgb = placed[:, :, :3].astype(np.float32) * brightness
frame_slice = frame[dst_y0:dst_y1, dst_x0:dst_x1]
frame_slice[solid] = np.clip(rgb[solid], 0, 255).astype(np.uint8)
@staticmethod
def _composite_layer(frame: np.ndarray, layer: Image.Image) -> None:
"""In-place RGBA-over-RGB composite, color-key-safe (magenta).
Strategy:
- Layer pixels with alpha < 64 → ignore (don't draw).
- Pixels with alpha >= 64:
* If the frame pixel is magenta (color key, transparent) → HARD
set. Otherwise pink mixed pixels would appear as fringes
showing through in the Tk window.
* If the frame pixel is non-magenta (inside the halo/mascot) →
soft-blend over alpha. Here the frame is opaque anyway,
so mixed pixels stay visible as a clean transition.
"""
layer_arr = np.asarray(layer) # (H,W,4)
alpha = layer_arr[:, :, 3]
draw_mask = alpha >= 64
if not draw_mask.any():
return
src_rgb = layer_arr[:, :, :3].astype(np.float32)
# Color-key detection: frame pixels that are exactly magenta → "transparent"
is_magenta = (
(frame[:, :, 0] == COLOR_KEY_RGB[0])
& (frame[:, :, 1] == COLOR_KEY_RGB[1])
& (frame[:, :, 2] == COLOR_KEY_RGB[2])
)
# 1) Hard-set over magenta (every draw_mask pixel over magenta is
# overwritten 1:1 with the layer color — no blending).
hard_mask = draw_mask & is_magenta
if hard_mask.any():
frame[hard_mask] = src_rgb[hard_mask].astype(np.uint8)
# 2) Soft-blend over already-occupied pixels (halo, mascot)
soft_mask = draw_mask & ~is_magenta
if soft_mask.any():
a = (alpha[soft_mask].astype(np.float32) / 255.0)[:, None]
dst = frame[soft_mask].astype(np.float32)
blended = src_rgb[soft_mask] * a + dst * (1.0 - a)
frame[soft_mask] = np.clip(blended, 0, 255).astype(np.uint8)
class OrbCommentBubble:
"""Speech bubble Toplevel that floats above the orb.
Mirrors the look of MascotGigi.gigi-bubble from the Desktop App
(dark body, yellow border, bold yellow text), rendered on a Tk Canvas
with rounded corners + a tail pointer aimed at the mascot. Same
LWA_COLORKEY transparency as the main orb.
"""
def __init__(
self,
parent: tk.Tk,
orb_x: int,
orb_y: int,
orb_w: int,
screen_w: int,
theme: BubbleTheme = MASCOT_BUBBLE_THEME,
) -> None:
self._parent = parent
self._orb_x = orb_x
self._orb_y = orb_y
self._orb_w = orb_w
self._screen_w = screen_w
self._theme = theme
self._top: tk.Toplevel | None = None
self._canvas: tk.Canvas | None = None
self._dismiss_after_id: str | None = None
self._font: tkfont.Font | None = None
self._transcript_font: tkfont.Font | None = None
# Min-show + queue. Older queued entries are discarded; only the
# most recent (text, duration) survives so the freshest line wins.
self._show_until_t: float = 0.0
self._queued_text: str | None = None
self._queued_duration_ms: int = 0
self._queue_after_id: str | None = None
self._build()
def update_anchor(self, orb_x: int, orb_y: int, screen_w: int) -> None:
"""Reposition reference for the next show() call (used after the
underlying mascot moves due to taskbar resize / monitor change)."""
self._orb_x = orb_x
self._orb_y = orb_y
self._screen_w = screen_w
self.hide()
def set_orb_width(self, orb_w: int) -> None:
"""Re-centre over an orb that changed size (a live style swap)."""
self._orb_w = orb_w
def _build(self) -> None:
top = tk.Toplevel(self._parent)
top.overrideredirect(True)
top.wm_attributes("-topmost", True)
# Same per-platform transparency split as the main orb root: macOS
# has no color key, so the bubble Toplevel itself goes transparent;
# a TclError degrades to an opaque (key-coloured) bubble.
self._mac_transparent = False
if sys.platform == "darwin":
try:
top.wm_attributes("-transparent", True)
top.configure(bg="systemTransparent")
self._mac_transparent = True
except tk.TclError:
import logging
logging.getLogger("jarvis.orb").warning(
"macOS -transparent unsupported — the comment bubble renders opaque"
)
top.configure(bg=COLOR_KEY_HEX)
else:
top.wm_attributes("-transparentcolor", COLOR_KEY_HEX)
top.configure(bg=COLOR_KEY_HEX)
_hide_tk_window_from_task_switcher(top)
_exclude_tk_window_from_capture(top)
top.withdraw()
canvas = tk.Canvas(
top,
bg="systemTransparent" if self._mac_transparent else COLOR_KEY_HEX,
highlightthickness=0,
borderwidth=0,
)
canvas.pack(fill="both", expand=True)
if self._mac_transparent:
# New Toplevel = new NSWindow — give it the clear backing too
# (BUG-075).
top.update_idletasks()
apply_macos_clear_backing()
self._top = top
self._canvas = canvas
# Bind named fonts to this Toplevel's interpreter explicitly. The
# macOS host keeps a separate bootstrap Tk root alive before creating
# the mascot root; relying on tkinter's process-global default root
# would create the fonts in the wrong interpreter and make the bubble
# fail as soon as it tries to draw text.
weight = "bold" if self._theme.bold else "normal"
self._font = tkfont.Font(
root=top,
family=BUBBLE_FONT_FAMILY,
size=BUBBLE_FONT_SIZE,
weight=weight,
)
self._transcript_font = tkfont.Font(
root=top,
family=BUBBLE_FONT_FAMILY,
size=TRANSCRIPT_BUBBLE_FONT_SIZE,
weight=weight,
)
def set_theme(self, theme: BubbleTheme) -> None:
"""Repaint in another style's colours from the next show() onwards.
Called on a live style swap (mascot <-> voice orb). The bubble on
screen right now is hidden rather than converted: a half-second of the
old colours is nothing, a half-drawn bubble is a bug.
"""
if theme == self._theme:
return
self._theme = theme
weight = "bold" if theme.bold else "normal"
for font in (self._font, self._transcript_font):
if font is not None:
try:
font.configure(weight=weight)
except tk.TclError:
pass
self.hide()
def show(
self,
text: str,
duration_ms: int = 3500,
*,
variant: str = "comment",
) -> None:
if not self._top or not self._canvas or not self._font:
return
if variant == "transcript":
self._show_transcript(text, duration_ms)
return
if not text:
return
# Min-show guard: if the current bubble has not been on screen long
# enough yet, queue this one and let `_show_queued` fire it later.
now = time.perf_counter()
if now < self._show_until_t:
self._queued_text = text
self._queued_duration_ms = duration_ms
if self._queue_after_id is None:
wait_ms = max(1, int(round((self._show_until_t - now) * 1000)))
self._queue_after_id = self._top.after(wait_ms, self._show_queued)
return
if self._dismiss_after_id is not None:
try:
self._top.after_cancel(self._dismiss_after_id)
except tk.TclError:
pass
self._dismiss_after_id = None
theme = self._theme
# Probe text size by creating a throwaway text item and reading bbox.
probe_id = self._canvas.create_text(
0,
0,
text=text,
font=self._font,
anchor="nw",
width=BUBBLE_MAX_WIDTH,
fill=theme.text,
)
bbox = self._canvas.bbox(probe_id)
self._canvas.delete(probe_id)
if bbox is None:
return
text_w = max(BUBBLE_MIN_WIDTH, bbox[2] - bbox[0])
text_h = bbox[3] - bbox[1]
bubble_w = text_w + 2 * BUBBLE_PADDING_X
body_h = text_h + 2 * BUBBLE_PADDING_Y
tail_h = BUBBLE_TAIL_H if theme.tail else 0
total_h = body_h + tail_h
bubble_x = self._orb_x + self._orb_w // 2 - bubble_w // 2
bubble_x = max(8, min(bubble_x, self._screen_w - bubble_w - 8))
bubble_y = max(8, self._orb_y - total_h - BUBBLE_GAP_FROM_ORB)
# Tail tip aligned to mascot center, clamped inside the bubble body.
mascot_center_x = self._orb_x + self._orb_w // 2
tail_tip_x = mascot_center_x - bubble_x
tail_half = BUBBLE_TAIL_W // 2
min_tip = BUBBLE_CORNER_RADIUS + tail_half + 2
max_tip = bubble_w - BUBBLE_CORNER_RADIUS - tail_half - 2
if min_tip <= max_tip:
tail_tip_x = max(min_tip, min(tail_tip_x, max_tip))
else:
tail_tip_x = bubble_w // 2
self._top.geometry(f"{bubble_w}x{total_h}+{bubble_x}+{bubble_y}")
self._canvas.configure(width=bubble_w, height=total_h)
self._canvas.delete("all")
self._draw_rounded_rect(
1,
1,
bubble_w - 1,
body_h - 1,
theme.corner_radius,
fill=theme.bg,
outline=theme.border,
width=theme.border_width,
)
if theme.tail:
tail_base_y = body_h - 1
tail_points = [
tail_tip_x - tail_half,
tail_base_y,
tail_tip_x + tail_half,
tail_base_y,
tail_tip_x,
tail_base_y + BUBBLE_TAIL_H,
]
self._canvas.create_polygon(
tail_points,
fill=theme.bg,
outline=theme.border,
width=theme.border_width,
)
# Hide the seam between body bottom and tail base.
self._canvas.create_line(
tail_tip_x - tail_half + 1,
tail_base_y,
tail_tip_x + tail_half - 1,
tail_base_y,
fill=theme.bg,
width=theme.border_width + 1,
)
self._canvas.create_text(
BUBBLE_PADDING_X,
BUBBLE_PADDING_Y,
text=text,
font=self._font,
anchor="nw",
width=BUBBLE_MAX_WIDTH,
fill=theme.text,
)
self._top.deiconify()
try:
self._top.lift()
except tk.TclError:
pass
self._show_until_t = time.perf_counter() + min(BUBBLE_MIN_SHOW_S, duration_ms / 1000.0)
self._dismiss_after_id = self._top.after(duration_ms, self.hide)
def _show_transcript(self, text: str, duration_ms: int) -> None:
if self._top is None or self._canvas is None or self._transcript_font is None:
return
if self._dismiss_after_id is not None:
try:
self._top.after_cancel(self._dismiss_after_id)
except tk.TclError:
pass
self._dismiss_after_id = None
if self._queue_after_id is not None:
try:
self._top.after_cancel(self._queue_after_id)
except tk.TclError:
pass
self._queue_after_id = None
self._queued_text = None
theme = self._theme
display_text = text.strip() or "..."
bubble_w = min(TRANSCRIPT_BUBBLE_WIDTH, max(220, self._screen_w - 16))
text_width = min(
TRANSCRIPT_BUBBLE_TEXT_WIDTH,
max(120, bubble_w - 2 * BUBBLE_PADDING_X),
)
line_height = max(1, self._transcript_font.metrics("linespace"))
probe_id = self._canvas.create_text(
0,
0,
text=display_text,
font=self._transcript_font,
anchor="nw",
width=text_width,
fill=theme.text,
)
bbox = self._canvas.bbox(probe_id)
self._canvas.delete(probe_id)
text_h = line_height if bbox is None else max(line_height, bbox[3] - bbox[1])
visible_lines = _transcript_visible_line_count(text_h, line_height)
body_h = _transcript_body_height(visible_lines, line_height)
tail_h = BUBBLE_TAIL_H if theme.tail else 0
total_h = body_h + tail_h
mascot_center_x = self._orb_x + self._orb_w // 2
# With a tail the bubble hangs off to one side so the pointer can aim at
# the mascot's head; without one there is nothing to aim, and anything
# but centred reads as a misplaced window.
bubble_x = (
mascot_center_x - bubble_w + 30 if theme.tail else mascot_center_x - bubble_w // 2
)
bubble_x = max(8, min(bubble_x, self._screen_w - bubble_w - 8))
bubble_y = max(8, self._orb_y - total_h - BUBBLE_GAP_FROM_ORB)
tail_tip_x = mascot_center_x - bubble_x
tail_half = BUBBLE_TAIL_W // 2
min_tip = BUBBLE_CORNER_RADIUS + tail_half + 2
max_tip = bubble_w - BUBBLE_CORNER_RADIUS - tail_half - 2
if min_tip <= max_tip:
tail_tip_x = max(min_tip, min(tail_tip_x, max_tip))
else:
tail_tip_x = bubble_w // 2
self._top.geometry(f"{bubble_w}x{total_h}+{bubble_x}+{bubble_y}")
self._canvas.configure(width=bubble_w, height=total_h)
self._canvas.delete("all")
self._draw_rounded_rect(
1,
1,
bubble_w - 1,
body_h - 1,
theme.corner_radius,
fill=theme.bg,
outline=theme.border,
width=theme.border_width,
)
if theme.tail:
tail_base_y = body_h - 1
tail_points = [
tail_tip_x - tail_half,
tail_base_y,
tail_tip_x + tail_half,
tail_base_y,
tail_tip_x,
tail_base_y + BUBBLE_TAIL_H,
]
self._canvas.create_polygon(
tail_points,
fill=theme.bg,
outline=theme.border,
width=theme.border_width,
)
self._canvas.create_line(
tail_tip_x - tail_half + 1,
tail_base_y,
tail_tip_x + tail_half - 1,
tail_base_y,
fill=theme.bg,
width=theme.border_width + 1,
)
self._canvas.create_text(
BUBBLE_PADDING_X,
body_h - BUBBLE_PADDING_Y,
text=display_text,
font=self._transcript_font,
anchor="sw",
width=text_width,
fill=theme.text,
)
self._top.deiconify()
try:
self._top.lift()
except tk.TclError:
pass
self._show_until_t = time.perf_counter()
self._dismiss_after_id = self._top.after(duration_ms, self.hide)
def _show_queued(self) -> None:
self._queue_after_id = None
text = self._queued_text
duration_ms = self._queued_duration_ms
self._queued_text = None
self._queued_duration_ms = 0
if text:
self.show(text, duration_ms)
# -- the pet's status variant ------------------------------------------
def _cancel_timers(self) -> None:
if self._top is None:
return
for attr in ("_dismiss_after_id", "_queue_after_id"):
after_id = getattr(self, attr)
if after_id is None:
continue
try:
self._top.after_cancel(after_id)
except tk.TclError:
logging.getLogger("jarvis.orb").debug("bubble timer cancel failed", exc_info=True)
setattr(self, attr, None)
self._queued_text = None
def hide(self) -> None:
if self._top is None:
return
if self._dismiss_after_id is not None:
try:
self._top.after_cancel(self._dismiss_after_id)
except tk.TclError:
pass
self._dismiss_after_id = None
if self._queue_after_id is not None:
try:
self._top.after_cancel(self._queue_after_id)
except tk.TclError:
pass
self._queue_after_id = None
self._queued_text = None
try:
self._top.withdraw()
except tk.TclError:
pass
def _draw_rounded_rect(self, x1, y1, x2, y2, r, **kwargs) -> int:
if self._canvas is None:
return 0
points = [
x1 + r,
y1,
x1 + r,
y1,
x2 - r,
y1,
x2 - r,
y1,
x2,
y1,
x2,
y1 + r,
x2,
y1 + r,
x2,
y2 - r,
x2,
y2 - r,
x2,
y2,
x2 - r,
y2,
x2 - r,
y2,
x1 + r,
y2,
x1 + r,
y2,
x1,
y2,
x1,
y2 - r,
x1,
y2 - r,
x1,
y1 + r,
x1,
y1 + r,
x1,
y1,
]
return self._canvas.create_polygon(points, smooth=True, **kwargs)
class OrbControlRow:
"""The four round controls under the voice orb — see :mod:`ui.orb.controls`.
Its own frameless, always-on-top Toplevel rather than extra pixels on the
orb's window, for three reasons that all point the same way: the orb window
is exactly the sphere (a taller window would put an invisible click-eating
rectangle over whatever is underneath), the row has to appear and disappear
on its own schedule, and the orb's frame loop must not repaint four static
discs sixty times a second.
Visibility is deliberately conditional (maintainer decision 2026-08-06): at
rest the desktop shows a sphere and nothing else. The row arrives when the
pointer does, or when a conversation is running — the two moments where a
control is something the user is reaching for rather than clutter they did
not ask for.
"""
#: Grace period between losing the pointer and hiding, in ms. The row is a
#: separate window a few pixels below the orb, so travelling from one to
#: the other means genuinely leaving both — without this the row would
#: vanish under the pointer on its way to being clicked.
HOVER_GRACE_MS = 260
#: After a hang-up, ignore clicks for this long. Same guard as the Jarvis
#: Bar's close-X: the optimistic state flip must not let a second click
#: land as "start a new session" (the request_hangup storm, 2026-06-19).
CLICK_GUARD_S = 0.6
#: Actions whose click arms :attr:`CLICK_GUARD_S` while a session runs.
GUARDED_ACTIONS: tuple[str, ...] = ("mic", "close")
def __init__(self, parent: tk.Tk, orb_x: int, orb_y: int, orb_w: int, orb_h: int) -> None:
self._parent = parent
self._orb_x = orb_x
self._orb_y = orb_y
self._orb_w = orb_w
self._orb_h = orb_h
self._top: tk.Toplevel | None = None
self._canvas: tk.Canvas | None = None
self._photo: ImageTk.PhotoImage | None = None
self._image_id: int | None = None
self._state = self._initial_state()
self._visible = False
self._pointer_inside = False
self._hide_after_id: str | None = None
self._pressed_action: str | None = None
self._click_block_until = 0.0
self._on_action: Callable[[str], None] | None = None
self._width, self._height = self._row_size()
self._build()
# -- layout hooks (the pet strip overrides these) ------------------------
def _initial_state(self) -> Any:
return orb_controls.ControlState()
def _row_size(self) -> tuple[int, int]:
return orb_controls.row_size()
def _render_frame(self) -> Image.Image:
return orb_controls.render_row(self._state, color_key=tuple(COLOR_KEY_RGB.tolist()))
def _hit(self, x: float, y: float) -> str | None:
return orb_controls.hit_test(x, y)
def _with_hovered(self, action: str | None) -> Any:
return orb_controls.ControlState(
active=self._state.active,
speaker_muted=self._state.speaker_muted,
hovered=action,
can_attach=self._state.can_attach,
)
def _row_y(self) -> int:
return self._orb_y + self._orb_h + orb_controls.ROW_GAP_FROM_ORB
# -- wiring ---------------------------------------------------------
def set_on_action(self, callback: Callable[[str], None] | None) -> None:
"""Route a resolved button press ("attach"/"mic"/"close"/"speaker")."""
self._on_action = callback
def _build(self) -> None:
top = tk.Toplevel(self._parent)
top.overrideredirect(True)
top.wm_attributes("-topmost", True)
self._mac_transparent = False
if sys.platform == "darwin":
try:
top.wm_attributes("-transparent", True)
top.configure(bg="systemTransparent")
self._mac_transparent = True
except tk.TclError:
logging.getLogger("jarvis.orb").warning(
"macOS -transparent unsupported — the orb controls render opaque"
)
top.configure(bg=COLOR_KEY_HEX)
else:
top.wm_attributes("-transparentcolor", COLOR_KEY_HEX)
top.configure(bg=COLOR_KEY_HEX)
_hide_tk_window_from_task_switcher(top)
_exclude_tk_window_from_capture(top)
top.withdraw()
canvas = tk.Canvas(
top,
width=self._width,
height=self._height,
bg="systemTransparent" if self._mac_transparent else COLOR_KEY_HEX,
highlightthickness=0,
borderwidth=0,
)
canvas.pack(fill="both", expand=True)
if self._mac_transparent:
top.update_idletasks()
apply_macos_clear_backing()
canvas.bind("<Motion>", self._on_motion)
canvas.bind("<Enter>", self._on_enter)
canvas.bind("<Leave>", self._on_leave)
canvas.bind("<ButtonPress-1>", self._on_press)
canvas.bind("<ButtonRelease-1>", self._on_release)
self._top = top
self._canvas = canvas
self._repaint()
# -- geometry -------------------------------------------------------
def update_anchor(self, orb_x: int, orb_y: int) -> None:
"""Follow the orb after a drag / monitor change."""
self._orb_x = orb_x
self._orb_y = orb_y
if self._visible:
self._place()
def set_orb_size(self, orb_w: int, orb_h: int) -> None:
"""Re-centre under an orb that changed size (a live style swap)."""
self._orb_w = orb_w
self._orb_h = orb_h
if self._visible:
self._place()
def _place(self) -> None:
if self._top is None:
return
x = self._orb_x + self._orb_w // 2 - self._width // 2
y = self._row_y()
try:
self._top.geometry(f"{self._width}x{self._height}+{x}+{y}")
except tk.TclError:
pass
# -- state ----------------------------------------------------------
def set_state(
self,
*,
active: bool | None = None,
speaker_muted: bool | None = None,
can_attach: bool | None = None,
) -> None:
"""Update what the discs say, repainting only on a real change."""
state = orb_controls.ControlState(
active=self._state.active if active is None else bool(active),
speaker_muted=(
self._state.speaker_muted if speaker_muted is None else bool(speaker_muted)
),
hovered=self._state.hovered,
can_attach=self._state.can_attach if can_attach is None else bool(can_attach),
)
if state == self._state:
return
self._state = state
self._repaint()
def _repaint(self) -> None:
if self._canvas is None:
return
try:
frame = self._render_frame()
image = key_to_alpha(frame) if self._mac_transparent else frame
self._photo = ImageTk.PhotoImage(image, master=self._canvas)
if self._image_id is None:
self._image_id = self._canvas.create_image(0, 0, anchor="nw", image=self._photo)
else:
self._canvas.itemconfigure(self._image_id, image=self._photo)
except tk.TclError:
pass
# -- visibility -----------------------------------------------------
def show(self) -> None:
if self._top is None or self._visible:
return
self._cancel_pending_hide()
self._place()
try:
self._top.deiconify()
if self._mac_transparent:
apply_macos_clear_backing()
self._top.lift()
except tk.TclError:
return
self._visible = True
def hide(self) -> None:
self._cancel_pending_hide()
self._pointer_inside = False
if self._state.hovered is not None:
self._state = self._with_hovered(None)
self._repaint()
if self._top is None or not self._visible:
return
try:
self._top.withdraw()
except tk.TclError:
pass
self._visible = False
def hide_after_grace(self) -> None:
"""Hide unless the pointer comes back within :attr:`HOVER_GRACE_MS`."""
if self._top is None or not self._visible:
return
self._cancel_pending_hide()
try:
self._hide_after_id = self._top.after(self.HOVER_GRACE_MS, self._grace_elapsed)
except tk.TclError:
self.hide()
def _grace_elapsed(self) -> None:
self._hide_after_id = None
if self._pointer_inside:
return
self.hide()
def _cancel_pending_hide(self) -> None:
if self._hide_after_id is None or self._top is None:
self._hide_after_id = None
return
try:
self._top.after_cancel(self._hide_after_id)
except tk.TclError:
pass
self._hide_after_id = None
@property
def pointer_inside(self) -> bool:
return self._pointer_inside
@property
def window(self) -> tk.Toplevel | None:
return self._top
@property
def visible(self) -> bool:
return self._visible
def destroy(self) -> None:
self._cancel_pending_hide()
top = self._top
self._top = None
self._canvas = None
self._photo = None
if top is None:
return
try:
top.destroy()
except tk.TclError:
pass
# -- pointer --------------------------------------------------------
def _on_enter(self, event: tk.Event) -> None:
self._pointer_inside = True
self._cancel_pending_hide()
self._on_motion(event)
def _on_leave(self, _event: tk.Event) -> None:
self._pointer_inside = False
self._set_hovered(None)
self.hide_after_grace()
def _on_motion(self, event: tk.Event) -> None:
self._set_hovered(self._hit(event.x, event.y))
def _set_hovered(self, action: str | None) -> None:
if action == self._state.hovered:
return
self._state = self._with_hovered(action)
self._repaint()
if self._canvas is not None:
try:
self._canvas.configure(cursor="hand2" if action else "")
except tk.TclError:
pass
def _on_press(self, event: tk.Event) -> None:
self._pressed_action = self._hit(event.x, event.y)
def _on_release(self, event: tk.Event) -> None:
pressed = self._pressed_action
self._pressed_action = None
if pressed is None:
return
# Press and release must agree: a pointer that slid off the disc did
# not click it, and every action here is one the user would rather not
# trigger by accident.
if self._hit(event.x, event.y) != pressed:
return
if time.monotonic() < self._click_block_until:
return
if pressed in self.GUARDED_ACTIONS and self._state.active:
self._click_block_until = time.monotonic() + self.CLICK_GUARD_S
callback = self._on_action
if callback is None:
return
try:
callback(pressed)
except Exception: # noqa: BLE001 — a bad action must not kill the Tk loop
logging.getLogger("jarvis.orb").debug(
"orb control action %r failed", pressed, exc_info=True
)
class PetControlStrip(OrbControlRow):
"""The pet's control strip — see ``ui.orb.controls`` (``PET_ACTIONS``).
The voice orb's row with three differences that make it the pet's own: it
shows only while the overlay's ``keep_visible`` says so (Jarvis is engaged,
the pointer is on the pet, or there is no figure to hover), its empty area
is a drag handle for the whole group (the only one when the pet is "None"),
and its orb pulses with the live audio level through cached frames, so a
strip at rest never repaints.
"""
GUARDED_ACTIONS: tuple[str, ...] = ("orb", "call")
#: Longer than the orb row's: the pointer crosses a gap between the
#: figure and the strip, and a strip that vanishes on the way is a miss.
HOVER_GRACE_MS = 600
def __init__(
self,
parent: tk.Tk,
orb_x: int,
orb_y: int,
orb_w: int,
orb_h: int,
*,
scale: float = 1.0,
on_drag_press: Callable[[Any], None] | None = None,
on_drag_motion: Callable[[Any], None] | None = None,
on_drag_release: Callable[[Any], None] | None = None,
on_context: Callable[[Any], None] | None = None,
keep_visible: Callable[[], bool] | None = None,
) -> None:
self._scale = float(scale)
self._keep_visible = keep_visible
self._on_drag_press = on_drag_press
self._on_drag_motion = on_drag_motion
self._on_drag_release = on_drag_release
self._on_context = on_context
self._dragging = False
# The press point (screen px) and whether the pointer has since
# travelled far enough to make the press a drag rather than a click.
self._drag_moved = False
self._press_root: tuple[int, int] = (0, 0)
super().__init__(parent, orb_x, orb_y, orb_w, orb_h)
# -- layout hooks -----------------------------------------------------
def _initial_state(self) -> orb_controls.PetStripState:
return orb_controls.PetStripState()
def _row_size(self) -> tuple[int, int]:
return orb_controls.pet_strip_size(self._scale)
def _render_frame(self) -> Image.Image:
return orb_controls.render_pet_strip(
self._state, self._scale, tuple(int(c) for c in COLOR_KEY_RGB)
)
def _hit(self, x: float, y: float) -> str | None:
return orb_controls.pet_hit_test(x, y, self._scale)
def _with_hovered(self, action: str | None) -> orb_controls.PetStripState:
return replace(self._state, hovered=action)
def _row_y(self) -> int:
gap = max(1, int(round(orb_controls.PET_STRIP_GAP_FROM_FIGURE * self._scale)))
return self._orb_y + self._orb_h + gap
def _build(self) -> None:
super()._build()
if self._canvas is not None:
self._canvas.bind("<B1-Motion>", self._on_drag_motion_event)
self._canvas.bind("<Button-3>", self._on_context_event)
@property
def scale(self) -> float:
return self._scale
def set_scale(self, scale: float) -> None:
"""Re-lay the strip at another scale (``pet_scale`` or DPI changed)."""
scale = float(scale)
if scale == self._scale:
return
self._scale = scale
self._width, self._height = self._row_size()
if self._canvas is not None:
try:
self._canvas.configure(width=self._width, height=self._height)
except tk.TclError:
logging.getLogger("jarvis.orb").debug("strip resize failed", exc_info=True)
self._repaint()
if self._visible:
self._place()
# -- state ------------------------------------------------------------
@property
def state(self) -> orb_controls.PetStripState:
return self._state
def set_state(
self,
*,
active: bool | None = None,
speaker_muted: bool | None = None,
can_attach: bool | None = None,
mic_muted: bool | None = None,
level: int | None = None,
motion: str | None = None,
phase: int | None = None,
notify_off: bool | None = None,
ring: int | None = None,
call_ring: int | None = None,
spin: int | None = None,
) -> None:
"""Update what the strip says, repainting only on a real change."""
_ = can_attach # the pet strip has no attach control
current = self._state
state = orb_controls.PetStripState(
mic_muted=current.mic_muted if mic_muted is None else bool(mic_muted),
speaker_muted=current.speaker_muted if speaker_muted is None else bool(speaker_muted),
active=current.active if active is None else bool(active),
level=current.level if level is None else int(level),
motion=current.motion if motion is None else str(motion),
phase=current.phase if phase is None else int(phase),
spin=current.spin if spin is None else int(spin),
hovered=current.hovered,
notify_off=current.notify_off if notify_off is None else bool(notify_off),
ring=current.ring if ring is None else int(ring),
call_ring=current.call_ring if call_ring is None else int(call_ring),
)
if state == current:
return
self._state = state
self._repaint()
# -- pointer ----------------------------------------------------------
def hide_after_grace(self) -> None:
"""Hide after the grace, unless the overlay still wants the strip up."""
if self._keep_visible is not None and self._keep_visible():
return
super().hide_after_grace()
def _grace_elapsed(self) -> None:
# The conversation may have started during the grace.
if self._keep_visible is not None and self._keep_visible():
self._hide_after_id = None
return
super()._grace_elapsed()
def _on_press(self, event: tk.Event) -> None:
# Every press may become a drag — on a control too. The strip is all
# controls, so with the pet "None" there would otherwise be nothing
# to grab. A press that never travels past DRAG_THRESHOLD_PX stays a
# click; one that does moves the pet and the control does not fire.
super()._on_press(event)
self._dragging = True
self._drag_moved = False
self._press_root = (event.x_root, event.y_root)
if self._on_drag_press is not None:
self._on_drag_press(event)
def _on_drag_motion_event(self, event: tk.Event) -> None:
if not self._dragging:
return
if not self._drag_moved:
px, py = self._press_root
if abs(event.x_root - px) + abs(event.y_root - py) < DRAG_THRESHOLD_PX:
return
self._drag_moved = True
self._set_hovered(None)
if self._on_drag_motion is not None:
self._on_drag_motion(event)
def _on_release(self, event: tk.Event) -> None:
dragging, moved = self._dragging, self._drag_moved
self._dragging = False
self._drag_moved = False
if dragging and self._on_drag_release is not None:
self._on_drag_release(event)
if moved:
self._pressed_action = None
return
super()._on_release(event)
def _on_context_event(self, event: tk.Event) -> None:
if self._on_context is not None:
self._on_context(event)
def _clamp_pet_scale(value: object) -> float:
"""``[ui] pet_scale`` as a usable multiplier (0.5–2.0, 1.0 when unusable)."""
try:
scale = float(value) # type: ignore[arg-type]
except (TypeError, ValueError):
return 1.0
if not math.isfinite(scale):
return 1.0
return max(0.5, min(2.0, scale))
#: Pet Tk images kept per frame key. A pet has at most 7 states x 8 frames;
#: the bound only matters when a user flips between pets or sizes.
PET_PHOTO_CACHE_MAX = 64
#: The mascot and voice orb repaint on a fixed ~60 fps timer.
FRAME_INTERVAL_MS = 16
#: While the strip's indicator moves (listening, talking, thinking) the pet
#: ticks at least this often, so the strokes follow the voice even when the
#: figure is slow.
PET_PULSE_INTERVAL_MS = 100
#: The loading loop and the "connected" flourish turn faster than a level can
#: change, so the strip ticks at this rate while either is on screen.
PET_CONNECT_INTERVAL_MS = 40
#: A level older than this no longer moves the strip's strokes (the voice stopped).
PET_LEVEL_FRESH_S = 0.25
#: Overlay modes and what the strip's indicator shows for them. Dictation
#: while the key is held is a live microphone; once it is released and the
#: speech is being transcribed there is no signal left, only work.
PET_VOICE_MODES = ("listen", "speak", "dictate")
PET_THINK_MODES = ("think", "dictate_transcribing")
class OrbOverlay:
"""Public facade — Tkinter-based, thread-safe via root.after(0, ...).
tkinter itself is not thread-safe, but `root.after(0, fn)` schedules
fn safely onto the Tk main loop. So we route every call from other
threads (Jarvis-Core, demo thread) through it.
"""
def __init__(
self,
sticky: bool = False,
mic_reactive: bool = False,
style: str | None = None,
mascot_path: str | Path | None = None,
pet_id: str | None = None,
pet_scale: float | None = 1.0,
pet_bubble: bool = True,
pet_strip_always: bool = False,
) -> None:
"""
style: one of :data:`ORB_STYLES` — ``"mascot"`` (the Gigi ghost),
``"voice_orb"`` (the procedural weather sphere) or ``"pet"`` (an
animated pixel-art companion, ``docs/pets.md``). Anything else,
including the legacy ``"orb"``, is coerced to ``"mascot"``.
mascot_path: optional explicit path, otherwise via ENV or the default asset.
pet_id / pet_scale / pet_bubble: the pet style's ``[ui]`` settings — which
pet, its size multiplier (0.5–2.0) and whether the status bubble shows.
pet_strip_always: keep the pet's control strip up even at rest.
ENV-Override: ``JARVIS_ORB_STYLE=mascot|voice_orb`` selects the look;
unknown values are ignored.
"""
self._sticky = sticky
self._mic_reactive = mic_reactive
self._root: tk.Tk | None = None
self._canvas: tk.Canvas | None = None
self._comment_bubble: OrbCommentBubble | None = None
self._renderer: MascotRenderer | VoiceOrbRenderer | PetRenderer | None = None
# Cached mascot anchor + min-show-time guard.
self._mascot_x: int = 0
self._mascot_y: int = 0
# Drag-and-pin state. _manual_pinned switches the 1500 ms recheck
# loop into clamp-only mode and tells boot to skip the taskbar
# anchor.
self._manual_pinned: bool = False
self._drag_state: _DragState | None = None
# Double-double-click on the orb fires this callback (user spec
# 2026-05-17 + revision 2026-05-18: two double-clicks within
# MUTE_GESTURE_WINDOW_MS toggle the Jarvis-wide mute). The orb
# stays decoupled from the bus — OrbBusBridge injects a
# callable that publishes ``VoiceMuteToggleRequested``.
self._mute_toggle_callback: Callable[[], None] | None = None
# Right-click on non-pet orbs raises the main window. OrbBusBridge
# injects a callable that publishes ``ShowWindowRequested``; the orb
# itself stays bus-agnostic (same contract as the mute toggle).
self._on_show_window: Callable[[], None] | None = None
self._on_visibility_changed: Callable[[bool], None] | None = None
self._context_menu = None
# The control row's actions. Each is optional: wired, the callback
# decides (the macOS host forwards it to the parent process, which is
# the only place a SpeechPipeline exists); unwired, the row falls back
# to the live pipeline in THIS process — the same two-step the Jarvis
# Bar uses for its own talk / hang-up buttons.
self._on_talk: Callable[[], None] | None = None
self._on_hangup: Callable[[], None] | None = None
self._on_speaker_toggle: Callable[[], None] | None = None
#: The four round controls under the sphere. Only the voice orb wears
#: them — the mascot has its own arms and expressions, and a row of
#: discs under the ghost would read as a toolbar bolted to a cartoon.
self._controls: OrbControlRow | None = None
self._pointer_over_orb = False
self._speaker_muted = False
# --- the desktop pet (style "pet", docs/pets.md) ---
self._pet_id = str(pet_id or DEFAULT_PET_ID).strip() or DEFAULT_PET_ID
self._pet_scale = _clamp_pet_scale(1.0 if pet_scale is None else pet_scale)
self._pet_bubble = bool(pet_bubble)
#: ``[ui] pet_strip_always``: the strip stays up even at rest.
self._pet_strip_always = bool(pet_strip_always)
#: A look change is already queued for the Tk thread: a slider drag
#: sends a burst, and only the newest values need one rescale.
self._pet_look_queued = False
#: Mirrors ``VoiceMuteChanged`` for the strip's microphone control.
self._mic_muted = False
#: Hidden by the shortcut or the settings page — lasts until restart.
self._user_hidden = False
self._on_compose: Callable[[], None] | None = None
#: The bell: notifications show (True) or stay quiet. Runtime only,
#: like the speaker mute — a silenced bell forgotten overnight would
#: hide tomorrow's "your agent is done" without a trace.
self._notify_enabled = True
self._on_notify_toggle: Callable[[bool], None] | None = None
#: The notification cards' window, created with the first card.
self._notices: PetNoticeStack | None = None
#: The thought bubble above the pet's head, created when Jarvis first thinks.
self._thought: PetThoughtBubble | None = None
self._ring_after_id: str | None = None
#: The phone disc's ringing timer, like the bell's.
self._call_ring_after_id: str | None = None
#: The monitor's display scale (1.0 at 100 %), read once the root exists.
self._dpi_ratio = 1.0
# Frame-loop bookkeeping: ONE pending tick at most, and for renderers
# that name their frames (the pet) one cached Tk image per frame.
self._frame_after_id: str | None = None
self._frame_key: Hashable | None = None
self._photo_cache: OrderedDict[Hashable, Any] = OrderedDict()
self._frame_error_logged = False
self._topmost_fns: tuple[Callable[..., Any], Callable[..., Any]] | None = None
self._work_area_cache: tuple[tuple[int, int], int] | None = None
# Counter + Tk timer-id for the two-double-click gesture. The
# earlier single-double-click implementation muted Jarvis as soon
# as the user clicked twice on the popup logo, which fired
# accidentally whenever the user clicked the freshly appeared
# orb. Two double-clicks (four rapid clicks) is intentional.
self._mute_click_count: int = 0
self._mute_click_reset_id: str | None = None
# ADR-0016 visible-feedback contract: bridge injects a callable
# that publishes ``UserVisibleFeedback`` from the bus side. The
# orb stays bus-agnostic; this lets unit tests run without a bus.
# Signature: ``(mode: str, observed: dict[str, Any]) -> None``.
self._feedback_publisher: Callable[[str, dict[str, Any]], None] | None = None
self._show_until_t: float = 0.0
self._pending_hide_after_id: str | None = None
self._photo: ImageTk.PhotoImage | None = None
self._image_id: int | None = None
self._mode: str = "idle"
# The strip's clock of the strokes bending into the loading loop while
# a call connects, and of their one-shot back out (time.monotonic()).
self._connect_timeline = orb_controls.ConnectTimeline()
self._ext_level: float | None = None
self._ext_level_at: float = -math.inf
self._t0: float = 0.0
self._running: bool = False
self._started = threading.Event()
self._ui_queue: queue.Queue = queue.Queue()
self._tk_thread_id: int | None = None
# Lazy import so the orb stays startable even without sounddevice
# (mic-reactive mode is optional).
self._mic = None
# Style resolution. Keep accepting the old knobs so existing launchers
# do not crash, but never render the removed legacy orb.
env_style = (os.environ.get("JARVIS_ORB_STYLE") or "").strip().lower()
requested_style = env_style or (style or DEFAULT_ORB_STYLE).lower()
self._mascot_path_hint = str(mascot_path) if mascot_path else None
#: The look is the pet's, showing the mascot figure instead of the
#: pet chosen under My Pets (see ``_adopt_style``).
self._mascot_figure = False
self._style = self._adopt_style(_coerce_style(requested_style))
# Window size belongs to the style, not to the module: the voice orb is
# half again as large as the mascot (see VOICE_ORB_WIN_W).
self._win_w, self._win_h = window_size_for_style(self._style)
# --- Public API ----------------------------------------------------
def start(self, auto_demo: bool = False) -> None:
self._tk_thread_id = threading.get_ident()
# Test-safety guard: under pytest, never put a REAL mascot window on the
# developer's desktop unless explicitly opted in (JARVIS_GUI_TESTS=1).
# A routine `pytest tests/unit/` run (and parallel runs across worktrees)
# would otherwise leave a live 'JarvisOrb' Tk window on screen until the
# test process exits — users saw several mascots stacked beside their
# chosen overlay style even though the desktop app was rendering only the
# selected one. No production effect: pytest is never imported in the
# live app, so this branch is dead there. ``_started`` is still set so a
# ``start_in_thread`` caller unblocks immediately instead of timing out.
if "pytest" in sys.modules and not os.environ.get("JARVIS_GUI_TESTS"):
self._started.set()
return
from dodaios.ui.tk_runtime import prepare_tk_runtime
prepare_tk_runtime()
# DPI awareness MUST be set before Win32 GetWindowRect calls, else
# taskbar coords come back DPI-virtualised and the mascot ends up
# misplaced on 125%/150% scaled displays.
_ensure_dpi_awareness()
self._root = tk.Tk()
self._root.title("JarvisOrb")
self._root.overrideredirect(True) # Frameless, no drop shadow
self._root.wm_attributes("-topmost", True)
# Per-pixel transparency, per platform: Windows keys out the magenta
# color key on the layered window; macOS has no color key, so there
# the WINDOW itself becomes transparent (Aqua-Tk's "-transparent" +
# the systemTransparent background) and every frame carries a real
# alpha channel instead (key_to_alpha in the frame loop).
self._mac_transparent = False
if sys.platform == "darwin":
try:
self._root.wm_attributes("-transparent", True)
self._root.configure(bg="systemTransparent")
self._mac_transparent = True
except tk.TclError:
import logging
logging.getLogger("jarvis.orb").warning(
"macOS -transparent unsupported — the mascot will show its key colour"
)
self._root.configure(bg=COLOR_KEY_HEX)
else:
if not _apply_color_key(self._root):
# No per-pixel transparency on this session: showing the window
# would put an opaque magenta square on the user's desktop.
# Tear the root down and report started, so the caller's
# start_in_thread() unblocks instead of timing out.
try:
self._root.destroy()
except tk.TclError:
pass
self._root = None
self._started.set()
return
# The colour key belongs to THIS window only. Once this Tk loop
# stops pumping — any long GIL-holding stretch on another thread
# does it — Windows paints an unlayered ``Ghost`` stand-in over the
# same rectangle, and the keyed-out padding arrives as an opaque
# black box around the mascot. Same defect as the bar's.
try:
from dodaios.core.process_utils import disable_windows_app_ghosting
disable_windows_app_ghosting()
except Exception: # noqa: BLE001 — cosmetic; the orb must still boot
import logging
logging.getLogger("jarvis.orb").debug(
"window-ghosting suppression unavailable — a stalled orb may "
"show an opaque box",
exc_info=True,
)
# Apply the Jarvis icon BEFORE hiding from the task switcher: Windows
# caches the taskbar entry on first show, so even a brief flash with
# the default pythonw icon sticks. Belt-and-suspenders: stable AppID
# so this process doesn't share Python.exe's taskbar group, then Tk's
# own iconbitmap, then Win32 WM_SETICON + SetClassLongPtrW (the only
# way to override the class-default that drives the taskbar icon).
_apply_jarvis_icon_to_tk_root(self._root)
_hide_tk_window_from_task_switcher(self._root)
_exclude_tk_window_from_capture(self._root)
self._dpi_ratio = self._read_dpi_ratio()
if self._style == "pet":
# The pet's window size comes from its sprite sheet, so the pack is
# loaded before the anchor below is computed from that size.
self._renderer = self._build_renderer("pet")
self._win_w, self._win_h = window_size_for_style("pet", self._renderer)
# Resolve mascot anchor. If the user has manually pinned the orb
# in a prior session, restore that position; otherwise compute
# the live Windows-taskbar-aligned default.
#
# BUG-027 defense: when the persisted pin lives on a non-primary
# monitor, resolve_placement reports recovered=True so we clear the
# stale entry and fall back to the primary anchor. The user can opt
# out via ``[overlay.mascot] allow_secondary_monitor_pin = true``
# in jarvis.toml.
screen_w = self._root.winfo_screenwidth()
screen_h = self._root.winfo_screenheight()
persisted = load_position_from_toml(JARVIS_TOML_PATH)
# ADR-0016 L1 — boot-flash state. Populated only when the pin
# honours a secondary monitor (Power-User escape hatch). In that
# case we deiconify the orb at the PRIMARY anchor for ~800 ms
# before migrating to the pin, so the user always SEES the orb on
# boot regardless of where it was last dragged.
self._boot_flash_target_xy: tuple[int, int] | None = None
if persisted is not None and persisted.monitor:
screens = screens_from_tk(self._root)
allow_secondary = load_allow_secondary_monitor_pin(JARVIS_TOML_PATH)
placement = resolve_placement(
persisted,
screens,
mascot_size_px=self._win_w,
require_primary=not allow_secondary,
)
if not placement.recovered:
# Persisted monitor still present — honour user's pin.
self._manual_pinned = True
self._mascot_x = placement.abs_x
self._mascot_y = placement.abs_y
anchor = MascotAnchor(
x=placement.abs_x,
y=placement.abs_y,
taskbar_aligned=False,
)
# L1 gate (BUG-027 / ADR-0016): when the honored pin is on
# a NON-primary monitor in a multi-monitor topology, start
# the orb at the primary anchor and migrate after a brief
# visible flash. Single-monitor and primary-pin boots
# skip the flash entirely (no visual noise in 99% case).
resolved_screen = next((s for s in screens if s.name == placement.monitor), None)
if (
len(screens) > 1
and resolved_screen is not None
and not resolved_screen.is_primary
):
primary_anchor = self._resolve_anchor(screen_w, screen_h)
self._boot_flash_target_xy = (
placement.abs_x,
placement.abs_y,
)
self._root.geometry(
f"{self._win_w}x{self._win_h}+{primary_anchor.x}+{primary_anchor.y}"
)
else:
self._root.geometry(
f"{self._win_w}x{self._win_h}+{placement.abs_x}+{placement.abs_y}"
)
else:
# Monitor gone, no screens, or pin on non-primary monitor
# while require_primary is set — fall back to default and
# clear the stale entry so next boot starts clean.
try:
clear_position_in_toml(JARVIS_TOML_PATH)
except OSError:
pass
anchor = self._resolve_anchor(screen_w, screen_h)
self._mascot_x = anchor.x
self._mascot_y = anchor.y
self._root.geometry(f"{self._win_w}x{self._win_h}+{anchor.x}+{anchor.y}")
else:
anchor = self._resolve_anchor(screen_w, screen_h)
self._mascot_x = anchor.x
self._mascot_y = anchor.y
self._root.geometry(f"{self._win_w}x{self._win_h}+{anchor.x}+{anchor.y}")
self._canvas = tk.Canvas(
self._root,
width=self._win_w,
height=self._win_h,
bg="systemTransparent" if self._mac_transparent else COLOR_KEY_HEX,
highlightthickness=0,
borderwidth=0,
)
self._canvas.pack(fill="both", expand=True)
if self._mac_transparent:
# Tk 9 needs the native backing cleared too (BUG-075); flush
# geometry so the NSWindow exists before the AppKit pass.
self._root.update_idletasks()
apply_macos_clear_backing()
# Drag + interaction bindings. Tk dispatch:
# <Button-1> → drag-start (always fires, even on a double-click)
# <B1-Motion> → drag-update (only fires while LMB held)
# <ButtonRelease-1> → drag-finish (or no-op if it was a click)
# <Double-Button-1> → mute toggle (fires after Button-1+Release)
# <Button-3> → pet context menu, or raise the main window
# <Button-2> → reset position (moved off the old right-click menu)
# User spec 2026-05-17: double-click on the orb mutes Jarvis.
# Spec 2026-06-02: right-click now opens the Jarvis window (same as the
# jarvis-bar). "Reset position" moved from the old right-click menu to
# middle-click; mute stays on the double-double-click gesture. Drag-start
# does not commit any geometry change until the threshold is crossed, so
# a fast double-click stays harmless.
self._canvas.bind("<ButtonPress-1>", self._on_drag_press)
self._canvas.bind("<B1-Motion>", self._on_drag_motion)
self._canvas.bind("<ButtonRelease-1>", self._on_drag_release)
self._canvas.bind("<Double-Button-1>", self._on_mute_double_click)
self._canvas.bind("<Button-3>", self._on_right_click)
self._canvas.bind("<Button-2>", self._on_reset_double_click)
# Pointer presence drives the control row (see OrbControlRow): reaching
# for the orb is the moment its controls become useful.
self._canvas.bind("<Enter>", self._on_orb_pointer_enter)
self._canvas.bind("<Leave>", self._on_orb_pointer_leave)
# Drag-drop onto the mascot (desktop extra, cross-platform via tkdnd).
# Pure addition, fully guarded: a no-op when tkinterdnd2 is absent
# (NullDropTarget) so the live overlay is never destabilised. Dropped
# paths/text go to the process-global bridge, which the desktop app
# marshals to the brain intake (dodaios/brain/drop_context.ingest_drop).
try:
from dodaios.overlay.drop_bridge import dispatch_drop
from dodaios.overlay.drop_target import make_drop_target
make_drop_target().register(self._canvas, dispatch_drop)
except Exception: # noqa: BLE001 — drop is optional; never block orb boot.
logging.getLogger("jarvis.orb").debug(
"mascot drop target registration skipped", exc_info=True
)
self._comment_bubble = OrbCommentBubble(
parent=self._root,
orb_x=anchor.x,
orb_y=anchor.y,
orb_w=self._win_w,
screen_w=screen_w,
theme=bubble_theme_for_style(self._style),
)
self._ensure_controls()
if self._style == "pet":
self._sync_pet_strip_scale()
if self._renderer is None:
self._renderer = self._build_renderer(self._style)
self._t0 = time.perf_counter()
self._running = True
# ADR-0016 L1 — selective boot flash. When the persisted pin is
# honored on a secondary monitor (Power-User mode), show the orb
# at the primary anchor for 800 ms BEFORE migrating to the pin.
# Skipped in single-monitor / primary-pin / default-anchor boots.
if self._boot_flash_target_xy is not None and not self._sticky:
target_x, target_y = self._boot_flash_target_xy
self._root.deiconify()
self._root.after(800, lambda: self._finish_boot_flash(target_x, target_y))
elif not self._sticky:
self._root.withdraw()
self._started.set()
# Start the mic listener only after window creation, so any
# sounddevice errors (no mic, PortAudio init) surface only after the
# orb is visible and aren't silently swallowed at startup.
if self._mic_reactive:
try:
from ui.orb.mic_listener import MicListener
self._mic = MicListener(on_level=self.set_level)
self._mic.start()
except Exception as exc:
print(f"[orb] Mic-reactive mode failed to start: {exc}")
if auto_demo:
threading.Thread(target=self._run_demo, daemon=True).start()
self._schedule_ui_queue()
# Through the guard, not a direct call: a show() drained just above may
# already have armed the loop, and a second chain would double every tick.
self._ensure_frame_loop()
self._schedule_position_recheck()
self._root.mainloop()
def _resolve_anchor(self, screen_w: int, screen_h: int) -> MascotAnchor:
"""Read live taskbar+tray rects from Win32 and compute mascot anchor.
The pet is not square and carries its control strip below it, so its
anchor takes x from its width, y from its height, and then lifts the
whole group until the STRIP stands on the taskbar line.
"""
taskbar = get_taskbar_info()
tray_rect = get_tray_notify_rect()
def _anchor(size: int) -> MascotAnchor:
return compute_mascot_position(
screen_w,
screen_h,
mascot_size=size,
taskbar=taskbar,
tray_rect=tray_rect,
tray_safe_margin_px=TRAY_SAFE_MARGIN_PX,
right_edge_margin_px=RIGHT_EDGE_MARGIN_PX,
overlap_px=TASKBAR_OVERLAP_PX,
autohide_bottom_margin_px=AUTOHIDE_BOTTOM_MARGIN_PX,
)
if self._style != "pet":
return _anchor(self._win_w)
by_width = _anchor(self._win_w)
by_height = _anchor(self._win_h)
return MascotAnchor(
x=by_width.x,
y=max(8, by_height.y - self._pet_below_height()),
taskbar_aligned=by_height.taskbar_aligned,
)
def _pet_strip_scale(self) -> float:
"""The strip's scale: the monitor's DPI ratio times ``pet_scale``."""
renderer = self._renderer
if isinstance(renderer, PetRenderer):
return renderer.strip_scale
return max(0.25, self._dpi_ratio * self._pet_scale)
def _pet_below_height(self) -> int:
"""Height of what hangs under the pet's figure: the gap plus the strip."""
scale = self._pet_strip_scale()
_strip_w, strip_h = orb_controls.pet_strip_size(scale)
gap = max(1, int(round(orb_controls.PET_STRIP_GAP_FROM_FIGURE * scale)))
return strip_h + gap
def _sync_pet_strip_scale(self) -> None:
"""Bring the strip and the card column to the current strip scale."""
scale = self._pet_strip_scale()
row = self._controls
if isinstance(row, PetControlStrip):
row.set_scale(scale)
notices = self._notices
if notices is not None:
strip_w, _strip_h = orb_controls.pet_strip_size(scale)
notices.set_scale(
scale, int(round(strip_w * PET_NOTICE_WIDTH_PER_STRIP)), self._thought_art_px()
)
self._sync_notice_anchor()
def _clamp_position(
self, x: int, y: int, monitor_geo: tuple[int, int, int, int]
) -> tuple[int, int]:
"""Keep the window (for the pet: the figure plus its strip) on screen."""
if self._style != "pet":
return clamp_to_work_area(x, y, monitor_geo, mascot_size_px=self._win_w)
clamped_x, _ = clamp_to_work_area(x, y, monitor_geo, mascot_size_px=self._win_w)
_, clamped_y = clamp_to_work_area(
x, y, monitor_geo, mascot_size_px=self._win_h + self._pet_below_height()
)
return clamped_x, clamped_y
def _move_attached(self, x: int, y: int, screen_w: int) -> None:
"""Bring the bubble and the control row along after the window moved."""
bubble = self._comment_bubble
if bubble is not None and self._style != "pet":
bubble.update_anchor(x, y, screen_w)
if self._controls is not None:
self._controls.update_anchor(x, y)
self._sync_notice_anchor(refresh_limit=False)
def _read_dpi_ratio(self) -> float:
"""The monitor's display scale as Tk sees it (1.0 at 100 %)."""
if self._root is None:
return 1.0
try:
return dpi_ratio_for(float(self._root.winfo_fpixels("1i")))
except (tk.TclError, TypeError, ValueError):
return 1.0
def _schedule_position_recheck(self) -> None:
"""Re-resolve the mascot anchor periodically.
Two paths:
- manual_pinned=False: existing taskbar-anchor recompute (DPI /
monitor / taskbar resize tracking).
- manual_pinned=True: clamp-only — keep orb on the visible work
area if monitors changed; otherwise leave it alone.
"""
if not self._running or not self._root:
return
try:
screen_w = self._root.winfo_screenwidth()
screen_h = self._root.winfo_screenheight()
if self._manual_pinned:
screens = screens_from_tk(self._root)
monitor_geo, monitor_name = self._monitor_at_orb_center(screens)
clamped_x, clamped_y = self._clamp_position(
self._mascot_x, self._mascot_y, monitor_geo
)
if (clamped_x, clamped_y) != (self._mascot_x, self._mascot_y):
self._mascot_x = clamped_x
self._mascot_y = clamped_y
self._root.geometry(f"{self._win_w}x{self._win_h}+{clamped_x}+{clamped_y}")
self._move_attached(clamped_x, clamped_y, screen_w)
try:
save_position_to_toml(
JARVIS_TOML_PATH,
MascotPosition(
monitor=monitor_name,
x_relative=clamped_x - monitor_geo[0],
y_relative=clamped_y - monitor_geo[1],
),
)
except OSError:
pass
else:
anchor = self._resolve_anchor(screen_w, screen_h)
if (anchor.x, anchor.y) != (self._mascot_x, self._mascot_y):
self._mascot_x = anchor.x
self._mascot_y = anchor.y
self._root.geometry(f"{self._win_w}x{self._win_h}+{anchor.x}+{anchor.y}")
self._move_attached(anchor.x, anchor.y, screen_w)
if self._style == "pet":
# Same cadence, one more job: a persistent pet must not sink
# under a freshly opened window (see _reassert_topmost).
self._reassert_topmost()
except (tk.TclError, OSError):
logging.getLogger("jarvis.orb").debug("orb position recheck skipped", exc_info=True)
if self._root is not None:
self._root.after(POSITION_RECHECK_MS, self._schedule_position_recheck)
def _topmost_helpers(
self,
) -> tuple[Callable[..., Any], Callable[..., Any]] | None:
"""The Jarvis Bar's Win32 Z-order probe and repair, imported once."""
if self._topmost_fns is None:
try:
from dodaios.ui.dodaiosbar.overlay import ( # noqa: PLC0415
_win32_force_topmost,
_win32_topmost_band_is_healthy,
)
except Exception: # noqa: BLE001 — cosmetic; the -topmost flag remains
logging.getLogger("jarvis.orb").debug("topmost helpers unavailable", exc_info=True)
return None
self._topmost_fns = (_win32_topmost_band_is_healthy, _win32_force_topmost)
return self._topmost_fns
def _reassert_topmost(self, *, force: bool = False) -> None:
"""Put the pet's windows back in Windows' real topmost band.
A mapped Tk window can keep its topmost flag and still sit under an
ordinary window (the Jarvis Bar's bug, same cure). ``SWP_NOACTIVATE``
inside the helper keeps this from ever stealing focus. Windows only;
elsewhere Tk's ``-topmost`` request is all there is.
"""
if sys.platform != "win32" or self._root is None or not self._window_mapped():
return
helpers = self._topmost_helpers()
if helpers is None:
return
is_healthy, force_topmost = helpers
windows: list[Any] = [self._root]
row = self._controls
if row is not None and row.visible and row.window is not None:
windows.append(row.window)
notices = self._notices
if notices is not None and notices.window is not None:
windows.append(notices.window)
thought = self._thought
if thought is not None and thought.window is not None:
windows.append(thought.window)
for window in windows:
try:
if force or is_healthy(window) is not True:
force_topmost(window)
except Exception: # noqa: BLE001 — Z-order repair is best-effort
logging.getLogger("jarvis.orb").debug("topmost re-assert failed", exc_info=True)
# ------------------------------------------------------------------
# Drag-and-pin handlers (Spec: docs/superpowers/specs/2026-05-17-orb-drag-design.md)
# ------------------------------------------------------------------
def _on_drag_press(self, event: tk.Event) -> None:
if self._root is None:
return
self._drag_state = _DragState(
start_root_x=event.x_root,
start_root_y=event.y_root,
offset_x=event.x_root - self._mascot_x,
offset_y=event.y_root - self._mascot_y,
moved=False,
)
try:
self._root.configure(cursor="fleur")
except tk.TclError:
pass
def _on_drag_motion(self, event: tk.Event) -> None:
if self._drag_state is None or self._root is None:
return
dx = event.x_root - self._drag_state.start_root_x
dy = event.y_root - self._drag_state.start_root_y
if not self._drag_state.moved and (abs(dx) + abs(dy)) < DRAG_THRESHOLD_PX:
return
if not self._drag_state.moved and self._style == "pet":
# Picked up: a real drag, not a click.
self._apply_pet_feed("on_held", True)
self._drag_state.moved = True
new_x = event.x_root - self._drag_state.offset_x
new_y = event.y_root - self._drag_state.offset_y
self._mascot_x = new_x
self._mascot_y = new_y
try:
self._root.geometry(f"{self._win_w}x{self._win_h}+{new_x}+{new_y}")
except tk.TclError:
return
self._move_attached(new_x, new_y, self._root.winfo_screenwidth())
def _on_drag_release(self, _event: tk.Event) -> None:
if self._root is not None:
try:
self._root.configure(cursor="")
except tk.TclError:
pass
state = self._drag_state
self._drag_state = None
if state is None or not state.moved:
return # click, not drag
if self._style == "pet":
self._apply_pet_feed("on_held", False)
screens = screens_from_tk(self._root)
monitor_geo, monitor_name = self._monitor_at_orb_center(screens)
clamped_x, clamped_y = self._clamp_position(self._mascot_x, self._mascot_y, monitor_geo)
if (clamped_x, clamped_y) != (self._mascot_x, self._mascot_y):
self._mascot_x = clamped_x
self._mascot_y = clamped_y
try:
self._root.geometry(f"{self._win_w}x{self._win_h}+{clamped_x}+{clamped_y}")
except tk.TclError:
logging.getLogger("jarvis.orb").debug("orb clamp move failed", exc_info=True)
if self._style == "pet":
# The monitor may have changed with the drop: re-read its work area.
self._work_area_cache = None
if self._controls is not None:
self._controls.update_anchor(self._mascot_x, self._mascot_y)
self._sync_notice_anchor()
self._manual_pinned = True
try:
save_position_to_toml(
JARVIS_TOML_PATH,
MascotPosition(
monitor=monitor_name,
x_relative=self._mascot_x - monitor_geo[0],
y_relative=self._mascot_y - monitor_geo[1],
),
)
except OSError as exc:
# Persistence failure is non-fatal — orb stays at new position
# for this session; next restart falls back to default.
print(f"[orb] save_position_to_toml failed: {exc}")
def set_on_mute_toggle(self, callback: Callable[[], None] | None) -> None:
"""Inject the Jarvis-wide mute toggle action.
Fired when the user double-clicks the orb. The callback is
responsible for the actual mute logic — this layer just
translates the gesture. Pass ``None`` to detach.
Architectural note: keeping this as an opaque callback preserves
the rule from ``ui/orb/bus_bridge.py`` that the orb knows nothing
about Jarvis-Core, EventBus, or Supervisor states. The bridge in
the upper layer is the one that publishes events.
"""
self._mute_toggle_callback = callback
# ------------------------------------------------------------------
# Control row (voice-orb style only)
# ------------------------------------------------------------------
def _controls_wanted(self) -> bool:
"""Does this style show a control row at all?
The voice orb wears its four discs, the pet its strip. The mascot has
its own arms and expressions, and a row of discs under the ghost would
read as a toolbar bolted to a cartoon.
"""
return self._style in ("voice_orb", "pet")
def _ensure_controls(self) -> None:
"""Create, swap or tear down the row so it matches the current style."""
if self._root is None:
return
if not self._controls_wanted():
if self._controls is not None:
self._controls.destroy()
self._controls = None
return
wanted = PetControlStrip if self._style == "pet" else OrbControlRow
if self._controls is not None:
if type(self._controls) is wanted:
return
self._controls.destroy()
self._controls = None
try:
if wanted is PetControlStrip:
row: OrbControlRow = PetControlStrip(
parent=self._root,
orb_x=self._mascot_x,
orb_y=self._mascot_y,
orb_w=self._win_w,
orb_h=self._win_h,
scale=self._pet_strip_scale(),
on_drag_press=self._on_drag_press,
on_drag_motion=self._on_drag_motion,
on_drag_release=self._on_drag_release,
on_context=self._on_right_click,
keep_visible=self._pet_strip_wanted,
)
else:
row = OrbControlRow(
parent=self._root,
orb_x=self._mascot_x,
orb_y=self._mascot_y,
orb_w=self._win_w,
orb_h=self._win_h,
)
except tk.TclError:
logging.getLogger("jarvis.orb").debug("orb control row unavailable", exc_info=True)
return
row.set_on_action(self._on_control_action)
row.set_state(
active=self._mode in ACTIVE_VOICE_MODES,
speaker_muted=self._speaker_muted,
)
if isinstance(row, PetControlStrip):
row.set_state(mic_muted=self._mic_muted, notify_off=not self._notify_enabled)
self._controls = row
def _on_orb_pointer_enter(self, _event: tk.Event | None = None) -> None:
self._pointer_over_orb = True
row = self._controls
if row is not None:
row.show()
def _pet_strip_wanted(self) -> bool:
"""Should the pet's strip be up right now?
Always when the user asked for it (``[ui] pet_strip_always``). Else
only while it is useful: Jarvis is listening, thinking or talking, the
pointer is on the figure or the strip, or the pet is "None" (the strip
is all there is, so hiding it would leave nothing to hover).
"""
if self._pet_strip_always or self._figure_id() == NO_PET_ID:
return True
if self._mode in ACTIVE_VOICE_MODES + PET_VOICE_MODES + PET_THINK_MODES:
return True
notices = self._notices
if notices is not None and notices.count:
# The bell rang for these cards; it stays in sight while they do.
return True
row = self._controls
return self._pointer_over_orb or (row is not None and row.pointer_inside)
def _on_orb_pointer_leave(self, _event: tk.Event | None = None) -> None:
self._pointer_over_orb = False
row = self._controls
if row is None:
return
if self._style == "pet":
row.hide_after_grace() # a no-op while the strip is still wanted
return
# A live conversation keeps the controls out: hanging up is the one
# thing the user reaches for mid-call, and hunting for a row that hides
# itself is worse than a row that stays.
if self._mode in ACTIVE_VOICE_MODES:
return
row.hide_after_grace()
def _sync_controls_visibility(self) -> None:
"""Reconcile the row with mode + pointer after a state change."""
row = self._controls
if row is None:
return
active = self._mode in ACTIVE_VOICE_MODES
row.set_state(active=active)
if self._style == "pet":
# The pet alone at rest; its strip joins it while it is useful.
if not self._window_mapped():
row.hide()
elif self._pet_strip_wanted():
row.show()
else:
row.hide_after_grace()
return
# Never on its own: the row is the orb's controls, so a mode change
# arriving while the sphere is withdrawn must not float four buttons
# over an empty desktop.
if not self._orb_is_visible():
row.hide()
return
if active or self._pointer_over_orb or row.pointer_inside:
row.show()
else:
row.hide_after_grace()
def _reveal_controls(self) -> None:
"""Post-deiconify pass: refresh the speaker disc, then place the row."""
if self._controls is None:
return
self._refresh_speaker_state()
self._sync_controls_visibility()
def _orb_is_visible(self) -> bool:
if self._root is None:
return False
try:
return bool(self._root.winfo_viewable())
except tk.TclError:
return False
def _on_control_action(self, action: str) -> None:
"""Run one control-row button. Always on the Tk thread."""
if action == "attach":
self._do_attach()
elif action in ("mic", "orb"):
self._do_talk_or_hangup()
elif action == "close":
self._do_close()
elif action == "speaker":
self._do_speaker_toggle()
elif action == "bell":
self._do_bell_toggle()
elif action == "compose":
self._do_compose()
elif action == "mic_mute":
self._do_mic_mute()
elif action == "call":
self._do_call()
def _do_call(self) -> None:
"""The phone disc: call Jarvis (ringing as it dials), or hang up."""
if self._mode not in ACTIVE_VOICE_MODES:
self._ring_phone()
self._do_talk_or_hangup()
def _ring_phone(self, phase: int = 1) -> None:
"""Shake the handset: one strip frame per ``PET_RING_STEP_S``."""
root = self._root
row = self._controls
if root is None or not isinstance(row, PetControlStrip):
self._call_ring_after_id = None
return
if phase == 1 and self._call_ring_after_id is not None:
try:
root.after_cancel(self._call_ring_after_id)
except tk.TclError:
logging.getLogger("jarvis.orb").debug("phone timer cancel failed", exc_info=True)
if phase >= orb_controls.PET_RING_PHASES * orb_controls.PET_CALL_RING_PASSES:
self._call_ring_after_id = None
row.set_state(call_ring=0)
return
row.set_state(call_ring=phase)
delay = int(orb_controls.PET_RING_STEP_S * 1000)
self._call_ring_after_id = root.after(delay, lambda: self._ring_phone(phase + 1))
def _do_bell_toggle(self) -> None:
"""The bell: notifications on or off for this run (Tk thread).
Off sends the cards on screen away at once; on rings the bell so the
click is answered by something that moves.
"""
self._notify_enabled = not self._notify_enabled
row = self._controls
if isinstance(row, PetControlStrip):
row.set_state(notify_off=not self._notify_enabled)
if self._notify_enabled:
self._ring_bell()
elif self._notices is not None:
self._notices.clear()
callback = self._on_notify_toggle
if callback is not None:
try:
callback(self._notify_enabled)
except Exception: # noqa: BLE001 — a bad callback must not kill the Tk loop
logging.getLogger("jarvis.orb").debug(
"notify toggle callback failed", exc_info=True
)
def _ring_bell(self, phase: int = 1) -> None:
"""Swing the bell once: one strip frame per ``PET_RING_STEP_S``."""
root = self._root
row = self._controls
if root is None or not isinstance(row, PetControlStrip):
self._ring_after_id = None
return
if phase == 1 and self._ring_after_id is not None:
try:
root.after_cancel(self._ring_after_id)
except tk.TclError:
logging.getLogger("jarvis.orb").debug("bell timer cancel failed", exc_info=True)
if phase >= orb_controls.PET_RING_PHASES:
self._ring_after_id = None
row.set_state(ring=0)
return
row.set_state(ring=phase)
delay = int(orb_controls.PET_RING_STEP_S * 1000)
self._ring_after_id = root.after(delay, lambda: self._ring_bell(phase + 1))
def _do_compose(self) -> None:
"""The pen: raise the main window on a fresh chat (``ComposeRequested``).
Without a compose callback (an older bridge) the right-click action is
the honest fallback — it at least brings the window up.
"""
callback = self._on_compose or self._on_show_window
if callback is None:
logging.getLogger("jarvis.orb").info("pet compose ignored — nothing wired")
return
callback()
def _do_mic_mute(self) -> None:
"""The strip's microphone: flip Jarvis's mute.
The flip on the strip is optimistic; ``set_muted`` (fed by
``VoiceMuteChanged``) reconciles it with what the pipeline really did.
Unwired, nothing is flipped — a mute icon that mutes nothing lies.
"""
if self._mute_toggle_callback is None:
logging.getLogger("jarvis.orb").info("pet mic mute ignored — nothing wired")
return
self._mic_muted = not self._mic_muted
row = self._controls
if isinstance(row, PetControlStrip):
row.set_state(mic_muted=self._mic_muted)
self._fire_mute_toggle()
def _do_attach(self) -> None:
"""Pick files and hand them to the conversation (same path as a drop)."""
log = logging.getLogger("jarvis.orb")
count = orb_controls.pick_and_dispatch_files(
self._root, on_error=lambda message: log.warning("orb attach: %s", message)
)
if count:
log.info("orb attach: handed %d file(s) to the conversation", count)
def _do_talk_or_hangup(self) -> None:
"""The mic disc: start a conversation, or end the running one."""
if self._mode in ACTIVE_VOICE_MODES:
self._do_hangup()
return
callback = self._on_talk
if callback is not None:
callback()
return
pipeline = self._speech_pipeline()
starter = getattr(pipeline, "request_voice_session", None)
if callable(starter):
starter()
def _do_hangup(self) -> None:
callback = self._on_hangup
if callback is not None:
callback()
else:
pipeline = self._speech_pipeline()
hangup = getattr(pipeline, "request_hangup", None)
if callable(hangup):
hangup()
# Local feedback now instead of waiting for microphone teardown plus
# the EventBus round-trip; the authoritative state reconciles it.
self._set_mode("idle")
self._sync_controls_visibility()
def _do_close(self) -> None:
"""X: end the conversation and put the orb away, like the in-app X."""
if self._mode in ACTIVE_VOICE_MODES:
self._do_hangup()
row = self._controls
if row is not None:
row.hide()
self._pointer_over_orb = False
self._show_until_t = 0.0
self._actually_hide()
def _do_speaker_toggle(self) -> None:
"""Silence / restore the assistant's voice for this session only."""
callback = self._on_speaker_toggle
if callback is not None:
callback()
# The host process cannot see the pipeline, so it cannot report the
# resulting state either. Mirror optimistically — the next reveal
# re-reads the truth via _refresh_speaker_state.
self._speaker_muted = not self._speaker_muted
else:
result = orb_controls.toggle_speaker_mute(
source="pet" if self._style == "pet" else "orb"
)
if result is None:
logging.getLogger("jarvis.orb").info(
"orb speaker toggle ignored — no live speech pipeline"
)
return
self._speaker_muted = result
row = self._controls
if row is not None:
row.set_state(speaker_muted=self._speaker_muted)
def _refresh_speaker_state(self) -> None:
"""Re-read the real TTS mute so the disc cannot drift out of sync."""
if self._on_speaker_toggle is not None:
return # hosted: this process has no pipeline to ask
muted = orb_controls.speaker_is_muted()
if muted == self._speaker_muted:
return
self._speaker_muted = muted
row = self._controls
if row is not None:
row.set_state(speaker_muted=muted)
@staticmethod
def _speech_pipeline():
"""The live pipeline, or ``None`` off the desktop process."""
try:
from dodaios.core.runtime_refs import get_speech_pipeline
except Exception: # noqa: BLE001 — importable in practice; never fatal
return None
return get_speech_pipeline()
def set_on_talk(self, callback: Callable[[], None] | None) -> None:
"""Inject "start a voice session" (the mic disc while idle).
Wired by ``dodaios.ui.dodaiosbar.host`` when the orb runs in the macOS
companion process, where no SpeechPipeline exists; the parent applies
it. In-process the orb calls the pipeline itself.
"""
self._on_talk = callback
def set_on_hangup(self, callback: Callable[[], None] | None) -> None:
"""Inject "end the running session" (the mic disc while active, and X)."""
self._on_hangup = callback
def set_on_speaker_toggle(self, callback: Callable[[], None] | None) -> None:
"""Inject the assistant-voice mute toggle (the speaker disc)."""
self._on_speaker_toggle = callback
def set_on_show_window(self, callback: Callable[[], None] | None) -> None:
"""Inject the main-window action used by non-pet orb right-clicks.
Same bus-agnostic contract as
``set_on_mute_toggle``: OrbBusBridge passes a callable that publishes
``ShowWindowRequested``. Pass ``None`` to detach.
"""
self._on_show_window = callback
def _on_right_click(self, _event: tk.Event | None = None) -> None:
"""Open the pet's menu; other orb styles raise the main window."""
if self._style == "pet":
self._show_pet_context_menu(_event)
return
self._open_main_window()
def _show_pet_context_menu(self, event: tk.Event | None = None) -> None:
root = self._root
if root is None:
return
from dodaios.ui.pets.context_menu import preferences
from ui.orb.pet_context_menu import PetContextMenu
try:
if self._context_menu is not None:
self._context_menu.destroy()
labels, shortcut = preferences()
menu = PetContextMenu(root, scale=getattr(self, "_dpi_ratio", 1.0))
self._context_menu = menu
menu.add_command(
label=labels[0], command=self._open_main_window,
state="normal" if self._on_show_window is not None else "disabled",
)
menu.add_command(label=labels[1], command=self._on_reset_double_click)
menu.add_separator()
menu.add_command(
label=labels[2], accelerator=shortcut, command=lambda: self.set_visible(False),
)
x, y = (event.x_root, event.y_root) if event is not None else root.winfo_pointerxy()
try:
menu.tk_popup(int(x), int(y))
finally:
menu.grab_release()
except tk.TclError:
logging.getLogger("jarvis.orb").exception("Pet context menu could not be opened")
def _open_main_window(self) -> None:
callback = self._on_show_window
if callback is None:
return
try:
callback()
except Exception as exc: # noqa: BLE001
# The Tk thread must not crash on a downstream bus hiccup.
import logging
logging.getLogger("jarvis.orb").warning("orb show-window callback raised: %r", exc)
def _on_mute_double_click(self, _event: tk.Event) -> None:
"""First half of the mute gesture: increment a counter and arm a
reset timer. Mute toggles only after a *second* ``<Double-Button-1>``
within ``MUTE_GESTURE_WINDOW_MS`` ms (i.e. four clicks in quick
succession). One stray double-click — e.g. when the user clicks
the orb the moment it pops up — leaves the counter at 1 and
expires harmlessly.
Tk fires ``<Double-Button-1>`` *in addition* to the regular
``<Button-1>`` press/release pair. The press already entered
``_on_drag_press`` and primed the drag state; we abort it here so
a cursor twitch between the second press and release does not
commit a move.
"""
self._drag_state = None
self._mute_click_count += 1
if self._mute_click_count >= 2:
# Second double-click inside the window — fire the toggle.
# Reset book-keeping first so a downstream callback exception
# cannot strand the counter in the "armed" state.
self._mute_click_count = 0
self._cancel_mute_click_reset()
self._fire_mute_toggle()
return
# First double-click. Cancel any previous timer (defensive) and
# arm a fresh one that resets the counter if no second gesture
# follows.
self._cancel_mute_click_reset()
if self._root is None:
# Tests / headless harness: no timer available. Without the
# reset timer the second click ought to still toggle, so
# this branch is a graceful no-op for the timer-arm step.
return
try:
self._mute_click_reset_id = self._root.after(
MUTE_GESTURE_WINDOW_MS, self._reset_mute_click_count
)
except tk.TclError as exc:
# Root went away mid-gesture — treat as graceful no-op so the
# next legitimate gesture still works after the orb is rebuilt.
print(f"[orb] mute gesture timer-arm failed: {exc}")
def _reset_mute_click_count(self) -> None:
"""Tk-timer callback: clear the counter after ``MUTE_GESTURE_WINDOW_MS``
with no second double-click. Called from the Tk main-thread, so no
synchronisation needed.
"""
self._mute_click_count = 0
self._mute_click_reset_id = None
def _cancel_mute_click_reset(self) -> None:
"""Cancel the pending Tk-after timer, if any. Safe to call when
no timer is armed (e.g. before the first click of a gesture).
"""
if self._mute_click_reset_id is None or self._root is None:
self._mute_click_reset_id = None
return
try:
self._root.after_cancel(self._mute_click_reset_id)
except tk.TclError:
# Timer already fired or root disposed — both are harmless.
pass
self._mute_click_reset_id = None
def _fire_mute_toggle(self) -> None:
"""Invoke the registered mute-toggle callback exactly once.
Used by the two-double-click gesture path *and* by the right-
click context menu, which is the always-on recovery path: it
must NOT require a four-click ritual to undo an accidental mute.
"""
callback = self._mute_toggle_callback
if callback is None:
print("[orb] mute toggle gesture fired without registered callback")
return
try:
callback()
except Exception as exc: # noqa: BLE001
# Tk thread must not crash on a downstream bus hiccup — the
# gesture is supposed to silence Jarvis, not blow up the orb.
print(f"[orb] mute toggle callback raised: {exc!r}")
def _on_reset_double_click(self, _event: tk.Event | None = None) -> None:
"""Reset the orb to its default anchor position.
Historically bound to ``<Double-Button-1>`` (moved to mute on
2026-05-17) and then reachable via the right-click menu. Spec
2026-06-02 binds it to middle-click (``<Button-2>``) since right-click
now raises the main window. Still reachable via the voice
``OrbResetRequested`` path and kept callable by the same name so the
existing reset-coverage stays valid.
"""
if self._root is None:
return
self._manual_pinned = False
self._drag_state = None
try:
clear_position_in_toml(JARVIS_TOML_PATH)
except OSError as exc:
print(f"[orb] clear_position_in_toml failed: {exc}")
screen_w = self._root.winfo_screenwidth()
screen_h = self._root.winfo_screenheight()
anchor = self._resolve_anchor(screen_w, screen_h)
self._mascot_x = anchor.x
self._mascot_y = anchor.y
try:
self._root.geometry(f"{self._win_w}x{self._win_h}+{anchor.x}+{anchor.y}")
except tk.TclError:
return
if self._comment_bubble is not None:
self._comment_bubble.update_anchor(anchor.x, anchor.y, screen_w)
if self._controls is not None:
self._controls.update_anchor(anchor.x, anchor.y)
def _monitor_at_orb_center(self, screens: list) -> tuple[tuple[int, int, int, int], str]:
"""Return (geometry, device_name) of the monitor containing the orb center."""
cx = self._mascot_x + self._win_w // 2
cy = self._mascot_y + self._win_h // 2
for s in screens:
sx, sy, sw, sh = s.geometry
if sx <= cx < sx + sw and sy <= cy < sy + sh:
return s.geometry, s.name
# Fallback: primary monitor.
primary = next((s for s in screens if s.is_primary), None)
if primary is not None:
return primary.geometry, primary.name
if screens:
return screens[0].geometry, screens[0].name
# Last resort: single-screen guess.
if self._root is not None:
sw = self._root.winfo_screenwidth()
sh = self._root.winfo_screenheight()
return (0, 0, sw, sh), ""
return (0, 0, 1920, 1080), ""
#: Min on-screen duration after a show() call. Even if hide() is invoked
#: immediately afterwards, the mascot stays visible for at least this long.
SHOW_MIN_DURATION_S: float = 2.5
def show(self, mode: str = "listen") -> None:
"""Reveal the mascot in ``mode``. Thread-safe.
The mode is validated SYNCHRONOUSLY, on the caller's thread, before the
reveal is queued. That ordering is the contract, not a detail: the work
itself is handed to the Tk thread, so a mode rejected inside ``_show``
would be dropped later, on another thread, where no exception can ever
reach the caller — the call would return "successfully" and the user
would simply see nothing. Callers that keep a fallback look for a
surface which cannot render a mode depend on hearing about the
rejection here.
Raises ``ValueError`` for a mode outside the shared vocabulary.
"""
if mode not in MODES:
raise ValueError(f"Unknown mode: {mode!r} (allowed: {', '.join(MODES)})")
def _show() -> None:
self._cancel_pending_hide()
self._set_mode(mode)
if self._root and not self._pet_hidden_by_user():
self._root.deiconify()
if self._mac_transparent:
# Tk 9 can (re)materialize the NSWindow on mapping after a
# withdraw; a construction-time clear-backing pass does not
# survive that, leaving the opaque grey box (BUG-075).
# Re-assert on every reveal — idempotent and cheap.
apply_macos_clear_backing()
# ADR-0016 visible-feedback contract: schedule a post-frame
# visibility snapshot. 50 ms gives Tk time to actually map
# the window before we sample winfo_viewable / winfo_x.
# We must NOT block the deiconify path — publish is fire-
# and-forget; failures are swallowed by the publisher.
self._root.after(50, self._publish_visibility_feedback, mode)
# Same 50 ms reason: the row asks whether the orb is mapped,
# and right after deiconify Tk still says it is not. The
# speaker disc re-reads the real TTS mute here too, so a mute
# set elsewhere (settings slider, voice command) is reflected
# rather than remembered wrong.
self._root.after(50, self._reveal_controls)
if self._style == "pet":
self._sync_controls_visibility()
self._ensure_frame_loop()
now = time.perf_counter() - self._t0
self._show_until_t = max(self._show_until_t, now + self.SHOW_MIN_DURATION_S)
self._enqueue_ui(_show)
def _finish_boot_flash(self, target_x: int, target_y: int) -> None:
"""ADR-0016 L1: end the boot-flash phase by migrating the orb to
the persisted pin and hiding it again. Runs on the Tk thread.
Defensive: if a wake-word arrived during the 800 ms flash and the
orb is already in a visible state for LISTENING etc., the
``_show_until_t`` guard keeps it on-screen at the target position
rather than withdrawing immediately. The user sees the orb slide
from primary anchor to the secondary pin — that is the intended
UX so they always know where the orb is.
"""
if self._root is None:
return
self._mascot_x = target_x
self._mascot_y = target_y
try:
self._root.geometry(f"{self._win_w}x{self._win_h}+{target_x}+{target_y}")
except tk.TclError:
return
# Only withdraw if no active LISTENING/THINKING/SPEAKING state has
# claimed the orb during the flash window. ``_show_until_t`` is
# set by ``show()`` and stays in the future while the orb is
# actively requested visible. The pet is on screen while idle, so
# only a pet the user hid goes away here.
now = time.perf_counter() - self._t0
withdraw = self._user_hidden if self._style == "pet" else now >= self._show_until_t
if withdraw:
try:
self._root.withdraw()
except tk.TclError:
logging.getLogger("jarvis.orb").debug("boot-flash withdraw failed", exc_info=True)
elif self._style == "pet":
self._move_attached(target_x, target_y, self._root.winfo_screenwidth())
self._boot_flash_target_xy = None
def set_feedback_publisher(
self, callback: Callable[[str, dict[str, Any]], None] | None
) -> None:
"""Inject the ADR-0016 visible-feedback publisher.
Called from ``OrbBusBridge.attach`` so the bridge owns the bus
reference and the orb stays bus-agnostic. Set to ``None`` to
detach (useful in unit tests).
"""
self._feedback_publisher = callback
def _publish_visibility_feedback(self, mode: str) -> None:
"""Sample the live Tk geometry and forward to the registered
publisher (if any). Runs on the Tk main thread via ``root.after``.
Errors must NOT propagate — a bad bus or a stale root would
otherwise crash the Tk event loop and freeze the orb.
"""
publisher = self._feedback_publisher
if publisher is None or self._root is None:
return
try:
viewable = int(self._root.winfo_viewable())
x = int(self._root.winfo_x())
y = int(self._root.winfo_y())
geometry = f"{self._win_w}x{self._win_h}+{x}+{y}"
except tk.TclError:
return
observed = {
"viewable": viewable,
"geometry": geometry,
"x": x,
"y": y,
"monitor": self._mascot_x and "" or "", # placeholder, see below
}
# We deliberately leave ``monitor`` empty here — the bridge owns
# monitor naming because it has access to ``screens_from_tk`` via
# drag_persistence; injecting that lookup into the orb would
# break the bus-agnostic boundary.
observed.pop("monitor", None)
try:
publisher(mode, observed)
except Exception: # noqa: BLE001
import logging
logging.getLogger("jarvis.orb").debug(
"feedback publisher raised; suppressed", exc_info=True
)
def hide(self) -> None:
def _hide() -> None:
self._cancel_pending_hide()
if not self._root:
return
now = time.perf_counter() - self._t0
remaining_s = self._show_until_t - now
if remaining_s > 0.001:
wait_ms = max(1, int(round(remaining_s * 1000)))
self._pending_hide_after_id = self._root.after(wait_ms, self._actually_hide)
else:
self._actually_hide()
self._enqueue_ui(_hide)
def _actually_hide(self) -> None:
self._pending_hide_after_id = None
menu = getattr(self, "_context_menu", None)
if menu is not None:
menu.destroy()
# The controls belong to the orb, not to the desktop: a row of buttons
# left floating where the sphere used to be is a widget with nothing
# behind it.
row = self._controls
if row is not None:
row.hide()
self._pointer_over_orb = False
if self._notices is not None:
# The pet's cards hang off the pet; they go with it.
self._notices.hide()
if self._thought is not None:
self._thought.hide()
if self._root is not None:
try:
self._root.withdraw()
except tk.TclError:
logging.getLogger("jarvis.orb").debug("orb withdraw failed", exc_info=True)
def stop(self) -> None:
"""Tear the mascot overlay down at runtime (live display-style swap).
Additive — not on the normal voice path. Clears ``_running`` so the
after-loops (``_schedule_frame`` / ``_schedule_ui_queue`` /
``_schedule_position_recheck``) all stop rescheduling on their next
tick (each guards on ``self._running`` first), then hides the comment
bubble and destroys the root on the Tk thread. Fully guarded so a
teardown hiccup never propagates.
"""
self._running = False
root = self._root
if root is None:
return
def _teardown() -> None:
try:
bubble = self._comment_bubble
if bubble is not None and hasattr(bubble, "hide"):
bubble.hide()
except Exception: # noqa: BLE001 — teardown must reach root.destroy
logging.getLogger("jarvis.orb").debug("orb bubble teardown failed", exc_info=True)
try:
row = self._controls
self._controls = None
if row is not None:
row.destroy()
except Exception: # noqa: BLE001 — teardown must reach root.destroy
logging.getLogger("jarvis.orb").debug(
"orb control row teardown failed", exc_info=True
)
try:
notices = self._notices
self._notices = None
if notices is not None:
notices.destroy()
thought = self._thought
self._thought = None
if thought is not None:
thought.destroy()
except Exception: # noqa: BLE001 — teardown must reach root.destroy
logging.getLogger("jarvis.orb").debug("notice stack teardown failed", exc_info=True)
try:
root.destroy()
except Exception: # noqa: BLE001 — the process may be exiting anyway
logging.getLogger("jarvis.orb").debug("orb root destroy failed", exc_info=True)
try:
root.after(0, _teardown)
except Exception: # noqa: BLE001 — a dead interpreter has nothing to tear down
logging.getLogger("jarvis.orb").debug("orb teardown scheduling failed", exc_info=True)
def _cancel_pending_hide(self) -> None:
if self._pending_hide_after_id is not None and self._root is not None:
try:
self._root.after_cancel(self._pending_hide_after_id)
except tk.TclError:
pass
self._pending_hide_after_id = None
def _bubble_wanted(self) -> bool:
"""Does this style speak through a bubble at all?
The mascot does — a character with a face says things in a bubble. The
voice orb does NOT (maintainer, 2026-08-06): the sphere carries the
whole state itself, and a panel of text floating over the desktop was
the part that read as clutter. Everything the bubble used to say is now
in how the orb moves — it swells on the voice, and its colours churn
while it thinks.
"""
if self._style == "pet":
return self._pet_bubble
return self._style != "voice_orb"
def show_comment(self, text: str, duration_ms: int = 3500) -> None:
"""Pop a speech bubble above the orb. Thread-safe.
Does NOT trigger the mouth animation — call start_mouth_animation()
separately so the mouth only moves while audio is actually playing.
On the pet the text lands in its status bubble instead.
"""
if self._style == "pet":
# The pet's card shows what Jarvis thinks (``show_status``), never
# spoken text; a comment is still a sign of life.
self._note_activity()
return
bubble = self._comment_bubble
if bubble is None or not text or not self._bubble_wanted():
return
self._enqueue_ui(lambda: bubble.show(text, duration_ms))
def show_listening_transcript(self, text: str = "", duration_ms: int = 30000) -> None:
"""Show the larger live transcript bubble used while the user speaks.
The pet's card does not echo the transcript: it shows what Jarvis
thinks (``show_status``), and the bridge clears it. Hearing the user is
still a sign of life that keeps the pet awake.
"""
if self._style == "pet":
self._note_activity()
return
bubble = self._comment_bubble
if bubble is None or not self._bubble_wanted():
return
self._enqueue_ui(lambda: bubble.show(text, duration_ms, variant="transcript"))
def hide_comment(self) -> None:
"""Hide the speech bubble immediately. Thread-safe.
The pet's status bubble is not snatched away the moment a turn ends:
it fades six seconds later, so the last line can still be read.
"""
if self._style == "pet":
self.clear_status(PET_STATUS_LINGER_S)
return
bubble = self._comment_bubble
if bubble is None:
return
self._enqueue_ui(bubble.hide)
# --- the desktop pet (docs/pets.md "Surface methods") ------------------
@property
def wants_status_lines(self) -> bool:
"""True when this surface shows condensed status lines (the pet only)."""
return self._style == "pet"
@property
def keeps_visible_when_idle(self) -> bool:
"""True while the look is the pet: the bridge shows ``idle`` instead of hiding.
Read on every idle edge, so a live swap between the pet (or the
mascot, which is a pet) and the voice orb changes the idle regime at
once. ``hide()`` itself stays a real withdraw for every look.
"""
return self._style == "pet"
@property
def pet_user_hidden(self) -> bool:
"""True while the user hid the pet (shortcut / settings) for this run."""
return self._user_hidden
def set_on_compose(self, callback: Callable[[], None] | None) -> None:
"""Inject the pen control's action (the bridge publishes ``ComposeRequested``)."""
self._on_compose = callback
@property
def notifications_enabled(self) -> bool:
"""Is the bell on (notifications show)?"""
return self._notify_enabled
def set_on_notifications_toggle(self, callback: Callable[[bool], None] | None) -> None:
"""Called on the Tk thread with the new state after the bell was clicked."""
self._on_notify_toggle = callback
def set_notifications_enabled(self, enabled: bool) -> None:
"""Switch the bell without a click (a respawned host restoring it). Thread-safe."""
flag = bool(enabled)
def _apply() -> None:
self._notify_enabled = flag
row = self._controls
if isinstance(row, PetControlStrip):
row.set_state(notify_off=not flag)
if not flag and self._notices is not None:
self._notices.clear()
self._enqueue_ui(_apply)
def push_notice(self, kind: str = "info", title: str = "", detail: str = "") -> None:
"""Show one notification card under the pet and ring the bell. Thread-safe.
``kind`` is ``done``, ``attention``, ``error`` or ``info``. Dropped
while the bell is off, the pet is hidden, or the look is not the pet.
"""
if self._style != "pet":
return
kind_text = str(kind or "info")
title_text = str(title or "")
detail_text = str(detail or "")
self._enqueue_ui(lambda: self._apply_notice(kind_text, title_text, detail_text))
def _apply_notice(self, kind: str, title: str, detail: str) -> None:
if self._style != "pet" or not self._notify_enabled:
return
notices = self._card_column()
if notices is None:
return
notices.push(kind, title, detail)
self._sync_controls_visibility()
self._ring_bell()
def _card_column(self) -> PetNoticeStack | None:
"""The pet's card column, built on first use; ``None`` when the pet
cannot show cards right now (no window, hidden by the user)."""
if self._style != "pet" or self._root is None:
return None
if self._user_hidden or not self._window_mapped():
return None
notices = self._notices
if notices is None:
scale = self._pet_strip_scale()
strip_w, _strip_h = orb_controls.pet_strip_size(scale)
try:
notices = PetNoticeStack(
self._root,
scale=scale,
width=int(round(strip_w * PET_NOTICE_WIDTH_PER_STRIP)),
art_px=self._thought_art_px(),
)
except tk.TclError:
logging.getLogger("jarvis.orb").debug("card column unavailable", exc_info=True)
return None
self._notices = notices
self._sync_notice_anchor()
return notices
def _notice_anchor(self, *, refresh_limit: bool = True) -> tuple[int, int, int, int, int]:
"""``(center_x, below_y, above_y, limit_bottom, screen_w)`` for the cards."""
center_x, below_y, above_y, limit = self._status_anchor(refresh_limit=refresh_limit)
try:
screen_w = int(self._root.winfo_screenwidth()) if self._root is not None else 1920
except tk.TclError:
screen_w = 1920
return center_x, below_y, above_y, limit, screen_w
def _sync_notice_anchor(self, *, refresh_limit: bool = True) -> None:
"""Bring the cards and the thought bubble to where the pet is now."""
if self._style != "pet":
return
thought = self._thought
if thought is not None:
thought.set_look(art_px=self._thought_art_px(), scale=self._pet_strip_scale())
thought.set_anchor(*self._thought_anchor())
notices = self._notices
if notices is None:
return
scale = self._pet_strip_scale()
strip_w, _strip_h = orb_controls.pet_strip_size(scale)
notices.set_scale(
scale, int(round(strip_w * PET_NOTICE_WIDTH_PER_STRIP)), self._thought_art_px()
)
notices.set_anchor(self._notice_anchor(refresh_limit=refresh_limit))
def _thought_art_px(self) -> int:
"""Screen pixels per art pixel: the pet sprite's own, so the bubble
is drawn at exactly the figure's pixel size."""
renderer = self._renderer
if isinstance(renderer, PetRenderer) and renderer.has_figure:
return max(1, int(renderer.factor))
return max(2, int(round(3 * self._pet_strip_scale())))
def _thought_anchor(self) -> tuple[int, int, int]:
"""``(head_x, head_y, screen_w)``: where the bubble's puffs end, just
above and right of the middle of the pet's head."""
head_x = self._mascot_x + int(self._win_w * 0.6)
head_y = self._mascot_y + int(self._win_h * 0.08)
try:
screen_w = int(self._root.winfo_screenwidth()) if self._root is not None else 1920
except tk.TclError:
screen_w = 1920
return head_x, head_y, screen_w
def _thought_bubble(self) -> PetThoughtBubble | None:
"""The bubble, built on first use; ``None`` when the pet cannot show it."""
if self._style != "pet" or self._root is None:
return None
if self._user_hidden or not self._window_mapped():
return None
if self._thought is None:
try:
self._thought = PetThoughtBubble(
self._root, art_px=self._thought_art_px(), scale=self._pet_strip_scale()
)
except tk.TclError:
logging.getLogger("jarvis.orb").debug("thought bubble unavailable", exc_info=True)
return None
self._thought.set_anchor(*self._thought_anchor())
return self._thought
def set_pet(self, pet_id: str) -> None:
"""Swap the figure live; ``"none"`` keeps the strip without a figure. Thread-safe.
The choice is kept while the mascot is the style and shows again once
the style is the pet.
"""
pet = str(pet_id or "").strip() or NO_PET_ID
self._pet_id = pet
self._note_activity()
self._enqueue_ui(self._apply_pet)
def set_pet_look(
self,
scale: float | None = None,
bubble: bool | None = None,
strip_always: bool | None = None,
) -> None:
"""Apply the pet's size, bubble and always-on strip live. Thread-safe."""
if scale is not None:
self._pet_scale = _clamp_pet_scale(scale)
if bubble is not None:
self._pet_bubble = bool(bubble)
if strip_always is not None:
self._pet_strip_always = bool(strip_always)
self._note_activity()
if self._root is None:
return # no window yet: the first paint reads the values just stored
if self._pet_look_queued:
return # the queued apply reads the values just stored
self._pet_look_queued = True
self._enqueue_ui(self._apply_pet_look)
def set_pet_outcome(self, kind: str) -> None:
"""Play the one-shot ``success`` or ``error`` animation. Thread-safe."""
outcome = str(kind or "").strip().lower()
if outcome not in ONE_SHOT_STATES:
return
self._enqueue_ui(lambda: self._apply_outcome(outcome))
def set_pet_action(self, kind: str | None) -> None:
"""Show what Jarvis is doing inside a turn. Thread-safe.
``working`` (a tool step) or ``searching`` (a lookup); ``None`` ends it.
"""
action = str(kind or "").strip().lower() or None
if action is not None and action not in ACTION_STATES:
return
self._enqueue_ui(lambda: self._apply_pet_feed("on_action", action))
def set_pet_busy(self, busy: bool) -> None:
"""An agent task is running in the background: the pet works. Thread-safe."""
flag = bool(busy)
self._enqueue_ui(lambda: self._apply_pet_feed("on_busy", flag))
def _apply_pet_feed(self, method: str, value: object) -> None:
"""Hand one input to the pet's state machine and repaint (Tk thread)."""
renderer = getattr(self, "_renderer", None)
if not isinstance(renderer, PetRenderer):
return
getattr(renderer, method)(value)
self._kick_frame()
def show_status(self, title: str = "", detail: str = "") -> None:
"""Show or update what Jarvis is thinking, in the thought bubble. Thread-safe.
The current step when there is one (``detail``), else the heading
(``title``) — except the bare "Thinking …" label, which the bubble
says with its bobbing dots instead of words.
"""
if self._style != "pet":
return
self._note_activity()
if not self._pet_bubble:
return
line = " ".join(str(detail or "").split()) or " ".join(str(title or "").split())
if not detail and _is_bare_thinking_label(line):
line = ""
self._enqueue_ui(lambda: self._apply_status(line))
def clear_status(self, linger_s: float = PET_STATUS_LINGER_S) -> None:
"""Fade the thinking line out after ``linger_s`` seconds (at once when 0). Thread-safe."""
if self._style != "pet":
return
try:
linger = max(0.0, float(linger_s))
except (TypeError, ValueError):
linger = PET_STATUS_LINGER_S
def _apply() -> None:
if self._thought is not None:
self._thought.clear(linger)
self._enqueue_ui(_apply)
def set_muted(self, muted: bool) -> None:
"""Mirror Jarvis's microphone mute on the strip. Thread-safe."""
self._mic_muted = bool(muted)
self._note_activity()
self._enqueue_ui(self._sync_strip_flags)
def set_speaker_muted(self, muted: bool) -> None:
"""Mirror the assistant-voice mute on the speaker control. Thread-safe."""
self._speaker_muted = bool(muted)
self._note_activity()
self._enqueue_ui(self._sync_strip_flags)
def set_visible(self, visible: bool) -> None:
"""Hide or show the whole pet (shortcut, settings). Runtime only. Thread-safe."""
self._user_hidden = not bool(visible)
self._note_activity()
self._enqueue_ui(self._apply_user_visibility)
self._notify_visibility_changed()
def set_on_visibility_changed(self, callback: Callable[[bool], None] | None) -> None:
"""Report pet dismissal to the companion host's parent process."""
self._on_visibility_changed = callback
def _notify_visibility_changed(self) -> None:
callback = self._on_visibility_changed
if self._style != "pet" or callback is None:
return
try:
callback(not self._user_hidden)
except Exception: # noqa: BLE001 — observers must not break the Tk loop
logging.getLogger("jarvis.orb").debug("pet visibility callback failed", exc_info=True)
def toggle_visible(self) -> None:
"""The pet shortcut: hide the pet, or show it and bring it to the front."""
self._note_activity()
self._enqueue_ui(self._toggle_visible_now)
def _pet_hidden_by_user(self) -> bool:
return self._style == "pet" and self._user_hidden
def _note_activity(self) -> None:
"""Every call from Jarvis keeps the pet awake (docs/pets.md "States")."""
if self._style != "pet":
return
self._enqueue_ui(self._apply_activity)
def _apply_activity(self) -> None:
renderer = self._renderer
if not isinstance(renderer, PetRenderer):
return
before = renderer.state()
renderer.on_activity()
if renderer.state() != before:
self._kick_frame()
def _figure_id(self) -> str:
"""The pet on screen: the mascot's own, or the one chosen under My Pets."""
return MASCOT_PET_ID if self._mascot_figure else self._pet_id
def _custom_mascot_image(self) -> bool:
"""True when a mascot image was configured: that picture is shown as it is."""
return bool(self._mascot_path_hint or os.environ.get("JARVIS_ORB_MASCOT_PATH"))
def _adopt_style(self, style: str) -> str:
"""Record what ``style`` shows and return the look that draws it.
The mascot is the built-in ``MASCOT_PET_ID`` pet, so it is drawn by the
pet look. Only a configured mascot image keeps the still picture.
"""
self._mascot_figure = style == "mascot" and not self._custom_mascot_image()
return "pet" if self._mascot_figure else style
def _apply_pet(self) -> None:
renderer = self._renderer
if self._style != "pet" or not isinstance(renderer, PetRenderer):
return
renderer.load(self._figure_id())
self._refit_pet_window()
# "None" keeps its strip up; a figure lets it rest hidden again.
self._sync_controls_visibility()
def _apply_pet_look(self) -> None:
self._pet_look_queued = False
if self._style != "pet":
return
if not self._pet_bubble and self._thought is not None:
self._thought.hide()
renderer = self._renderer
if isinstance(renderer, PetRenderer):
renderer.set_look(pet_scale=self._pet_scale)
self._refit_pet_window()
self._sync_pet_strip_scale()
self._sync_controls_visibility() # the always-on switch may have flipped
def _apply_outcome(self, kind: str) -> None:
renderer = self._renderer
if not isinstance(renderer, PetRenderer):
return
renderer.on_outcome(kind)
self._kick_frame()
def _refit_pet_window(self) -> None:
"""Resize to the pet's new size, keeping its feet where they stood.
The bottom centre stays fixed, so the strip under the figure does not
jump when the user picks another pet or another size.
"""
old_w, old_h = self._win_w, self._win_h
new_w, new_h = window_size_for_style("pet", self._renderer)
self._reset_frame_cache()
if (new_w, new_h) != (old_w, old_h):
self._mascot_x = self._mascot_x + old_w // 2 - new_w // 2
self._mascot_y = self._mascot_y + old_h - new_h
self._win_w, self._win_h = new_w, new_h
self._resize_window()
self._kick_frame()
def _sync_strip_flags(self) -> None:
row = self._controls
if isinstance(row, PetControlStrip):
row.set_state(mic_muted=self._mic_muted, speaker_muted=self._speaker_muted)
elif row is not None:
row.set_state(speaker_muted=self._speaker_muted)
def _apply_status(self, line: str) -> None:
if not self._pet_bubble:
return
# No bubble over an empty desktop: it belongs to the pet.
thought = self._thought_bubble()
if thought is not None:
thought.set_text(line)
def _status_anchor(self, *, refresh_limit: bool = True) -> tuple[int, int, int, int]:
"""``(center_x, below_y, above_y, limit_bottom)`` for the status card."""
ratio = self._pet_strip_scale()
bubble_gap = max(1, int(round(PET_BUBBLE_GAP * ratio)))
center_x = self._mascot_x + self._win_w // 2
below_y = self._mascot_y + self._win_h + self._pet_below_height() + bubble_gap
above_y = self._mascot_y - bubble_gap
return (center_x, below_y, above_y, self._work_area_bottom(refresh=refresh_limit))
def _work_area_bottom(self, *, refresh: bool = True) -> int:
"""Bottom edge of the work area under the pet (cached between moves)."""
center = (self._mascot_x + self._win_w // 2, self._mascot_y + self._win_h // 2)
cached = self._work_area_cache
if cached is not None and (not refresh or cached[0] == center):
return cached[1]
bottom: int | None = None
try:
from dodaios.platform.monitors import work_area_at # noqa: PLC0415
area = work_area_at(*center)
if area:
bottom = int(area[1]) + int(area[3])
except Exception: # noqa: BLE001 — placement falls back to the screen edge
logging.getLogger("jarvis.orb").debug("work area lookup failed", exc_info=True)
if bottom is None:
try:
bottom = int(self._root.winfo_screenheight()) if self._root else 1080
except tk.TclError:
bottom = 1080
self._work_area_cache = (center, bottom)
return bottom
def _apply_user_visibility(self) -> None:
if self._style != "pet":
return
if self._user_hidden:
self._show_until_t = 0.0
self._cancel_pending_hide()
self._actually_hide()
return
self._reveal_pet(raise_to_front=False)
def _toggle_visible_now(self) -> None:
if self._style != "pet":
return
if not self._user_hidden and self._window_mapped():
self._user_hidden = True
self._apply_user_visibility()
self._notify_visibility_changed()
return
self._user_hidden = False
self._reveal_pet(raise_to_front=True)
self._notify_visibility_changed()
def _reveal_pet(self, *, raise_to_front: bool) -> None:
"""Map the pet window, its strip, and restart the frame loop."""
root = self._root
if root is None:
return
self._cancel_pending_hide()
try:
root.deiconify()
if self._mac_transparent:
apply_macos_clear_backing()
root.lift()
except tk.TclError:
logging.getLogger("jarvis.orb").debug("pet reveal failed", exc_info=True)
return
self._sync_controls_visibility()
if raise_to_front:
# Focus-safe: SetWindowPos with SWP_NOACTIVATE, never a focus grab.
self._reassert_topmost(force=True)
self._ensure_frame_loop()
def start_mouth_animation(self, duration_ms: int = 60000) -> None:
"""Run the mascot's open/close mouth animation for `duration_ms`."""
def _start() -> None:
renderer = self._renderer
if renderer is not None and hasattr(renderer, "start_mouth_anim"):
t_now = time.perf_counter() - self._t0
renderer.start_mouth_anim(duration_ms / 1000.0, t_now)
self._enqueue_ui(_start)
def stop_mouth_animation(self) -> None:
"""Immediately stop the mouth animation. Thread-safe."""
def _stop() -> None:
renderer = self._renderer
if renderer is not None and hasattr(renderer, "stop_mouth_anim"):
renderer.stop_mouth_anim()
self._enqueue_ui(_stop)
def set_mode(self, mode: str) -> None:
"""Repaint the mascot in ``mode`` without touching visibility.
Validated synchronously for the same reason as :meth:`show` — see there.
"""
if mode not in MODES:
raise ValueError(f"Unknown mode: {mode!r} (allowed: {', '.join(MODES)})")
self._enqueue_ui(lambda: self._set_mode(mode))
def set_level(self, level: float) -> None:
# Two plain attribute writes from the audio threads (atomic under the
# GIL); the Tk thread reads them on its next frame tick. The stamp
# lets the pet tell a live voice from a level that stopped arriving.
self._ext_level = max(0.0, min(1.0, float(level)))
self._ext_level_at = time.monotonic()
# --- Animation API ------------------------------------------------
def play_animation(self, name: str, **params) -> None:
"""Starts a named animation (e.g. 'wave', 'salute', 'think').
Thread-safe: queued via ``root.after(0, ...)`` onto the Tk mainloop.
The pet handles the activation wave as a short listening nod.
Stacking behavior: several animations can run at the same time.
Calling play_animation('wave') again while a 'wave' is still active
adds a second instance — this is intentional (multiple waves).
To "replace" it, call stop_animation('wave') first.
"""
if isinstance(self._renderer, PetRenderer):
if name == "wave":
def _greet() -> None:
if isinstance(self._renderer, PetRenderer):
self._renderer.greet()
self._kick_frame()
self._enqueue_ui(_greet)
return
if not isinstance(self._renderer, MascotRenderer):
return
if name not in ANIMATION_REGISTRY:
import logging
logging.getLogger("jarvis.orb").warning(
"play_animation(%r) unknown — available: %s",
name,
sorted(ANIMATION_REGISTRY),
)
return
renderer = self._renderer
def _start() -> None:
t_now = time.perf_counter() - self._t0
try:
anim = make_animation(name, t_start=t_now, **params)
renderer.add_animation(anim)
except Exception:
import logging
logging.getLogger("jarvis.orb").exception(
"play_animation(%r) failed",
name,
)
self._enqueue_ui(_start)
def stop_animation(self, name: str) -> None:
"""Stops all running instances of an animation (e.g. 'think').
No-op if no instance exists or the renderer isn't the mascot.
Important for endlessly-looping animations like 'think', 'sleep'.
"""
if not isinstance(self._renderer, MascotRenderer):
return
renderer = self._renderer
self._enqueue_ui(lambda: renderer.stop_animation(name))
def clear_animations(self) -> None:
"""Ends all active animations immediately."""
if not isinstance(self._renderer, MascotRenderer):
return
renderer = self._renderer
self._enqueue_ui(renderer.clear_animations)
def active_animations(self) -> list[str]:
"""Snapshot of the currently running animation names.
NOT thread-safe (read without a lock); intended for tests/debugging only.
"""
if not isinstance(self._renderer, MascotRenderer):
return []
return self._renderer.active_animation_names()
def set_style(self, style: str) -> None:
"""Switches the renderer at runtime (see :data:`ORB_STYLES`).
Thread-safe — queued via root.after. If ``"mascot"`` is requested but
the PNG is not found, the current renderer stays unchanged
(the caller learns about it via the logger warning entry).
"""
style = _coerce_style(style)
if self._root is None:
# Not started yet → remember the style, start() picks it up
self._style = self._adopt_style(style)
return
self._enqueue_ui(lambda: self._apply_style(style))
def _apply_style(self, style: str) -> None:
was_mascot_figure = self._mascot_figure
style = self._adopt_style(style)
if style == "pet":
# The pet is the other way round: its size comes FROM its renderer.
new_renderer = self._build_renderer(style)
if new_renderer is None:
self._mascot_figure = was_mascot_figure
return # already logged in _build_renderer
new_size = window_size_for_style(style, new_renderer)
else:
# Size first: _build_renderer paints at the window's edge length, so
# a renderer built before the resize would be drawn at the old scale.
new_size = window_size_for_style(style)
old_size = (self._win_w, self._win_h)
self._win_w, self._win_h = new_size
new_renderer = self._build_renderer(style)
if new_renderer is None:
# Undo the resize — the old renderer is still the one painting.
self._win_w, self._win_h = old_size
self._mascot_figure = was_mascot_figure
return # The fallback case was already logged in _build_renderer
self._renderer = new_renderer
self._style = style
self._win_w, self._win_h = new_size
self._reset_frame_cache()
self._resize_window()
# The bubble's look and the control row both belong to the style, so a
# live swap has to carry them across or the new sphere inherits the
# ghost's yellow bubble (and vice versa).
if self._comment_bubble is not None:
self._comment_bubble.set_theme(bubble_theme_for_style(style))
if style != "pet" and self._notices is not None:
# Notifications are the pet's; the other looks have no bell.
self._notices.hide()
if style != "pet" and self._thought is not None:
self._thought.hide()
self._ensure_controls()
self._sync_controls_visibility()
self._kick_frame()
def _resize_window(self) -> None:
"""Re-fit root, canvas and the attached surfaces after a style or size swap."""
if self._root is None:
return
try:
self._root.geometry(f"{self._win_w}x{self._win_h}+{self._mascot_x}+{self._mascot_y}")
if self._canvas is not None:
self._canvas.configure(width=self._win_w, height=self._win_h)
except tk.TclError:
logging.getLogger("jarvis.orb").debug("orb resize failed", exc_info=True)
return
try:
screen_w = self._root.winfo_screenwidth()
except tk.TclError:
screen_w = self._win_w
if self._comment_bubble is not None:
self._comment_bubble.set_orb_width(self._win_w)
if self._controls is not None:
self._controls.set_orb_size(self._win_w, self._win_h)
self._move_attached(self._mascot_x, self._mascot_y, screen_w)
def _build_renderer(self, style: str) -> MascotRenderer | VoiceOrbRenderer | PetRenderer | None:
if style == "pet":
try:
renderer = PetRenderer(
self._figure_id(),
pet_scale=self._pet_scale,
dpi_ratio=self._dpi_ratio,
color_key=(int(COLOR_KEY_RGB[0]), int(COLOR_KEY_RGB[1]), int(COLOR_KEY_RGB[2])),
)
# A fresh state machine starts where the conversation is.
renderer.on_mode(self._mode)
return renderer
except Exception as exc: # noqa: BLE001
logging.getLogger("jarvis.orb").warning(
"PetRenderer init failed (%s); overlay will stay hidden.", exc
)
return None
if style == "voice_orb":
try:
return VoiceOrbRenderer(
size=self._win_w,
color_key=(int(COLOR_KEY_RGB[0]), int(COLOR_KEY_RGB[1]), int(COLOR_KEY_RGB[2])),
)
except Exception as exc: # noqa: BLE001
import logging
logging.getLogger("jarvis.orb").warning(
"VoiceOrbRenderer init failed (%s); overlay will stay hidden.",
exc,
)
return None
if style == "mascot":
mascot_path = _resolve_mascot_path(self._mascot_path_hint)
if mascot_path is None:
import logging
logging.getLogger("jarvis.orb").warning(
"Mascot style requested but PNG not found "
"(looked in: %s, ENV JARVIS_ORB_MASCOT_PATH, %s) — "
"overlay will stay hidden.",
self._mascot_path_hint,
DEFAULT_MASCOT_REL,
)
return None
try:
return MascotRenderer(mascot_path)
except Exception as exc: # noqa: BLE001
import logging
logging.getLogger("jarvis.orb").warning(
"MascotRenderer init failed (%s); overlay will stay hidden.",
exc,
)
return None
return None
# --- Internal --------------------------------------------------------
def _set_mode(self, mode: str) -> None:
"""Apply ``mode`` on the Tk thread. The public entry points already
validated it; this stays a guard for the internal call sites."""
if mode not in MODES:
raise ValueError(f"Unknown mode: {mode!r} (allowed: {', '.join(MODES)})")
changed = mode != self._mode
self._connect_timeline.note_mode(self._mode, mode, time.monotonic())
self._mode = mode
renderer = getattr(self, "_renderer", None)
if isinstance(renderer, PetRenderer):
renderer.on_mode(mode)
self._kick_frame()
if changed:
self._sync_controls_visibility()
def _enqueue_ui(self, fn) -> None:
"""Queue UI work for the Tk thread.
Direct ``root.after`` calls from the backend asyncio thread are
unreliable on Windows and can raise ``RuntimeError: main thread is not
in main loop``. The Tk event loop drains this queue itself.
"""
if self._root is None:
return
if self._tk_thread_id == threading.get_ident():
fn()
return
self._ui_queue.put(fn)
def _schedule_ui_queue(self) -> None:
if not self._running or self._root is None:
return
while True:
try:
fn = self._ui_queue.get_nowait()
except queue.Empty:
break
try:
fn()
except Exception:
import logging
logging.getLogger("jarvis.orb").exception("Orb UI command failed")
self._root.after(20, self._schedule_ui_queue)
# --- Thread lifecycle for integration into async/asyncio worlds -----
def start_in_thread(self, auto_demo: bool = False, timeout: float = 3.0) -> None:
"""Starts the Tk mainloop on a daemon thread and returns.
On Windows, Tk is stable on a background thread as long as all
UI mutations are queued via `root.after(0, fn)` — our
show/hide/set_mode/set_level methods already do this.
On macOS this is a logged no-op: Aqua-Tk (like AppKit) is
main-thread-only, and a Tk root on a worker thread aborts the whole
process natively (BUG-057, same class as the BUG-056 tray).
Blocks until the window actually exists (self._started event),
so the caller can safely call show()/hide() afterward without
running into a None root.
"""
import logging
_log = logging.getLogger("jarvis.orb")
if sys.platform == "darwin":
_log.info(
"Orb overlay not started: macOS allows Tk windows on the "
"main thread only — running without the on-screen orb."
)
return
def _run():
try:
self.start(auto_demo=auto_demo)
except Exception as exc:
# pythonw.exe has no stdout → print goes nowhere. The logger
# writes to the watchdog log and makes silent deaths visible.
_log.exception("Orb thread start failed: %s", exc)
t = threading.Thread(target=_run, name="orb-tk-mainloop", daemon=True)
t.start()
ok = self._started.wait(timeout=timeout)
if not ok:
_log.error(
"Orb window not initialized within %.1fs — UI will not pop up.",
timeout,
)
else:
_log.info("Orb overlay Tk mainloop is running (window initialized).")
def _schedule_frame(self) -> None:
"""One frame tick. Re-arms itself; ONE pending tick exists at most.
Two rules on top of painting. A withdrawn window gets no ticks at all
(nothing is on screen to animate); every path that maps the window
restarts the loop through :meth:`_ensure_frame_loop`. And one failing
frame never ends the animation: the re-arm sits in a ``finally``.
"""
self._frame_after_id = None
if not self._running or not self._root or not self._canvas or not self._renderer:
return
if not self._window_mapped():
return
delay_ms = FRAME_INTERVAL_MS
try:
delay_ms = self._paint_frame()
except Exception: # noqa: BLE001 — logged once; the loop must survive a bad frame
if not getattr(self, "_frame_error_logged", False):
self._frame_error_logged = True
logging.getLogger("jarvis.orb").exception("orb frame failed; animation continues")
finally:
self._arm_frame(delay_ms)
def _paint_frame(self) -> int:
"""Paint the frame due now. Returns the delay until the next tick, in ms."""
renderer = self._renderer
t = time.perf_counter() - self._t0
frame_key_fn = getattr(renderer, "frame_key", None)
if callable(frame_key_fn):
feed_level = getattr(renderer, "feed_level", None)
if callable(feed_level):
feed_level(self._ext_level, self._ext_level_at)
return self._paint_keyed_frame(renderer, t, frame_key_fn(t))
img = renderer.render(t, self._mode, self._ext_level)
if self._mac_transparent:
# macOS has no color key — the frame carries a real alpha
# channel instead (magenta → fully transparent).
img = key_to_alpha(img)
# The PhotoImage must be kept as self._photo — otherwise Tkinter
# garbage-collects the image before it gets rendered. It must also be
# created in this root's Tcl interpreter: the macOS companion process
# keeps a separate bootstrap Tk root alive to initialize NSApp, so an
# unqualified PhotoImage lands in that other interpreter and the mascot
# canvas reports ``image \"pyimageN\" does not exist``.
self._photo = ImageTk.PhotoImage(img, master=self._root)
self._show_photo(self._photo)
return FRAME_INTERVAL_MS # ~60 FPS
def _paint_keyed_frame(self, renderer: Any, t: float, key: Hashable) -> int:
"""The pet's path: repaint only when the frame changes, sleep until it does."""
if key != self._frame_key or self._image_id is None:
cache = self._photo_cache
photo = cache.get(key)
if photo is None:
img = renderer.render(t, self._mode, self._ext_level)
if self._mac_transparent:
img = key_to_alpha(img)
photo = ImageTk.PhotoImage(img, master=self._root)
cache[key] = photo
while len(cache) > PET_PHOTO_CACHE_MAX:
cache.popitem(last=False)
else:
cache.move_to_end(key)
self._photo = photo
self._show_photo(photo)
self._frame_key = key
delay_ms = int(renderer.next_frame_delay_ms(t))
if self._pump_strip_level():
row = self._controls
connecting = isinstance(row, PetControlStrip) and row.state.motion in (
"connect",
"connected",
)
pulse_ms = PET_CONNECT_INTERVAL_MS if connecting else PET_PULSE_INTERVAL_MS
delay_ms = min(delay_ms, pulse_ms)
return delay_ms
def _show_photo(self, photo: Any) -> None:
if self._image_id is None:
self._image_id = self._canvas.create_image(0, 0, anchor="nw", image=photo)
else:
self._canvas.itemconfig(self._image_id, image=photo)
def _pump_strip_level(self) -> bool:
"""Drive the strip's three strokes. True while they move.
Listening or talking: the strokes follow the live audio level.
Thinking: a highlight travels across them. Connecting: the loading
strokes bend into a spinning loop, then straighten once connected. At
rest they stand still and the strip is not repainted at all.
"""
row = self._controls
if not isinstance(row, PetControlStrip):
return False
now = time.monotonic()
look = self._connect_timeline.look(self._mode, now)
phase = spin = 0
if look is not None:
# Connecting: the strokes bend into the loading loop; connected:
# the one-shot back out of it.
motion, phase, spin = look.motion, look.phase, look.spin
elif self._mode in PET_VOICE_MODES:
motion = "voice"
elif self._mode in PET_THINK_MODES:
motion = "think"
else:
motion = "rest"
fresh = now - self._ext_level_at <= PET_LEVEL_FRESH_S
metered = motion in ("voice", "connect")
level = orb_controls.quantize_level(self._ext_level) if metered and fresh else 0
if look is None:
phase = orb_controls.indicator_phase(motion, now)
row.set_state(level=level, motion=motion, phase=phase, spin=spin)
return motion != "rest"
def _arm_frame(self, delay_ms: int) -> None:
root = self._root
if root is None or not self._running:
return
try:
self._frame_after_id = root.after(max(1, int(delay_ms)), self._schedule_frame)
except (tk.TclError, RuntimeError):
logging.getLogger("jarvis.orb").debug("orb frame re-arm failed", exc_info=True)
def _kick_frame(self) -> None:
"""Repaint right away (a state change), replacing the pending tick."""
root = self._root
if root is None or not self._running:
return
pending = self._frame_after_id
self._frame_after_id = None
if pending is not None:
try:
root.after_cancel(pending)
except tk.TclError:
logging.getLogger("jarvis.orb").debug("frame tick cancel failed", exc_info=True)
self._arm_frame(1)
def _ensure_frame_loop(self) -> None:
"""Restart the frame loop after the window was mapped again."""
if self._frame_after_id is None:
self._kick_frame()
def _reset_frame_cache(self) -> None:
self._photo_cache.clear()
self._frame_key = None
def _window_mapped(self) -> bool:
"""Is the orb window mapped (not withdrawn)? Test doubles count as mapped."""
root = self._root
if root is None:
return False
try:
return str(root.state()) != "withdrawn"
except (tk.TclError, AttributeError):
return True
def _run_demo(self) -> None:
self._started.wait(timeout=5.0)
time.sleep(0.5)
self.show(mode="listen")
time.sleep(8.0)
self.set_mode("speak")
time.sleep(5.0)
self.hide()
time.sleep(1.5)
self.show(mode="listen")
time.sleep(4.0)
self.hide()
def main() -> int:
parser = argparse.ArgumentParser(description="Dodaios-Orb Overlay")
parser.add_argument(
"--sticky",
action="store_true",
help="Window permanently visible (design preview)",
)
parser.add_argument(
"--mic",
action="store_true",
help="Mic-reactive: pulses with microphone volume + shockwave rings",
)
parser.add_argument(
"--mascot",
action="store_true",
help="Uses the SWG/Gigi mascot.",
)
parser.add_argument(
"--voice-orb",
action="store_true",
help="Uses the procedural voice orb (the desktop twin of the in-app orb).",
)
parser.add_argument(
"--mascot-path",
type=str,
default=None,
help=(
"Optional: explicit path to a mascot PNG (otherwise assets/icons/dodaios-gigi-256.png)."
),
)
parser.add_argument(
"--animation",
type=str,
default=None,
help=(
"Visual QA: plays a specific animation in an endless loop "
"(implies --mascot --sticky). Available: " + ", ".join(sorted(ANIMATION_REGISTRY))
),
)
parser.add_argument(
"--all-animations",
action="store_true",
help="Plays all animations one after another (implies --mascot --sticky).",
)
args = parser.parse_args()
if args.animation and args.animation not in ANIMATION_REGISTRY:
print(
f"[orb] Unknown animation {args.animation!r}. "
f"Available: {', '.join(sorted(ANIMATION_REGISTRY))}"
)
return 2
use_mascot = args.mascot or bool(args.animation) or args.all_animations
sticky = args.sticky or args.mic or bool(args.animation) or args.all_animations
style = "voice_orb" if args.voice_orb and not use_mascot else "mascot"
overlay = OrbOverlay(
sticky=sticky,
mic_reactive=args.mic,
style=style,
mascot_path=args.mascot_path,
)
# Demo threads depending on the CLI argument
auto_demo = False
if args.animation:
# Re-loops the requested animation every 2.5s — for visual QA
def _loop_anim() -> None:
overlay._started.wait(timeout=5.0)
overlay.show(mode="listen")
while True:
overlay.play_animation(args.animation)
# Sleep as long as the animation takes + a 0.6s pause; looping
# animations (duration=0) we re-loop every 4s (re-trigger).
cls = ANIMATION_REGISTRY[args.animation]
wait = cls.duration if cls.duration > 0 else 4.0
time.sleep(wait + 0.6)
if cls.duration <= 0:
overlay.stop_animation(args.animation)
threading.Thread(target=_loop_anim, daemon=True).start()
elif args.all_animations:
def _all_demo() -> None:
overlay._started.wait(timeout=5.0)
overlay.show(mode="listen")
time.sleep(0.5)
for name, cls in ANIMATION_REGISTRY.items():
print(f"[orb] >>> {name}")
overlay.play_animation(name)
wait = cls.duration if cls.duration > 0 else 3.0
time.sleep(wait + 0.5)
if cls.duration <= 0:
overlay.stop_animation(name)
time.sleep(0.3)
threading.Thread(target=_all_demo, daemon=True).start()
else:
# Classic demo (shows the listen/speak switch) when nothing is specified.
# No auto_demo with --mic (otherwise the demo script would hide the
# orb exactly while the user is speaking into the mic).
auto_demo = not (args.sticky or args.mic)
overlay.start(auto_demo=auto_demo)
return 0
if __name__ == "__main__":
sys.exit(main())