shimmer.py

#!/usr/bin/env python3
import argparse
import signal
import sys
import time


RESET = "\033[0m"
HIDE_CURSOR = "\033[?25l"
SHOW_CURSOR = "\033[?25h"
CLEAR_LINE = "\033[2K"


def gray(level: int) -> str:
    """Return an ANSI 256-color grayscale foreground escape."""
    level = max(0, min(23, level))
    return f"\033[38;5;{232 + level}m"


def render_shimmer(text: str, frame: int, band_width: int) -> str:
    # Start off-screen so the light sweeps in and out cleanly.
    pos = frame % (len(text) + band_width * 2) - band_width
    chunks: list[str] = []

    for index, char in enumerate(text):
        distance = abs(index - pos)

        if distance > band_width:
            level = 8
        else:
            # 8..23, brightest in the center of the moving band.
            level = 8 + round((1 - distance / band_width) * 15)

        chunks.append(f"{gray(level)}{char}")

    return "".join(chunks) + RESET


def shimmer(text: str, fps: float, band_width: int, duration: float | None) -> None:
    delay = 1 / fps
    frame = 0
    started = time.monotonic()

    sys.stdout.write(HIDE_CURSOR)
    sys.stdout.flush()

    try:
        while True:
            if duration is not None and time.monotonic() - started >= duration:
                break

            sys.stdout.write("\r" + CLEAR_LINE + render_shimmer(text, frame, band_width))
            sys.stdout.flush()
            frame += 1
            time.sleep(delay)
    finally:
        sys.stdout.write("\r" + CLEAR_LINE + SHOW_CURSOR + RESET)
        sys.stdout.flush()


def main() -> int:
    parser = argparse.ArgumentParser(description="CLI text shimmer loading effect.")
    parser.add_argument("text", nargs="?", default="Thinking...", help="text to animate")
    parser.add_argument("--fps", type=float, default=24, help="frames per second")
    parser.add_argument("--band-width", type=int, default=4, help="width of the bright band")
    parser.add_argument("--duration", type=float, default=None, help="seconds to run")
    args = parser.parse_args()

    if args.fps <= 0:
        parser.error("--fps must be greater than 0")
    if args.band_width <= 0:
        parser.error("--band-width must be greater than 0")

    shimmer(args.text, args.fps, args.band_width, args.duration)
    return 0


if __name__ == "__main__":
    signal.signal(signal.SIGINT, lambda _sig, _frame: sys.exit(130))
    raise SystemExit(main())