diff --git a/README.md b/README.md index 3ef07d1..c3080dc 100644 --- a/README.md +++ b/README.md @@ -117,7 +117,7 @@ Note: increasing `interval_seconds` proportionally slows the terracotta breath a ## Themes -understatus ships five built-in themes. Set the active theme in one line: +understatus ships nine built-in themes. Set the active theme in one line: ```toml # ~/.config/understatus/config.toml @@ -141,6 +141,10 @@ understatus themes # list all available themes | `vivid` | `░ ▒ ▓ █ █` | Traffic-light colors (green → amber → red) with block-fill glyphs. | | `ember` | `· ∙ • ● ◉` | Warm amber/terracotta monochromatic ladder with dot glyphs. | | `emoji` | `😌 🙂 😅 🥵 🔥` | Emoji face ramp. Each glyph occupies 2 terminal columns. | +| `neon` | `░ ▒ ▓ █ █` | Neon cyberpunk — electric cyan → magenta with hue-cycling pulse. | +| `aurora` | `▁ ▃ ▅ ▆ █` | Aurora borealis — teal → purple gradient with flash pulse. | +| `sunset` | `· ∙ • ● ◉` | Sunset — gold → coral → purple with flash pulse. | +| `spectrum` | `▁ ▂ ▄ ▆ █` | Per-band rainbow — green → magenta with hue-cycling pulse. | **COLOR-ONCE principle:** Color is applied to the glyph character only. Numeric values (CPU%, memory, cost, etc.) are always uncolored regardless of theme. @@ -150,6 +154,57 @@ understatus themes # list all available themes --- +## Pulse styles + +When the pulse is active (CPU ≥ `pulse_on_threshold`), `pulse_style` controls how the critical-band glyph animates. There are four styles: + +| Style | Behavior | +|-------|----------| +| `calm` | Fixed glyph shape. Terracotta luminance breathing — hue never shifts, only brightness cycles between `pulse_palette[0]` (bright) and `pulse_palette[1]` (dim). Most subtle. **Default for original themes.** | +| `flash` | Fixed glyph shape. Uses the theme's own `pulse_palette` endpoints (the same high/low colors as that theme's `calm` breath), but applies a sharper sine curve — the midpoint brightness contrast is more pronounced (punchier breathing). | +| `hue` | Fixed glyph shape. The glyph tint cycles through the full hue wheel (rainbow shimmer) over one `pulse_period_seconds`. Saturation and value stay constant; only hue rotates 360°. | +| `swap` | Hue cycling (same as `hue`) **plus** glyph shape alternation: the critical glyph swaps between its filled and hollow forms (e.g. `◆` ↔ `◇`) on the second half of each period. Most eye-catching. | + +**Flashy theme defaults:** The four bold themes ship with a fitting default style — `neon` and `spectrum` use `hue`; `aurora` and `sunset` use `flash`. The original five themes (`calm`, `mono`, `vivid`, `ember`, `emoji`) all use `calm`. All are overridable per the per-key override rule above. + +**When pulse is OFF:** Regardless of `pulse_style`, when CPU is below `pulse_off_threshold` the pulse is inactive and the glyph renders with its static `band_tints` color — no animation of any kind. + +### Trigger thresholds + +```toml +# ~/.config/understatus/config.toml +[pulse] +pulse_on_threshold = 90 # default: CPU% at which pulse activates +pulse_off_threshold = 80 # default: CPU% below which pulse deactivates (hysteresis) +``` + +The pulse turns ON when CPU reaches `pulse_on_threshold` (90) and stays ON until CPU drops below `pulse_off_threshold` (80) — so it keeps animating briefly during cool-down. This avoids flicker at the boundary. + +Lower the thresholds to pulse at a lower CPU load: + +```toml +[pulse] +pulse_on_threshold = 75 +pulse_off_threshold = 65 +``` + +### Changing the pulse style + +```toml +# ~/.config/understatus/config.toml +[pulse] +pulse_style = "hue" # calm | flash | hue | swap +``` + +Or switch from the command line (takes effect on the next render): + +```bash +understatus pulse hue # change pulse style +understatus pulse # print current style +``` + +--- + ## Configuration File: `~/.config/understatus/config.toml` @@ -157,13 +212,13 @@ All keys are optional; omitting a key uses its default. | Key | Default | Description | |-----|---------|-------------| -| `theme` | `"calm"` | Active theme preset. Valid values: `calm`, `mono`, `vivid`, `ember`, `emoji`. The theme fills all eight visual keys not explicitly set in config; individual keys can still override it. | +| `theme` | `"calm"` | Active theme preset. Valid values: `calm`, `mono`, `vivid`, `ember`, `emoji`, `neon`, `aurora`, `sunset`, `spectrum`. The theme fills all eight visual keys not explicitly set in config; individual keys can still override it. | | `[cpu] sample_window_ms` | `25` | Interval (ms) between the two CPU snapshots. Larger = less noise, more latency. | | `[cpu] load_glyphs` | `["○","▁","▄","▆","◆"]` | Glyphs for idle→critical load stages. Color is applied to the glyph only. Filled by the active theme; override by writing this key explicitly. | | `[pulse] pulse_on_threshold` | `90` | CPU% at which the critical glyph starts breathing. | | `[pulse] pulse_off_threshold` | `80` | CPU% below which the breath turns off (hysteresis). | | `[pulse] pulse_period_seconds` | `30` | One full breath cycle in seconds. Keep `period / interval_seconds >= 6` for smooth animation. | -| `[pulse] pulse_style` | `"calm"` | `"calm"` = fixed glyph shape + terracotta brightness breath (hue never changes). `"bold"` = legacy style. | +| `[pulse] pulse_style` | `"calm"` | Pulse animation style when active. `"calm"` = theme's `pulse_palette` luminance breath, hue-invariant (most subtle). `"flash"` = same `pulse_palette` endpoints, sharper midpoint contrast. `"hue"` = hue-wheel cycling (rainbow shimmer). `"swap"` = hue cycling + glyph shape alternation (most eye-catching). See [Pulse styles](#pulse-styles). | | `[chain] chain_command` | `""` | Populated by `install`. The command that runs alongside understatus. | | `[chain] order` | `"self_first"` | `"self_first"` or `"chain_first"` — which output appears on the left. | | `[chain] chain_cache_ttl_seconds` | `10` | How long (s) to cache the chained command's stdout before re-spawning it. | @@ -217,7 +272,7 @@ understatus binary (new process per call — no daemon, no state files, no lock **Glyph + tint design (COLOR-ONCE):** `band_tints[0..3]` are cool blue-grey values of increasing brightness (idle to high load). `band_tints[4]` is the lone warm color — terracotta — reserved for the critical stage. Only the glyph character receives color; all numeric values and labels stay uncolored. The active theme fills these colors; individual config keys override the preset. -**Terracotta breath:** When CPU stays at ≥90%, the critical-band glyph cycles between `pulse_palette[0]` (brighter) and `pulse_palette[1]` (dimmer) over `pulse_period_seconds`. Hue never shifts — only brightness. This is the `"calm"` pulse style. Smooth animation requires `pulse_period / interval_seconds >= 6` (6 or more render frames per cycle). +**Pulse animation:** When CPU stays at or above `pulse_on_threshold` (default 90%), the critical-band glyph animates according to `pulse_style`. The `"calm"` style cycles between `pulse_palette[0]` (brighter) and `pulse_palette[1]` (dimmer) with hue-invariant brightness breathing. `"flash"` uses the same theme `pulse_palette` endpoints but a sharper curve (punchier breathing). `"hue"` rotates through the full hue wheel. `"swap"` adds glyph shape alternation on top of hue rotation. The pulse stays ON until CPU drops below `pulse_off_threshold` (default 80%) — keeping the animation going briefly during cool-down to avoid boundary flicker. Smooth animation requires `pulse_period / interval_seconds >= 6` (6 or more render frames per cycle). See [Pulse styles](#pulse-styles). **Session cache isolation:** Per-render caches (chain command output, pulse state, network counter delta) are keyed by `session_id`. Multiple terminal windows running understatus simultaneously do not share or corrupt each other's cached values. Battery state is machine-global and is shared across sessions. @@ -256,7 +311,7 @@ macOS용 AI 코딩 CLI statusline 애드온입니다. CPU%, 메모리, 배터리 **주요 특징** -- **5종 테마** — `calm`(기본), `mono`, `vivid`, `ember`, `emoji`. 테마는 8개 시각 키(글리프·색상 등)를 한 번에 설정하며, 개별 키를 config.toml에 명시하면 테마보다 우선합니다. +- **9종 테마** — `calm`(기본), `mono`, `vivid`, `ember`, `emoji`, `neon`, `aurora`, `sunset`, `spectrum`. 테마는 8개 시각 키(글리프·색상 등)를 한 번에 설정하며, 개별 키를 config.toml에 명시하면 테마보다 우선합니다. - **COLOR-ONCE 원칙** — 색은 글리프 문자에만 적용. 숫자 값(CPU%, 비용 등)은 항상 무색. - **≥90% 호흡** — CPU가 90% 이상으로 유지되면 임계 밴드 글리프가 테라코타 명도로 천천히 숨쉽니다(hue 변화 없음). 부드러운 애니메이션에는 `pulse_period / interval_seconds >= 6` 조건이 필요하며, 위반 시 설치 시점에 경고가 출력됩니다. - **반응형 CPU** — 매 렌더마다 두 스냅샷(~25ms 간격) 직접 측정. loadavg 아님. @@ -302,6 +357,40 @@ understatus themes # 사용 가능한 테마 목록 | `vivid` | `░ ▒ ▓ █ █` | 신호등 색 + 블록 글리프 | | `ember` | `· ∙ • ● ◉` | 따뜻한 앰버/테라코타 단색 + 도트 글리프 | | `emoji` | `😌 🙂 😅 🥵 🔥` | 이모지 표정 램프 (각 글리프 2칸 폭) | +| `neon` | `░ ▒ ▓ █ █` | 네온 사이버펑크 (일렉트릭 시안→마젠타, hue 순환 펄스) | +| `aurora` | `▁ ▃ ▅ ▆ █` | 오로라 청록→보라 그라데이션 (flash 펄스) | +| `sunset` | `· ∙ • ● ◉` | 노을 골드→코랄→퍼플 (flash 펄스) | +| `spectrum` | `▁ ▂ ▄ ▆ █` | 밴드별 무지개 (초록→마젠타, hue 순환 펄스) | + +**펄스 스타일** + +CPU가 `pulse_on_threshold`(기본 90%) 이상이면 임계 밴드 글리프가 `pulse_style`에 따라 애니메이션됩니다. + +| 스타일 | 동작 | +|--------|------| +| `calm` | 글리프 고정. 테라코타 명도 호흡 (hue 변화 없음). 가장 차분함. **기존 테마 기본.** | +| `flash` | 글리프 고정. 해당 테마의 `pulse_palette` 끝점(`calm` 호흡과 동일한 high/low 색)을 사용하되 더 가파른 사인 곡선 적용 — 중간 위상 대비가 더 강렬함. | +| `hue` | 글리프 고정. 글리프 색이 한 주기(pulse_period_seconds) 동안 색상환 전체를 순환 (무지개 shimmer). | +| `swap` | `hue` 순환 **+** 글리프 모양 교대: 주기 후반부에 `◆`↔`◇` 등 채움/빈 형태를 번갈아 표시. 가장 눈에 띔. | + +화려한 테마 기본: `neon`·`spectrum` = `hue`, `aurora`·`sunset` = `flash`. 기존 5종은 모두 `calm`. 개별 키로 재정의 가능. + +펄스가 OFF(CPU < `pulse_off_threshold`)이면 스타일과 무관하게 정적 밴드 틴트로 표시됩니다 (애니메이션 없음). + +```toml +# ~/.config/understatus/config.toml +[pulse] +pulse_on_threshold = 90 # 펄스 발동 CPU% (기본) +pulse_off_threshold = 80 # 펄스 해제 CPU% — 히스테리시스 (기본) +pulse_style = "hue" # calm | flash | hue | swap +``` + +펄스는 CPU가 `pulse_on_threshold`(90)에 도달하면 켜지고, `pulse_off_threshold`(80) 미만으로 떨어질 때까지 유지됩니다 — 냉각 중에도 잠시 애니메이션이 지속되어 경계에서 깜빡임을 방지합니다. + +```bash +understatus pulse hue # 펄스 스타일 변경 (config.toml만 수정, 즉시 적용) +understatus pulse # 현재 펄스 스타일 확인 +``` 설정 파일: `~/.config/understatus/config.toml` (없으면 모두 기본값) diff --git a/docs/superpowers/plans/2026-06-04-flashy-themes.md b/docs/superpowers/plans/2026-06-04-flashy-themes.md new file mode 100644 index 0000000..ff65346 --- /dev/null +++ b/docs/superpowers/plans/2026-06-04-flashy-themes.md @@ -0,0 +1,1094 @@ +# 화려한 테마 (색 프리셋 4종 + bold 펄스 채널) Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** understatus에 화려한 색 테마 4종(neon/aurora/sunset/spectrum)과 옵트인 bold 펄스 채널(`pulse_style`: calm/flash/hue/swap)을 추가한다. + +**Architecture:** Phase 1은 `themes.rs`에 프리셋만 추가하는 순수 데이터 변경(render 무변경). Phase 2는 데드 데이터였던 `pulse_style`을 `theme.rs`의 `pulse_color`/`pick_emoji`에서 실제 시각 채널로 분기시키고, `understatus pulse