plotui 0.4.2__tar.gz → 0.5.0__tar.gz

{plotui-0.4.2 → plotui-0.5.0}/Cargo.lock

@@ -305,6 +305,7 @@ dependencies = [
  "crossterm_winapi",
  "derive_more",
  "document-features",
+ "filedescriptor",
  "mio",
  "parking_lot",
  "rustix",
@@ -1117,10 +1118,11 @@ checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
 [[package]]
 name = "plotui"
-version = "0.4.2"
+version = "0.5.0"
 dependencies = [
  "clap",
  "crossterm",
+ "plotui-bind",
  "plotui-core",
  "plotui-ratatui",
  "plotui-term",
@@ -1129,18 +1131,18 @@ dependencies = [
 
 [[package]]
 name = "plotui-bind"
-version = "0.4.2"
+version = "0.5.0"
 dependencies = [
  "plotui-core",
 ]
 
 [[package]]
 name = "plotui-core"
-version = "0.4.2"
+version = "0.5.0"
 
 [[package]]
 name = "plotui-ffi"
-version = "0.4.2"
+version = "0.5.0"
 dependencies = [
  "cbindgen",
  "plotui-bind",
@@ -1151,7 +1153,7 @@ dependencies = [
 
 [[package]]
 name = "plotui-protocol"
-version = "0.4.2"
+version = "0.5.0"
 dependencies = [
  "base64",
  "flate2",
@@ -1160,7 +1162,7 @@ dependencies = [
 
 [[package]]
 name = "plotui-py"
-version = "0.4.2"
+version = "0.5.0"
 dependencies = [
  "numpy",
  "plotui-bind",
@@ -1172,7 +1174,7 @@ dependencies = [
 
 [[package]]
 name = "plotui-ratatui"
-version = "0.4.2"
+version = "0.5.0"
 dependencies = [
  "crossterm",
  "plotui-core",
@@ -1183,7 +1185,7 @@ dependencies = [
 
 [[package]]
 name = "plotui-term"
-version = "0.4.2"
+version = "0.5.0"
 dependencies = [
  "plotui-core",
  "plotui-protocol",
@@ -1192,7 +1194,7 @@ dependencies = [
 
 [[package]]
 name = "plotui-wasm"
-version = "0.4.2"
+version = "0.5.0"
 dependencies = [
  "plotui-bind",
  "plotui-core",

{plotui-0.4.2 → plotui-0.5.0}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/plotui-core", "crates/plotui-protocol", "crates/plotui-term", "crates/plotui-bind", "crates/plotui-py"]
 
 [workspace.package]
-version = "0.4.2"
+version = "0.5.0"
 edition = "2021"
 license = "MIT"
 repository = "https://github.com/sebaheg/plotui"
@@ -14,11 +14,11 @@ keywords = ["plot", "terminal", "tui", "kitty", "visualization"]
 categories = ["visualization", "command-line-utilities"]
 
 [workspace.dependencies]
-plotui-core = { version = "0.4.2", path = "crates/plotui-core" }
-plotui-protocol = { version = "0.4.2", path = "crates/plotui-protocol" }
-plotui-term = { version = "0.4.2", path = "crates/plotui-term" }
-plotui-bind = { version = "0.4.2", path = "crates/plotui-bind" }
-plotui-ratatui = { version = "0.4.2", path = "crates/plotui-ratatui" }
+plotui-core = { version = "0.5.0", path = "crates/plotui-core" }
+plotui-protocol = { version = "0.5.0", path = "crates/plotui-protocol" }
+plotui-term = { version = "0.5.0", path = "crates/plotui-term" }
+plotui-bind = { version = "0.5.0", path = "crates/plotui-bind" }
+plotui-ratatui = { version = "0.5.0", path = "crates/plotui-ratatui" }
 ratatui = { version = "0.30", default-features = false }
 crossterm = "0.29"
 

{plotui-0.4.2 → plotui-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotui
-Version: 0.4.2
+Version: 0.5.0
 Requires-Dist: textual>=0.60 ; extra == 'textual'
 Provides-Extra: textual
 License-File: LICENSE
@@ -21,9 +21,12 @@ drops into a [Textual](https://textual.textualize.io/),
 [Bubble Tea](https://github.com/charmbracelet/bubbletea) app as a first-class
 widget, with the rendering engine written in Rust so it stays fast in 2D and 3D.
 
-> Status: **early scaffold.** Working today: 2D scatter/line/bar charts with
-> axes, ticks, and a legend; a 3D scatter/graph engine; a Kitty-image raw demo;
-> and a Textual widget. See the roadmap below.
+> Status: **early scaffold.** Working today: 2D scatter/line/step/bar,
+> histogram, box, heatmap, and band charts with axes, ticks, titles,
+> explicit ranges, log scales, categorical labels, a colorbar and a legend;
+> DAG/pipeline graphs with a layered layout and a DOT subset reader; a 3D
+> scatter/graph/surface/mesh engine; a Kitty-image raw demo; and a Textual
+> widget.
 
 ## Architecture
 
@@ -32,6 +35,10 @@ terminal.** It has no event loop and no input handling — the TUI framework
 (Textual, Ratatui, or Bubble Tea) owns the loop, forwards input to the
 camera, and asks for a frame.
 
+```
+f64 data ─▶ camera + rasterizer ─▶ RGBA buffer ─▶ Kitty escape bytes ─▶ your terminal's cell grid
+```
+
 ```
 crates/
   plotui-core/      pure engine: data model, 3D camera, rasterizer → RGBA
@@ -49,7 +56,9 @@ examples/           raw_demo.py (Kitty images), textual_demo.py
 ```
 
 `core` and `protocol` are pure and I/O-free, so the same engine can back every
-frontend and be unit-tested by hashing pixel buffers.
+frontend and be unit-tested by hashing pixel buffers. The protocol layer emits
+Kitty graphics escapes — chunked, placement-aware, and wrapped for tmux
+passthrough — as pure functions of the RGBA frame.
 
 ## Integrations
 
@@ -85,11 +94,41 @@ cargo binstall plotui                           # prebuilt, via cargo-binstall
 ```
 
 ```bash
-seq 1 100 | awk '{print $1, sin($1/10)}' | plotui line
+seq 1 100 | LC_ALL=C awk '{print $1, sin($1/10)}' | plotui line
 plotui scatter -H -d, data.csv                  # header row + comma-delimited
-plotui bar counts.tsv
+plotui bar counts.tsv                           # --horizontal, --stack, --group
+plotui step states.txt                          # holds its value between samples
+plotui hist samples.txt                         # binned automatically
+plotui box -H measurements.tsv                  # one box per column
+plotui dag pipeline.dot                         # a DAG from a DOT file; hover a task
+                                                # to light everything it waits on
+plotui line --log-y --title "queue depth" \
+            --x-title minute --y-title items    # titles and log scales
+plotui line --x-range 0:100 --y-range 0:1       # pin an extent, LO:HI
+tail -f app.log | LC_ALL=C awk '{print $2}' \
+                | plotui line -f --window 200   # live, on the last 200 samples
+plotui example scatter                          # built-in demo scenes, no data needed
+plotui example deps                             # plotui's own dependency graph, laid
+                                                # out live by a force simulation
+plotui example pipeline                         # a nightly forecast DAG, running
 ```
 
+`--follow` (`-f`) keeps the reader open instead of plotting once at EOF: rows
+are parsed as they arrive and appended in place, so the chart grows without a
+redraw from scratch and pan/zoom survive. It needs piped input and a terminal
+to draw into — a malformed line is skipped rather than fatal, and the count is
+reported when you quit. The shape of the input (delimiter, column count,
+whether x is a calendar) is settled by the first row and held for the rest of
+the stream.
+
+On a long feed the whole run compresses into a sliver, so `--window <N>` keeps
+the view on the last N samples and `--last <span>` on the last `30s` / `5m` /
+`2h` of x. Neither drops data: the window is a *view*, drawn on the range
+slider (which a window switches on) against the entire run, so you can drag
+back through everything that has arrived. Doing so hands the view over — a
+reader who has scrolled back to an incident does not want the next row to
+yank them forward — and **f** goes live again, jumping to the head.
+
 Like every plotui frontend, the CLI needs a terminal with Kitty graphics
 (supported terminals below); elsewhere it prints a notice and exits.
 
@@ -128,7 +167,8 @@ terminals, never a degraded plot. Override with
 from plotui import Plot
 
 # 2D: axes, ticks, and a legend appear automatically. Traces added without a
-# color take palette slots in fixed order; `name=` puts a series in the legend.
+# color take colorway slots in fixed order; `name=` puts a series in the
+# legend. Colors accept (r, g, b) tuples or shorthands: "#e63c78", "red".
 plot = Plot()
 plot.add_line(xs, ys, name="forecast")
 plot.add_scatter(xs2, ys2, name="observed")
@@ -140,9 +180,42 @@ plot.add_bar(xs3, heights)
 plot.add_line(xs, tokens, name="tokens", axis="y2")
 plot.add_line(xs, cpu_minutes, name="cpu min", axis="y3")
 
+# Titles: each buys its own margin, so the plot area shrinks rather than
+# drawing over the data. The y title is drawn rotated in the left margin.
+plot.set_title("p99 latency")
+plot.set_x_title("requests")
+plot.set_y_title("ms")
+
+# Ranges and scales: an explicit range pins the *extent* only — no autoscale
+# padding, and zoom/pan still compose on top of it (unlike set_x_window,
+# which is the live window and supersedes the camera). A log axis ticks in
+# powers of ten; values at or below zero have no log coordinate and neither
+# set the range nor draw.
+plot.set_x_range((0, 100))                         # None restores autoscale
+plot.set_y_range((0.1, 1e4))
+plot.set_y_log(True)                               # set_x_log for x
+
+# DAGs and pipelines: labelled boxes wired by arrows, laid out by rank. Node
+# centres are data coordinates; each box is sized in pixels from its label,
+# so zooming spreads the graph apart while the text stays readable.
+from plotui import LayeredLayout, from_dot, reachable
+
+layout = LayeredLayout(len(tasks), edges)          # rankdir="TB" or "LR"
+plot = Plot()
+h = plot.add_graph2d(*layout.positions(), edges,
+                     labels=tasks, routes=layout.routes())
+plot.set_graph_colors(h, states)                   # repaint as the run advances
+lit = reachable(len(tasks), edges, hovered)        # everything it waits on
+plot = from_dot(open("pipeline.dot").read())       # or straight from DOT
+
 # 3D: any 3D trace switches the plot to the orbit camera.
 plot = Plot()
-plot.add_scatter3d(xs, ys, zs, color=(230, 60, 120), size=2.0)
+plot.add_scatter3d(xs, ys, zs, name="Cluster A")   # colors from the colorway
+
+# Colorways: the default sequence is pink/cyan/orange-first; swap it with a
+# built-in name or your own list before adding traces.
+plot.set_colorway("vivid")                         # "plotui", "muted", "vivid"
+plot.set_colorway(["#e63c78", "cyan", (240, 161, 60)])
 
 # Streaming: every add_* returns a trace handle. Append through it instead
 # of rebuilding — O(new points), autoscale follows; numpy arrays are read
@@ -202,40 +275,14 @@ interaction in a subclass, override the `apply_rotate` / `apply_pan` /
 routes through — do **not** override the Textual `on_*` handlers (Textual
 dispatches those to every class in the MRO, so both would run).
 
-## Roadmap
-
-- [x] Flicker-free Kitty placement via Unicode-placeholder virtual placement
-      (fixed image id, atomic replace) — wire the pixel path into the Textual widget
-- [x] 2D traces: scatter, line, bar; axes, ticks, tick labels, legend
-- [x] Independent right-hand y-axes (`axis="y2"`/`"y3"`) with tinted tick labels
-- [ ] 2D step trace; axis titles; time-formatted x ticks
-- [ ] 3D surface / mesh; axis cube with labels
-- [x] Interactive hover / pick for 3D graph nodes *and* edges (opt-in via
-      `PlotWidget(..., pickable=True)`: hover lights the element up white,
-      click posts `ElementPicked`)
-- [ ] Hover / pick for 2D traces; spatial index for large graphs
-- [x] Streaming append: trace handles, `extend`, `set_visible`, incremental bounds
-- [x] numpy fast-path input (one bulk copy, no per-element conversion)
-- [ ] Rolling window (`max_points`) for endless streams
-- [x] Graceful render-path auto-detection (placeholder / direct Kitty, with a
-      supported-terminals notice elsewhere and a `PLOTUI_RENDER` override)
-- [ ] Sixel + iTerm2 OSC 1337 encoders for terminals without Kitty graphics
-- [x] Prebuilt wheels (maturin + GitHub Actions): `pip install plotui` — macOS
-      arm64/x86_64, Linux x86_64/aarch64, abi3 ≥ 3.9; the wheel bundles the
-      CLI binary
-- [x] Ratatui frontend (native): `plotui-ratatui` — StatefulWidget + app-owned
-      PlotState, full parity with the Textual widget
-      (`cargo run -p plotui-ratatui --example demo`)
-- [x] Bubble Tea frontend (cgo): `go/` bindings over the `plotui-ffi` C ABI +
-      the `teaplot` component for Bubble Tea v2 (see `go/README.md`)
-- [x] CLI: `plotui line|scatter|bar` from stdin or a file — interactive on a
-      TTY, one static frame when piped; installed via curl, Homebrew, cargo,
-      or pip (see Install above)
-- [ ] CLI v2: `--follow` streaming, `scatter3d`, histogram/density/count
-      transforms, `--out png`
-- [ ] Prebuilt static libs for the Go bindings (today: local source build)
-
 ## License
 
-MIT
+MIT, except for one embedded asset: chart text is set in
+[Martian Mono](https://github.com/evilmartians/mono) (Copyright 2020 The
+Martian Mono Project Authors), used under the SIL Open Font License 1.1. The
+glyph outlines are compiled into `plotui-core` as
+`crates/plotui-core/src/glyphs.rs`; the license travels with them in
+`crates/plotui-core/fonts/MartianMono-OFL.txt`. The font carries no Reserved
+Font Name, and nothing about the OFL reaches your code — it covers the font
+data, not the crate.
 

{plotui-0.4.2 → plotui-0.5.0}/README.md

@@ -9,9 +9,12 @@ drops into a [Textual](https://textual.textualize.io/),
 [Bubble Tea](https://github.com/charmbracelet/bubbletea) app as a first-class
 widget, with the rendering engine written in Rust so it stays fast in 2D and 3D.
 
-> Status: **early scaffold.** Working today: 2D scatter/line/bar charts with
-> axes, ticks, and a legend; a 3D scatter/graph engine; a Kitty-image raw demo;
-> and a Textual widget. See the roadmap below.
+> Status: **early scaffold.** Working today: 2D scatter/line/step/bar,
+> histogram, box, heatmap, and band charts with axes, ticks, titles,
+> explicit ranges, log scales, categorical labels, a colorbar and a legend;
+> DAG/pipeline graphs with a layered layout and a DOT subset reader; a 3D
+> scatter/graph/surface/mesh engine; a Kitty-image raw demo; and a Textual
+> widget.
 
 ## Architecture
 
@@ -20,6 +23,10 @@ terminal.** It has no event loop and no input handling — the TUI framework
 (Textual, Ratatui, or Bubble Tea) owns the loop, forwards input to the
 camera, and asks for a frame.
 
+```
+f64 data ─▶ camera + rasterizer ─▶ RGBA buffer ─▶ Kitty escape bytes ─▶ your terminal's cell grid
+```
+
 ```
 crates/
   plotui-core/      pure engine: data model, 3D camera, rasterizer → RGBA
@@ -37,7 +44,9 @@ examples/           raw_demo.py (Kitty images), textual_demo.py
 ```
 
 `core` and `protocol` are pure and I/O-free, so the same engine can back every
-frontend and be unit-tested by hashing pixel buffers.
+frontend and be unit-tested by hashing pixel buffers. The protocol layer emits
+Kitty graphics escapes — chunked, placement-aware, and wrapped for tmux
+passthrough — as pure functions of the RGBA frame.
 
 ## Integrations
 
@@ -73,11 +82,41 @@ cargo binstall plotui                           # prebuilt, via cargo-binstall
 ```
 
 ```bash
-seq 1 100 | awk '{print $1, sin($1/10)}' | plotui line
+seq 1 100 | LC_ALL=C awk '{print $1, sin($1/10)}' | plotui line
 plotui scatter -H -d, data.csv                  # header row + comma-delimited
-plotui bar counts.tsv
+plotui bar counts.tsv                           # --horizontal, --stack, --group
+plotui step states.txt                          # holds its value between samples
+plotui hist samples.txt                         # binned automatically
+plotui box -H measurements.tsv                  # one box per column
+plotui dag pipeline.dot                         # a DAG from a DOT file; hover a task
+                                                # to light everything it waits on
+plotui line --log-y --title "queue depth" \
+            --x-title minute --y-title items    # titles and log scales
+plotui line --x-range 0:100 --y-range 0:1       # pin an extent, LO:HI
+tail -f app.log | LC_ALL=C awk '{print $2}' \
+                | plotui line -f --window 200   # live, on the last 200 samples
+plotui example scatter                          # built-in demo scenes, no data needed
+plotui example deps                             # plotui's own dependency graph, laid
+                                                # out live by a force simulation
+plotui example pipeline                         # a nightly forecast DAG, running
 ```
 
+`--follow` (`-f`) keeps the reader open instead of plotting once at EOF: rows
+are parsed as they arrive and appended in place, so the chart grows without a
+redraw from scratch and pan/zoom survive. It needs piped input and a terminal
+to draw into — a malformed line is skipped rather than fatal, and the count is
+reported when you quit. The shape of the input (delimiter, column count,
+whether x is a calendar) is settled by the first row and held for the rest of
+the stream.
+
+On a long feed the whole run compresses into a sliver, so `--window <N>` keeps
+the view on the last N samples and `--last <span>` on the last `30s` / `5m` /
+`2h` of x. Neither drops data: the window is a *view*, drawn on the range
+slider (which a window switches on) against the entire run, so you can drag
+back through everything that has arrived. Doing so hands the view over — a
+reader who has scrolled back to an incident does not want the next row to
+yank them forward — and **f** goes live again, jumping to the head.
+
 Like every plotui frontend, the CLI needs a terminal with Kitty graphics
 (supported terminals below); elsewhere it prints a notice and exits.
 
@@ -116,7 +155,8 @@ terminals, never a degraded plot. Override with
 from plotui import Plot
 
 # 2D: axes, ticks, and a legend appear automatically. Traces added without a
-# color take palette slots in fixed order; `name=` puts a series in the legend.
+# color take colorway slots in fixed order; `name=` puts a series in the
+# legend. Colors accept (r, g, b) tuples or shorthands: "#e63c78", "red".
 plot = Plot()
 plot.add_line(xs, ys, name="forecast")
 plot.add_scatter(xs2, ys2, name="observed")
@@ -128,9 +168,42 @@ plot.add_bar(xs3, heights)
 plot.add_line(xs, tokens, name="tokens", axis="y2")
 plot.add_line(xs, cpu_minutes, name="cpu min", axis="y3")
 
+# Titles: each buys its own margin, so the plot area shrinks rather than
+# drawing over the data. The y title is drawn rotated in the left margin.
+plot.set_title("p99 latency")
+plot.set_x_title("requests")
+plot.set_y_title("ms")
+
+# Ranges and scales: an explicit range pins the *extent* only — no autoscale
+# padding, and zoom/pan still compose on top of it (unlike set_x_window,
+# which is the live window and supersedes the camera). A log axis ticks in
+# powers of ten; values at or below zero have no log coordinate and neither
+# set the range nor draw.
+plot.set_x_range((0, 100))                         # None restores autoscale
+plot.set_y_range((0.1, 1e4))
+plot.set_y_log(True)                               # set_x_log for x
+
+# DAGs and pipelines: labelled boxes wired by arrows, laid out by rank. Node
+# centres are data coordinates; each box is sized in pixels from its label,
+# so zooming spreads the graph apart while the text stays readable.
+from plotui import LayeredLayout, from_dot, reachable
+
+layout = LayeredLayout(len(tasks), edges)          # rankdir="TB" or "LR"
+plot = Plot()
+h = plot.add_graph2d(*layout.positions(), edges,
+                     labels=tasks, routes=layout.routes())
+plot.set_graph_colors(h, states)                   # repaint as the run advances
+lit = reachable(len(tasks), edges, hovered)        # everything it waits on
+plot = from_dot(open("pipeline.dot").read())       # or straight from DOT
+
 # 3D: any 3D trace switches the plot to the orbit camera.
 plot = Plot()
-plot.add_scatter3d(xs, ys, zs, color=(230, 60, 120), size=2.0)
+plot.add_scatter3d(xs, ys, zs, name="Cluster A")   # colors from the colorway
+
+# Colorways: the default sequence is pink/cyan/orange-first; swap it with a
+# built-in name or your own list before adding traces.
+plot.set_colorway("vivid")                         # "plotui", "muted", "vivid"
+plot.set_colorway(["#e63c78", "cyan", (240, 161, 60)])
 
 # Streaming: every add_* returns a trace handle. Append through it instead
 # of rebuilding — O(new points), autoscale follows; numpy arrays are read
@@ -190,39 +263,13 @@ interaction in a subclass, override the `apply_rotate` / `apply_pan` /
 routes through — do **not** override the Textual `on_*` handlers (Textual
 dispatches those to every class in the MRO, so both would run).
 
-## Roadmap
-
-- [x] Flicker-free Kitty placement via Unicode-placeholder virtual placement
-      (fixed image id, atomic replace) — wire the pixel path into the Textual widget
-- [x] 2D traces: scatter, line, bar; axes, ticks, tick labels, legend
-- [x] Independent right-hand y-axes (`axis="y2"`/`"y3"`) with tinted tick labels
-- [ ] 2D step trace; axis titles; time-formatted x ticks
-- [ ] 3D surface / mesh; axis cube with labels
-- [x] Interactive hover / pick for 3D graph nodes *and* edges (opt-in via
-      `PlotWidget(..., pickable=True)`: hover lights the element up white,
-      click posts `ElementPicked`)
-- [ ] Hover / pick for 2D traces; spatial index for large graphs
-- [x] Streaming append: trace handles, `extend`, `set_visible`, incremental bounds
-- [x] numpy fast-path input (one bulk copy, no per-element conversion)
-- [ ] Rolling window (`max_points`) for endless streams
-- [x] Graceful render-path auto-detection (placeholder / direct Kitty, with a
-      supported-terminals notice elsewhere and a `PLOTUI_RENDER` override)
-- [ ] Sixel + iTerm2 OSC 1337 encoders for terminals without Kitty graphics
-- [x] Prebuilt wheels (maturin + GitHub Actions): `pip install plotui` — macOS
-      arm64/x86_64, Linux x86_64/aarch64, abi3 ≥ 3.9; the wheel bundles the
-      CLI binary
-- [x] Ratatui frontend (native): `plotui-ratatui` — StatefulWidget + app-owned
-      PlotState, full parity with the Textual widget
-      (`cargo run -p plotui-ratatui --example demo`)
-- [x] Bubble Tea frontend (cgo): `go/` bindings over the `plotui-ffi` C ABI +
-      the `teaplot` component for Bubble Tea v2 (see `go/README.md`)
-- [x] CLI: `plotui line|scatter|bar` from stdin or a file — interactive on a
-      TTY, one static frame when piped; installed via curl, Homebrew, cargo,
-      or pip (see Install above)
-- [ ] CLI v2: `--follow` streaming, `scatter3d`, histogram/density/count
-      transforms, `--out png`
-- [ ] Prebuilt static libs for the Go bindings (today: local source build)
-
 ## License
 
-MIT
+MIT, except for one embedded asset: chart text is set in
+[Martian Mono](https://github.com/evilmartians/mono) (Copyright 2020 The
+Martian Mono Project Authors), used under the SIL Open Font License 1.1. The
+glyph outlines are compiled into `plotui-core` as
+`crates/plotui-core/src/glyphs.rs`; the license travels with them in
+`crates/plotui-core/fonts/MartianMono-OFL.txt`. The font carries no Reserved
+Font Name, and nothing about the OFL reaches your code — it covers the font
+data, not the crate.

{plotui-0.4.2 → plotui-0.5.0}/crates/plotui-bind/README.md

@@ -9,9 +9,12 @@ drops into a [Textual](https://textual.textualize.io/),
 [Bubble Tea](https://github.com/charmbracelet/bubbletea) app as a first-class
 widget, with the rendering engine written in Rust so it stays fast in 2D and 3D.
 
-> Status: **early scaffold.** Working today: 2D scatter/line/bar charts with
-> axes, ticks, and a legend; a 3D scatter/graph engine; a Kitty-image raw demo;
-> and a Textual widget. See the roadmap below.
+> Status: **early scaffold.** Working today: 2D scatter/line/step/bar,
+> histogram, box, heatmap, and band charts with axes, ticks, titles,
+> explicit ranges, log scales, categorical labels, a colorbar and a legend;
+> DAG/pipeline graphs with a layered layout and a DOT subset reader; a 3D
+> scatter/graph/surface/mesh engine; a Kitty-image raw demo; and a Textual
+> widget.
 
 ## Architecture
 
@@ -20,6 +23,10 @@ terminal.** It has no event loop and no input handling — the TUI framework
 (Textual, Ratatui, or Bubble Tea) owns the loop, forwards input to the
 camera, and asks for a frame.
 
+```
+f64 data ─▶ camera + rasterizer ─▶ RGBA buffer ─▶ Kitty escape bytes ─▶ your terminal's cell grid
+```
+
 ```
 crates/
   plotui-core/      pure engine: data model, 3D camera, rasterizer → RGBA
@@ -37,7 +44,9 @@ examples/           raw_demo.py (Kitty images), textual_demo.py
 ```
 
 `core` and `protocol` are pure and I/O-free, so the same engine can back every
-frontend and be unit-tested by hashing pixel buffers.
+frontend and be unit-tested by hashing pixel buffers. The protocol layer emits
+Kitty graphics escapes — chunked, placement-aware, and wrapped for tmux
+passthrough — as pure functions of the RGBA frame.
 
 ## Integrations
 
@@ -73,11 +82,41 @@ cargo binstall plotui                           # prebuilt, via cargo-binstall
 ```
 
 ```bash
-seq 1 100 | awk '{print $1, sin($1/10)}' | plotui line
+seq 1 100 | LC_ALL=C awk '{print $1, sin($1/10)}' | plotui line
 plotui scatter -H -d, data.csv                  # header row + comma-delimited
-plotui bar counts.tsv
+plotui bar counts.tsv                           # --horizontal, --stack, --group
+plotui step states.txt                          # holds its value between samples
+plotui hist samples.txt                         # binned automatically
+plotui box -H measurements.tsv                  # one box per column
+plotui dag pipeline.dot                         # a DAG from a DOT file; hover a task
+                                                # to light everything it waits on
+plotui line --log-y --title "queue depth" \
+            --x-title minute --y-title items    # titles and log scales
+plotui line --x-range 0:100 --y-range 0:1       # pin an extent, LO:HI
+tail -f app.log | LC_ALL=C awk '{print $2}' \
+                | plotui line -f --window 200   # live, on the last 200 samples
+plotui example scatter                          # built-in demo scenes, no data needed
+plotui example deps                             # plotui's own dependency graph, laid
+                                                # out live by a force simulation
+plotui example pipeline                         # a nightly forecast DAG, running
 ```
 
+`--follow` (`-f`) keeps the reader open instead of plotting once at EOF: rows
+are parsed as they arrive and appended in place, so the chart grows without a
+redraw from scratch and pan/zoom survive. It needs piped input and a terminal
+to draw into — a malformed line is skipped rather than fatal, and the count is
+reported when you quit. The shape of the input (delimiter, column count,
+whether x is a calendar) is settled by the first row and held for the rest of
+the stream.
+
+On a long feed the whole run compresses into a sliver, so `--window <N>` keeps
+the view on the last N samples and `--last <span>` on the last `30s` / `5m` /
+`2h` of x. Neither drops data: the window is a *view*, drawn on the range
+slider (which a window switches on) against the entire run, so you can drag
+back through everything that has arrived. Doing so hands the view over — a
+reader who has scrolled back to an incident does not want the next row to
+yank them forward — and **f** goes live again, jumping to the head.
+
 Like every plotui frontend, the CLI needs a terminal with Kitty graphics
 (supported terminals below); elsewhere it prints a notice and exits.
 
@@ -116,7 +155,8 @@ terminals, never a degraded plot. Override with
 from plotui import Plot
 
 # 2D: axes, ticks, and a legend appear automatically. Traces added without a
-# color take palette slots in fixed order; `name=` puts a series in the legend.
+# color take colorway slots in fixed order; `name=` puts a series in the
+# legend. Colors accept (r, g, b) tuples or shorthands: "#e63c78", "red".
 plot = Plot()
 plot.add_line(xs, ys, name="forecast")
 plot.add_scatter(xs2, ys2, name="observed")
@@ -128,9 +168,42 @@ plot.add_bar(xs3, heights)
 plot.add_line(xs, tokens, name="tokens", axis="y2")
 plot.add_line(xs, cpu_minutes, name="cpu min", axis="y3")
 
+# Titles: each buys its own margin, so the plot area shrinks rather than
+# drawing over the data. The y title is drawn rotated in the left margin.
+plot.set_title("p99 latency")
+plot.set_x_title("requests")
+plot.set_y_title("ms")
+
+# Ranges and scales: an explicit range pins the *extent* only — no autoscale
+# padding, and zoom/pan still compose on top of it (unlike set_x_window,
+# which is the live window and supersedes the camera). A log axis ticks in
+# powers of ten; values at or below zero have no log coordinate and neither
+# set the range nor draw.
+plot.set_x_range((0, 100))                         # None restores autoscale
+plot.set_y_range((0.1, 1e4))
+plot.set_y_log(True)                               # set_x_log for x
+
+# DAGs and pipelines: labelled boxes wired by arrows, laid out by rank. Node
+# centres are data coordinates; each box is sized in pixels from its label,
+# so zooming spreads the graph apart while the text stays readable.
+from plotui import LayeredLayout, from_dot, reachable
+
+layout = LayeredLayout(len(tasks), edges)          # rankdir="TB" or "LR"
+plot = Plot()
+h = plot.add_graph2d(*layout.positions(), edges,
+                     labels=tasks, routes=layout.routes())
+plot.set_graph_colors(h, states)                   # repaint as the run advances
+lit = reachable(len(tasks), edges, hovered)        # everything it waits on
+plot = from_dot(open("pipeline.dot").read())       # or straight from DOT
+
 # 3D: any 3D trace switches the plot to the orbit camera.
 plot = Plot()
-plot.add_scatter3d(xs, ys, zs, color=(230, 60, 120), size=2.0)
+plot.add_scatter3d(xs, ys, zs, name="Cluster A")   # colors from the colorway
+
+# Colorways: the default sequence is pink/cyan/orange-first; swap it with a
+# built-in name or your own list before adding traces.
+plot.set_colorway("vivid")                         # "plotui", "muted", "vivid"
+plot.set_colorway(["#e63c78", "cyan", (240, 161, 60)])
 
 # Streaming: every add_* returns a trace handle. Append through it instead
 # of rebuilding — O(new points), autoscale follows; numpy arrays are read
@@ -190,39 +263,13 @@ interaction in a subclass, override the `apply_rotate` / `apply_pan` /
 routes through — do **not** override the Textual `on_*` handlers (Textual
 dispatches those to every class in the MRO, so both would run).
 
-## Roadmap
-
-- [x] Flicker-free Kitty placement via Unicode-placeholder virtual placement
-      (fixed image id, atomic replace) — wire the pixel path into the Textual widget
-- [x] 2D traces: scatter, line, bar; axes, ticks, tick labels, legend
-- [x] Independent right-hand y-axes (`axis="y2"`/`"y3"`) with tinted tick labels
-- [ ] 2D step trace; axis titles; time-formatted x ticks
-- [ ] 3D surface / mesh; axis cube with labels
-- [x] Interactive hover / pick for 3D graph nodes *and* edges (opt-in via
-      `PlotWidget(..., pickable=True)`: hover lights the element up white,
-      click posts `ElementPicked`)
-- [ ] Hover / pick for 2D traces; spatial index for large graphs
-- [x] Streaming append: trace handles, `extend`, `set_visible`, incremental bounds
-- [x] numpy fast-path input (one bulk copy, no per-element conversion)
-- [ ] Rolling window (`max_points`) for endless streams
-- [x] Graceful render-path auto-detection (placeholder / direct Kitty, with a
-      supported-terminals notice elsewhere and a `PLOTUI_RENDER` override)
-- [ ] Sixel + iTerm2 OSC 1337 encoders for terminals without Kitty graphics
-- [x] Prebuilt wheels (maturin + GitHub Actions): `pip install plotui` — macOS
-      arm64/x86_64, Linux x86_64/aarch64, abi3 ≥ 3.9; the wheel bundles the
-      CLI binary
-- [x] Ratatui frontend (native): `plotui-ratatui` — StatefulWidget + app-owned
-      PlotState, full parity with the Textual widget
-      (`cargo run -p plotui-ratatui --example demo`)
-- [x] Bubble Tea frontend (cgo): `go/` bindings over the `plotui-ffi` C ABI +
-      the `teaplot` component for Bubble Tea v2 (see `go/README.md`)
-- [x] CLI: `plotui line|scatter|bar` from stdin or a file — interactive on a
-      TTY, one static frame when piped; installed via curl, Homebrew, cargo,
-      or pip (see Install above)
-- [ ] CLI v2: `--follow` streaming, `scatter3d`, histogram/density/count
-      transforms, `--out png`
-- [ ] Prebuilt static libs for the Go bindings (today: local source build)
-
 ## License
 
-MIT
+MIT, except for one embedded asset: chart text is set in
+[Martian Mono](https://github.com/evilmartians/mono) (Copyright 2020 The
+Martian Mono Project Authors), used under the SIL Open Font License 1.1. The
+glyph outlines are compiled into `plotui-core` as
+`crates/plotui-core/src/glyphs.rs`; the license travels with them in
+`crates/plotui-core/fonts/MartianMono-OFL.txt`. The font carries no Reserved
+Font Name, and nothing about the OFL reaches your code — it covers the font
+data, not the crate.