sleev 1.8.1 → 1.8.2

package/README.md

@@ -18,6 +18,59 @@ This CLI is developed in the `sleev` repository and released together with the
 gateway as one versioned unit; see that repo's `README.md` and `CLAUDE.md` for
 architecture and contributor docs.
 
+## Session charts
+
+Pixel session charts are experimental and **disabled by default**. Enable with
+`sleev experimental advanced-graphics enable`, then reopen the TUI. Use
+`sleev experimental advanced-graphics status` or `disable` to inspect or turn it
+off. This local setting does not require a running gateway. The accounting
+correction applies regardless of this setting.
+
+When enabled, session charts use pixel graphics only after the terminal confirms
+Kitty or Sixel support and reports its cell size in pixels. Axes, request labels, and controls
+remain native terminal text. The existing text chart is used when graphics or
+pixel dimensions are unavailable, inside tmux/screen, and while overlays cover
+the chart. Scrolling dashboards also use text until the plot fits directly in
+the visible viewport.
+
+Detection shares the Unix input loop, including over SSH; there is no separate
+capability-probe reader. Native Windows currently uses the text chart: the
+console backend cannot report pixel dimensions. Windows Terminal over SSH to
+a Unix host can use Sixel when it reports support and cell dimensions.
+`SLEEV_TUI_GRAPHICS=auto|kitty|sixel|text` selects the protocol preference;
+the default is `auto`, which keeps text rendering until a positive capability
+reply arrives. Terminal environment names alone do not enable pixels. Explicit
+Kitty/Sixel overrides force the protocol; they do not bypass the experimental
+setting. Overrides still require real pixel dimensions and do not
+enable graphics inside tmux/screen.
+
+Fit mode retains spikes and compression drops at pixel resolution. Hover's
+request-range badge identifies the requests within that terminal column; the
+crosshair and value badges inspect the **last request in the range**. Normal
+zoom still uses one terminal column per request. Existing compare, pan, vertical
+zoom, full-screen, and keyboard controls apply to both renderers.
+
+The pixel chart scales to the visible requests and enabled series, with a small
+margin above and below the data. Panning updates the range; Fit uses the entire
+session. Hidden comparison data does not stretch the scale.
+
+Unchanged pixel frames send no image data. Sixel hover updates repaint only
+changed cell columns; resizing, moving the plot, or changing most of the image
+replaces the full canvas. Encoded updates and the retained raster are each
+bounded to 48 MiB. A second, equally bounded static raster is reused for hover;
+request series are prepared only when data changes. Only the session plot uses
+this renderer. Kitty uses lossless PNG with row prediction to limit terminal
+traffic; Sixel uses a 32-color palette and deduplicates full-canvas colors before
+quantization. Consecutive compatible pointer events are collapsed before graph
+updates, preserving button and key boundaries.
+
+Synthetic interaction timings (including the view and codecs, excluding terminal
+I/O) can be reproduced with `cargo test -p sleev-tui --lib --release
+fullscreen_chart_profile -- --ignored --nocapture`. The ignored `codec_profile`
+benchmark breaks down raster, palette, and encoding costs. Fullscreen Sixel pans
+remain more expensive than hover; terminal transport and emulator rendering add
+to these CPU timings.
+
 ## Legal
 
 `sleev` is proprietary software owned by Sleev Labs Inc. It is published with