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
"""The desktop pet's card column: what Jarvis finished.
Under the control strip hangs one quiet column of done cards (the look is
:mod:`ui.orb.pet_cards`; what Jarvis is thinking shows in the thought bubble
above the pet, :mod:`ui.orb.thought_bubble`). A card appears when a Jarvis
turn, or a task Jarvis started, finished: a check, what was asked, the start
of the answer. Several stack: the newest in front, up to two older ones
peeking out behind it, smaller and fainter. Hovering fans them into a column;
a click sends one away; each leaves on its own after a while, never while the
pointer rests on them.
Split like :mod:`ui.orb.controls`: a pure model and geometry
(:class:`NoticeModel`, :func:`column_layout`, :class:`Spring`), and one Tk
window (:class:`PetNoticeStack`) that composites the cards into a single
frame while something moves and leaves the screen alone while nothing does
(:class:`ui.orb.layered_surface.AlphaWindow`: real per-pixel alpha on Windows,
a colour key elsewhere).
"""
from __future__ import annotations
import logging
import time
import tkinter as tk
from dataclasses import dataclass, field
from itertools import count
from typing import Any
from PIL import Image
from ui.orb import pet_cards
from ui.orb.layered_surface import AlphaWindow
log = logging.getLogger("jarvis.orb")
#: Card kinds the stack keeps.
NOTICE_KINDS: tuple[str, ...] = ("done", "error")
#: Seconds a card stays before it leaves on its own.
NOTICE_TTL_S: dict[str, float] = {"done": 9.0, "error": 14.0}
#: Cards kept at most; a newer one pushes the oldest out.
NOTICE_KEEP = 3
#: Cards visible behind the front one while the stack is folded.
NOTICE_PEEK = 2
#: The same card again within this window refreshes instead of stacking.
NOTICE_DEDUPE_S = 3.0
#: Unscaled geometry: the gap between cards, how far a folded card peeks out
#: and how much smaller and fainter each one behind is.
CARD_GAP = 8
PEEK_OFFSET = 10
PEEK_SHRINK = 0.05
PEEK_FADE = 0.25
SPRING_STIFFNESS = 320.0
SPRING_DAMPING = 30.0
FRAME_MS = 16
EXPIRY_POLL_MS = 400
COLLAPSE_GRACE_MS = 280
#: How far a card drifts while it fades in or out.
DRIFT_PX = 10
# --- model -------------------------------------------------------------------
@dataclass
class Notice:
id: int
kind: str
title: str
detail: str
created: float
expires: float
@dataclass
class NoticeModel:
"""The done cards, newest first. Pure: the clock is passed in."""
keep: int = NOTICE_KEEP
items: list[Notice] = field(default_factory=list)
_ids: Any = field(default_factory=lambda: count(1))
def push(self, kind: str, title: str, detail: str, now: float) -> tuple[Notice, list[Notice]]:
"""Add a card; returns it and the cards it pushed out of the stack."""
kind = kind if kind in NOTICE_KINDS else "done"
ttl = NOTICE_TTL_S[kind]
for item in self.items:
if (item.kind, item.title, item.detail) == (kind, title, detail) and (
now - item.created < NOTICE_DEDUPE_S
):
item.expires = now + ttl
return item, []
notice = Notice(next(self._ids), kind, title, detail, now, now + ttl)
self.items.insert(0, notice)
dropped = self.items[self.keep :]
del self.items[self.keep :]
return notice, dropped
def dismiss(self, notice_id: int) -> Notice | None:
for index, item in enumerate(self.items):
if item.id == notice_id:
return self.items.pop(index)
return None
def expire(self, now: float) -> list[Notice]:
gone = [item for item in self.items if item.expires <= now]
if gone:
self.items = [item for item in self.items if item.expires > now]
return gone
def pause(self, seconds: float) -> None:
"""Push every deadline back (the pointer rested on the stack)."""
if seconds > 0:
for item in self.items:
item.expires += seconds
def clear(self) -> list[Notice]:
gone, self.items = self.items, []
return gone
# --- geometry ----------------------------------------------------------------
@dataclass(frozen=True)
class Slot:
"""Where a card wants to be: its top edge, size factor and opacity."""
y: float
size: float
opacity: float
def column_layout(heights: list[int], *, expanded: bool, scale: float) -> list[Slot]:
"""Targets for the cards (newest first), top down.
Folded, every card lines up its bottom with the front card's bottom and
peeks out below it, a step smaller and fainter per place; cards past
``NOTICE_PEEK`` hide behind the last peeking one. Fanned out, they form a
column.
"""
gap = CARD_GAP * scale
cursor = 0.0
slots: list[Slot] = []
if expanded:
for h in heights:
slots.append(Slot(cursor, 1.0, 1.0))
cursor += h + gap
return slots
if not heights:
return slots
front_bottom = heights[0]
for index, h in enumerate(heights):
level = min(index, NOTICE_PEEK)
size = 1.0 - PEEK_SHRINK * level
opacity = (1.0 - PEEK_FADE * level) if index <= NOTICE_PEEK else 0.0
bottom = front_bottom + level * PEEK_OFFSET * scale
slots.append(Slot(bottom - h * size, size, opacity))
return slots
class Spring:
"""One damped spring value."""
__slots__ = ("target", "value", "velocity")
def __init__(self, value: float, target: float | None = None) -> None:
self.value = float(value)
self.velocity = 0.0
self.target = float(value if target is None else target)
def step(self, dt: float) -> None:
steps = max(1, int(dt / 0.008 + 0.999))
h = dt / steps
for _ in range(steps):
accel = SPRING_STIFFNESS * (self.target - self.value) - SPRING_DAMPING * self.velocity
self.velocity += accel * h
self.value += self.velocity * h
@property
def settled(self) -> bool:
reach = max(1.0, abs(self.target))
return abs(self.target - self.value) < 0.004 * reach and abs(self.velocity) < 0.04 * reach
def snap(self) -> None:
self.value = self.target
self.velocity = 0.0
# --- the window --------------------------------------------------------------
@dataclass
class _Item:
"""One card on screen: its content and its moving parts."""
key: int # the notice id
kind: str
title: str
detail: str
y: Spring
size: Spring
opacity: Spring
born: float
leaving: bool = False
#: Where the card was last drawn (x0, y0, x1, y1) for hit tests.
box: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0)
class PetNoticeStack:
"""The card column's own frameless window. Every method runs on the Tk thread."""
def __init__(
self, parent: tk.Misc, *, scale: float = 1.0, width: int = 360, art_px: int = 3
) -> None:
self._scale = max(0.25, float(scale))
self._art_px = max(1, int(art_px))
self._card_w = max(160, int(width))
self._model = NoticeModel()
self._items: dict[int, _Item] = {}
self._leaving: list[_Item] = []
self._expanded = False
self._hovered: int | None = None
self._pointer_inside = False
self._hover_since: float | None = None
self._upward = False
self._anchor: tuple[int, int, int, int, int] | None = None
self._frame_after: str | None = None
self._expiry_after: str | None = None
self._collapse_after: str | None = None
self._last_tick = 0.0
self._window = AlphaWindow(
parent, self.window_size, backdrop=pet_cards.FILL_SOLID, name="pet's cards"
)
self._window.bind("<Motion>", self._on_motion)
self._window.bind("<Enter>", self._on_motion)
self._window.bind("<Leave>", self._on_leave)
self._window.bind("<ButtonRelease-1>", self._on_click)
# -- geometry -------------------------------------------------------------
@property
def _pad(self) -> int:
return pet_cards.card_pad(self._art_px)
@property
def window_size(self) -> tuple[int, int]:
"""Room for every kept card fanned out (each as tall as a card gets)."""
tallest = pet_cards.render_card(
"done",
"x",
"word " * 80,
scale=round(self._scale, 3),
max_width=self._card_w,
art_px=self._art_px,
content=False,
)
tallest_card = tallest.height - 2 * self._pad
height = NOTICE_KEEP * (tallest_card + CARD_GAP * self._scale)
return tallest.width, int(height) + 2 * self._pad
# -- public ---------------------------------------------------------------
@property
def count(self) -> int:
"""Done cards on screen."""
return len(self._model.items)
@property
def window(self) -> tk.Toplevel | None:
"""The column's toplevel while it is on screen (for Z-order repair)."""
return self._window.top if self._window.shown else None
def set_scale(self, scale: float, width: int, art_px: int | None = None) -> None:
scale, width = max(0.25, float(scale)), max(160, int(width))
px = self._art_px if art_px is None else max(1, int(art_px))
if (scale, width, px) == (self._scale, self._card_w, self._art_px):
return
self._scale, self._card_w, self._art_px = scale, width, px
self._window.resize(self.window_size)
self._retarget(snap=True)
self._place()
self._kick()
def set_anchor(self, anchor: tuple[int, int, int, int, int]) -> None:
"""``(center_x, below_y, above_y, limit_bottom, screen_w)``.
The column hangs from ``below_y`` when it fits above ``limit_bottom``,
else it grows upward from ``above_y``.
"""
self._anchor = anchor
upward = anchor[1] + self.window_size[1] - 2 * self._pad > anchor[3]
if upward != self._upward:
self._upward = upward
self._retarget(snap=True)
self._kick()
self._place()
def push(self, kind: str, title: str, detail: str) -> None:
"""A done (or failed) card."""
title = " ".join(str(title or "").split())
detail = " ".join(str(detail or "").split())
if not title:
title, detail = detail, ""
if not title:
return
now = time.monotonic()
notice, dropped = self._model.push(kind, title, detail, now)
for gone in dropped:
self._send_off(gone.id)
item = self._items.get(notice.id)
if item is None:
self._items[notice.id] = _Item(
key=notice.id,
kind=notice.kind,
title=notice.title,
detail=notice.detail,
y=Spring(0.0),
size=Spring(0.96),
opacity=Spring(0.0),
born=now,
)
self._retarget(fresh=notice.id)
else:
item.born = now
self._retarget()
self._place()
self._window.show()
self._kick()
def clear(self) -> None:
"""Send every done card away (the bell was switched off)."""
for gone in self._model.clear():
self._send_off(gone.id)
self._expanded = False
self._retarget()
self._kick()
def hide(self) -> None:
"""Withdraw at once (the pet was hidden); everything is dropped."""
self._model.clear()
self._items.clear()
self._leaving.clear()
self._withdraw()
def destroy(self) -> None:
self._cancel_all()
self._window.destroy()
# -- motion ---------------------------------------------------------------
def _send_off(self, notice_id: int) -> None:
item = self._items.pop(notice_id, None)
if item is None:
return
item.leaving = True
item.opacity.target = 0.0
item.size.target = item.size.value * 0.95
self._leaving.append(item)
def _card_image(
self,
item: _Item,
*,
hovered: bool = False,
frame: int | None = None,
content: bool = True,
) -> Image.Image:
return pet_cards.render_card(
item.kind,
item.title,
item.detail,
scale=round(self._scale, 3),
max_width=self._card_w,
art_px=self._art_px,
hovered=hovered,
icon_frame=pet_cards.ICON_FRAMES if frame is None else frame,
content=content,
)
def _card_height(self, item: _Item) -> int:
return self._card_image(item).height - 2 * self._pad
def _cards(self) -> list[_Item]:
"""The done cards on screen, newest first."""
return [self._items[n.id] for n in self._model.items if n.id in self._items]
def _retarget(self, *, snap: bool = False, fresh: int | None = None) -> None:
cards = self._cards()
heights = [self._card_height(c) for c in cards]
slots = column_layout(heights, expanded=self._expanded, scale=self._scale)
inner_h = self.window_size[1] - 2 * self._pad
for item, slot, h in zip(cards, slots, heights, strict=False):
y = slot.y
if self._upward:
# Growing up from above the pet: mirror the column, newest
# nearest the pet.
y = inner_h - (slot.y + h * slot.size)
item.y.target = y
item.size.target = slot.size
item.opacity.target = slot.opacity
if item.key == fresh:
# A new card starts a little off its place and drifts in
# while it fades up.
drift = DRIFT_PX * self._scale
item.y.value = y + (drift if self._upward else -drift)
if snap:
for spring in (item.y, item.size, item.opacity):
spring.snap()
def _kick(self, delay: int = FRAME_MS) -> None:
top = self._window.top
if top is None or self._frame_after is not None:
return
self._cancel(("_expiry_after",))
self._last_tick = time.monotonic()
self._frame_after = top.after(delay, self._tick)
def _tick(self) -> None:
self._frame_after = None
top = self._window.top
if top is None:
return
now = time.monotonic()
dt = min(0.05, max(0.001, now - self._last_tick))
self._last_tick = now
moving = False
for item in [*self._cards(), *self._leaving]:
for spring in (item.y, item.size, item.opacity):
if spring.settled:
spring.snap()
else:
spring.step(dt)
moving = True
if now - item.born < 0.6:
moving = True # the check is still ticking itself
self._leaving = [i for i in self._leaving if i.opacity.value > 0.02]
self._paint(now)
if moving or self._leaving:
self._frame_after = top.after(FRAME_MS, self._tick)
return
if not self._items:
self._withdraw()
return
self._schedule_expiry()
def _schedule_expiry(self) -> None:
top = self._window.top
if top is None or self._expiry_after is not None or not self._items:
return
self._expiry_after = top.after(EXPIRY_POLL_MS, self._check_expiry)
def _check_expiry(self) -> None:
self._expiry_after = None
if self._window.top is None:
return
now = time.monotonic()
if self._pointer_inside:
# Reading is not idling: the clocks stand still under the pointer.
if self._hover_since is not None:
self._model.pause(now - self._hover_since)
self._hover_since = now
gone = self._model.expire(now)
for notice in gone:
self._send_off(notice.id)
if gone:
if not self._model.items:
self._expanded = False
self._retarget()
self._kick()
return
self._schedule_expiry()
# -- painting -------------------------------------------------------------
def _paint(self, now: float) -> None:
frame = self._window.blank()
pad = self._pad
width = frame.width
# Back to front: the deepest card first, leaving cards on top.
for item in [*reversed(self._cards()), *self._leaving]:
opacity = max(0.0, min(1.0, item.opacity.value))
if opacity <= 0.01:
item.box = (0.0, 0.0, 0.0, 0.0)
continue
ticked = int((now - item.born) / 0.5 * pet_cards.ICON_FRAMES)
image = self._card_image(
item,
hovered=item.key == self._hovered and not item.leaving,
frame=min(pet_cards.ICON_FRAMES, ticked),
# Behind the front card: its edge only, no text showing
# through the see-through card in front.
content=item.size.value > 0.985 or item.leaving,
)
size = max(0.5, item.size.value)
if abs(size - 1.0) > 0.004:
image = image.resize(
(max(1, int(image.width * size)), max(1, int(image.height * size))),
Image.Resampling.NEAREST, # pixel art stays crisp
)
if opacity < 0.995:
image = image.copy()
image.putalpha(image.getchannel("A").point(lambda v, o=opacity: int(v * o)))
inset = pad * size
x = (width - image.width) // 2
y = int(round(item.y.value + pad - inset))
frame.alpha_composite(image, (max(0, x), max(0, y)))
item.box = (x + inset, y + inset, x + image.width - inset, y + image.height - inset)
self._window.present(frame)
# -- pointer --------------------------------------------------------------
def _card_at(self, x: float, y: float) -> int | None:
for item in self._cards(): # front-most first
x0, y0, x1, y1 = item.box
if x0 <= x <= x1 and y0 <= y <= y1 and item.opacity.value > 0.5:
return item.key
return None
def _on_motion(self, event: tk.Event) -> None:
hit = self._card_at(event.x, event.y)
inside = hit is not None
if inside and not self._pointer_inside:
self._hover_since = time.monotonic()
self._pointer_inside = inside
if inside:
self._cancel(("_collapse_after",))
if not self._expanded and len(self._model.items) > 1:
self._expanded = True
self._retarget()
elif self._expanded:
self._schedule_collapse()
if hit != self._hovered:
self._hovered = hit
self._window.set_cursor("hand2" if hit is not None else "")
self._kick()
def _on_leave(self, _event: tk.Event) -> None:
if self._pointer_inside and self._hover_since is not None:
self._model.pause(time.monotonic() - self._hover_since)
self._pointer_inside = False
self._hover_since = None
self._hovered = None
self._schedule_collapse()
self._kick()
def _on_click(self, event: tk.Event) -> None:
hit = self._card_at(event.x, event.y)
if hit is None:
return
self._model.dismiss(hit)
self._send_off(hit)
self._hovered = None
if not self._model.items:
self._expanded = False
self._retarget()
self._kick()
def _schedule_collapse(self) -> None:
top = self._window.top
if top is None or self._collapse_after is not None or not self._expanded:
return
self._collapse_after = top.after(COLLAPSE_GRACE_MS, self._collapse_now)
def _collapse_now(self) -> None:
self._collapse_after = None
if not self._pointer_inside and self._expanded:
self._expanded = False
self._retarget()
self._kick()
# -- window ---------------------------------------------------------------
def _place(self) -> None:
if self._anchor is None:
return
center_x, below_y, above_y, _limit, screen_w = self._anchor
width, height = self.window_size
pad = self._pad
x = max(8 - pad, min(center_x - width // 2, screen_w - width + pad - 8))
y = above_y - height + pad if self._upward else below_y - pad
self._window.move(x, y)
def _withdraw(self) -> None:
self._cancel_all()
self._expanded = False
self._pointer_inside = False
self._hovered = None
self._window.withdraw()
def _cancel(self, names: tuple[str, ...]) -> None:
top = self._window.top
for attr in names:
after_id = getattr(self, attr)
if after_id is not None and top is not None:
try:
top.after_cancel(after_id)
except tk.TclError:
log.debug("card timer cancel failed", exc_info=True)
setattr(self, attr, None)
def _cancel_all(self) -> None:
self._cancel(("_frame_after", "_expiry_after", "_collapse_after"))
__all__ = [
"NOTICE_KINDS",
"Notice",
"NoticeModel",
"PetNoticeStack",
"Slot",
"Spring",
"column_layout",
]