pre-flight: bandwidth test + persistent config

First-run host launch now offers a one-time upstream measurement
against speed.cloudflare.com/__up via ureq (~5 MB POST, ~5s). The
result lives at ~/.config/pixelpass/config.toml under [bandwidth]
and feeds the default --max-viewers calculation on subsequent runs.

Sticky semantics for the dialog:
- Unmeasured: first-run prompt (Run / Skip)
- Measured / Skipped: silent — never re-prompts
- Failed: ask again on next launch (Retry / give up → Skipped)

`pixelpass --reconfigure` re-runs the test unconditionally for users
whose connection has changed (new ISP, moved house, etc.).

--max-viewers is now Option<u32>. When unset, host startup loads the
saved measurement, runs recommended_max_viewers(safe_mbps, bitrate),
and surfaces the source in the banner: "max viewers : N (auto: X.X
Mbps measured upstream)" — or user-specified / default fallback.

User verified end-to-end on 2026-05-21 16:54 EDT: first-run dialog,
skip path, run path, --reconfigure refresh, and banner integration
all work as expected.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

src/common/config.rs

@@ -0,0 +1,101 @@
+//! Persistent user-level config at `~/.config/pixelpass/config.toml`.
+//!
+//! Right now this only tracks the bandwidth pre-flight result. Future
+//! preferences (default player, default bitrate, etc.) can hang off the
+//! same file under their own `[section]`.
+
+use anyhow::{Context, Result};
+use chrono::{DateTime, Utc};
+use directories::ProjectDirs;
+use serde::{Deserialize, Serialize};
+use std::fs;
+use std::io::Write;
+use std::path::PathBuf;
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct Config {
+    #[serde(default)]
+    pub bandwidth: BandwidthEntry,
+}
+
+/// Result of the first-run upstream measurement.
+///
+/// `status = "unmeasured"` means we've never asked the user — show the
+/// first-run dialog. `"measured"` means we have a number. `"skipped"`
+/// means the user opted out (sticky — don't ask again). `"failed"`
+/// means the last attempt errored and we should ask the user on next
+/// interactive launch whether to retry.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct BandwidthEntry {
+    #[serde(default = "default_status")]
+    pub status: BandwidthStatus,
+    #[serde(default)]
+    pub upstream_mbps: Option<f64>,
+    #[serde(default)]
+    pub measured_at: Option<DateTime<Utc>>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum BandwidthStatus {
+    Unmeasured,
+    Measured,
+    Skipped,
+    Failed,
+}
+
+impl Default for BandwidthStatus {
+    fn default() -> Self {
+        Self::Unmeasured
+    }
+}
+
+fn default_status() -> BandwidthStatus {
+    BandwidthStatus::Unmeasured
+}
+
+/// Returns `~/.config/pixelpass/config.toml` (or the XDG equivalent on other
+/// platforms). The parent directory is created lazily by [`save`].
+pub fn config_path() -> Result<PathBuf> {
+    let dirs = ProjectDirs::from("", "", "pixelpass")
+        .context("could not locate a config directory for pixelpass")?;
+    Ok(dirs.config_dir().join("config.toml"))
+}
+
+/// Returns the loaded config, or a `Default` instance if the file doesn't
+/// exist yet. Bubble up parse errors so we don't silently overwrite a
+/// hand-edited config the user is debugging.
+pub fn load() -> Result<Config> {
+    let path = config_path()?;
+    match fs::read_to_string(&path) {
+        Ok(s) => toml::from_str::<Config>(&s)
+            .with_context(|| format!("failed to parse {}", path.display())),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(Config::default()),
+        Err(e) => Err(e).with_context(|| format!("failed to read {}", path.display())),
+    }
+}
+
+/// Atomic write via tempfile-in-same-dir + rename.
+pub fn save(cfg: &Config) -> Result<()> {
+    let path = config_path()?;
+    let parent = path
+        .parent()
+        .context("config path has no parent directory")?;
+    fs::create_dir_all(parent)
+        .with_context(|| format!("failed to create {}", parent.display()))?;
+
+    let serialized =
+        toml::to_string_pretty(cfg).context("failed to serialize config to TOML")?;
+
+    let tmp = parent.join(format!(".config.toml.tmp.{}", std::process::id()));
+    {
+        let mut f = fs::File::create(&tmp)
+            .with_context(|| format!("failed to create {}", tmp.display()))?;
+        f.write_all(serialized.as_bytes())
+            .with_context(|| format!("failed to write {}", tmp.display()))?;
+        f.sync_all().ok();
+    }
+    fs::rename(&tmp, &path)
+        .with_context(|| format!("failed to rename {} -> {}", tmp.display(), path.display()))?;
+    Ok(())
+}