feat(ui): theme-signature animations and micro-interactions

[therahul-yo]

What

Makes the terminal UI distinctly Superton's — each theme now carries its own motion signature, not just a palette.

• Per-theme streaming cursors (▎ ember, ▌ crimson, ▖ void, _ ash) with a breathing muted↔secondary color cycle while tokens stream
• Per-theme spinner tempo — crimson ticks sharper, void drifts slower; waits >8s breathe the spinner color so long pulls visibly stay alive
• Theme-signature rules — titled rules carry the theme's prompt glyph: ── ◉ memory ────
• Two-pulse flash on theme/model switches — reads as a deliberate confirmation wink
• Ready-card heartbeat — init finale lands with a 3-frame pulsing dot
• Staggered search-result cascade via new reveal_cards() (Live-free, zero flicker risk)
• ▰▰▱ mini score bars tinted by score_color() in shell search hits and ask --why
• Ghost prompt placeholder — dim ask anything · /help until first keystroke (prompt-toolkit pin → ≥3.0.19)

All animations degrade to static prints on non-TTY.

Tests

14 new tests (cursor/tempo schema, score_bar clamping, reveal_cards non-TTY no-sleep, rule glyph, flash no-op, stream_answer non-TTY). 240 passed locally + ruff clean.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Theme customization with custom cursor appearance and animation speeds
  • Animated card reveal effect for search results display
  • Shell prompt now shows helpful hint text

• Improvements

  • Search results include visual score bar indicators
  • Enhanced visual feedback during streaming with color-shifting animations
  • Improved UI consistency across theme applications

• Tests

  • Added comprehensive UI primitive tests

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
superton	Ready	Preview, Comment	Jun 11, 2026 4:40pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 897c0974-b09a-4f25-b813-e094889548b5

📥 Commits

Reviewing files that changed from the base of the PR and between 1528666 and 580e53e.

📒 Files selected for processing (5)

• pyproject.toml
• superton/cli.py
• superton/shell.py
• superton/ui.py
• tests/test_ui_primitives.py

---

📝 Walkthrough

Walkthrough

The PR enhances UI polish and animations by introducing per-theme cursor glyphs and animation tempo multipliers, creating new rendering primitives for staggered cards and score bars, updating core animations to use theme properties, and integrating these throughout shell search and CLI score rendering with comprehensive test coverage.

Changes

UI Polish and Animation Enhancements

Layer / File(s)	Summary
Theme infrastructure with cursor and tempo pyproject.toml, superton/ui.py	Theme dataclass gains cursor and tempo fields; all theme instances updated per-theme; prompt-toolkit bumped to ≥3.0.19.
New UI primitive functions superton/ui.py	Added typing_cursor() (theme-aware cursor glyph), reveal_cards() (staggered TTY rendering), and score_bar() (mini score visualization).
Animation behaviors with tempo and theme cursor superton/ui.py	spinner() scales phases by tempo and alternates color on long waits; flash() rewritten as two-pulse confirm; ready_card() adds dot-pulse; rule() appends and sizes for prompt glyph.
Streaming cursor with breathing animation superton/ui.py	stream_answer() stores cursor glyph and timestamp; cursor alternates muted↔secondary on ~0.4s rhythm; retire phase uses theme cursor.
Shell prompt placeholder and search card rendering superton/shell.py	Interactive prompt gains theme-colored placeholder. Search hits refactored into rich card groups (score+bar header + muted preview) rendered via ui.reveal_cards() with staggered cascade.
CLI ask command score rendering superton/cli.py	Retrieval table score column now Rich Text objects with styled numeric score and appended score bar.
UI primitives test coverage tests/test_ui_primitives.py	Tests for theme cursor/tempo, typing cursor glyph, score bar full/empty/clamp, reveal cards stagger/non-TTY, rule glyph presence, flash non-terminal, stream_answer cursor non-terminal.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• therahul-yo/Superton#2: Introduces superton/ui.py abstraction and routes CLI/shell through it; main PR extends Theme/cursor behavior and adds new primitives on that foundation.
• therahul-yo/Superton#4: Refactors superton/ui.py cursor/typing and restyle superton/shell.py search display with cards/chips; main PR builds directly on the same cursor/shell rendering patterns.
• therahul-yo/Superton#20: Modifies superton/cli.py ask command output; main PR changes how retrieval table renders score, overlapping in the same command's rendering logic.

Poem

🐰 Theme cursors breathe and glow,
Tempo dances to the flow,
Cards cascade in staggered grace,
Score bars shine in themed space,
Polish shines from shell to test!
✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 42.86% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(ui): theme-signature animations and micro-interactions' directly captures the main change: adding theme-specific motion and micro-interactions to the UI layer.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}