ccusage-viz 0.2.0__tar.gz → 0.2.2__tar.gz

{ccusage_viz-0.2.0 → ccusage_viz-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ccusage-viz
-Version: 0.2.0
+Version: 0.2.2
 Summary: Stateless terminal visualizations for ccusage token data
 Author: Cookie HOO
 License-Expression: GPL-3.0-only
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: System :: Monitoring
 Requires-Dist: plotext>=6.1,<7
-Requires-Dist: term-animate>=0.1.0,<0.2.0
+Requires-Dist: term-animate>=0.1.1,<0.2.0
 Requires-Python: >=3.11, <3.14
 Project-URL: Homepage, https://github.com/Cookie-HOO/ccusage-viz
 Project-URL: Issues, https://github.com/Cookie-HOO/ccusage-viz/issues
@@ -26,7 +26,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/ccusage-viz.svg)](https://pypi.org/project/ccusage-viz/) [![Python](https://img.shields.io/pypi/pyversions/ccusage-viz.svg)](https://pypi.org/project/ccusage-viz/) [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](LICENSE) [![CI](https://github.com/Cookie-HOO/ccusage-viz/actions/workflows/ci.yml/badge.svg)](https://github.com/Cookie-HOO/ccusage-viz/actions/workflows/ci.yml)
 
-> **Alpha · 0.2.0** — interfaces may change before 1.0. See the [roadmap](ROADMAP.md) for current direction.
+> **Alpha · 0.2.2** — interfaces may change before 1.0. See the [roadmap](ROADMAP.md) for current direction.
 
 `ccusage-viz` is an independent, unofficial terminal visualizer for
 [`ccusage`](https://github.com/ryoppippi/ccusage) token data. It turns
@@ -59,6 +59,12 @@ pricing, balances, quotas, allowances, or other non-token account analytics.
 > This project is not affiliated with or endorsed by the `ccusage` project or
 > its maintainers.
 
+## Interactive Help
+
+Every interactive view provides Help: press `h` whenever you need to see its
+available controls. While editing Overlay text or a command, use `Ctrl-H`
+instead so the literal `h` remains available to the draft.
+
 ## Dashboard presets
 
 `dashboard` composes independently configured charts in one terminal. The default
@@ -78,10 +84,35 @@ ccuv dashboard
 | `spotlight-wide` | `ccuv dashboard spotlight-wide` | Best for prioritizing Timeline trends. Timeline-led. | <img src="docs/assets/readme/dashboard-spotlight-wide.png" alt="Preview" width="180"> |
 | `spotlight-wide2` | `ccuv dashboard spotlight-wide2` | Best for prioritizing Timeline and Stack together. Timeline + Stack-led. | <img src="docs/assets/readme/dashboard-spotlight-wide2.png" alt="Preview" width="180"> |
 
+> [!TIP]
+> Both shipped clock presets display a localized time-state Overlay at bottom-right
+> by default. It follows the local wall clock and can be adjusted for the current
+> Dashboard session.
+
 > [!TIP]
 > Dashboard coordinates pane queries: identical in-flight provider requests are
 > shared, avoiding duplicate work while multiple panes refresh.
 
+## Animation overlays
+
+Add run-local context to a standalone animation or an explicit Dashboard Animation
+Pane: place static text, show a localized time state, or render output from a
+trusted local command.
+
+```bash
+ccuv animate rain --overlay-text "Focus time"
+ccuv animate analog-clock --overlay-command "ccuv text time-state --run"
+ccuv animate rain --overlay-command "date"
+```
+
+> [!WARNING]
+> `--overlay-command` runs user-supplied local shell code. It inherits every
+> environment variable visible to `ccuv` at launch, so treat commands and their
+> execution environment as trusted local code.
+
+See the [usage guide](docs/usage.md) for Overlay options, refresh behavior, and
+Dashboard Animation Pane syntax.
+
 ## Standalone views
 
 Choose a standalone view when you need to focus on one question rather than an

{ccusage_viz-0.2.0 → ccusage_viz-0.2.2}/README.md

@@ -4,7 +4,7 @@
 
 [![PyPI](https://img.shields.io/pypi/v/ccusage-viz.svg)](https://pypi.org/project/ccusage-viz/) [![Python](https://img.shields.io/pypi/pyversions/ccusage-viz.svg)](https://pypi.org/project/ccusage-viz/) [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](LICENSE) [![CI](https://github.com/Cookie-HOO/ccusage-viz/actions/workflows/ci.yml/badge.svg)](https://github.com/Cookie-HOO/ccusage-viz/actions/workflows/ci.yml)
 
-> **Alpha · 0.2.0** — interfaces may change before 1.0. See the [roadmap](ROADMAP.md) for current direction.
+> **Alpha · 0.2.2** — interfaces may change before 1.0. See the [roadmap](ROADMAP.md) for current direction.
 
 `ccusage-viz` is an independent, unofficial terminal visualizer for
 [`ccusage`](https://github.com/ryoppippi/ccusage) token data. It turns
@@ -37,6 +37,12 @@ pricing, balances, quotas, allowances, or other non-token account analytics.
 > This project is not affiliated with or endorsed by the `ccusage` project or
 > its maintainers.
 
+## Interactive Help
+
+Every interactive view provides Help: press `h` whenever you need to see its
+available controls. While editing Overlay text or a command, use `Ctrl-H`
+instead so the literal `h` remains available to the draft.
+
 ## Dashboard presets
 
 `dashboard` composes independently configured charts in one terminal. The default
@@ -56,10 +62,35 @@ ccuv dashboard
 | `spotlight-wide` | `ccuv dashboard spotlight-wide` | Best for prioritizing Timeline trends. Timeline-led. | <img src="docs/assets/readme/dashboard-spotlight-wide.png" alt="Preview" width="180"> |
 | `spotlight-wide2` | `ccuv dashboard spotlight-wide2` | Best for prioritizing Timeline and Stack together. Timeline + Stack-led. | <img src="docs/assets/readme/dashboard-spotlight-wide2.png" alt="Preview" width="180"> |
 
+> [!TIP]
+> Both shipped clock presets display a localized time-state Overlay at bottom-right
+> by default. It follows the local wall clock and can be adjusted for the current
+> Dashboard session.
+
 > [!TIP]
 > Dashboard coordinates pane queries: identical in-flight provider requests are
 > shared, avoiding duplicate work while multiple panes refresh.
 
+## Animation overlays
+
+Add run-local context to a standalone animation or an explicit Dashboard Animation
+Pane: place static text, show a localized time state, or render output from a
+trusted local command.
+
+```bash
+ccuv animate rain --overlay-text "Focus time"
+ccuv animate analog-clock --overlay-command "ccuv text time-state --run"
+ccuv animate rain --overlay-command "date"
+```
+
+> [!WARNING]
+> `--overlay-command` runs user-supplied local shell code. It inherits every
+> environment variable visible to `ccuv` at launch, so treat commands and their
+> execution environment as trusted local code.
+
+See the [usage guide](docs/usage.md) for Overlay options, refresh behavior, and
+Dashboard Animation Pane syntax.
+
 ## Standalone views
 
 Choose a standalone view when you need to focus on one question rather than an

{ccusage_viz-0.2.0 → ccusage_viz-0.2.2}/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 [![PyPI](https://img.shields.io/pypi/v/ccusage-viz.svg)](https://pypi.org/project/ccusage-viz/) [![Python](https://img.shields.io/pypi/pyversions/ccusage-viz.svg)](https://pypi.org/project/ccusage-viz/) [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](LICENSE) [![CI](https://github.com/Cookie-HOO/ccusage-viz/actions/workflows/ci.yml/badge.svg)](https://github.com/Cookie-HOO/ccusage-viz/actions/workflows/ci.yml)
 
-> **Alpha · 0.2.0** — 在 1.0 前接口仍可能变化。当前方向请见[路线图](ROADMAP.md)。
+> **Alpha · 0.2.2** — 在 1.0 前接口仍可能变化。当前方向请见[路线图](ROADMAP.md)。
 
 `ccusage-viz` 是面向 [`ccusage`](https://github.com/ryoppippi/ccusage) Token
 数据的独立、非官方终端可视化工具。它把 `ccusage` 命令输出转换为交互式终端图表，
@@ -32,6 +32,10 @@ ccusage-viz 只关注 **Token 消耗** 与由 Token 消耗直接推导的指标
 
 > 本项目与 `ccusage` 项目及其维护者没有隶属关系，也未获得其背书。
 
+## 交互帮助
+
+所有交互式界面都提供帮助：不知道如何操作时，按 `h` 查看当前可用控制。编辑 Overlay 文本或命令时，请使用 `Ctrl-H`，这样字面量 `h` 仍可输入草稿。
+
 ## Dashboard 预设
 
 `dashboard` 将彼此独立配置的图表组合在同一终端中。默认预设为 `wide-clock`：
@@ -50,9 +54,27 @@ ccuv dashboard
 | `spotlight-wide` | `ccuv dashboard spotlight-wide` | 推荐用于优先关注 Timeline 趋势。Timeline 主导。 | <img src="docs/assets/readme/dashboard-spotlight-wide.png" alt="预览" width="180"> |
 | `spotlight-wide2` | `ccuv dashboard spotlight-wide2` | 推荐用于同时优先关注 Timeline 和 Stack。Timeline + Stack 主导。 | <img src="docs/assets/readme/dashboard-spotlight-wide2.png" alt="预览" width="180"> |
 
+> [!TIP]
+> 两个内置时钟预设默认都会在右下角展示本地化的时段状态 Overlay。它会随本地时间变化，且可在当前 Dashboard 会话中调整。
+
 > [!TIP]
 > Dashboard 会协调 Pane 查询：多个 Pane 刷新时，相同的进行中 Provider 请求会被共享，避免重复工作。
 
+## 动画 Overlay
+
+为独立动画或显式指定的 Dashboard 动画 Pane 添加仅在当前运行中生效的上下文：可以展示静态文本、本地化时段状态，或展示受信任本地命令的输出。
+
+```bash
+ccuv animate rain --overlay-text "Focus time"
+ccuv animate analog-clock --overlay-command "ccuv text time-state --run"
+ccuv animate rain --overlay-command "date"
+```
+
+> [!WARNING]
+> `--overlay-command` 会运行用户提供的本地 shell 代码。它会继承 `ccuv` 启动时可见的全部环境变量，因此应将命令及其执行环境视为受信任的本地代码。
+
+Overlay 参数、刷新行为与 Dashboard 动画 Pane 语法请参阅[使用指南](docs/usage.zh-CN.md)。
+
 ## 独立视图
 
 当你需要聚焦于单一问题，而不是使用由多个 Pane 组成的总览时，请选择独立视图。

{ccusage_viz-0.2.0 → ccusage_viz-0.2.2}/docs/architecture.md

@@ -247,8 +247,12 @@ Animation is a separate resource kind, not a Chart variant and not an implicit p
 
 `term-animate` remains a pure projection dependency. ccuv owns terminal lifecycle, input, viewport allocation, session clocks, repaint deadlines, clipping, and cleanup, while named library themes remain library-owned. It passes active/idle state only to effects that declare state support. An animation Pane owns no Provider, query runtime, scheduler, or lifecycle operation.
 
+An Overlay is a host-local presentation resource, owned by its standalone animation host or Dashboard Animation Pane rather than by a Chart, Provider, or the animation library. Static text needs no schedule. A command Overlay owns its local shell execution schedule, bounded result history, and sanitized display output; its lifecycle ends with its host. Overlay repaint and command deadlines can redraw only their existing host frame and never start a token-data query.
+
 Monitor attachments are local to their Monitor Pane or standalone Monitor host and are disabled by default. Users enable one from the advanced ranking/list controls; it then renders after a comparable accepted interval is available and uses ccuv's accepted token-delta decision to choose active versus idle for effects that declare state support. Their repaint deadlines redraw the existing frame only; they never initiate a query. Enabled attachments begin with the `classic` theme; advanced controls cycle all library-declared Monitor effects and then ccuv-local `none`. This transient `none` state retains no catalog effect, creates no provider work, and is unavailable to standalone animation and Dashboard animation panes.
 
+Dashboard undo/redo is likewise bounded, session-only UI state owned by the Dashboard Host. It records Dashboard-state-represented composition and settings, never Provider results, Chart facts, or persisted configuration. It does not restore host-local Overlay drafts, position or offset mutations, or command-result history.
+
 Chart Components require Query and Result Processing; animation projection does not. The shared terminal Frame and Painter infrastructure composes their output without turning animation into a chart component or widening chart/provider dependencies.
 
 ## Dependency direction

{ccusage_viz-0.2.0 → ccusage_viz-0.2.2}/docs/architecture.zh-CN.md

@@ -251,12 +251,19 @@ Animation 是独立资源类型，不是 Chart 变体，也不是所有图表默
 裁剪和清理，而具名主题仍由动画库负责。它只向声明支持状态的效果传递 active/idle。动画 Pane 不拥有 Provider、
 查询运行时、scheduler 或 lifecycle operation。
 
+Overlay 是 Host 本地拥有的呈现资源，归属独立动画 Host 或 Dashboard 动画 Pane，而不归属 Chart、Provider 或动画库。
+静态文本不需要调度；命令 Overlay 拥有自身的本地 shell 执行调度、有界结果历史和净化后的展示输出，其生命周期随 Host
+结束。Overlay 的重绘与命令 deadline 只能重绘已有 Host Frame，绝不会发起 Token 数据查询。
+
 Monitor 附件只属于其所在的 Monitor Pane 或独立 Monitor Host，默认关闭。用户可在 ranking/list 视图的高级
 控制中启用；已有可比较的已接受 interval 后它才渲染，并用 ccuv 已接受的 Token 增量为声明支持状态的效果决定
 active 或 idle。附件 deadline 只重绘当前 Frame，绝不会发起查询。启用的附件使用 `classic` 主题；高级控制会循环
 全部动画库声明为 Monitor 可用的效果，随后进入 ccuv 本地的`无`。这个临时`无`状态不属于 catalog、不创建 provider
 工作，也不能用于独立动画或 Dashboard 动画 Pane。
 
+Dashboard 的撤销/重做同样是 Dashboard Host 拥有的、有界且仅会话内存在的 UI 状态。它只记录 Dashboard 状态所表示的组合与设置，
+绝不记录 Provider 结果、Chart 事实或持久化配置，也不会恢复 Host 本地的 Overlay 草稿、位置或偏移修改、命令结果历史。
+
 Chart Component 需要 Query 与 Result Processing；动画投影不需要。两者共享终端 Frame 与 Painter 基础设施来组合输出，
 但 Animation 不会变成 Chart Component，也不会扩大 chart/provider 的依赖方向。
 

{ccusage_viz-0.2.0 → ccusage_viz-0.2.2}/docs/assets/readme/README.md

@@ -7,7 +7,7 @@ Chinese READMEs. Both landing pages use these exact names and paths.
 
 | File | Used for | Command represented |
 | --- | --- | --- |
-| `dashboard-wide-clock.png` | Default Dashboard: wide layout with a digital-clock Pane | `ccuv dashboard` / `ccuv dashboard wide-clock` |
+| `dashboard-wide-clock.png` | Default Dashboard: wide layout with an analog-clock Pane | `ccuv dashboard` / `ccuv dashboard wide-clock` |
 | `dashboard-narrow-clock.png` | Narrow Dashboard with a digital-clock Pane | `ccuv dashboard narrow-clock` |
 | `dashboard-wide.png` | Balanced 2×2 Dashboard overview | `ccuv dashboard wide` |
 | `dashboard-narrow.png` | Compact, vertically focused Dashboard | `ccuv dashboard narrow` |

{ccusage_viz-0.2.0 → ccusage_viz-0.2.2}/docs/design-philosophy.md

@@ -4,19 +4,21 @@ This document records the stable product concepts and design constraints of `ccu
 
 ## Product boundaries and forms
 
-1. **The product expresses token consumption and directly supported derivatives only.**
+1. **Token analytics express token consumption and directly supported derivatives only.**
 
    A token metric belongs only when a data source can express it directly and reliably. TPM is currently the only rate metric. Cost, monetary estimates, call or request counts, quotas, QPM, rate limits, and other metrics inferred from token counts are outside the product boundary.
 
-2. **Standalone and Dashboard are the two product forms.**
+   Provider-free animations, clocks, and their run-local Overlays are presentation resources, not token analytics. They may show static context, local-time state, or trusted local-command output, but they neither create a token metric nor query a Provider.
 
-   Every interactive chart interface is a TUI. Standalone runs Timeline, Calendar, Stack, Ranking, or Monitor independently. Dashboard organizes multiple independently configured charts in one TUI.
+2. **Standalone and Dashboard are the two host forms.**
 
-3. **A Pane preserves its corresponding Standalone data and chart semantics.**
+   Every interactive chart interface is a TUI. Standalone runs Timeline, Calendar, Stack, Ranking, or Monitor independently, and also hosts provider-free Animation. Dashboard organizes independently configured Chart and Animation Panes in one TUI. Animation is a playback surface rather than a Token chart; it may own a declarative Overlay source and run-local presentation state.
 
-   A Pane is a contextual superset of Standalone content. It adds composition concerns such as focus, placement, ordering, and switching, but Dashboard behavior must not change the underlying chart's time or metric contract.
+3. **A Chart Pane preserves its corresponding Standalone data and chart semantics.**
 
-   **Exception:** Dashboard owns Pane refresh and sampling cadence. Copying a Pane as a Standalone command materializes the corresponding Interval.
+   A Chart Pane is a contextual superset of Standalone chart content. It adds composition concerns such as focus, placement, ordering, and switching, but Dashboard behavior must not change the underlying chart's time or metric contract.
+
+   **Exception:** Dashboard owns refresh cadence for historical Chart Panes and sampling cadence for Monitor Panes. Copying either as a Standalone command materializes the corresponding Interval. Animation Panes have neither data cadence nor a Provider lifecycle: their hosts instead own playback clocks and repaint deadlines.
 
 ## Configuration ownership
 
@@ -27,7 +29,7 @@ This document records the stable product concepts and design constraints of `ccu
    | Independent Dashboard setting | Scope | Pane behavior |
    | --- | --- | --- |
    | Layout, Weights, focus, Pane order | Dashboard geometry and navigation | Not part of Pane configuration |
-   | Global pause, Controls | Dashboard session shell | A Pane owns no local pause or Controls state |
+   | Global pause, Controls | Dashboard session shell | Chart Panes own no local data pause or Controls state; an Animation Pane owns local playback pause while it is being adjusted |
    | Dashboard Theme and Style | Shell, Header, and Summary | Does not change Pane Theme or chart Style |
    | Header Style and Summary period | Dashboard Header | Does not change Pane Density, Scope, or Granularity |
 
@@ -46,9 +48,13 @@ This document records the stable product concepts and design constraints of `ccu
    | Theme, Style, Density, and Legend | Each Pane defines chart presentation; Theme does not inherit Dashboard Theme |
    | Chart-specific settings | Belong only to the corresponding Pane |
 
-   Pane configuration and Pane fragments must not contain Demo Mode or Demo Size. Standalone still owns its own Demo settings, Interval, refresh, and pause behavior. Every Pane must remain independently explainable; copying it as Standalone materializes the necessary Dashboard-owned context.
+   Chart Pane fragments do not contain Dashboard- or host-owned lifecycle settings such as Demo mode, Watch/Interval, ASCII, or refresh cadence. Animation Pane fragments may additionally carry their declarative Overlay source and presentation settings. Standalone still owns its own Demo settings, Interval, refresh, and pause behavior. Every Pane must remain independently explainable; copying a Chart Pane as Standalone materializes the necessary Dashboard-owned context.
+
+2. **Command Overlays are bounded trusted-local presentation work.**
 
-2. **Process context is not Pane configuration.**
+   An Overlay has exactly one source: static text or a command. A command Overlay runs through the local shell with stdin disabled, a bounded execution time and output, sanitized display text, and bounded run-local result history. It inherits the environment visible to ccuv at launch, so the command and its execution environment are trusted-local input. Its execution and repaint deadlines are host-local presentation work: they never create a Token query or alter Provider scheduling.
+
+3. **Process context is not Pane configuration.**
 
    Language, the `ccusage` executable, query timeout, and Provider execution environment apply uniformly within the process and are not Pane-overridable settings.
 
@@ -138,13 +144,13 @@ This document records the stable product concepts and design constraints of `ccu
 
    A persistent, copyable setting whose states users compare or change at runtime is expressed as a valued CLI mode even when it currently has only two states. The CLI, TUI, status display, and copied command share the same concepts and canonical values. This keeps commands self-describing without requiring users to remember defaults or translate between a TUI state and a positive or negative flag. For example, Weekdays and Other use `show | hide`, while Stack Cache uses `combined | split`. Compact commands may omit default modes; Full commands state every effective mode explicitly.
 
-   **Exception:** A conspicuous capability choice or execution-lifecycle exception that is normally absent may remain a flag when its presence fully expresses the intent and it is not an ordinary runtime-adjustable setting. ASCII and Historical no-Watch are the current exceptions. Mode consistency must not create redundant controls for behavior already owned by a higher-level setting such as Density, Style, or Layout.
+   **Exception:** A conspicuous capability choice or execution-lifecycle exception that is normally absent may remain a flag when its presence fully expresses the intent and it is not an ordinary runtime-adjustable setting. ASCII and Historical no-Watch are the current exceptions. A deprecated compatibility flag is not a current product surface: it is neither promoted in user documentation nor used by copied commands. Mode consistency must not create redundant controls for behavior already owned by a higher-level setting such as Density, Style, or Layout.
 
 3. **Quick and Advanced reveal capability progressively.**
 
    Quick and Advanced are divided by usage frequency rather than an internal distinction between data and appearance. Quick covers Data Scope, analysis, and primary presentation in common analytical workflows. Advanced contains infrequent, precise, or conditional controls. Both operate on the same immediate configuration, and contextually meaningless options are omitted rather than shown disabled.
 
-   Standalone uses exactly two rows: current runtime status plus effective settings, then the active Quick or Advanced actions. Dashboard-global adjustment has one Dashboard-wide page for Theme, Style, Header, Summary, and Layout; it has no Advanced page or Pane-specific actions. A Dashboard Pane in chart view begins with the same two chart rows as Standalone, followed by Dashboard-management rows for content/lifecycle, position/focus, and logical size ratios. `a` switches only the chart action row; Dashboard management remains available on either page. A Pane text view is instead a read-only inspection context: it keeps only its reading/copy/view controls visible; lifecycle operations such as `r` and Space are not hidden-but-active commands; and chart adjustment and Dashboard management remain suppressed while text is shown. Enter, Escape, and the inactivity timeout finish adjustment by restoring ordinary chart browsing for the Dashboard and every Pane, without rolling back already-effective changes. The inactivity timeout belongs only to an active adjustment session, not to ordinary browse-mode text inspection. There is no clickable Finish target. On narrow terminals, complete low-priority action units are omitted and `…(+N)` reports the exact number still available by keyboard, while page identity, the `a` switch, and Enter/Escape guidance remain visible.
+   Standalone uses exactly two rows: current runtime status plus effective settings, then the active Quick or Advanced actions. Dashboard-global adjustment has one Dashboard-wide page for Theme, Style, Header, Summary, and Layout; it has no Advanced page or Pane-specific actions. A Dashboard Chart Pane in chart view begins with the same two chart rows as Standalone, followed by Dashboard-management rows for content/lifecycle, position/focus, and logical size ratios. An Animation Pane instead exposes its own playback, theme/style, and Overlay controls; it does not inherit chart data controls. `a` switches the active Pane's applicable action page; Dashboard management remains available on either page. A Chart-Pane text view is a read-only inspection context: only navigation, copy, and view cycling remain available, while lifecycle, configuration, and Dashboard-management keys are unavailable until returning to Chart view. Enter, Escape, and the inactivity timeout finish adjustment by restoring ordinary chart browsing for the Dashboard and every Pane, without rolling back already-effective changes. The inactivity timeout belongs only to an active adjustment session, not to ordinary browse-mode text inspection. There is no clickable Finish target. On narrow terminals, complete low-priority action units are omitted and `…(+N)` reports the exact number still available by keyboard, while page identity, the `a` switch, and Enter/Escape guidance remain visible.
 
 4. **Finite choices preserve and truthfully display any valid startup value.**
 
@@ -156,7 +162,7 @@ This document records the stable product concepts and design constraints of `ccu
 
    Most settings commit on each adjustment. The visible configuration updates at once, and any data already derivable from accepted facts is recomputed immediately. Enter and Escape therefore have the same meaning in an ordinary settings surface: both leave the surface while preserving the effective state. They do not save, discard, or roll back changes that have already taken effect. Layout and Weights follow the same rule.
 
-   **Exception:** An operation that cannot produce a valid value until the user completes input or selection uses an isolated draft: Filter, numeric Grid, Pane Replace, and Pane Add. Enter commits a valid complete draft and Escape discards only that child operation, returning to its parent adjustment. Dashboard `z` is an immediate layout-shortcut selection: `wide`, `narrow`, `all`, and `auto` select rectangular shortcuts, while the three Spotlight choices select non-rectangular topology. It changes geometry only and preserves the existing Pane objects, ordering, focus, accepted data, configuration, Monitor history, and lifecycles. `Z` opens the numeric Grid draft, which accepts only `ROWSxCOLUMNS`; from `auto` or Spotlight it starts at the smallest practical two-column grid for the existing Pane count. Applying either operation rebuilds equal Weights for the resulting topology. Pane Replace atomically installs a fresh default Pane at the same list index and retires the displaced lifecycle. Pane Add uses `N` for before and `n` for after the focused Pane's list index. Fixed layouts preserve their column count and expand their row count when insertion requires capacity; deletion reclaims only wholly empty trailing rows. A second confirmation is reserved for consequences that are destructive, difficult to reverse, or otherwise unclear; ordinary reversible configuration does not require one.
+   **Exception:** An operation that cannot produce a valid value until the user completes input or selection uses an isolated draft: Filter, Overlay source editing, numeric Grid, Pane Replace, and Pane Add. Enter commits a valid complete draft and Escape discards only that child operation, returning to its parent adjustment. Dashboard `z` opens a layout chooser: `j`/`k` or the arrow keys select `wide`, `narrow`, `all`, `auto`, or a Spotlight topology; Enter commits and Escape cancels. A committed choice changes geometry only and preserves existing Pane objects, ordering, focus, accepted data, configuration, Monitor history, and lifecycles. `Z` opens the numeric Grid draft, which accepts only `ROWSxCOLUMNS`; from `auto` or Spotlight it starts at the smallest practical two-column grid for the existing Pane count. Applying either operation rebuilds equal Weights for the resulting topology. Pane Replace atomically installs a fresh default Pane at the same list index and retires the displaced lifecycle. Pane Add uses `N` for before and `n` for after the focused Pane's list index. Fixed layouts preserve their column count and expand their row count when insertion requires capacity; deletion reclaims only wholly empty trailing rows. A second confirmation is reserved for consequences that are destructive, difficult to reverse, or otherwise unclear; ordinary reversible configuration does not require one.
 
 6. **Committed configuration and displayed data must describe the same state.**
 
@@ -166,15 +172,19 @@ This document records the stable product concepts and design constraints of `ccu
 
 7. **Keys express stable concepts, not a generic capitalization rule.**
 
-   `m` always means modify the current chart: it modifies the current view in Standalone and the current Pane in Dashboard browse mode; clicking a Pane selects it and performs the equivalent action. Uppercase `G` opens Dashboard-global settings, and clicking the Header is equivalent. Uppercase letters do not generally reverse their lowercase options. Related keys may instead represent distinct, stable families of the same concept: `p` cycles common trailing periods, while `P` cycles common natural periods to date. The interface names the active family so a calendar-aligned period is not mistaken for a trailing duration.
+   `m` means modify the current visual resource: it modifies the current Standalone chart or animation, and the selected Dashboard Pane in browse mode. A primary click selects or arms a Pane; double-click enters Pane adjustment. While adjusting, double-clicking another Pane transfers focus. `d` opens Dashboard-global settings. Uppercase letters do not generally reverse their lowercase options. Related keys may instead represent distinct, stable families of the same concept: `p` cycles common trailing periods, while `P` cycles common natural periods to date. The interface names the active family so a calendar-aligned period is not mistaken for a trailing duration.
 
    **Exception:** Theme has a large, growing choice set, so `t` advances and `T` reverses. `N` and `n` are the deliberate semantic pair for inserting a Pane before or after the focused Pane's list index. Other ordinary letter actions are lowercase-only.
 
-8. **Directional operations support both arrow keys and `hjkl`.**
+8. **Non-text directional surfaces support both arrow keys and `hjkl`.**
+
+   A navigation or adjustment surface that is not a text editor must also accept `k`, `j`, `h`, or `l` respectively and perform the identical state transition. Controls may combine both key sets in space-sensitive guidance, but the two entry paths must never differ in boundaries, cycling, or confirmation behavior. Text editors retain their own text-entry contract.
 
-   Any context that offers up, down, left, or right navigation or adjustment must also accept `k`, `j`, `h`, or `l` respectively and perform the identical state transition. Controls may combine both key sets in space-sensitive guidance, but the two entry paths must never differ in boundaries, cycling, or confirmation behavior.
+9. **Help is contextual, read-only evidence of the active surface.**
 
-9. **Responsibility boundaries prevent semantic confusion rather than useful multiple entry points.**
+   Help reflects the current mode, page, Pane kind, dialog, editor, and history surface rather than restating a fixed global key map. It does not mutate configuration or create work, and its content must remain aligned with the controls currently available.
+
+10. **Responsibility boundaries prevent semantic confusion rather than useful multiple entry points.**
 
    Standalone, Dashboard, and Pane share terminology, ordering, state representation, and adjustment behavior, but each operation appears only where its target is unambiguous. Multiple entry points are valid when they express the same intent and produce the same result. One interaction concept must not silently change another; for example, changing Granularity does not change Period.
 
@@ -246,9 +256,9 @@ This document records the stable product concepts and design constraints of `ccu
 
 7. **Refresh includes the reconciliation and repaint required by its results.**
 
-   `r` always refreshes the current context. Sorting, derived computation, and full repaint caused by refreshed data are consequences of that same operation, not separate re-sort or repaint commands. A Dashboard manual refresh gives every component an immediate refresh opportunity, invalidates the paint cache, and covers the full Dashboard. Resume performs the same refresh and repaint before fixed Ticks continue. Resize automatically recomputes all geometry and clears obsolete regions without requiring a data query. Full repaint does not imply an unconditional terminal clear.
+   `r` always refreshes the current data-bearing context. Sorting, derived computation, and full repaint caused by refreshed data are consequences of that same operation, not separate re-sort or repaint commands. A Dashboard manual refresh gives the Header and Chart Panes an immediate refresh opportunity, invalidates the paint cache, and covers the full Dashboard. Resume performs the same refresh and repaint before fixed Ticks continue. Resize automatically recomputes all geometry and clears obsolete regions without requiring a data query. Animation playback, Overlay execution, and Monitor-attachment repaint use their own host-local deadlines rather than this data-refresh operation. Full repaint does not imply an unconditional terminal clear.
 
-   **Exception:** Pause stops periodic Ticks only. Paused time creates no periodic work or backlog, while manual refresh and a one-shot completion debounced from an explicit configuration change may still run. Such completion does not resume periodic scheduling. A Monitor baseline, sampling gap, pause/resume, data-affecting reconfiguration, or counter reset clears the separate current observation until the next valid sample pair; retained Timeline history remains available and discontinuities remain Gaps. Standalone Watch and Monitor retain their own refresh, pause, and Interval behavior.
+   **Exception:** Dashboard browse-mode pause stops periodic data Ticks and pauses every Animation Pane's playback; paused time creates no periodic work or backlog, while manual refresh and a one-shot completion debounced from an explicit configuration change may still run. Such completion does not resume periodic scheduling. While adjusting an Animation Pane, Space instead controls only that Pane's playback clock. A Monitor baseline, sampling gap, pause/resume, data-affecting reconfiguration, or counter reset clears the separate current observation until the next valid sample pair; retained Timeline history remains available and discontinuities remain Gaps. A Monitor attachment uses accepted delta state for active/idle projection and may repaint its idle scene without advancing token observation or starting a query. Standalone Watch and Monitor retain their own refresh, pause, and Interval behavior.
 
 ## Reproducibility and documentation boundaries
 
@@ -260,14 +270,18 @@ This document records the stable product concepts and design constraints of `ccu
 
    A Preset supplies a complete Dashboard base state that may receive explicit startup overrides or appended Panes. Without a Preset, a command must explicitly provide a Pane, except for bare `dashboard`. Runtime `z` deliberately does not apply a Preset's content template: it retains the current Pane list and selects only the corresponding geometry. Copied commands expand actual Pane state and preserve the active layout rather than relying on a source Preset name.
 
-3. **Session state is excluded from reproducible configuration.**
+3. **Run-local presentation state is excluded from reproducible configuration.**
+
+   Current focus, pause state, Controls visibility, inspection view, transient errors, Animation playback, Overlay offset, and Overlay command-result history belong to the running session and do not enter copied commands. Declarative Overlay source and display settings can be copied with their Animation Pane, but an editor draft cannot.
+
+4. **Undo/redo is bounded session navigation, not persistence.**
 
-   Current focus, pause state, Controls visibility, inspection view, and transient errors belong to the running session and do not enter copied commands.
+   `u` and `U` undo and redo Dashboard configuration edits through a bounded, session-local history; a new edit after undo replaces the redo branch. History restores only Dashboard-state-represented composition and settings. It does not restore Overlay source drafts, Overlay position or offset mutations, command records, command-history state, Provider results, or chart facts, and it never enters copied commands.
 
-4. **Design philosophy records stable constraints only.**
+5. **Design philosophy records stable constraints only.**
 
    Complete CLI spelling, option matrices, key maps, Preset contents, and operating examples belong in user guides. Component interfaces, state machines, and test criteria belong in formal design specifications. A new feature should fit one of these principles; any necessary exception must state its boundary explicitly.
 
-5. **Documentation is layered by depth and kept consistent in one maintenance pass.**
+6. **Documentation is layered by depth and kept consistent in one maintenance pass.**
 
    The README builds first-contact understanding through natural explanations and a small product map. Architecture documents define implemented ownership and runtime boundaries, while design philosophy explains stable principles and reasons. Formal design specifications preserve decisions and test criteria; the roadmap describes planned work only. English and Simplified Chinese documents must describe the same contracts, and changes to terminology, defaults, or ownership are reconciled across these layers rather than deferred.

{ccusage_viz-0.2.0 → ccusage_viz-0.2.2}/docs/design-philosophy.zh-CN.md

@@ -4,19 +4,21 @@
 
 ## 产品边界与形态
 
-1. **产品只表达 Token 消耗及受支持的直接衍生指标。**
+1. **Token 分析只表达 Token 消耗及受支持的直接衍生指标。**
 
    只有数据源能够直接且可靠表达的 Token 指标才进入产品。目前唯一的速率指标是 TPM。费用、金额估算、调用或请求次数、配额、QPM、速率限制，以及从 Token 数量推测出的其他指标均不在产品范围内。
 
-2. **Standalone 和 Dashboard 是两种产品形态。**
+   不依赖 Provider 的动画、时钟及其仅在当前运行中存在的 Overlay 属于呈现资源，不属于 Token 分析。它们可以展示静态上下文、本地时间状态或受信任本地命令输出，但既不会创建 Token 指标，也不会查询 Provider。
 
-   每个交互式图表界面都是 TUI。Standalone 独立运行 Timeline、Calendar、Stack、Ranking 或 Monitor；Dashboard 在一个 TUI 中组织多张独立配置的图表。
+2. **Standalone 和 Dashboard 是两种 Host 形态。**
 
-3. **Pane 保留对应 Standalone 的数据与图表语义。**
+   每个交互式图表界面都是 TUI。Standalone 独立运行 Timeline、Calendar、Stack、Ranking 或 Monitor，也可承载不依赖 Provider 的 Animation；Dashboard 在一个 TUI 中组织独立配置的图表 Pane 与动画 Pane。Animation 是播放表面而非 Token 图表；它可以拥有声明式 Overlay 来源与仅在本次运行中存在的呈现状态。
 
-   Pane 是 Standalone 内容在 Dashboard 上下文中的超集，只增加焦点、位置、顺序和切换等组合能力。Dashboard 行为不得改变底层图表的时间或指标契约。
+3. **图表 Pane 保留对应 Standalone 的数据与图表语义。**
 
-   **例外：**Pane 的刷新与采样节奏由 Dashboard 统一拥有；复制为 Standalone 命令时再物化对应 Interval。
+   图表 Pane 是 Standalone 图表内容在 Dashboard 上下文中的超集，只增加焦点、位置、顺序和切换等组合能力。Dashboard 行为不得改变底层图表的时间或指标契约。
+
+   **例外：**Dashboard 拥有历史图表 Pane 的刷新节奏和 Monitor Pane 的采样节奏；复制为 Standalone 命令时再物化对应 Interval。动画 Pane 没有数据节奏或 Provider 生命周期，而是由其 Host 拥有播放时钟和重绘 deadline。
 
 ## 配置所有权
 
@@ -27,7 +29,7 @@
    | Dashboard 独立设置 | 作用范围 | Pane 行为 |
    | --- | --- | --- |
    | Layout、Weights、焦点、Pane 顺序 | Dashboard 几何与导航 | 不构成 Pane 配置 |
-   | 全局暂停、Controls | Dashboard 会话外壳 | Pane 不拥有局部暂停或 Controls 状态 |
+   | 全局暂停、Controls | Dashboard 会话外壳 | 图表 Pane 不拥有局部数据暂停或 Controls 状态；调整动画 Pane 时，该 Pane 拥有局部播放暂停 |
    | Dashboard Theme、Style | 外壳、Header 与 Summary | 不改变 Pane Theme 或图表 Style |
    | Header Style、Summary 周期 | Dashboard Header | 不改变 Pane Density、Scope 或 Granularity |
 
@@ -46,9 +48,13 @@
    | Theme、Style、Density、Legend | 每个 Pane 独立定义图表呈现；Theme 不继承 Dashboard Theme |
    | 图表专属设置 | 只属于对应 Pane |
 
-   Pane 配置和 Pane 片段不得包含 Demo Mode 或 Demo Size。Standalone 仍独立拥有自己的 Demo 设置、Interval、刷新和暂停行为。每个 Pane 都必须可以独立解释；复制为 Standalone 时再物化 Dashboard 拥有的必要上下文。
+   图表 Pane 片段不得包含 Dashboard 或 Host 拥有的生命周期设置，例如 Demo 模式、Watch/Interval、ASCII 或刷新节奏。动画 Pane 片段还可以包含声明式 Overlay 来源及其呈现设置。Standalone 仍独立拥有自己的 Demo 设置、Interval、刷新和暂停行为。每个 Pane 都必须可以独立解释；复制图表 Pane 为 Standalone 时再物化 Dashboard 拥有的必要上下文。
+
+2. **命令 Overlay 是有界的受信任本地呈现工作。**
 
-2. **进程上下文不是 Pane 配置。**
+   Overlay 恰有一个来源：静态文本或命令。命令 Overlay 通过本地 shell 运行，stdin 禁用，执行时间与输出有界，展示文本会被净化，命令结果历史只在本次运行中有界保留。它继承 ccuv 启动时可见的环境，因此命令及其执行环境属于受信任本地输入。其执行和重绘 deadline 是 Host 本地呈现工作：绝不会创建 Token 查询或改变 Provider 调度。
+
+3. **进程上下文不是 Pane 配置。**
 
    Language、`ccusage` 可执行文件、查询超时和 Provider 执行环境在进程内统一生效，但不构成 Pane 的可覆盖设置。
 
@@ -138,13 +144,13 @@
 
    对于可持久化、可复制，并由用户在运行时比较或调整的设置，即使当前只有两个状态，CLI 也使用带值参数明确表达模式。CLI、TUI、状态展示与复制命令共享同一组概念和规范值，使命令无需依赖默认值，也无需在 TUI 状态与正向或否定 Flag 之间转换。例如，Weekdays 与 Other 使用 `show | hide`，Stack Cache 使用 `combined | split`。Compact Command 可以省略默认模式；Full Command 必须显式列出全部有效模式。
 
-   **例外：**通常不出现、参数本身即可完整表达意图，且不属于普通运行时可调整设置的醒目能力选择或执行生命周期例外，可以保留为 Flag。当前例外是 ASCII 和 Historical no-Watch。模式统一不得为已经由 Density、Style 或 Layout 等上层设置完整控制的行为制造冗余开关。
+   **例外：**通常不出现、参数本身即可完整表达意图，且不属于普通运行时可调整设置的醒目能力选择或执行生命周期例外，可以保留为 Flag。当前例外是 ASCII 和 Historical no-Watch。已废弃的兼容 Flag 不属于当前产品表面：不会在用户文档中推广，也不会写入复制出的命令。模式统一不得为已经由 Density、Style 或 Layout 等上层设置完整控制的行为制造冗余开关。
 
 3. **能力通过 Quick 和 Advanced 渐进呈现。**
 
    Quick 与 Advanced 按使用频率划分，而不是按数据与外观的内部分类划分。Quick 覆盖常见分析流程中的 Data Scope、分析方式与主要呈现；Advanced 放置低频、精细或条件性控制。两者操作同一份即时配置，当前上下文无意义的选项应省略，而不是禁用后继续展示。
 
-   Standalone 只使用两行：第一行展示运行状态与当前生效设置，第二行展示当前 Quick 或 Advanced 操作。Dashboard 全局调整只有一个 Dashboard 级页面，用于 Theme、Style、Header、Summary 与 Layout；不提供 Advanced 页面或 Pane 专属操作。Dashboard Pane 处于图表视图时，先使用与 Standalone 相同的两行图表区域，再提供内容/生命周期、位置/焦点和逻辑尺寸比例等 Dashboard 管理操作。`a` 只切换图表操作行；Dashboard 管理操作在任一页面都可用。Pane 文字视图则是只读检查上下文：只保留阅读、复制与切换视图操作，`r` 和 Space 等生命周期操作不是隐藏但仍可用的命令，并在显示文字期间暂停图表调整与 Dashboard 管理。Enter、Escape 和无操作超时都会结束调整，将 Dashboard 与所有 Pane 恢复为普通图表浏览，同时保留已生效修改；该无操作超时只属于活跃的调整会话，不适用于普通浏览模式的文字检查视图。不提供可点击的“完成”。窄终端按完整操作单元隐藏低优先级项，并用 `…(+N)` 精确提示仍可通过键盘使用的操作数量；页面身份、`a` 切换与 Enter/Escape 提示始终保留。
+   Standalone 只使用两行：第一行展示运行状态与当前生效设置，第二行展示当前 Quick 或 Advanced 操作。Dashboard 全局调整只有一个 Dashboard 级页面，用于 Theme、Style、Header、Summary 与 Layout；不提供 Advanced 页面或 Pane 专属操作。Dashboard 图表 Pane 处于图表视图时，先使用与 Standalone 相同的两行图表区域，再提供内容/生命周期、位置/焦点和逻辑尺寸比例等 Dashboard 管理操作。动画 Pane 则提供自己的播放、主题/样式与 Overlay 控制，不继承图表数据控制。`a` 切换当前 Pane 适用的操作页；Dashboard 管理操作在任一页面都可用。图表 Pane 的文字视图是只读检查上下文：仅可导航、复制与切换视图；返回 Chart 视图前，生命周期、配置与 Dashboard 管理按键均不可用。Enter、Escape 和无操作超时都会结束调整，将 Dashboard 与所有 Pane 恢复为普通图表浏览，同时保留已生效修改；该无操作超时只属于活跃的调整会话，不适用于普通浏览模式的文字检查视图。不提供可点击的“完成”。窄终端按完整操作单元隐藏低优先级项，并用 `…(+N)` 精确提示仍可通过键盘使用的操作数量；页面身份、`a` 切换与 Enter/Escape 提示始终保留。
 
 4. **有限档位保留并如实显示合法启动值。**
 
@@ -156,7 +162,7 @@
 
    大部分设置在每次调整时立即提交；可见配置立即更新，能够从已接受事实推导的数据也立即重新计算。因此，普通设置界面中的 Enter 与 Escape 含义相同：都保留当前有效状态并离开界面。两者都不保存、放弃或回滚已经生效的修改。Layout 和 Weights 遵循同一规则。
 
-   **例外：**只有完成输入或选择后才能形成有效取值的操作使用隔离草稿，包括 Filter、数值 Grid、Pane Replace 与 Pane Add。Enter 提交完整且合法的草稿；Escape 只放弃当前子操作并返回父级调整。Dashboard 的 `z` 是即时生效的布局快捷方式选择：`wide`、`narrow`、`all` 和 `auto` 选择矩形快捷布局，三种 Spotlight 则选择非矩形拓扑。它只改变几何，保留现有 Pane 对象、顺序、焦点、已接受数据、配置、Monitor 历史和生命周期。`Z` 打开数值 Grid 草稿，只接受 `行x列`；从 `auto` 或 Spotlight 进入时，以可容纳现有 Pane 数量的最小实用双列网格开始。应用任一操作后，都为结果拓扑重建等权 Weights。Pane Replace 在原列表索引原子安装全新默认 Pane，并终止被替换 Pane 的生命周期。Pane Add 使用 `N` 在焦点 Pane 列表索引之前插入，使用 `n` 在其后插入。固定布局保留列数；插入需要更多容量时扩展行数，删除后只回收完全为空的末尾行。只有操作具有破坏性、难以恢复或后果不够清晰时才增加二次确认，普通可逆配置不需要确认。
+   **例外：**只有完成输入或选择后才能形成有效取值的操作使用隔离草稿，包括 Filter、Overlay 来源编辑、数值 Grid、Pane Replace 与 Pane Add。Enter 提交完整且合法的草稿；Escape 只放弃当前子操作并返回父级调整。Dashboard 的 `z` 打开布局选择器：`j`/`k` 或方向键选择 `wide`、`narrow`、`all`、`auto` 或 Spotlight 拓扑；Enter 确认，Escape 取消。确认后的选择只改变几何，保留现有 Pane 对象、顺序、焦点、已接受数据、配置、Monitor 历史和生命周期。`Z` 打开数值 Grid 草稿，只接受 `行x列`；从 `auto` 或 Spotlight 进入时，以可容纳现有 Pane 数量的最小实用双列网格开始。应用任一操作后，都为结果拓扑重建等权 Weights。Pane Replace 在原列表索引原子安装全新默认 Pane，并终止被替换 Pane 的生命周期。Pane Add 使用 `N` 在焦点 Pane 列表索引之前插入，使用 `n` 在其后插入。固定布局保留列数；插入需要更多容量时扩展行数，删除后只回收完全为空的末尾行。只有操作具有破坏性、难以恢复或后果不够清晰时才增加二次确认，普通可逆配置不需要确认。
 
 6. **已提交配置与展示数据必须描述同一状态。**
 
@@ -166,15 +172,19 @@
 
 7. **按键表达稳定概念，而不是通用大小写规则。**
 
-   `m` 始终表示修改当前图表：在 Standalone 中修改当前视图，在 Dashboard 浏览模式中修改当前 Pane；点击 Pane 会选择它并执行等价操作。大写 `G` 打开 Dashboard 全局设置，点击 Header 是等价入口。大写字母通常不反向循环对应小写选项。相关按键也可以分别代表同一概念下稳定且不同的类别：`p` 循环常用尾随周期，`P` 循环常用自然周期至今。界面必须标明当前类别，避免把自然周期误解为尾随时长。
+   `m` 表示修改当前视觉资源：在 Standalone 中修改当前图表或动画，在 Dashboard 浏览模式中修改已选 Pane。单击选择或准备 Pane；双击进入 Pane 调整。调整中双击另一 Pane 可转移焦点。`d` 打开 Dashboard 全局设置。大写字母通常不反向循环对应小写选项。相关按键也可以分别代表同一概念下稳定且不同的类别：`p` 循环常用尾随周期，`P` 循环常用自然周期至今。界面必须标明当前类别，避免把自然周期误解为尾随时长。
 
    **例外：**Theme 有较多且会增长的候选，保留 `t` 向前和 `T` 向后切换。`N` 与 `n` 是有意设计的语义对，分别在当前 Pane 列表索引之前或之后插入。其他普通字母操作只接受小写。
 
-8. **方向操作同时支持方向键与 `hjkl`。**
+8. **非文本编辑的方向操作同时支持方向键与 `hjkl`。**
+
+   不属于文本编辑器的导航或调整界面，都必须分别接受 `k`、`j`、`h`、`l`，并执行完全相同的状态变化。界面提示可以根据空间合并表达两组按键，但不能让两种入口产生不同边界、循环或确认行为。文本编辑器保留自己的文字输入契约。
 
-   任何提供上、下、左、右导航或调整的上下文，都必须分别接受 `k`、`j`、`h`、`l`，并执行完全相同的状态变化。界面提示可以根据空间合并表达两组按键，但不能让两种入口产生不同边界、循环或确认行为。
+9. **帮助是当前界面的上下文只读证据。**
 
-9. **职责边界防止语义混乱，而不是禁止有价值的多入口。**
+   帮助反映当前模式、页面、Pane 类型、对话框、编辑器和历史界面，而不是重复一份固定的全局按键表。它不修改配置、不创建工作，其内容必须与当前可用的控制保持一致。
+
+10. **职责边界防止语义混乱，而不是禁止有价值的多入口。**
 
    Standalone、Dashboard 和 Pane 共享术语、顺序、状态表达与调整行为，但一个操作只出现在目标明确的上下文中。多个入口可以表达同一意图，但必须产生相同结果。一个交互概念不得暗中改变另一个概念，例如调整 Granularity 不会改变 Period。
 
@@ -246,9 +256,9 @@
 
 7. **刷新包含结果所需的重新计算与重绘。**
 
-   `r` 始终刷新当前上下文；由刷新数据产生的排序、派生计算和完整重绘都是同一次操作的结果，不提供独立的重排或重绘命令。Dashboard 手动刷新向所有组件提供立即刷新机会，使绘制缓存失效并覆盖完整 Dashboard；继续执行同样的刷新与重绘后恢复固定 Tick。Resize 自动重算全部几何并清除旧区域，但不要求查询数据。完整重绘不等于无条件清屏。
+   `r` 始终刷新当前承载数据的上下文；由刷新数据产生的排序、派生计算和完整重绘都是同一次操作的结果，不提供独立的重排或重绘命令。Dashboard 手动刷新向 Header 和图表 Pane 提供立即刷新机会，使绘制缓存失效并覆盖完整 Dashboard；继续执行同样的刷新与重绘后恢复固定 Tick。Resize 自动重算全部几何并清除旧区域，但不要求查询数据。动画播放、Overlay 执行和 Monitor 附件重绘使用各自 Host 本地的 deadline，而不是这项数据刷新操作。完整重绘不等于无条件清屏。
 
-   **例外：**Pause 只停止周期 Tick；暂停期间不产生周期工作或积累 backlog，但手动刷新和用户修改配置后经防抖合并的一次性补齐仍可执行。此类补齐不会恢复周期调度。Monitor 建立基线、出现采样间隙、暂停/恢复、修改影响数据的配置或检测到计数器重置时，会清空独立的当前观测，直到形成下一组有效采样对；已保留的 Timeline 历史继续可用，不连续处仍显示为 Gap。Standalone Watch 与 Monitor 保留自己的刷新、暂停和 Interval 行为。
+   **例外：**Dashboard 浏览模式的暂停会停止周期数据 Tick，并暂停全部动画 Pane 的播放；暂停期间不产生周期工作或积累 backlog，但手动刷新和用户修改配置后经防抖合并的一次性补齐仍可执行。此类补齐不会恢复周期调度。调整动画 Pane 时，Space 则只控制该 Pane 的播放时钟。Monitor 建立基线、出现采样间隙、暂停/恢复、修改影响数据的配置或检测到计数器重置时，会清空独立的当前观测，直到形成下一组有效采样对；已保留的 Timeline 历史继续可用，不连续处仍显示为 Gap。Monitor 附件使用已接受的 delta 状态决定 active/idle 投影，其 idle 场景可以重绘，但不会推进 Token 观测或发起查询。Standalone Watch 与 Monitor 保留自己的刷新、暂停和 Interval 行为。
 
 ## 可复现性与文档边界
 
@@ -260,14 +270,18 @@
 
    Preset 提供完整的 Dashboard 基础状态，并可在启动命令中接受显式覆盖或追加 Pane；没有 Preset 时，除无参数 `dashboard` 外，必须显式提供 Pane。运行时 `z` 有意不应用 Preset 的内容模板：它保留当前 Pane 列表，只选择对应几何。复制命令展开实际 Pane 状态并保留当前布局，而不依赖来源 Preset 名称。
 
-3. **会话状态不进入可复现配置。**
+3. **仅在当前运行中存在的呈现状态不进入可复现配置。**
+
+   当前焦点、暂停状态、Controls 可见性、检查视图、临时错误、动画播放、Overlay 偏移以及 Overlay 命令结果历史都属于运行会话，不应写入复制命令。声明式 Overlay 来源与显示设置可随其动画 Pane 被复制，但编辑器草稿不可复制。
+
+4. **撤销/重做是有界的会话导航，不是持久化。**
 
-   当前焦点、暂停状态、Controls 可见性、检查视图和临时错误属于运行会话，不应写入复制的命令。
+   `u` 和 `U` 通过有界、仅当前会话存在的历史撤销、重做 Dashboard 配置修改；撤销后新的编辑会替换重做分支。历史只恢复由 Dashboard 状态表示的组合与设置，不会恢复 Overlay 来源草稿、Overlay 位置或偏移修改、命令记录、命令历史状态、Provider 结果或图表事实，也绝不会写入复制命令。
 
-4. **设计哲学只记录稳定约束。**
+5. **设计哲学只记录稳定约束。**
 
    完整 CLI 拼写、参数矩阵、快捷键表、Preset 内容和操作示例属于用户指南；组件接口、状态机和测试标准属于正式设计规格。新增功能应能归入本文原则；必须破例时，应明确写出例外及边界。
 
-5. **文档按认知深度分层，并在同一次维护中保持一致。**
+6. **文档按认知深度分层，并在同一次维护中保持一致。**
 
    README 通过自然语言和小型产品地图建立第一印象；架构文档定义已经实现的所有权与运行边界，设计哲学解释稳定原则与理由。正式设计规格保留决策和测试标准，Roadmap 只描述计划工作。英文与简体中文文档必须表达相同契约；术语、默认值或所有权发生变化时，应同步协调这些层级，而不是延后处理。

{ccusage_viz-0.2.0 → ccusage_viz-0.2.2}/docs/known-issues.md

@@ -6,19 +6,20 @@ This page tracks known behavior in supported `ccusage-viz` and `ccusage`
 combinations. Update or remove an entry when the relevant upstream behavior
 changes.
 
-## Dashboard may become unresponsive after running for a while
+## 🟡 Dashboard unresponsiveness — mitigation implemented, under observation
 
-### Symptoms and scope
+### Status and scope
 
-After the Dashboard has been running for some time, keyboard input and refreshes
-may stop responding. The terminal may need to be closed and reopened before the
-Dashboard can be used again.
+`0.2.1` includes a shutdown-handling mitigation for the reported case where a
+stalled Dashboard could only be exited with `Ctrl-C`. The change is treated as
+**fixed under observation**, not as a verified permanent resolution: it requires
+continued real-session use before this entry can be removed.
 
-### Recovery
+### If it recurs
 
-Close the affected terminal, open a new terminal session, and start the Dashboard
-again. If possible, record how long it ran, the Dashboard layout, refresh or
-sampling intervals, and any sanitized output before reopening it.
+Use `Ctrl-C` to exit the affected session, then start Dashboard again. Please
+record how long it ran, the Dashboard layout, refresh or sampling intervals, and
+any sanitized output before restarting, and report the recurrence.
 
 ## Active Monitor observations can temporarily disappear and later resume
 

{ccusage_viz-0.2.0 → ccusage_viz-0.2.2}/docs/known-issues.zh-CN.md

@@ -4,17 +4,17 @@
 
 本页记录受支持的 `ccusage-viz` 与 `ccusage` 组合中已知的行为。相关上游行为变化后，应更新或移除对应条目。
 
-## Dashboard 运行一段时间后可能失去响应
+## 🟡 Dashboard 失去响应：已实施缓解措施，持续观测中
 
-### 症状与范围
+### 状态与范围
 
-Dashboard 运行一段时间后，键盘输入和刷新可能停止响应。此时可能需要关闭终端并重新打开，
-Dashboard 才能恢复使用。
+`0.2.1` 为已报告的 Dashboard 卡住后只能通过 `Ctrl-C` 退出的问题加入了退出处理缓解措施。该改动
+按**已修复、观测中**处理，而非已验证的永久解决方案：在移除此条目前，仍需持续通过真实会话观察。
 
-### 恢复方式
+### 若再次发生
 
-关闭受影响的终端，重新打开终端会话，再次启动 Dashboard。若方便，请记录运行时长、Dashboard
-布局、刷新或采样间隔，以及重新打开前能够获取的脱敏输出。
+使用 `Ctrl-C` 退出受影响会话，再次启动 Dashboard。请记录运行时长、Dashboard 布局、刷新或采样间隔，
+以及重启前能够获取的脱敏输出，并报告复现情况。
 
 ## Monitor 当前观测值可能暂时消失，之后恢复