diff options
| author | Paul Buetow <paul@buetow.org> | 2026-03-09 08:05:26 +0200 |
|---|---|---|
| committer | Paul Buetow <paul@buetow.org> | 2026-03-09 08:05:26 +0200 |
| commit | 9f35d16940f35591dd0b0c782d2ec8e57bba84b5 (patch) | |
| tree | 031bd61cd47299ed66736012370541f4af760ceb /docs | |
| parent | 1277f03a01fafd5ce7931bf9d48dc92f089c6894 (diff) | |
tui: harden paused flame rendering
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/tui-flamegraph-behavior.md | 46 |
1 files changed, 46 insertions, 0 deletions
diff --git a/docs/tui-flamegraph-behavior.md b/docs/tui-flamegraph-behavior.md new file mode 100644 index 0000000..cc9bb5d --- /dev/null +++ b/docs/tui-flamegraph-behavior.md @@ -0,0 +1,46 @@ +# TUI Flamegraph Expected Behavior + +This document records the expected interaction and layout behavior for the TUI +flamegraph. It is intended as a stable reference for regressions and for tests +under `internal/tui/flamegraph/` and `internal/tui/dashboard/`. + +## Interaction + +- `space` toggles pause. `p` does not pause the flamegraph and remains reserved + for the global PID picker at the top-level TUI. +- `enter` and left-click zoom into the selected or clicked frame. +- Clicking an ancestor frame in the zoom lineage re-roots the view to that + ancestor. +- `u`, `backspace`, and `esc` undo one zoom step. +- Direct clicks into a deep descendant create a single undo step back to the + previous zoom root, not an implicit stack of every skipped ancestor. +- While paused, navigation and zoom must continue to work against the frozen + snapshot. + +## Layout + +- The selected frame must not render with underline or a horizontal highlight + line across the bar. +- The current zoom root must span the full flamegraph width. +- The children of the current zoom root must be normalized to the full viewport + width, even when the zoom root has self time or exclusive weight. +- Zooming from any direction must produce the same full-width result for the + newly selected zoom root. +- The zoom lineage rows shown above the zoomed subtree provide context, but they + must not steal horizontal space from the zoomed subtree. + +## Rendering + +- Rendering the dashboard view must not mutate persistent flamegraph state. +- Redundant same-size viewport updates must be no-ops. +- In paused mode, repeated renders must not reintroduce stale frame geometry or + leave artifacts from a previous layout on screen. + +## Regression Coverage + +These expectations are covered by tests in: + +- `internal/tui/flamegraph/renderer_test.go` +- `internal/tui/flamegraph/model_test.go` +- `internal/tui/flamegraph/stress_test.go` +- `internal/tui/dashboard/model_test.go` |