code-muse 0.0.1__py3-none-any.whl

code_muse/messaging/shimmer.py

@@ -0,0 +1,154 @@
+"""Time-synchronized shimmer / sparkle text effect.
+
+Port of the Codex `shimmer_spans` effect (Rust/ratatui) to Python/Rich.
+Produces a cosine-based highlight band that sweeps across text characters
+so all shimmer text on screen animates in lockstep.
+
+Works with truecolor (RGB blending) and degrades gracefully on terminals
+without truecolor support (uses DIM/BOLD modifiers).
+"""
+
+import math
+import time
+
+from rich.style import Style
+from rich.text import Span
+
+from code_muse.terminal_utils import detect_truecolor_support
+
+# ---------------------------------------------------------------------------
+# Process-start anchor so every shimmer instance is synchronized
+# ---------------------------------------------------------------------------
+
+_process_start: float | None = None
+
+
+def _elapsed_since_start() -> float:
+    """Seconds since the first shimmer call in this process."""
+    global _process_start
+    if _process_start is None:
+        _process_start = time.monotonic()
+    return time.monotonic() - _process_start
+
+
+# ---------------------------------------------------------------------------
+# RGB helpers
+# ---------------------------------------------------------------------------
+
+RGB = tuple[int, int, int]
+
+# Sensible defaults for terminals whose true fg/bg we cannot query.
+_DEFAULT_BASE: RGB = (160, 160, 160)  # medium gray — typical dimmed foreground
+_DEFAULT_HIGHLIGHT: RGB = (255, 255, 255)  # white — background highlight
+
+
+def blend(fg: RGB, bg: RGB, alpha: float) -> RGB:
+    """Linear alpha-blend between two RGB colours.
+
+    Returns components clamped to 0..255.
+    """
+    inv = 1.0 - alpha
+    return (
+        min(255, max(0, int(fg[0] * alpha + bg[0] * inv))),
+        min(255, max(0, int(fg[1] * alpha + bg[1] * inv))),
+        min(255, max(0, int(fg[2] * alpha + bg[2] * inv))),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Shimmer spans
+# ---------------------------------------------------------------------------
+
+# Cosine half-width of the highlight band in character positions.
+_BAND_HALF_WIDTH = 5.0
+
+# Padding added to each side of the text so the band can enter/exit smoothly.
+_PADDING = 10
+
+# Period of the sweep in seconds.
+_SWEEP_SECONDS = 2.0
+
+
+def shimmer_spans(
+    text: str,
+    *,
+    base_color: RGB | None = None,
+    highlight_color: RGB | None = None,
+) -> list[Span]:
+    """Return a list of Rich ``Span`` objects with a shimmer highlight band.
+
+    The highlight sweeps across *text* once every ``_SWEEP_SECONDS`` seconds,
+    synchronized to the first call anywhere in the process so multiple
+    shimmer texts animate in lockstep.
+
+    Args:
+        text: The string to shimmer-ify.
+        base_color: RGB tuple for dimmed characters.  Defaults to
+            ``_DEFAULT_BASE``.
+        highlight_color: RGB tuple for the highlight peak.  Defaults to
+            ``_DEFAULT_HIGHLIGHT``.
+
+    Returns:
+        List of ``Span`` objects styled appropriately.
+    """
+    chars = list(text)
+    if not chars:
+        return []
+
+    base = base_color or _DEFAULT_BASE
+    highlight = highlight_color or _DEFAULT_HIGHLIGHT
+
+    has_truecolor = detect_truecolor_support()
+
+    period = len(chars) + _PADDING * 2
+    elapsed = _elapsed_since_start()
+    # Fractional position of the band centre (0 .. period).
+    pos_f = (elapsed % _SWEEP_SECONDS) / _SWEEP_SECONDS * float(period)
+
+    spans: list[Span] = []
+
+    for i, _ch in enumerate(chars):
+        # Signed distance from band centre (padding-adjusted).
+        i_pos = float(i + _PADDING)
+        dist = abs(i_pos - pos_f)
+
+        # Cosine intensity: 1.0 at the centre, 0.0 beyond half-width.
+        if dist <= _BAND_HALF_WIDTH:
+            x = math.pi * (dist / _BAND_HALF_WIDTH)
+            t = 0.5 * (1.0 + math.cos(x))
+        else:
+            t = 0.0
+
+        if has_truecolor:
+            alpha = t * 0.9  # peak blend strength
+            r, g, b = blend(highlight, base, alpha)
+            from rich.color import Color
+
+            style = Style(color=Color.from_rgb(r, g, b), bold=True)
+        else:
+            style = _color_for_level(t)
+
+        spans.append(Span(i, i + 1, style))
+
+    return spans
+
+
+# ---------------------------------------------------------------------------
+# Fallback for terminals without truecolor
+# ---------------------------------------------------------------------------
+
+
+def _color_for_level(intensity: float) -> Style:
+    """Map a cosine intensity to a Rich Style using modifiers only.
+
+    This keeps the shimmer readable on basic terminals:
+      - < 0.2 → DIM (faint)
+      - 0.2–0.6 → NORMAL
+      - > 0.6 → BOLD (bright)
+    """
+    if intensity < 0.2:
+        return Style(dim=True)
+    elif intensity < 0.6:
+        return Style()
+    else:
+        return Style(bold=True)

code_muse/messaging/spinner/__init__.py

@@ -0,0 +1,87 @@
+"""
+Shared spinner implementation for CLI mode.
+
+This module provides consistent spinner animations across different UI modes.
+"""
+
+from rich.spinner import SPINNERS
+
+from .console_spinner import ConsoleSpinner
+from .spinner_base import SpinnerBase
+
+SPINNERS["radar"] = {"interval": 80, "frames": ["◝", "◜", "◠", "◡"]}
+
+# Keep track of all active spinners to manage them globally
+_active_spinners = []
+
+
+def register_spinner(spinner):
+    """Register an active spinner to be managed globally."""
+    if spinner not in _active_spinners:
+        _active_spinners.append(spinner)
+
+
+def unregister_spinner(spinner):
+    """Remove a spinner from global management."""
+    if spinner in _active_spinners:
+        _active_spinners.remove(spinner)
+
+
+def pause_all_spinners():
+    """Pause all active spinners.
+
+    No-op when called from a sub-agent context to prevent
+    parallel sub-agents from interfering with the main spinner.
+    """
+    # Lazy import to avoid circular dependency
+    from code_muse.tools.subagent_context import is_subagent
+
+    if is_subagent():
+        return  # Sub-agents don't control the main spinner
+    for spinner in _active_spinners:
+        try:
+            spinner.pause()
+        except Exception:
+            # Ignore errors if a spinner can't be paused
+            pass
+
+
+def resume_all_spinners():
+    """Resume all active spinners.
+
+    No-op when called from a sub-agent context to prevent
+    parallel sub-agents from interfering with the main spinner.
+    """
+    # Lazy import to avoid circular dependency
+    from code_muse.tools.subagent_context import is_subagent
+
+    if is_subagent():
+        return  # Sub-agents don't control the main spinner
+    for spinner in _active_spinners:
+        try:
+            spinner.resume()
+        except Exception:
+            # Ignore errors if a spinner can't be resumed
+            pass
+
+
+def update_spinner_context(info: str) -> None:
+    """Update the shared context information displayed beside active spinners."""
+    SpinnerBase.set_context_info(info)
+
+
+def clear_spinner_context() -> None:
+    """Clear any context information displayed beside active spinners."""
+    SpinnerBase.clear_context_info()
+
+
+__all__ = [
+    "SpinnerBase",
+    "ConsoleSpinner",
+    "register_spinner",
+    "unregister_spinner",
+    "pause_all_spinners",
+    "resume_all_spinners",
+    "update_spinner_context",
+    "clear_spinner_context",
+]

code_muse/messaging/spinner/console_spinner.py

@@ -0,0 +1,250 @@
+"""
+Console spinner implementation for CLI mode using Rich's Live Display.
+"""
+
+import platform
+import threading
+import time
+
+from rich.console import Console
+from rich.live import Live
+from rich.text import Text
+
+from code_muse.config import get_animations_enabled
+from code_muse.motion import MotionMode, shimmer_text
+
+from .spinner_base import SpinnerBase
+
+
+class ConsoleSpinner(SpinnerBase):
+    """A console-based spinner implementation using Rich's Live Display."""
+
+    def __init__(self, console=None):
+        """Initialize the console spinner.
+
+        Args:
+            console: Optional Rich console instance to use for output.
+                    If not provided, a new one will be created.
+        """
+        super().__init__()
+        self.console = console or Console()
+        self._thread = None
+        self._stop_event = threading.Event()
+        self._paused = False
+        self._live = None
+        self._animations_enabled = get_animations_enabled()
+
+        # Register this spinner for global management
+        from . import register_spinner
+
+        register_spinner(self)
+
+    def start(self):
+        """Start the spinner animation."""
+        super().start()
+        self._stop_event.clear()
+
+        # Don't start a new thread if one is already running
+        if self._thread and self._thread.is_alive():
+            return
+
+        # Print blank line before spinner for visual separation from content
+        self.console.print()
+
+        # Create a Live display for the spinner
+        self._live = Live(
+            self._generate_spinner_panel(),
+            console=self.console,
+            refresh_per_second=8,
+            transient=True,  # Clear the spinner line when stopped (no residue left!)
+            auto_refresh=False,  # Don't auto-refresh to avoid wiping out user input
+        )
+        self._live.start()
+
+        # Start a thread to update the spinner frames
+        self._thread = threading.Thread(target=self._update_spinner)
+        self._thread.daemon = True
+        self._thread.start()
+
+    def stop(self):
+        """Stop the spinner animation."""
+        if not self._is_spinning:
+            return
+
+        self._stop_event.set()
+        self._is_spinning = False
+
+        if self._live:
+            self._live.stop()
+            self._live = None
+
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=0.5)
+
+        self._thread = None
+
+        # Windows-specific cleanup: Rich's Live display can leave terminal in corrupted state
+        if platform.system() == "Windows":
+            import sys
+
+            try:
+                # Reset ANSI formatting for both stdout and stderr
+                sys.stdout.write("\x1b[0m")  # Reset all attributes
+                sys.stdout.flush()
+                sys.stderr.write("\x1b[0m")
+                sys.stderr.flush()
+
+                # Clear the line and reposition cursor
+                sys.stdout.write("\r")  # Return to start of line
+                sys.stdout.write("\x1b[K")  # Clear to end of line
+                sys.stdout.flush()
+
+                # Flush keyboard input buffer to clear any stuck keys
+                try:
+                    import msvcrt
+
+                    while msvcrt.kbhit():
+                        msvcrt.getch()
+                except ImportError:
+                    pass  # msvcrt not available (not Windows or different Python impl)
+            except Exception:
+                pass  # Fail silently if cleanup doesn't work
+
+        # Unregister this spinner from global management
+        from . import unregister_spinner
+
+        unregister_spinner(self)
+
+    def update_frame(self):
+        """Update to the next frame."""
+        super().update_frame()
+
+    def _generate_spinner_panel(self):
+        """Generate a Rich panel containing the spinner text."""
+        from code_muse.tools.command_runner import is_awaiting_user_input
+
+        if self._paused or is_awaiting_user_input():
+            return Text("")
+
+        text = Text()
+
+        motion_mode = MotionMode.from_animations_enabled(self._animations_enabled)
+
+        if motion_mode == MotionMode.ANIMATED:
+            # Use shimmer text — the highlight band sweeps across "Thinking..."
+            thinking = Text("Thinking...")
+            thinking.spans = shimmer_text("Thinking...", motion_mode)
+            text.append(thinking)
+        else:
+            # Reduced motion: classic spinner frame
+            text.append(SpinnerBase.THINKING_MESSAGE, style="bold green")
+            text.append(self.current_frame, style="bold green")
+
+        context_info = SpinnerBase.get_context_info()
+        if context_info:
+            text.append(" ")
+            text.append(context_info, style="bold white")
+
+        return text
+
+    def _update_spinner(self):
+        """Update the spinner in a background thread."""
+        try:
+            while not self._stop_event.is_set():
+                # Update the frame
+                self.update_frame()
+
+                # Check if we're awaiting user input before updating the display
+                from code_muse.tools.command_runner import is_awaiting_user_input
+
+                awaiting_input = is_awaiting_user_input()
+
+                # Update the live display only if not paused and not awaiting input
+                if self._live and not self._paused and not awaiting_input:
+                    # Manually refresh instead of auto-refresh to avoid wiping input
+                    self._live.update(self._generate_spinner_panel())
+                    self._live.refresh()
+
+                # Short sleep to control animation speed
+                time.sleep(0.12)
+        except Exception as e:
+            # Note: Using sys.stderr - can't use messaging during spinner
+            import sys
+
+            sys.stderr.write(f"\nSpinner error: {e}\n")
+            self._is_spinning = False
+
+    def pause(self):
+        """Pause the spinner animation."""
+        if self._is_spinning:
+            self._paused = True
+            # Stop the live display completely to restore terminal echo during input
+            if self._live:
+                try:
+                    self._live.stop()
+                    self._live = None
+                    # Clear the line to remove any artifacts
+                    import sys
+
+                    sys.stdout.write("\r")  # Return to start of line
+                    sys.stdout.write("\x1b[K")  # Clear to end of line
+                    sys.stdout.flush()
+                except Exception:
+                    pass
+
+    def resume(self):
+        """Resume the spinner animation."""
+        # Check if we should show a spinner - don't resume if waiting for user input
+        from code_muse.tools.command_runner import is_awaiting_user_input
+
+        if is_awaiting_user_input():
+            return  # Don't resume if waiting for user input
+
+        if self._is_spinning and self._paused:
+            self._paused = False
+            # Restart the live display if it was stopped during pause
+            if not self._live:
+                try:
+                    # Clear any leftover artifacts before starting
+                    import sys
+
+                    sys.stdout.write("\r")  # Return to start of line
+                    sys.stdout.write("\x1b[K")  # Clear to end of line
+                    sys.stdout.flush()
+
+                    # Print blank line before spinner for visual separation
+                    self.console.print()
+
+                    self._live = Live(
+                        self._generate_spinner_panel(),
+                        console=self.console,
+                        refresh_per_second=8,
+                        transient=True,  # Clear spinner line when stopped
+                        auto_refresh=False,
+                    )
+                    self._live.start()
+                except Exception:
+                    pass
+            else:
+                # If live display still exists, clear console state first
+                try:
+                    # Force Rich to reset any cached console state
+                    if hasattr(self.console, "_buffer"):
+                        # Clear Rich's internal buffer to prevent artifacts
+                        self.console.file.write("\r")  # Return to start
+                        self.console.file.write("\x1b[K")  # Clear line
+                        self.console.file.flush()
+
+                    self._live.update(self._generate_spinner_panel())
+                    self._live.refresh()
+                except Exception:
+                    pass
+
+    def __enter__(self):
+        """Support for context manager."""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Clean up when exiting context manager."""
+        self.stop()

code_muse/messaging/spinner/spinner_base.py

@@ -0,0 +1,82 @@
+"""
+Base spinner implementation to be extended for different UI modes.
+"""
+
+from abc import ABC, abstractmethod
+from threading import Lock
+
+
+class SpinnerBase(ABC):
+    """Abstract base class for spinner implementations."""
+
+    # Shared spinner frames across implementations
+    FRAMES = ["◝", "◜", "◠", "◡"]
+
+    # Default message when processing
+    THINKING_MESSAGE = "Thinking... "
+
+    # Message when waiting for user input
+    WAITING_MESSAGE = "Waiting... "
+
+    # Current message - starts with thinking by default
+    MESSAGE = THINKING_MESSAGE
+
+    _context_info: str = ""
+    _context_lock: Lock = Lock()
+
+    def __init__(self):
+        """Initialize the spinner."""
+        self._is_spinning = False
+        self._frame_index = 0
+
+    @abstractmethod
+    def start(self):
+        """Start the spinner animation."""
+        self._is_spinning = True
+        self._frame_index = 0
+
+    @abstractmethod
+    def stop(self):
+        """Stop the spinner animation."""
+        self._is_spinning = False
+
+    @abstractmethod
+    def update_frame(self):
+        """Update to the next frame."""
+        if self._is_spinning:
+            self._frame_index = (self._frame_index + 1) % len(self.FRAMES)
+
+    @property
+    def current_frame(self):
+        """Get the current frame."""
+        return self.FRAMES[self._frame_index]
+
+    @property
+    def is_spinning(self):
+        """Check if the spinner is currently spinning."""
+        return self._is_spinning
+
+    @classmethod
+    def set_context_info(cls, info: str) -> None:
+        """Set shared context information displayed beside the spinner."""
+        with cls._context_lock:
+            cls._context_info = info
+
+    @classmethod
+    def clear_context_info(cls) -> None:
+        """Clear any context information displayed beside the spinner."""
+        cls.set_context_info("")
+
+    @classmethod
+    def get_context_info(cls) -> str:
+        """Return the current spinner context information."""
+        with cls._context_lock:
+            return cls._context_info
+
+    @staticmethod
+    def format_context_info(total_tokens: int, capacity: int, proportion: float) -> str:
+        """Create a concise context summary for spinner display."""
+        if capacity <= 0:
+            return ""
+        proportion_pct = proportion * 100
+        return f"Tokens: {total_tokens:,}/{capacity:,} ({proportion_pct:.1f}% used)"