usage-cli 0.29.32__py3-none-any.whl

menubar_title.py

@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+"""Menu bar title rendering."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from AppKit import NSAttributedString, NSFont, NSFontAttributeName, NSMutableAttributedString
+
+import critter_frames
+from menubar_chrome import (
+    _agy_menubar_icon,
+    _claude_menubar_icon,
+    _codex_menubar_icon,
+    _critter_frame_image,
+    _critter_icon_attachment_string,
+    _menubar_icon_attachment_string,
+)
+from menubar_state import PopoverState, _format_percent
+
+
+class _TitleApp(Protocol):
+    _menubar_text_cache: dict[str, Any]
+    critter_frame: int
+    dragon_frame: int
+    lion_frame: int
+    codex_5h_pct: float | None
+    _last_button_title_key: tuple[str, int | None, int | None, int | None] | None
+    _last_plain_title_key: tuple[str] | None
+    status_item: Any
+
+
+def _menubar_text_string(app: _TitleApp, text: str) -> Any:
+    cached = app._menubar_text_cache.get(text)
+    if cached is not None:
+        return cached
+    attributed = NSAttributedString.alloc().initWithString_attributes_(
+        text,
+        {NSFontAttributeName: NSFont.menuBarFontOfSize_(0)},
+    )
+    app._menubar_text_cache[text] = attributed
+    return attributed
+
+
+def _menubar_attributed_title(app: _TitleApp, state: PopoverState) -> Any:
+    title = NSMutableAttributedString.alloc().init()
+    phoenix_frame = int(app.critter_frame) % len(critter_frames.PHOENIX_FRAMES)
+    dragon_frame = int(app.dragon_frame) % len(critter_frames.DRAGON_FRAMES)
+    lion_frame = int(app.lion_frame) % len(critter_frames.LION_FRAMES)
+    if not state.hide_claude:
+        claude_percent = (
+            "--"
+            if state.claude_session.percent is None
+            else f"{_format_percent(state.claude_session.percent)}%"
+        )
+        title.appendAttributedString_(_menubar_icon_attachment_string(_claude_menubar_icon()))
+        title.appendAttributedString_(_menubar_text_string(app, f" {claude_percent}"))
+        phoenix_path = critter_frames.PHOENIX_FRAMES[phoenix_frame]
+        phoenix = _critter_frame_image(phoenix_path)
+        if phoenix is not None:
+            title.appendAttributedString_(_menubar_text_string(app, " "))
+            title.appendAttributedString_(
+                _critter_icon_attachment_string(phoenix_path, phoenix)
+            )
+    if not state.hide_codex and (app.codex_5h_pct is not None or state.hide_claude):
+        codex_percent = (
+            "--"
+            if app.codex_5h_pct is None
+            else f"{_format_percent(float(app.codex_5h_pct))}%"
+        )
+        if not state.hide_claude:
+            title.appendAttributedString_(_menubar_text_string(app, " · "))
+        title.appendAttributedString_(_menubar_icon_attachment_string(_codex_menubar_icon()))
+        title.appendAttributedString_(_menubar_text_string(app, f" {codex_percent}"))
+        dragon_path = critter_frames.DRAGON_FRAMES[dragon_frame]
+        dragon = _critter_frame_image(dragon_path)
+        if dragon is not None:
+            title.appendAttributedString_(_menubar_text_string(app, " "))
+            title.appendAttributedString_(
+                _critter_icon_attachment_string(dragon_path, dragon)
+            )
+    agy_session_percent = state.agy_session.percent
+    agy_visible = not state.hide_agy and agy_session_percent is not None
+    if agy_visible:
+        assert agy_session_percent is not None
+        agy_percent = f"{_format_percent(agy_session_percent)}%"
+        if title.length() > 0:
+            title.appendAttributedString_(_menubar_text_string(app, " · "))
+        title.appendAttributedString_(_menubar_icon_attachment_string(_agy_menubar_icon()))
+        title.appendAttributedString_(_menubar_text_string(app, f" {agy_percent}"))
+        lion_path = critter_frames.LION_FRAMES[lion_frame]
+        lion = _critter_frame_image(lion_path)
+        if lion is not None:
+            title.appendAttributedString_(_menubar_text_string(app, " "))
+            title.appendAttributedString_(
+                _critter_icon_attachment_string(lion_path, lion)
+            )
+    if title.length() == 0:
+        # Both providers hidden: keep a recognizable, clickable status item.
+        title.appendAttributedString_(_menubar_icon_attachment_string(_claude_menubar_icon()))
+    return title
+
+
+def _set_button_title(app: _TitleApp, state: PopoverState) -> None:
+    title = _compose_title(app, state)
+    phoenix_frame = int(app.critter_frame) if not state.hide_claude else None
+    dragon_visible = not state.hide_codex and (
+        app.codex_5h_pct is not None or state.hide_claude
+    )
+    dragon_frame = int(app.dragon_frame) if dragon_visible else None
+    lion_visible = not state.hide_agy and state.agy_session.percent is not None
+    lion_frame = int(app.lion_frame) if lion_visible else None
+    title_key = (title, phoenix_frame, dragon_frame, lion_frame)
+    if app._last_button_title_key == title_key:
+        return
+
+    button = app.status_item.button()
+    # setTitle: forces a full NSStatusItem relayout (_adjustLength) that
+    # cascades into the popover's frame/corner-mask recompute even while
+    # it's hidden. attributedTitle is what's actually rendered, so during
+    # critter/dragon/lion animation (their frame values changing every
+    # 0.10-0.18s) only push the plain title when its own text changed —
+    # not on every sprite frame — to avoid paying that relayout per frame.
+    plain_key = (title,)
+    if app._last_plain_title_key != plain_key:
+        button.setTitle_(title)
+        app._last_plain_title_key = plain_key
+    button.setAttributedTitle_(_menubar_attributed_title(app, state))
+    app._last_button_title_key = title_key
+
+
+def _compose_title(app: _TitleApp, state: PopoverState) -> str:
+    parts: list[str] = []
+    if not state.hide_claude:
+        claude = (
+            "--"
+            if state.claude_session.percent is None
+            else f"{_format_percent(state.claude_session.percent)}%"
+        )
+        parts.append(f"🐾 {claude}")
+    if not state.hide_codex and (app.codex_5h_pct is not None or state.hide_claude):
+        codex = (
+            "--"
+            if app.codex_5h_pct is None
+            else f"{_format_percent(float(app.codex_5h_pct))}%"
+        )
+        parts.append(f"📜 {codex}")
+    if not state.hide_agy and state.agy_session.percent is not None:
+        agy = f"{_format_percent(state.agy_session.percent)}%"
+        parts.append(f"🦁 {agy}")
+    # Both providers hidden: keep a recognizable, clickable status item.
+    return " · ".join(parts) if parts else "🐾"

menubar_update.py

@@ -0,0 +1,123 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+"""Background-safe release-check scheduling and update-cache maintenance."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Protocol
+
+import update_checker
+import update_gate
+import usage_diagnosis_snapshot
+from menubar_prefs import _auto_update_check_enabled
+from prefs import _load_preferences, _save_preferences
+
+logger = logging.getLogger(__name__)
+
+
+class _UpdateApp(Protocol):
+    def performSelectorOnMainThread_withObject_waitUntilDone_(
+        self, selector: str, obj: Any, wait: bool
+    ) -> None: ...
+
+    def _check_update_in_background(
+        self,
+        *,
+        manual: bool,
+        ignore_cooldown: bool,
+        ignore_skipped: bool,
+    ) -> None: ...
+
+
+def clear_stale_update_cache() -> None:
+    from menubar import _current_version
+
+    try:
+        current_version = _current_version()
+        prefs = _load_preferences()
+        updated_cache = update_gate.stale_cache_reset(prefs, current_version)
+        if updated_cache is not None:
+            prefs["last_update_check"] = updated_cache
+            _save_preferences(prefs)
+    except Exception:
+        pass
+
+
+def maybe_check_update_in_background(app: _UpdateApp) -> None:
+    usage_diagnosis_snapshot.maybe_schedule_refresh()
+    app._check_update_in_background(
+        manual=False,
+        ignore_cooldown=False,
+        ignore_skipped=False,
+    )
+
+
+def check_update_in_background(
+    app: _UpdateApp,
+    *,
+    manual: bool,
+    ignore_cooldown: bool,
+    ignore_skipped: bool,
+) -> None:
+    from menubar import _current_version
+
+    prefs = _load_preferences()
+    if not manual and not _auto_update_check_enabled(prefs):
+        return
+
+    if not manual and not update_gate.auto_check_is_due(prefs):
+        return
+
+    if not ignore_cooldown and update_gate.dismissed_recently(prefs):
+        return
+
+    try:
+        current_version = _current_version()
+        check_result = update_checker.check_latest_release_result(current_version)
+    except Exception:
+        if os.environ.get("USAGE_DEBUG") == "1":
+            logger.warning("update check failed", exc_info=True)
+        if manual:
+            app.performSelectorOnMainThread_withObject_waitUntilDone_(
+                "_showUpdateCheckFailed:",
+                None,
+                False,
+            )
+        return
+
+    if check_result.failed:
+        if manual:
+            app.performSelectorOnMainThread_withObject_waitUntilDone_(
+                "_showUpdateCheckFailed:",
+                None,
+                False,
+            )
+        return
+
+    release = check_result.release
+    prefs["last_update_check"] = update_gate.build_check_cache_entry(current_version, release)
+    _save_preferences(prefs)
+
+    if release is None:
+        if manual:
+            app.performSelectorOnMainThread_withObject_waitUntilDone_(
+                "_showNoUpdateAvailable:",
+                None,
+                False,
+            )
+        return
+
+    if not ignore_skipped and prefs.get("update_skipped_version") == release.version:
+        return
+
+    app.performSelectorOnMainThread_withObject_waitUntilDone_(
+        "_showUpdateAlert:",
+        release,
+        False,
+    )

panel_window.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+# mypy: disable-error-code="import-untyped,misc"
+from __future__ import annotations
+
+from typing import Any
+
+import objc
+from AppKit import (
+    NSBackingStoreBuffered,
+    NSColor,
+    NSFloatingWindowLevel,
+    NSMakePoint,
+    NSPanel,
+    NSWindowCollectionBehaviorCanJoinAllSpaces,
+    NSWindowCollectionBehaviorFullScreenAuxiliary,
+    NSWindowStyleMaskBorderless,
+    NSWindowStyleMaskNonactivatingPanel,
+)
+
+PANEL_CORNER_RADIUS = 12.0
+
+
+class PanelWindow(NSPanel):
+    def initWithContentRect_(self, content_rect: Any) -> PanelWindow:
+        style_mask = int(NSWindowStyleMaskBorderless) | int(
+            NSWindowStyleMaskNonactivatingPanel
+        )
+        self = objc.super(PanelWindow, self).initWithContentRect_styleMask_backing_defer_(
+            content_rect,
+            style_mask,
+            NSBackingStoreBuffered,
+            False,
+        )
+        if self is None:
+            return None
+        self.setOpaque_(False)
+        self.setBackgroundColor_(NSColor.clearColor())
+        self.setHasShadow_(True)
+        self.setLevel_(NSFloatingWindowLevel)
+        self.setMovableByWindowBackground_(True)
+        self.setHidesOnDeactivate_(False)
+        self.setReleasedWhenClosed_(False)
+        behavior = int(NSWindowCollectionBehaviorCanJoinAllSpaces) | int(
+            NSWindowCollectionBehaviorFullScreenAuxiliary
+        )
+        self.setCollectionBehavior_(behavior)
+        return self
+
+    def canBecomeKeyWindow(self) -> bool:
+        return True
+
+    def cancelOperation_(self, sender: Any) -> None:
+        self.close()
+
+    def setRoundedContentView_(self, view: Any) -> None:
+        view.setWantsLayer_(True)
+        layer = view.layer()
+        if layer is not None:
+            layer.setCornerRadius_(PANEL_CORNER_RADIUS)
+            layer.setMasksToBounds_(True)
+        self.setContentView_(view)
+
+    def setContentSizeKeepingTopLeft_(self, size: Any) -> None:
+        frame = self.frame()
+        top = float(frame.origin.y) + float(frame.size.height)
+        self.setContentSize_(size)
+        resized_frame = self.frame()
+        self.setFrameOrigin_(
+            NSMakePoint(
+                float(resized_frame.origin.x),
+                top - float(resized_frame.size.height),
+            )
+        )

panel_window_state.py

@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+from __future__ import annotations
+
+import math
+import sys
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+if sys.platform == "darwin":
+    from Foundation import NSUserDefaults
+else:
+    NSUserDefaults = None
+
+PANEL_WINDOW_ORIGIN_DEFAULTS_KEY = "usage.panelWindowOrigin"
+PANEL_WINDOW_TOP_LEFT_DEFAULTS_KEY = "usage.panelWindowTopLeft"
+PANEL_CONTENT_HEIGHTS_DEFAULTS_KEY = "usage.panelContentHeights"
+
+Origin = tuple[float, float]
+Size = tuple[float, float]
+VisibleFrame = tuple[float, float, float, float]
+
+
+def clamp_origin_to_visible_frames(
+    origin: Origin,
+    size: Size,
+    visible_frames: Sequence[VisibleFrame],
+) -> Origin:
+    if not visible_frames:
+        return origin
+
+    width = max(0.0, float(size[0]))
+    height = max(0.0, float(size[1]))
+    candidates: list[Origin] = []
+    for frame_x, frame_y, frame_width, frame_height in visible_frames:
+        maximum_x = float(frame_x) + max(0.0, float(frame_width) - width)
+        maximum_y = float(frame_y) + max(0.0, float(frame_height) - height)
+        candidate_x = min(max(float(origin[0]), float(frame_x)), maximum_x)
+        candidate_y = min(max(float(origin[1]), float(frame_y)), maximum_y)
+        candidates.append((candidate_x, candidate_y))
+
+    return min(
+        candidates,
+        key=lambda candidate: (candidate[0] - origin[0]) ** 2
+        + (candidate[1] - origin[1]) ** 2,
+    )
+
+
+def load_panel_window_origin(defaults: Any | None = None) -> Origin | None:
+    store = defaults
+    if store is None:
+        assert NSUserDefaults is not None
+        store = NSUserDefaults.standardUserDefaults()
+    value = store.arrayForKey_(PANEL_WINDOW_ORIGIN_DEFAULTS_KEY)
+    if not isinstance(value, Sequence) or isinstance(value, str | bytes) or len(value) != 2:
+        return None
+    x, y = value
+    if (
+        isinstance(x, bool)
+        or isinstance(y, bool)
+        or not isinstance(x, int | float)
+        or not isinstance(y, int | float)
+        or not math.isfinite(float(x))
+        or not math.isfinite(float(y))
+    ):
+        return None
+    return (float(x), float(y))
+
+
+def save_panel_window_top_left(
+    top_left: Origin,
+    defaults: Any | None = None,
+) -> None:
+    store = defaults
+    if store is None:
+        assert NSUserDefaults is not None
+        store = NSUserDefaults.standardUserDefaults()
+    store.setObject_forKey_(
+        [float(top_left[0]), float(top_left[1])],
+        PANEL_WINDOW_TOP_LEFT_DEFAULTS_KEY,
+    )
+
+
+def load_panel_window_top_left(defaults: Any | None = None) -> Origin | None:
+    store = defaults
+    if store is None:
+        assert NSUserDefaults is not None
+        store = NSUserDefaults.standardUserDefaults()
+    value = store.arrayForKey_(PANEL_WINDOW_TOP_LEFT_DEFAULTS_KEY)
+    if not isinstance(value, Sequence) or isinstance(value, str | bytes) or len(value) != 2:
+        return None
+    x, y = value
+    if (
+        isinstance(x, bool)
+        or isinstance(y, bool)
+        or not isinstance(x, int | float)
+        or not isinstance(y, int | float)
+        or not math.isfinite(float(x))
+        or not math.isfinite(float(y))
+    ):
+        return None
+    return (float(x), float(y))
+
+
+def save_panel_content_height(
+    panel_id: str,
+    height: float,
+    defaults: Any | None = None,
+) -> None:
+    store = defaults
+    if store is None:
+        assert NSUserDefaults is not None
+        store = NSUserDefaults.standardUserDefaults()
+    value = store.objectForKey_(PANEL_CONTENT_HEIGHTS_DEFAULTS_KEY)
+    heights = dict(value) if isinstance(value, Mapping) else {}
+    heights[panel_id] = float(height)
+    store.setObject_forKey_(heights, PANEL_CONTENT_HEIGHTS_DEFAULTS_KEY)
+
+
+def load_panel_content_height(
+    panel_id: str,
+    defaults: Any | None = None,
+) -> float | None:
+    store = defaults
+    if store is None:
+        assert NSUserDefaults is not None
+        store = NSUserDefaults.standardUserDefaults()
+    heights = store.objectForKey_(PANEL_CONTENT_HEIGHTS_DEFAULTS_KEY)
+    if not isinstance(heights, Mapping):
+        return None
+    value = heights.get(panel_id)
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, int | float)
+        or not math.isfinite(float(value))
+        or value <= 0
+    ):
+        return None
+    return float(value)
+
+
+def resolve_panel_size(
+    state: Any,
+    panel: Any | None,
+    defaults: Any | None = None,
+) -> Size:
+    import menubar_state
+
+    width, height = menubar_state.popover_dimensions(state, panel)
+    measurement_available = getattr(panel, "_content_height_reports_available", True)
+    if measurement_available and panel is not None and (
+        saved_height := load_panel_content_height(panel.id, defaults)
+    ):
+        height = saved_height
+    return (width, height)

panels/__init__.py

@@ -0,0 +1,186 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+from __future__ import annotations
+
+from functools import cache
+
+from panels.base import Panel
+
+
+@cache
+def all_panels() -> tuple[Panel, ...]:
+    # web_panel requires PyObjC at import time (objc/AppKit/WebKit), which only
+    # exists on macOS. Import it lazily so importing the panels package (e.g.
+    # wintray -> panels.payload on Windows) never pulls it in.
+    from panels.web_panel import HTMLPanel
+
+    # claude_card_height mirrors codex_card_height: the two cards share the same
+    # structure (header + two quota rows) and measure equal in headless renders.
+    return (
+        HTMLPanel(
+            "classic",
+            "panel_default_name",
+            "classic.html",
+            height=1004.0,
+            claude_card_height=192.0,
+            codex_card_height=192.0,
+            agy_card_height=192.0,
+            status_wrap_extra_height=30.0,
+            service_alert_height=32.0,
+        ),
+        HTMLPanel(
+            "matrix",
+            "panel_matrix",
+            "matrix.html",
+            height=1046.0,
+            claude_card_height=200.0,
+            codex_card_height=200.0,
+            agy_card_height=200.0,
+            status_wrap_extra_height=32.0,
+            service_alert_height=32.0,
+        ),
+        HTMLPanel(
+            "win95",
+            "panel_win95",
+            "win95.html",
+            height=1055.0,
+            claude_card_height=210.0,
+            codex_card_height=209.0,
+            agy_card_height=209.0,
+            status_wrap_extra_height=32.0,
+            service_alert_height=32.0,
+        ),
+        HTMLPanel(
+            "newspaper",
+            "panel_newspaper",
+            "newspaper.html",
+            height=1051.0,
+            claude_card_height=205.0,
+            codex_card_height=203.0,
+            agy_card_height=203.0,
+            status_wrap_extra_height=30.0,
+            service_alert_height=32.0,
+        ),
+        HTMLPanel(
+            "cloud_observation",
+            "panel_cloud_observation",
+            "cloud_observation.html",
+            height=1006.0,
+            claude_card_height=211.0,
+            codex_card_height=211.0,
+            agy_card_height=211.0,
+            service_alert_height=32.0,
+        ),
+        HTMLPanel(
+            "aquarium",
+            "panel_aquarium",
+            "aquarium.html",
+            height=1006.0,
+            claude_card_height=211.0,
+            codex_card_height=211.0,
+            agy_card_height=211.0,
+            service_alert_height=32.0,
+        ),
+        HTMLPanel(
+            "prism_arcade",
+            "panel_prism_arcade",
+            "prism_arcade.html",
+            height=1006.0,
+            claude_card_height=211.0,
+            codex_card_height=211.0,
+            agy_card_height=211.0,
+            service_alert_height=32.0,
+        ),
+        # Reuse classic's measured values because the DOM structure is identical;
+        # remeasure if a future render shows clipping.
+        HTMLPanel(
+            "stained_glass",
+            "panel_stained_glass",
+            "stained_glass.html",
+            height=1004.0,
+            claude_card_height=192.0,
+            codex_card_height=192.0,
+            agy_card_height=192.0,
+            status_wrap_extra_height=30.0,
+            service_alert_height=32.0,
+        ),
+        # Reuse classic's measured values because the DOM structure is identical;
+        # remeasure if a future render shows clipping.
+        HTMLPanel(
+            "origami",
+            "panel_origami",
+            "origami.html",
+            height=1004.0,
+            claude_card_height=192.0,
+            codex_card_height=192.0,
+            agy_card_height=192.0,
+            status_wrap_extra_height=30.0,
+            service_alert_height=32.0,
+        ),
+        HTMLPanel(
+            "black_hole",
+            "panel_black_hole",
+            "black_hole.html",
+            height=1006.0,
+            claude_card_height=211.0,
+            codex_card_height=211.0,
+            agy_card_height=211.0,
+            service_alert_height=32.0,
+        ),
+        HTMLPanel(
+            "lepidoptera",
+            "panel_lepidoptera",
+            "lepidoptera.html",
+            height=1046.0,
+            claude_card_height=208.0,
+            codex_card_height=208.0,
+            agy_card_height=208.0,
+            status_wrap_extra_height=32.0,
+            service_alert_height=32.0,
+        ),
+        HTMLPanel(
+            "world_cup",
+            "panel_world_cup",
+            "world_cup.html",
+            claude_card_height=0.0,
+            codex_card_height=0.0,
+            service_alert_height=32.0,
+        ),
+        HTMLPanel(
+            "talent_market",
+            "panel_talent_market",
+            "talent_market.html",
+            height=812.0,
+            claude_card_height=0.0,
+            codex_card_height=0.0,
+            dynamic_height=False,
+        ),
+        # 1038 = classic's 1004 + roughly 34px for the flavor swatches.
+        # This is estimated, not measured; verify clipping visually after packaging.
+        HTMLPanel(
+            "catppuccin",
+            "panel_catppuccin",
+            "catppuccin.html",
+            height=1038.0,
+            claude_card_height=192.0,
+            codex_card_height=192.0,
+            agy_card_height=192.0,
+            status_wrap_extra_height=30.0,
+            service_alert_height=32.0,
+        ),
+    )
+
+
+def panel_ids() -> tuple[str, ...]:
+    return tuple(panel.id for panel in all_panels())
+
+
+def get_panel(panel_id: str) -> Panel:
+    for panel in all_panels():
+        if panel.id == panel_id:
+            return panel
+    return all_panels()[0]