Release v0.2.0: spring animation, ping target, JSON stream, stats persistence, custom themes

- Add spring-physics value animation for smooth throughput transitions
- Make ping target configurable via --ping flag and ping_target config (default 1.1.1.1)
- Add --json-stream continuous JSON Lines output for real-time pipelines
- Persist daily traffic totals to ~/.config/flow/stats.json across restarts
- Support custom theme .toml files in ~/.config/flow/themes/
- Add make check target (fmt, vet, lint, test)
- Add ROADMAP.md and expand test coverage (animate, history persist, ping)
- Bump VERSION to 0.2.0 and update CHANGELOG/README

Author: programmersd21

CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.2.0] - 2026-07-15
+
+### Added
+- Spring-smoothed value animation — Throughput values now glide smoothly toward their targets using spring physics instead of snapping, matching the architecture documented in README.
+- Configurable ping target — Customize the latency check host via `ping_target` in config or `--ping` CLI flag (default: 1.1.1.1).
+- Streaming JSON output (`--json-stream`) — Continuous JSON Lines output to stdout for piping into other tools, one sample per line.
+- Daily totals persistence — Today's traffic totals are saved to `~/.config/flow/stats.json` on quit and restored on next launch, so totals survive process restarts.
+- Custom theme files — Place `.toml` files in `~/.config/flow/themes/` to define user themes with custom colors and gradients, automatically picked up at startup.
+- ROADWAY.md — Published project roadmap covering v0.2.x through v0.5.x.
+- Expanded test coverage — New test suites for animate package (spring physics, easing) and history persistence (save/load round-trip).
+
+### Changed
+- VERSION bumped to 0.2.0.
+- Makefile — Added `make check` target for format, vet, lint, and test in one command.
+
 ## [0.1.7] - 2026-07-10
 
 ### Added

Makefile

@@ -68,6 +68,13 @@ demo: build
 		echo "install gifsicle for further optimization: brew install gifsicle"; \
 	fi
 
+## check: format, vet, lint, and test
+check:
+	go fmt ./...
+	go vet ./...
+	golangci-lint run ./...
+	go test ./...
+
 ## help: print this message
 help:
 	@sed -n 's/^## //p' $(MAKEFILE_LIST) 2>/dev/null || findstr /B "##" Makefile

README.md

@@ -142,10 +142,11 @@ flow adjusts its display according to terminal width and height.
 
 ## Features
 
-- Live latency (ping) indicator with color-coded ↔ display
+- Live latency (ping) indicator with color-coded ↔ display and configurable target
+- Spring-smoothed throughput animation for premium visual feel
 - Network processes panel — press `n` to view active processes sorted by connection count
 - Interface details overlay — press `I` (capital i) to view IP addresses, MAC, link status, MTU
-- Theme selector with 8 built-in themes — press `t` to browse and select
+- Theme selector with 8 built-in themes plus custom user themes — press `t` to browse and select
 - Reset confirmation — press `r` twice to confirm, preventing accidental data loss
 - Real-time download and upload throughput
 - Interpolated display values using spring-based animation
@@ -155,7 +156,9 @@ flow adjusts its display according to terminal width and height.
 - Minimalist, high-end unicode today statistics and keybinding footer
 - Directional indicators for traffic trend
 - Automatic unit scaling from B/s to GB/s
-- Session peak tracking and daily traffic totals
+- Session peak tracking and daily traffic totals (persisted across restarts)
+- Streaming JSON output (`--json-stream`) for real-time data pipelines
+- Custom theme files in `~/.config/flow/themes/`
 - Four display modes with automatic responsive switching on both width and height resize
 - No required configuration; optional TOML configuration file
 - Non-interactive output modes for use in scripts
@@ -195,8 +198,10 @@ flow --tiny                 # single-line mode for status bars
 flow --mini                 # graphs-only mode, no headers/footers
 flow --compact              # compact layout with title row and waveforms
 flow --json                  # single JSON output, then exit
+flow --json-stream           # continuous JSON lines output
 flow --once                  # single plain-text output, then exit
 flow --interface wlan0       # specify network interface
+flow --ping 8.8.8.8          # ping target for latency measurement
 flow --refresh 500ms         # adjust sampling interval (default 100ms)
 flow --bits                 # display in bits/sec instead of bytes/sec
 flow --no-color
@@ -260,13 +265,14 @@ A configuration file is created automatically on first run:
 The `XDG_CONFIG_HOME` environment variable is respected on Linux if set.
 
 ```toml
-refresh   = "100ms"   # sampling interval
-history   = 60        # seconds of retained sparkline history
-theme     = "default"
-unit      = "auto"    # auto, kb, mb, or gb
-interface = "auto"    # auto, or a specific interface name (e.g. eth0, wlan0)
-no_color  = false
-bits      = false     # display throughput in bits/sec
+refresh     = "100ms"   # sampling interval
+history     = 60        # seconds of retained sparkline history
+theme       = "default"
+unit        = "auto"    # auto, kb, mb, or gb
+interface   = "auto"    # auto, or a specific interface name (e.g. eth0, wlan0)
+no_color    = false
+bits        = false     # display throughput in bits/sec
+ping_target = "1.1.1.1" # host for latency measurement
 ```
 
 <details>
@@ -290,6 +296,24 @@ All elements are centered on both axes. Panel border color changes according to
 
 </details>
 
+### Custom themes
+
+Place `.toml` files in `~/.config/flow/themes/` to define user themes:
+
+```toml
+name = "my-theme"
+text_dim    = "#64748b"
+text_muted  = "#94a3b8"
+text_soft   = "#cbd5e1"
+text_base   = "#e2e8f0"
+text_bright = "#f8fafc"
+text_pure   = "#ffffff"
+border      = "#334155"
+accent      = "#6366f1"
+download    = ["#3b82f6", "#6366f1", "#06b6d4", "#00f5d4", "#ffffff"]
+upload      = ["#10b981", "#22c55e", "#84cc16", "#a3e635", "#ffffff"]
+```
+
 ## Architecture
 
 flow runs two independent loops connected by a channel.

ROADMAP.md

@@ -0,0 +1,29 @@
+# Roadmap
+
+## v0.2.x: Polish & Practicality
+
+- Spring-smoothed value animation
+- Configurable ping target
+- Streaming JSON output (`--json-stream`)
+- Daily totals persisted between sessions
+- Custom user themes
+- Data export (`--json-stream` for piping)
+
+## v0.3.x: Deeper Insight
+
+- Per-connection process bandwidth (platform-permitting)
+- Historical sparklines (multi-hour view)
+- Configurable notification thresholds
+- Network interface discovery on startup
+
+## v0.4.x: Integration
+
+- Web dashboard companion (optional HTTP server)
+- Remote monitoring over SSH
+- Plugin system for custom data sources
+
+## v0.5.x: Scale
+
+- Multiple interface dashboard
+- Alert/webhook integration
+- Session replay and export

VERSION

@@ -1 +1 @@
-0.1.7
+0.2.0

cmd/flow/main.go

@@ -23,11 +23,13 @@ func main() {
 	flagMini := flag.Bool("mini", false, "graphs-only mini mode")
 	flagCompact := flag.Bool("compact", false, "numbers-only compact mode")
 	flagJSON := flag.Bool("json", false, "one-shot JSON snapshot, then exit")
+	flagJSONStream := flag.Bool("json-stream", false, "continuous JSON lines output")
 	flagOnce := flag.Bool("once", false, "one-shot plain-text snapshot, then exit")
 	flagIface := flag.String("interface", "", "force a specific network interface")
 	flagRefresh := flag.Duration("refresh", 0, "sampling interval (e.g. 250ms)")
 	flagNoColor := flag.Bool("no-color", false, "disable ANSI color output")
 	flagBits := flag.Bool("bits", false, "display throughput in bits/sec instead of bytes/sec")
+	flagPing := flag.String("ping", "", "ping target host (default: 1.1.1.1)")
 	flagVersion := flag.Bool("version", false, "print version and exit")
 
 	flag.Usage = func() {
@@ -63,12 +65,20 @@ func main() {
 	if *flagBits {
 		cfg.Bits = true
 	}
+	if *flagPing != "" {
+		cfg.PingTarget = *flagPing
+	}
 
 	col := collector.New(cfg.Interface)
 
 	refresh := cfg.RefreshDuration()
 	smp := sampler.New(col, refresh)
 
+	if *flagJSONStream {
+		runJSONStream(smp, refresh, cfg.Bits)
+		return
+	}
+
 	if *flagJSON || *flagOnce {
 		runOnce(col, smp, refresh, *flagJSON, cfg.Bits)
 		return
@@ -190,6 +200,34 @@ func runOnce(col *collector.Collector, smp *sampler.Sampler, refresh time.Durati
 	)
 }
 
+func runJSONStream(smp *sampler.Sampler, refresh time.Duration, bits bool) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	go smp.Run(ctx)
+
+	enc := json.NewEncoder(os.Stdout)
+	s1 := <-smp.Out
+	if s1.Err != nil {
+		fmt.Fprintf(os.Stderr, "flow: %v\n", s1.Err)
+		os.Exit(1)
+	}
+	for s := range smp.Out {
+		if s.Err != nil {
+			fmt.Fprintf(os.Stderr, "flow: %v\n", s.Err)
+			os.Exit(1)
+		}
+		_ = enc.Encode(map[string]interface{}{
+			"interface":      s.Interface,
+			"download_bps":   s.DownBps,
+			"upload_bps":     s.UpBps,
+			"download_human": ui.FormatBpsExt(s.DownBps, ui.UnitAuto, bits),
+			"upload_human":   ui.FormatBpsExt(s.UpBps, ui.UnitAuto, bits),
+			"timestamp":      s.At.Format(time.RFC3339Nano),
+		})
+	}
+}
+
 func autoUnitExt(bps float64, bits bool) string {
 	if bits {
 		bps = bps * 8

internal/animate/ease.go

@@ -2,6 +2,11 @@ package animate
 
 import "math"
 
+const (
+	stiffness = 180.0
+	damping   = 12.0
+)
+
 func Lerp(a, b, t float64) float64 {
 	return a + (b-a)*t
 }
@@ -23,3 +28,13 @@ func Clamp01(t float64) float64 {
 	}
 	return t
 }
+
+func Spring(current, target float64, velocity *float64, dt float64) float64 {
+	force := stiffness * (target - current)
+	*velocity += force * dt
+	*velocity *= 1.0 - damping*dt
+	if *velocity < 0.0001 && *velocity > -0.0001 {
+		*velocity = 0
+	}
+	return current + *velocity*dt
+}

internal/animate/ease_test.go

@@ -0,0 +1,50 @@
+package animate
+
+import (
+	"math"
+	"testing"
+)
+
+func TestClamp01(t *testing.T) {
+	if got := Clamp01(-0.5); got != 0 {
+		t.Errorf("Clamp01(-0.5) = %f; want 0", got)
+	}
+	if got := Clamp01(1.5); got != 1 {
+		t.Errorf("Clamp01(1.5) = %f; want 1", got)
+	}
+	if got := Clamp01(0.5); got != 0.5 {
+		t.Errorf("Clamp01(0.5) = %f; want 0.5", got)
+	}
+}
+
+func TestLerp(t *testing.T) {
+	if got := Lerp(0, 100, 0.5); got != 50 {
+		t.Errorf("Lerp(0, 100, 0.5) = %f; want 50", got)
+	}
+}
+
+func TestSpring(t *testing.T) {
+	var vel float64
+	val := Spring(0, 100, &vel, 0.016)
+	if val <= 0 {
+		t.Errorf("Spring(0, 100) = %f; want > 0 after one step", val)
+	}
+}
+
+func TestColorLerp(t *testing.T) {
+	r, g, b := ColorLerp(0, 0, 0, 255, 255, 255, 0.5)
+	if r != 128 || g != 128 || b != 128 {
+		t.Errorf("ColorLerp(black, white, 0.5) = (%d,%d,%d); want (128,128,128)", r, g, b)
+	}
+}
+
+func TestSpringConverges(t *testing.T) {
+	var vel float64
+	val := 0.0
+	for i := 0; i < 1000; i++ {
+		val = Spring(val, 100, &vel, 0.016)
+	}
+	if math.Abs(val-100) > 1 {
+		t.Errorf("Spring did not converge: %f (want ~100)", val)
+	}
+}

internal/config/config.go

@@ -13,24 +13,26 @@ import (
 )
 
 type Config struct {
-	Refresh   duration `toml:"refresh"`
-	History   int      `toml:"history"` // seconds of sparkline history
-	Theme     string   `toml:"theme"`
-	Unit      string   `toml:"unit"`      // auto | kb | mb | gb
-	Interface string   `toml:"interface"` // auto | specific name
-	NoColor   bool     `toml:"no_color"`
-	Bits      bool     `toml:"bits"`
+	Refresh    duration `toml:"refresh"`
+	History    int      `toml:"history"`
+	Theme      string   `toml:"theme"`
+	Unit       string   `toml:"unit"`
+	Interface  string   `toml:"interface"`
+	NoColor    bool     `toml:"no_color"`
+	Bits       bool     `toml:"bits"`
+	PingTarget string   `toml:"ping_target"`
 }
 
 func Defaults() Config {
 	return Config{
-		Refresh:   duration{100 * time.Millisecond},
-		History:   60,
-		Theme:     "default",
-		Unit:      "auto",
-		Interface: "auto",
-		NoColor:   false,
-		Bits:      false,
+		Refresh:    duration{100 * time.Millisecond},
+		History:    60,
+		Theme:      "default",
+		Unit:       "auto",
+		Interface:  "auto",
+		NoColor:    false,
+		Bits:       false,
+		PingTarget: "1.1.1.1",
 	}
 }
 
@@ -78,6 +80,7 @@ func Save(cfg Config) error {
 		cfg.Interface,
 		boolStr(cfg.NoColor),
 		boolStr(cfg.Bits),
+		cfg.PingTarget,
 	)
 	return err
 }
@@ -117,20 +120,22 @@ func writeDefaults(path string, cfg Config) error {
 		cfg.Interface,
 		boolStr(cfg.NoColor),
 		boolStr(cfg.Bits),
+		cfg.PingTarget,
 	)
 	return err
 }
 
 const defaultTOML = `# flow configuration
 # https://github.com/programmersd21/flow
 
-refresh   = "%s"     # sampling interval (e.g. "100ms", "250ms", "1s")
-history   = %d       # seconds of sparkline history retained
-theme     = "%s"
-unit      = "%s"     # auto | kb | mb | gb
-interface = "%s"     # auto or interface name (e.g. "eth0", "wlan0")
-no_color  = %s
-bits      = %s       # display throughput in bits/sec instead of bytes/sec
+refresh     = "%s"     # sampling interval (e.g. "100ms", "250ms", "1s")
+history     = %d       # seconds of sparkline history
+theme       = "%s"
+unit        = "%s"     # auto | kb | mb | gb
+interface   = "%s"     # auto or interface name (e.g. "eth0", "wlan0")
+no_color    = %s
+bits        = %s       # display in bits/sec instead of bytes/sec
+ping_target = "%s"     # host for latency measurement
 `
 
 func boolStr(b bool) string {