Skip to content

Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.

222 KB
Raw Blame
// SPDX-License-Identifier: MPL-2.0
//! Message bodies for protocol v0 (protocol §5, §7, §9).

use serde::{Deserialize, Serialize};

use crate::{DeviceId, ErrorCode};

/// Message type names (the envelope's `t` field).
pub mod types {
    pub const HELLO: &str = "hello";
    pub const HELLO_UPDATE: &str = "hello.update";
    pub const PING: &str = "ping";
    pub const PONG: &str = "pong";
    pub const OK: &str = "ok";
    pub const ERROR: &str = "error";
    pub const STREAM: &str = "stream";
    pub const EVENT_BATTERY: &str = "event.battery";
    pub const EVENT_DEVICE: &str = "event.device";
    pub const DEVICE_RING: &str = "device.ring";

    pub const PAIR_REQUEST: &str = "pair.request";
    pub const PAIR_ACCEPT: &str = "pair.accept";
    pub const PAIR_COMMIT: &str = "pair.commit";
    pub const PAIR_NONCE: &str = "pair.nonce";
    pub const PAIR_REVEAL: &str = "pair.reveal";
    pub const PAIR_CONFIRM: &str = "pair.confirm";
    pub const PAIR_DONE: &str = "pair.done";
    pub const PAIR_REVOKE: &str = "pair.revoke";

    pub const NOTIFY_SNAPSHOT: &str = "notify.snapshot";
    pub const NOTIFY_POSTED: &str = "notify.posted";
    pub const NOTIFY_REMOVED: &str = "notify.removed";
    pub const NOTIFY_SYNC: &str = "notify.sync";

    pub const CLIP_SET: &str = "clip.set";
    pub const NOTIFY_DISMISS: &str = "notify.dismiss";
    pub const NOTIFY_ACTION: &str = "notify.action";
    pub const MEDIA_STATE: &str = "media.state";
    pub const MEDIA_SYNC: &str = "media.sync";
    pub const MEDIA_COMMAND: &str = "media.command";
    pub const MEDIA_WATCH: &str = "media.watch";
    pub const MEDIA_FILE: &str = "media.file";
    pub const MEDIA_FILE_META: &str = "media.file.meta";
    pub const PC_POWER: &str = "pc.power";
    pub const PC_WAKE_INFO: &str = "pc.wake_info";
    pub const LINK_OPEN: &str = "link.open";
    pub const TASK_NOTIFY: &str = "task.notify";
    pub const PHOTOS_NEW: &str = "photos.new";
    pub const PHOTOS_ALBUMS: &str = "photos.albums";
    pub const PHOTOS_ALBUMS_LIST: &str = "photos.albums.list";
    pub const PHOTOS_LIST: &str = "photos.list";
    pub const PHOTOS_ITEMS: &str = "photos.items";
    pub const PHOTOS_THUMBS: &str = "photos.thumbs";
    pub const PHOTOS_THUMBS_LIST: &str = "photos.thumbs.list";
    pub const PHOTOS_GET: &str = "photos.get";
    pub const PHOTOS_SENDING: &str = "photos.sending";
    pub const PHOTOS_CHANGED: &str = "photos.changed";
    pub const CALL_STATE: &str = "call.state";
    pub const CALL_ACTION: &str = "call.action";
    pub const CALL_LOG: &str = "call.log";
    pub const CALL_LOG_CHANGED: &str = "call.log.changed";
    pub const CALL_DIAL: &str = "call.dial";
    pub const CALL_SIMS: &str = "call.sims";
    pub const CONTACTS_LIST: &str = "contacts.list";
    pub const CONTACTS_CHANGED: &str = "contacts.changed";
    pub const SMS_THREADS: &str = "sms.threads";
    pub const SMS_MESSAGES: &str = "sms.messages";
    pub const SMS_SEND: &str = "sms.send";
    pub const SMS_PART: &str = "sms.part";
    pub const SMS_CHANGED: &str = "sms.changed";
    pub const MIRROR_START: &str = "mirror.start";
    pub const MIRROR_STOP: &str = "mirror.stop";
    pub const MIRROR_POWER: &str = "mirror.power";
    pub const MIRROR_KEYFRAME: &str = "mirror.keyframe";
    pub const MIRROR_RESIZE: &str = "mirror.resize";
    pub const MIRROR_INPUT: &str = "mirror.input";
    pub const MIRROR_APPS: &str = "mirror.apps";
    pub const REMOTE_CHECK: &str = "remote.check";
    pub const REMOTE_INPUT: &str = "remote.input";
    pub const PHONE_TOGGLES: &str = "phone.toggles";
    pub const PHONE_TOGGLE_SET: &str = "phone.toggle.set";
    pub const DECK_LAYOUT: &str = "deck.layout";
    pub const DECK_STATE: &str = "deck.state";
    pub const DECK_PRESS: &str = "deck.press";
    pub const PC_AUDIO_SET: &str = "pc.audio.set";
    pub const STORAGE_LIST: &str = "storage.list";
    pub const STORAGE_ENTRIES: &str = "storage.entries";
    pub const STORAGE_READ: &str = "storage.read";
    pub const STORAGE_READ_META: &str = "storage.read.meta";
    pub const STORAGE_WRITE: &str = "storage.write";
    pub const STORAGE_WRITE_ACCEPT: &str = "storage.write.accept";
    pub const STORAGE_WRITE_DONE: &str = "storage.write.done";
    pub const STORAGE_MKDIR: &str = "storage.mkdir";
    pub const STORAGE_RENAME: &str = "storage.rename";
    pub const STORAGE_DELETE: &str = "storage.delete";
    pub const STORAGE_CHANGED: &str = "storage.changed";
    pub const ELEVATED_USB_START: &str = "elevated.usb.start";
    pub const ELEVATED_USB_READY: &str = "elevated.usb.ready";
    pub const MIC_START: &str = "mic.start";
    pub const MIC_STOP: &str = "mic.stop";
    pub const WEBCAM_START: &str = "webcam.start";
    pub const WEBCAM_STOP: &str = "webcam.stop";
    pub const WEBCAM_KEYFRAME: &str = "webcam.keyframe";
    pub const WEBCAM_OK: &str = "webcam.ok";
    pub const CAMERA_CAPTURE_REQUEST: &str = "camera.capture.request";
    pub const CAMERA_CAPTURE_OK: &str = "camera.capture.ok";
    pub const CAMERA_CAPTURE_CANCEL: &str = "camera.capture.cancel";
    pub const FILES_RESUME: &str = "files.resume";
    pub const FILES_CANCEL: &str = "files.cancel";
    pub const WAKE_RELAY: &str = "wake.relay";
    pub const AUDIO_PCM: &str = "audio.pcm";
}

/// What kind of device this is.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum DeviceKind {
    Phone,
    Tablet,
    Desktop,
    Laptop,
    #[serde(other)]
    Unknown,
}

/// A device's power level (see PLAN.md §4.6). Desktops report `NotApplicable`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum PowerLevel {
    Basic,
    Assist,
    Elevated,
    #[serde(rename = "n/a")]
    NotApplicable,
    /// Unknown values (e.g. from a newer peer) are treated as Basic.
    #[serde(other)]
    Unknown,
}

impl PowerLevel {
    /// The level to use for capability decisions.
    pub fn effective(self) -> PowerLevel {
        match self {
            PowerLevel::Unknown => PowerLevel::Basic,
            other => other,
        }
    }
}

/// Limits for measured display geometry (`DeviceInfo.screen`, protocol §5.1).
pub mod screen_limits {
    pub const VERSION: u32 = 1;
    pub const MIN_ASPECT: f32 = 0.2;
    pub const MAX_ASPECT: f32 = 5.0;
    pub const MAX_CORNER_RADIUS: f32 = 0.5;
    pub const MAX_CUTOUTS: usize = 8;
    pub const MAX_CUTOUT_PATH_BYTES: usize = 4096;
}

fn approx_eq_f32(a: f32, b: f32) -> bool {
    a.to_bits() == b.to_bits() || (a - b).abs() <= 1e-5
}

fn round_norm(v: f32) -> f32 {
    (v * 10000.0).round() / 10000.0
}

/// Normalized `[0.0, 1.0]` bounding rectangle on the upright portrait display.
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub struct ScreenRect {
    pub x: f32,
    pub y: f32,
    pub w: f32,
    pub h: f32,
}

impl PartialEq for ScreenRect {
    fn eq(&self, other: &Self) -> bool {
        approx_eq_f32(self.x, other.x)
            && approx_eq_f32(self.y, other.y)
            && approx_eq_f32(self.w, other.w)
            && approx_eq_f32(self.h, other.h)
    }
}
impl Eq for ScreenRect {}

impl ScreenRect {
    pub fn sanitized(self) -> Option<Self> {
        if !self.x.is_finite()
            || !self.y.is_finite()
            || !self.w.is_finite()
            || !self.h.is_finite()
            || self.w <= 0.0
            || self.h <= 0.0
        {
            return None;
        }
        let x = round_norm(self.x.clamp(0.0, 1.0));
        let y = round_norm(self.y.clamp(0.0, 1.0));
        let w = round_norm(self.w.clamp(0.0, (1.0 - x).max(0.0)));
        let h = round_norm(self.h.clamp(0.0, (1.0 - y).max(0.0)));
        (w > 0.0 && h > 0.0).then_some(Self { x, y, w, h })
    }
}

/// Normalized rounded-corner radii `[tl, tr, br, bl]` as fractions of upright screen width (`0.0..=0.5`).
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub struct ScreenCorners {
    pub tl: f32,
    pub tr: f32,
    pub br: f32,
    pub bl: f32,
}

impl PartialEq for ScreenCorners {
    fn eq(&self, other: &Self) -> bool {
        approx_eq_f32(self.tl, other.tl)
            && approx_eq_f32(self.tr, other.tr)
            && approx_eq_f32(self.br, other.br)
            && approx_eq_f32(self.bl, other.bl)
    }
}
impl Eq for ScreenCorners {}

impl ScreenCorners {
    pub fn sanitized(self) -> Option<Self> {
        if !self.tl.is_finite() || !self.tr.is_finite() || !self.br.is_finite() || !self.bl.is_finite() {
            return None;
        }
        Some(Self {
            tl: round_norm(self.tl.clamp(0.0, screen_limits::MAX_CORNER_RADIUS)),
            tr: round_norm(self.tr.clamp(0.0, screen_limits::MAX_CORNER_RADIUS)),
            br: round_norm(self.br.clamp(0.0, screen_limits::MAX_CORNER_RADIUS)),
            bl: round_norm(self.bl.clamp(0.0, screen_limits::MAX_CORNER_RADIUS)),
        })
    }
}

/// Measured front-display geometry of a phone or tablet (`DeviceInfo.screen`, protocol §5.1).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ScreenShape {
    /// Schema version (currently `1`).
    pub v: u32,
    /// Upright display aspect ratio (`width / height`, e.g. `0.45` for 9:20).
    pub aspect: f32,
    /// Measured corner radii as fractions of screen width (`Display.getRoundedCorner()` on API 31+).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub corners: Option<ScreenCorners>,
    /// Measured cutout bounding boxes (`DisplayCutout.getBoundingRects()`, normalized `0.0..=1.0`).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub cutouts: Vec<ScreenRect>,
    /// Measured cutout vector path (`DisplayCutout.getCutoutPath()` on API 31+, normalized SVG path in `0.0..=1.0`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cutout_path: Option<String>,
}

impl PartialEq for ScreenShape {
    fn eq(&self, other: &Self) -> bool {
        self.v == other.v
            && approx_eq_f32(self.aspect, other.aspect)
            && self.corners == other.corners
            && self.cutouts == other.cutouts
            && self.cutout_path == other.cutout_path
    }
}
impl Eq for ScreenShape {}

impl ScreenShape {
    pub fn sanitized(self) -> Option<Self> {
        if self.v != screen_limits::VERSION
            || !self.aspect.is_finite()
            || !(screen_limits::MIN_ASPECT..=screen_limits::MAX_ASPECT).contains(&self.aspect)
        {
            return None;
        }
        let cutout_path = self.cutout_path.and_then(|s| {
            let trimmed = s.trim();
            if trimmed.is_empty() || trimmed.len() > screen_limits::MAX_CUTOUT_PATH_BYTES {
                return None;
            }
            let valid_chars = trimmed.chars().all(|c| {
                c.is_ascii_digit()
                    || c.is_ascii_whitespace()
                    || matches!(
                        c,
                        'M' | 'L'
                            | 'H'
                            | 'V'
                            | 'C'
                            | 'S'
                            | 'Q'
                            | 'T'
                            | 'A'
                            | 'Z'
                            | 'm'
                            | 'l'
                            | 'h'
                            | 'v'
                            | 'c'
                            | 's'
                            | 'q'
                            | 't'
                            | 'a'
                            | 'z'
                            | '.'
                            | '-'
                            | '+'
                            | ','
                    )
            });
            valid_chars.then(|| trimmed.to_owned())
        });
        let cutouts = self
            .cutouts
            .into_iter()
            .filter_map(ScreenRect::sanitized)
            .take(screen_limits::MAX_CUTOUTS)
            .collect();
        Some(Self {
            v: screen_limits::VERSION,
            aspect: round_norm(self.aspect),
            corners: self.corners.and_then(ScreenCorners::sanitized),
            cutouts,
            cutout_path,
        })
    }
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeviceInfo {
    pub name: String,
    pub kind: DeviceKind,
    pub os: String,
    pub os_ver: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub model: Option<String>,
    /// Optional ARGB seed color for Material You sync.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub accent: Option<u32>,
    /// Optional measured front-display geometry for phones/tablets.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub screen: Option<ScreenShape>,
    /// Identifies the physical device across app reinstalls (a new identity key each
    /// time), so a re-paired device replaces its old entry instead of appearing twice.
    /// A salted hash, never the raw platform ID; see `install_id_from`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub install_id: Option<String>,
}

/// A device's name or model, at most, in characters.
pub const MAX_DEVICE_NAME_CHARS: usize = 64;
/// A device's OS name or version, at most, in characters.
pub const MAX_DEVICE_OS_CHARS: usize = 32;

/// `text` without control characters or the invisible marks that reorder
/// text (a name could otherwise show reversed or disguised), cut to
/// `max_chars` and trimmed.
fn clean_device_text(text: &str, max_chars: usize) -> String {
    let is_direction_mark = |c: char| matches!(c, '\u{061C}' | '\u{200E}' | '\u{200F}' | '\u{202A}'..='\u{202E}' | '\u{2066}'..='\u{2069}');
    let clean: String =
        text.chars().filter(|c| !c.is_control() && !is_direction_mark(*c)).take(max_chars).collect();
    clean.trim().to_owned()
}

impl DeviceInfo {
    /// What another device says about itself, made safe to store and show.
    pub fn sanitized(mut self) -> Self {
        self.name = clean_device_text(&self.name, MAX_DEVICE_NAME_CHARS);
        self.os = clean_device_text(&self.os, MAX_DEVICE_OS_CHARS);
        self.os_ver = clean_device_text(&self.os_ver, MAX_DEVICE_OS_CHARS);
        self.model =
            self.model.map(|m| clean_device_text(&m, MAX_DEVICE_NAME_CHARS)).filter(|m| !m.is_empty());
        self.screen = self.screen.and_then(ScreenShape::sanitized);
        self.install_id = self.install_id.filter(|id| is_valid_install_id(id));
        self
    }
}

/// Length of an install ID in hex characters (128 bits).
pub const INSTALL_ID_LEN: usize = 32;

/// Whether `id` is a well-formed install ID: lowercase hex, [`INSTALL_ID_LEN`] long.
pub fn is_valid_install_id(id: &str) -> bool {
    id.len() == INSTALL_ID_LEN && id.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Hello {
    pub proto: u32,
    pub min: u32,
    pub app: String,
    pub device: DeviceInfo,
    #[serde(default)]
    pub caps: Vec<String>,
    pub power: PowerLevel,
}

#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct HelloUpdate {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub caps: Option<Vec<String>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub power: Option<PowerLevel>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub device: Option<DeviceInfo>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct Ping {
    /// Sender's monotonic clock in milliseconds.
    pub ts: u64,
}

/// Echoes the `ts` of the matching ping.
pub type Pong = Ping;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Battery {
    pub level: u8,
    pub charging: bool,
    /// "ac", "usb" or "wireless".
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub plugged: Option<String>,
    /// Estimated minutes until full when charging (`BatteryManager.computeChargeTimeRemaining()`), if known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub full_in: Option<u16>,
    /// Cellular signal strength in bars (`0..=4`), if known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cell_bars: Option<u8>,
    /// Cellular network generation/type (`"5G"`, `"LTE"`, `"4G"`, `"3G"`, `"2G"`), if known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cell_type: Option<String>,
    /// Wi-Fi signal strength in bars (`0..=4`), if connected to Wi-Fi and known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wifi_bars: Option<u8>,
}

impl Battery {
    pub fn sanitized(mut self) -> Self {
        self.level = self.level.min(100);
        if !self.charging {
            self.full_in = None;
        } else if let Some(mins) = self.full_in
            && (mins == 0 || mins > 24 * 60)
        {
            self.full_in = None;
        }
        self.cell_bars = self.cell_bars.map(|b| b.min(4));
        self.cell_type =
            clean_text(self.cell_type.map(|s| s.chars().filter(|c| !c.is_control()).collect()), 8);
        self.wifi_bars = self.wifi_bars.map(|b| b.min(4));
        self.plugged = self.plugged.filter(|p| matches!(p.as_str(), "ac" | "usb" | "wireless"));
        self
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct Ring {
    pub on: bool,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ErrorBody {
    pub code: ErrorCode,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub msg: Option<String>,
}

/// First frame of every non-control stream.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StreamHeader {
    pub svc: String,
    pub op: String,
    pub v: u32,
}

/// An empty body (`{}`).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct Empty {}

// ---- Pairing (protocol §9) ----

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PairRequest {
    pub device: DeviceInfo,
    #[serde(with = "serde_bytes")]
    pub proof: Vec<u8>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PairAccept {
    pub device: DeviceInfo,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PairCommit {
    pub device: DeviceInfo,
    #[serde(with = "serde_bytes")]
    pub c: Vec<u8>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PairNonce {
    pub device: DeviceInfo,
    #[serde(rename = "nB", with = "serde_bytes")]
    pub n_b: Vec<u8>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PairReveal {
    #[serde(rename = "nA", with = "serde_bytes")]
    pub n_a: Vec<u8>,
}

// ---- Notifications (docs/protocol/notifications.md) ----

/// Size limits from the notifications spec (§2); senders and receivers both
/// enforce them with [`Notification::sanitized`].
pub mod notify_limits {
    pub const KEY_BYTES: usize = 256;
    pub const ACTION_ID_BYTES: usize = 64;
    pub const TITLE_CHARS: usize = 256;
    pub const TEXT_CHARS: usize = 4096;
    pub const ACTION_TITLE_CHARS: usize = 64;
    pub const ACTIONS: usize = 5;
    pub const ICON_BYTES: usize = 64 * 1024;
    pub const IMAGE_BYTES: usize = 160 * 1024;
    pub const SNAPSHOT_ITEMS: usize = 100;
    pub const LIVE_VERSION: u32 = 1;
    pub const CHIP_CHARS: usize = 32;
    pub const SEGMENTS: usize = 16;
    pub const POINTS: usize = 16;
    pub const CONVERSATION_VERSION: u32 = 1;
    pub const CONVERSATION_MESSAGES: usize = 25;
    pub const SENDER_CHARS: usize = 128;
    pub const AVATAR_BYTES: usize = 16 * 1024;
}

fn default_live_v() -> u32 {
    notify_limits::LIVE_VERSION
}

fn default_conversation_v() -> u32 {
    notify_limits::CONVERSATION_VERSION
}

/// One segment of a segmented progress bar (`Notification.ProgressStyle.Segment` on Android 16+).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct LiveSegment {
    /// Relative length of this segment (`> 0`).
    pub length: u32,
    /// Optional RGB/ARGB color; `None` when using the default theme color.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub color: Option<u32>,
}

/// One milestone point along a progress bar (`Notification.ProgressStyle.Point` on Android 16+).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct LivePoint {
    /// Position along `0..=max`.
    pub position: u32,
    /// Optional RGB/ARGB color; `None` when using the default theme color.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub color: Option<u32>,
}

/// Live Update metadata on a mirrored notification (`docs/protocol/notifications.md` §2.2).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NotificationLive {
    /// Schema version (currently `1`).
    #[serde(default = "default_live_v")]
    pub v: u32,
    /// Current progress (`0..=max`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub progress: Option<u32>,
    /// Maximum progress (`> 0` when determinate progress is present).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max: Option<u32>,
    /// True when progress is indeterminate.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub indeterminate: bool,
    /// Short critical status pill text (`Notification.getShortCriticalText()`, e.g. `"5 min"`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub chip: Option<String>,
    /// Optional segments of an Android 16 `ProgressStyle` bar.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub segments: Vec<LiveSegment>,
    /// Optional milestone points along an Android 16 `ProgressStyle` bar.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub points: Vec<LivePoint>,
    /// True when the notification shows a live elapsed/countdown timer (`EXTRA_SHOW_CHRONOMETER`)
    /// relative to `Notification.when` (Unix milliseconds).
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub chronometer: bool,
    /// True when the chronometer counts down toward `Notification.when` (`EXTRA_CHRONOMETER_COUNT_DOWN`).
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub countdown: bool,
}

impl Default for NotificationLive {
    fn default() -> Self {
        Self {
            v: notify_limits::LIVE_VERSION,
            progress: None,
            max: None,
            indeterminate: false,
            chip: None,
            segments: Vec::new(),
            points: Vec::new(),
            chronometer: false,
            countdown: false,
        }
    }
}

/// Never prints `chip` text in logs (protocol v0 §11).
impl std::fmt::Debug for NotificationLive {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("NotificationLive")
            .field("v", &self.v)
            .field("has_chip", &self.chip.is_some())
            .field("progress", &self.progress)
            .field("max", &self.max)
            .field("indeterminate", &self.indeterminate)
            .field("segments", &self.segments.len())
            .field("points", &self.points.len())
            .field("chronometer", &self.chronometer)
            .field("countdown", &self.countdown)
            .finish()
    }
}

impl NotificationLive {
    /// Applies limits and drops unknown schema versions (`v != 1`) or empty metadata.
    pub fn sanitized(mut self) -> Option<Self> {
        use notify_limits::*;
        if self.v != LIVE_VERSION {
            return None;
        }
        self.chip =
            clean_text(self.chip.map(|s| s.chars().filter(|c| !c.is_control()).collect()), CHIP_CHARS);
        self.segments.retain(|s| s.length > 0);
        self.segments.truncate(SEGMENTS);
        self.points.truncate(POINTS);
        if self.indeterminate {
            self.progress = None;
            self.max = None;
            self.segments.clear();
            self.points.clear();
        } else {
            if !self.segments.is_empty() && self.max.unwrap_or(0) == 0 {
                let sum = self.segments.iter().map(|s| s.length).fold(0u32, u32::saturating_add);
                if sum > 0 {
                    self.max = Some(sum);
                }
            }
            if self.max == Some(0) {
                self.max = None;
                self.progress = None;
            }
            if let Some(max) = self.max {
                self.progress = Some(self.progress.unwrap_or(0).min(max));
                self.points.retain(|p| p.position <= max);
            } else {
                self.progress = None;
                self.points.clear();
            }
        }
        if !self.chronometer {
            self.countdown = false;
        }
        if self.progress.is_none()
            && self.max.is_none()
            && !self.indeterminate
            && self.chip.is_none()
            && self.segments.is_empty()
            && self.points.is_empty()
            && !self.chronometer
        {
            return None;
        }
        Some(self)
    }
}

/// One message in a `Notification.MessagingStyle` conversation (`docs/protocol/notifications.md` §2.3).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NotificationChatMessage {
    /// Sender display name (`None` when sent by the phone's user).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sender: Option<String>,
    /// Message text.
    pub text: String,
    /// Message timestamp, Unix milliseconds.
    pub time: i64,
    /// True when sent by the phone's user (`MessagingStyle.user` or `Person == null`).
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub self_sent: bool,
    /// Optional sender avatar (JPEG/PNG, at most [`notify_limits::AVATAR_BYTES`]).
    #[serde(default, skip_serializing_if = "Option::is_none", with = "serde_bytes")]
    pub avatar: Option<Vec<u8>>,
}

/// Never prints sender names or message text (protocol v0 §11).
impl std::fmt::Debug for NotificationChatMessage {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("NotificationChatMessage")
            .field("time", &self.time)
            .field("self_sent", &self.self_sent)
            .field("has_avatar", &self.avatar.is_some())
            .finish_non_exhaustive()
    }
}

/// `Notification.MessagingStyle` conversation metadata on a mirrored notification (`docs/protocol/notifications.md` §2.3).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NotificationConversation {
    /// Schema version (currently `1`).
    #[serde(default = "default_conversation_v")]
    pub v: u32,
    /// Conversation title (group name or 1:1 contact name).
    pub title: String,
    /// True when `MessagingStyle.isGroupConversation` is true.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub group: bool,
    /// Conversation or contact avatar (JPEG/PNG, at most [`notify_limits::AVATAR_BYTES`]).
    #[serde(default, skip_serializing_if = "Option::is_none", with = "serde_bytes")]
    pub avatar: Option<Vec<u8>>,
    /// Messages in chronological order (oldest first, at most [`notify_limits::CONVERSATION_MESSAGES`]).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub messages: Vec<NotificationChatMessage>,
}

/// Never prints conversation title or messages (protocol v0 §11).
impl std::fmt::Debug for NotificationConversation {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("NotificationConversation")
            .field("v", &self.v)
            .field("group", &self.group)
            .field("messages", &self.messages.len())
            .field("has_avatar", &self.avatar.is_some())
            .finish_non_exhaustive()
    }
}

impl NotificationConversation {
    /// Applies limits and drops unknown schema versions (`v != 1`) or empty conversations.
    pub fn sanitized(mut self) -> Option<Self> {
        use notify_limits::*;
        if self.v != CONVERSATION_VERSION {
            return None;
        }
        self.title = clean_text(Some(self.title), TITLE_CHARS)?;
        if self.avatar.as_ref().is_some_and(|a| a.is_empty() || a.len() > AVATAR_BYTES) {
            self.avatar = None;
        }
        let mut cleaned = Vec::with_capacity(self.messages.len().min(CONVERSATION_MESSAGES));
        let skip = self.messages.len().saturating_sub(CONVERSATION_MESSAGES);
        for mut m in self.messages.into_iter().skip(skip) {
            let Some(text) = clean_text(Some(m.text), TEXT_CHARS) else {
                continue;
            };
            m.text = text;
            m.sender = if m.self_sent { None } else { clean_text(m.sender, SENDER_CHARS) };
            if m.avatar.as_ref().is_some_and(|a| a.is_empty() || a.len() > AVATAR_BYTES) {
                m.avatar = None;
            }
            cleaned.push(m);
        }
        if cleaned.is_empty() {
            return None;
        }
        self.messages = cleaned;
        Some(self)
    }
}

/// A button on a notification.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NotificationAction {
    /// Opaque to the PC.
    pub id: String,
    pub title: String,
    /// Takes text: shown as an inline reply field.
    #[serde(default)]
    pub reply: bool,
}

/// A phone notification, as mirrored to a PC.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Notification {
    /// The phone's ID for it.
    pub key: String,
    /// Package name, e.g. "com.whatsapp".
    pub app: String,
    /// User-visible app name.
    pub app_name: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub text: Option<String>,
    /// Secondary line, e.g. a conversation or account name.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sub: Option<String>,
    /// When it was posted, Unix milliseconds.
    pub when: i64,
    #[serde(default)]
    pub actions: Vec<NotificationAction>,
    /// Arrived without sound or pop-up on the phone.
    #[serde(default)]
    pub silent: bool,
    /// The app's icon (PNG), sent with an app's first notification per
    /// session.
    #[serde(default, skip_serializing_if = "Option::is_none", with = "serde_bytes")]
    pub icon: Option<Vec<u8>>,
    /// A picture it shows (a photo in a message, a big picture), JPEG.
    #[serde(default, skip_serializing_if = "Option::is_none", with = "serde_bytes")]
    pub image: Option<Vec<u8>>,
    /// Live Update metadata (ongoing progress, timer, or Android 16 Live Update).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub live: Option<NotificationLive>,
    /// `Notification.MessagingStyle` conversation metadata (RCS, WhatsApp, Telegram, Signal, etc.).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub conversation: Option<NotificationConversation>,
}

/// Never prints content: notification text must not reach logs (protocol
/// v0 §11).
impl std::fmt::Debug for Notification {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Notification")
            .field("app", &self.app)
            .field("actions", &self.actions.len())
            .field("silent", &self.silent)
            .field("live", &self.live.is_some())
            .field("conversation", &self.conversation.is_some())
            .finish_non_exhaustive()
    }
}

fn truncate_chars(s: &mut String, max: usize) {
    if let Some((cut, _)) = s.char_indices().nth(max) {
        s.truncate(cut);
    }
}

fn clean_text(s: Option<String>, max: usize) -> Option<String> {
    let mut s = s?.trim().to_owned();
    truncate_chars(&mut s, max);
    (!s.is_empty()).then_some(s)
}

impl Notification {
    /// Applies the spec's limits: truncates text, drops extra actions,
    /// oversized icons and malformed actions. `None` if the notification
    /// can't be shown at all (no key, or neither a title nor a text).
    pub fn sanitized(mut self) -> Option<Notification> {
        use notify_limits::*;
        if self.key.is_empty() || self.key.len() > KEY_BYTES {
            return None;
        }
        self.title = clean_text(self.title, TITLE_CHARS);
        self.text = clean_text(self.text, TEXT_CHARS);
        self.sub = clean_text(self.sub, TITLE_CHARS);
        self.live = self.live.and_then(NotificationLive::sanitized);
        self.conversation = self.conversation.and_then(NotificationConversation::sanitized);
        if self.title.is_none() && self.text.is_none() && self.conversation.is_none() {
            return None;
        }
        if self.title.is_none()
            && let Some(conv) = &self.conversation
        {
            self.title = Some(conv.title.clone());
        }
        if self.text.is_none()
            && let Some(conv) = &self.conversation
            && let Some(last) = conv.messages.last()
        {
            self.text = Some(last.text.clone());
        }
        truncate_chars(&mut self.app, TITLE_CHARS);
        truncate_chars(&mut self.app_name, TITLE_CHARS);
        self.actions.retain_mut(|a| {
            truncate_chars(&mut a.title, ACTION_TITLE_CHARS);
            !a.id.is_empty() && a.id.len() <= ACTION_ID_BYTES && !a.title.trim().is_empty()
        });
        self.actions.truncate(ACTIONS);
        if self.icon.as_ref().is_some_and(|i| i.is_empty() || i.len() > ICON_BYTES) {
            self.icon = None;
        }
        if self.image.as_ref().is_some_and(|i| i.is_empty() || i.len() > IMAGE_BYTES) {
            self.image = None;
        }
        Some(self)
    }
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NotifySnapshot {
    pub items: Vec<Notification>,
}

/// Body of `notify.removed` and `notify.dismiss`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NotifyKey {
    pub key: String,
}

/// Body of `notify.action`.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NotifyAction {
    pub key: String,
    pub action: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reply: Option<String>,
}

impl std::fmt::Debug for NotifyAction {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("NotifyAction").field("action", &self.action).finish_non_exhaustive()
    }
}

// ---- Media (docs/protocol/media.md) ----

/// Limits from docs/protocol/media.md.
pub mod media_limits {
    pub const PLAYERS: usize = 8;
    pub const ID_BYTES: usize = 256;
    pub const TEXT_CHARS: usize = 256;
    pub const ART_KEY_BYTES: usize = 64;
    pub const ART_BYTES: usize = 256 * 1024;
}

/// What a player can be asked to do (`MediaPlayer::actions`,
/// `MediaCommand::action`).
pub mod media_actions {
    pub const PLAY: &str = "play";
    pub const PAUSE: &str = "pause";
    pub const NEXT: &str = "next";
    pub const PREVIOUS: &str = "previous";
    pub const SEEK: &str = "seek";
    pub const ALL: &[&str] = &[PLAY, PAUSE, NEXT, PREVIOUS, SEEK];
}

/// Something playing (or paused) on a device.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MediaPlayer {
    /// The device's ID for the player, stable while it exists (e.g. the
    /// app's package name).
    pub id: String,
    /// User-visible app name.
    pub app: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub artist: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub album: Option<String>,
    #[serde(default)]
    pub playing: bool,
    /// Length, milliseconds.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub duration: Option<u64>,
    /// Position when this was sent, milliseconds; it moves on in real time
    /// while `playing`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub position: Option<u64>,
    /// Commands it takes, from [`media_actions`].
    #[serde(default)]
    pub actions: Vec<String>,
    /// Identifies the artwork; the same key means the same picture.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub art_key: Option<String>,
    /// The artwork (JPEG or PNG), sent once per key and session.
    #[serde(default, skip_serializing_if = "Option::is_none", with = "serde_bytes")]
    pub art: Option<Vec<u8>>,
}

/// Never prints what's playing (protocol v0 §11).
impl std::fmt::Debug for MediaPlayer {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("MediaPlayer")
            .field("id", &self.id)
            .field("playing", &self.playing)
            .field("actions", &self.actions)
            .finish_non_exhaustive()
    }
}

impl MediaPlayer {
    /// Applies the spec's limits. `None` if it can't be shown (no ID, or
    /// nothing to show it by).
    pub fn sanitized(mut self) -> Option<MediaPlayer> {
        use media_limits::*;
        if self.id.is_empty() || self.id.len() > ID_BYTES {
            return None;
        }
        truncate_chars(&mut self.app, TEXT_CHARS);
        self.title = clean_text(self.title, TEXT_CHARS);
        self.artist = clean_text(self.artist, TEXT_CHARS);
        self.album = clean_text(self.album, TEXT_CHARS);
        if self.title.is_none() && self.app.trim().is_empty() {
            return None;
        }
        let mut seen = std::collections::HashSet::new();
        self.actions.retain(|a| media_actions::ALL.contains(&a.as_str()) && seen.insert(a.clone()));
        if let (Some(position), Some(duration)) = (self.position, self.duration) {
            self.position = Some(position.min(duration));
        }
        if self.art_key.as_ref().is_some_and(|k| k.is_empty() || k.len() > ART_KEY_BYTES) {
            self.art_key = None;
        }
        if self.art_key.is_none() || self.art.as_ref().is_some_and(|a| a.is_empty() || a.len() > ART_BYTES) {
            self.art = None;
        }
        Some(self)
    }
}

/// Body of `media.state`: every player, most relevant first.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MediaState {
    pub players: Vec<MediaPlayer>,
}

/// Body of `media.command`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MediaCommand {
    pub player: String,
    pub action: String,
    /// For `seek`: where to, milliseconds.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub position: Option<u64>,
}

/// Play on phone (`docs/protocol/media.md` §4).
pub mod media_watch {
    /// Offered by phones that show a PC's playback streamed to them.
    pub const WATCH: &str = "media.watch";
    /// Offered by PCs that stream a player's picture and sound on request.
    pub const STREAM: &str = "media.stream";
    /// Stream service and operation for reading an offered file.
    pub const SERVICE: &str = "media";
    pub const OP_FILE: &str = "file";
    pub const VERSION: u32 = 1;
    /// The most one `media.file` read returns.
    pub const MAX_READ: u64 = 4 * 1024 * 1024;
}

/// A video file a PC player plays, offered with `media.watch` for the phone
/// to play itself (`docs/protocol/media.md` §4).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct WatchFile {
    /// Its file name, for the phone's player to tell the format by.
    pub name: String,
    /// Its size in bytes.
    pub size: u64,
    /// Where the PC had got to, milliseconds.
    #[serde(default)]
    pub position: u64,
}

impl WatchFile {
    pub fn is_valid(&self) -> bool {
        (1..=media_limits::TEXT_CHARS).contains(&self.name.chars().count())
            && is_valid_file_name(&self.name)
            && self.size > 0
    }
}

/// Body of `media.file` on a `media/file` stream: read `length` bytes of
/// the offered file from `offset`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct MediaFileRead {
    pub offset: u64,
    pub length: u64,
}

/// Body of `media.file.meta`: the file's size and how many bytes follow.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct MediaFileMeta {
    pub size: u64,
    pub length: u64,
}

/// Body of `media.watch`: a PC offers to stream what a player of its own
/// plays to the phone.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MediaWatch {
    /// The PC's ID for the player, as in `media.state`.
    pub player: String,
    /// What it plays, to show with the offer.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    /// A video file the phone plays itself, read from the PC, instead of
    /// watching the PC's stream.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub file: Option<WatchFile>,
}

impl MediaWatch {
    pub fn is_valid(&self) -> bool {
        (1..=media_limits::ID_BYTES).contains(&self.player.len())
            && self.title.as_ref().is_none_or(|t| t.chars().count() <= media_limits::TEXT_CHARS)
            && self.file.as_ref().is_none_or(WatchFile::is_valid)
    }
}

// ---- Actions (docs/protocol/actions.md) ----

/// Body of `pc.power`: `lock` or `sleep`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PcPower {
    pub action: String,
}

/// The longest link sent, in bytes.
pub const LINK_MAX_BYTES: usize = 4096;

/// Constants and limits for Wake-on-LAN (`docs/protocol/actions.md` §2.3).
pub mod wake {
    /// Offered by PCs that share their adapter addresses (`pc.wake_info`).
    pub const CAP: &str = "pc.wake";
    /// Maximum hardware addresses in a `pc.wake_info` message.
    pub const MAX_ADAPTERS: usize = 8;
    /// Maximum directed subnet broadcast addresses in a `pc.wake_info` message.
    pub const MAX_BROADCASTS: usize = 16;
    /// Size of a standard Wake-on-LAN magic packet (`6 + 16 * 6`).
    pub const MAGIC_PACKET_BYTES: usize = 102;
    /// Standard UDP ports for Wake-on-LAN magic packets.
    pub const DEFAULT_PORTS: &[u16] = &[9, 7];
}

/// Parses a 6-byte hardware (MAC) address written as `"aa:bb:cc:dd:ee:ff"` or
/// `"AA-BB-CC-DD-EE-FF"`. Rejects all-zero (`00:00:00:00:00:00`) and broadcast
/// (`ff:ff:ff:ff:ff:ff`) addresses.
pub fn parse_mac(s: &str) -> Option<[u8; 6]> {
    let s = s.trim();
    let sep = if s.contains(':') { ':' } else { '-' };
    let mut bytes = [0u8; 6];
    let mut parts = s.split(sep);
    for slot in &mut bytes {
        let part = parts.next()?;
        if part.len() != 2 || !part.bytes().all(|b| b.is_ascii_hexdigit()) {
            return None;
        }
        *slot = u8::from_str_radix(part, 16).ok()?;
    }
    // A multicast address (first octet's low bit set) is no adapter's own.
    if parts.next().is_some() || bytes == [0; 6] || bytes[0] & 1 == 1 {
        return None;
    }
    Some(bytes)
}

/// Formats a 6-byte hardware (MAC) address as lowercase `"aa:bb:cc:dd:ee:ff"`.
pub fn format_mac(mac: &[u8; 6]) -> String {
    format!("{:02x}:{:02x}:{:02x}:{:02x}:{:02x}:{:02x}", mac[0], mac[1], mac[2], mac[3], mac[4], mac[5])
}

/// Builds the standard 102-byte Wake-on-LAN magic packet: 6 bytes of `0xFF`
/// followed by `mac` repeated 16 times.
pub fn magic_packet(mac: &[u8; 6]) -> [u8; wake::MAGIC_PACKET_BYTES] {
    let mut pkt = [0xffu8; wake::MAGIC_PACKET_BYTES];
    for i in 0..16 {
        let start = 6 + i * 6;
        pkt[start..start + 6].copy_from_slice(mac);
    }
    pkt
}

/// Computes the directed IPv4 subnet broadcast address (`ip | !mask`) from an
/// adapter's IPv4 address and on-link prefix length (`1..=30`). Rejects
/// unspecified, loopback, link-local (`169.254.0.0/16`), multicast and
/// broadcast addresses.
pub fn ipv4_broadcast(ip: std::net::Ipv4Addr, prefix_len: u8) -> Option<std::net::Ipv4Addr> {
    if !(1..=30).contains(&prefix_len)
        || ip.is_unspecified()
        || ip.is_loopback()
        || ip.is_link_local()
        || ip.is_multicast()
        || ip.is_broadcast()
    {
        return None;
    }
    let mask = u32::MAX << (32 - u32::from(prefix_len));
    let bcast = std::net::Ipv4Addr::from(u32::from(ip) | !mask);
    (!bcast.is_unspecified() && !bcast.is_loopback() && !bcast.is_multicast()).then_some(bcast)
}

fn parse_wake_broadcast(s: &str) -> Option<std::net::Ipv4Addr> {
    let ip: std::net::Ipv4Addr = s.trim().parse().ok()?;
    if ip.is_unspecified() || ip.is_loopback() || ip.is_link_local() || ip.is_multicast() {
        return None;
    }
    Some(ip)
}

/// Body of `pc.wake_info` (`docs/protocol/actions.md` §2.3): the PC's
/// wake-capable adapter MAC addresses and directed subnet broadcast addresses.
#[derive(Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct PcWakeInfo {
    /// Hardware addresses (`"aa:bb:cc:dd:ee:ff"`), preferred adapter first.
    /// Empty when the user turned `pc_actions` off for this phone.
    #[serde(default)]
    pub macs: Vec<String>,
    /// Directed IPv4 subnet broadcast addresses (e.g. `"192.168.1.255"`).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub broadcasts: Vec<String>,
}

/// Never prints hardware or IP addresses in logs (protocol v0 §11).
impl std::fmt::Debug for PcWakeInfo {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PcWakeInfo")
            .field("macs", &self.macs.len())
            .field("broadcasts", &self.broadcasts.len())
            .finish()
    }
}

impl PcWakeInfo {
    pub fn is_valid(&self) -> bool {
        self.macs.len() <= wake::MAX_ADAPTERS
            && self.broadcasts.len() <= wake::MAX_BROADCASTS
            && self.macs.iter().all(|m| parse_mac(m).is_some())
            && self.broadcasts.iter().all(|b| parse_wake_broadcast(b).is_some())
    }

    /// Normalizes MAC addresses to lowercase `"aa:bb:cc:dd:ee:ff"`, filters out
    /// invalid entries, deduplicates preserving order, and enforces protocol
    /// bounds.
    pub fn sanitized(self) -> Self {
        let mut macs = Vec::new();
        for m in self.macs {
            if let Some(bytes) = parse_mac(&m) {
                let norm = format_mac(&bytes);
                if !macs.contains(&norm) {
                    macs.push(norm);
                    if macs.len() >= wake::MAX_ADAPTERS {
                        break;
                    }
                }
            }
        }
        if macs.is_empty() {
            return Self::default();
        }
        let mut broadcasts = Vec::new();
        for b in self.broadcasts {
            if let Some(ip) = parse_wake_broadcast(&b) {
                let norm = ip.to_string();
                if !broadcasts.contains(&norm) {
                    broadcasts.push(norm);
                    if broadcasts.len() >= wake::MAX_BROADCASTS {
                        break;
                    }
                }
            }
        }
        Self { macs, broadcasts }
    }

    /// Encodes as `"mac1,mac2|bcast1,bcast2"` for the `peers.wake_info` column.
    pub fn to_storage_string(&self) -> String {
        let clean = self.clone().sanitized();
        if clean.macs.is_empty() {
            String::new()
        } else {
            format!("{}|{}", clean.macs.join(","), clean.broadcasts.join(","))
        }
    }

    /// Decodes from the `peers.wake_info` column (`None` when empty or invalid).
    pub fn from_storage_str(s: &str) -> Option<Self> {
        let s = s.trim();
        if s.is_empty() {
            return None;
        }
        let (macs_part, bcasts_part) = s.split_once('|').unwrap_or((s, ""));
        let info = Self {
            macs: macs_part.split(',').filter(|p| !p.is_empty()).map(str::to_owned).collect(),
            broadcasts: bcasts_part.split(',').filter(|p| !p.is_empty()).map(str::to_owned).collect(),
        }
        .sanitized();
        (!info.macs.is_empty()).then_some(info)
    }
}

/// Relayed Wake-on-LAN request (`wake.relay`): sent to an online paired peer on
/// the target LAN asking it to broadcast a UDP magic packet for `mac`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct WakeRelay {
    pub mac: [u8; 6],
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub broadcast: Option<String>,
}

/// Low-latency PCM audio frame (`audio.pcm`) streamed from a PC to a phone.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AudioPcmFrame {
    pub sample_rate: u32,
    pub channels: u8,
    #[serde(with = "serde_bytes")]
    pub pcm: Vec<u8>,
}

// ---- Screen mirroring (docs/protocol/mirror.md) ----

pub mod mirror {
    /// Offered by phones that share their screen (with the user's consent).
    pub const CAPTURE: &str = "mirror.capture";
    /// Offered by PCs that show a phone's screen.
    pub const VIEW: &str = "mirror.view";
    pub const SERVICE: &str = "mirror";
    pub const OP_VIDEO: &str = "video";
    pub const VERSION: u32 = 1;
    /// Stream reset code: mirroring stopped.
    pub const STOPPED: u32 = 11;
    /// Offered by phones that take input from the PC while mirrored.
    pub const INPUT: &str = "mirror.input";
    /// Typed text in one message: at most this many bytes.
    pub const MAX_TEXT_BYTES: usize = 4096;
    pub const H264: &str = "h264";
    pub const H265: &str = "h265";
    pub const AV1: &str = "av1";
    /// Offered by a device that can decode HEVC video streams.
    pub const HEVC: &str = "mirror.decode.hevc";
    /// Offered by phones that stream all their sound while mirrored.
    pub const AUDIO: &str = "mirror.audio";
    /// Offered by phones that stream the sound of apps that allow it.
    pub const AUDIO_PLAYBACK: &str = "mirror.audio.playback";
    /// Offered by PCs that play a mirrored phone's sound.
    pub const LISTEN: &str = "mirror.listen";
    /// Offered by phones that share their sound on its own, without the
    /// screen (`MirrorStart::sound_only`).
    pub const SOUND: &str = "mirror.sound";
    pub const OP_AUDIO: &str = "audio";
    /// 16-bit little-endian PCM, channels interleaved.
    pub const PCM: &str = "pcm_s16le";
    /// Offered by phones that run an app on a display of its own, shown in
    /// a window of its own (Elevated).
    pub const VIRTUAL_DISPLAY: &str = "mirror.virtual_display";
    /// The session of the phone's own screen; app windows have others.
    pub const SCREEN: u32 = 0;
    /// Apps in a `mirror.apps` answer, at most.
    pub const MAX_APPS: usize = 500;
    /// An app's icon (PNG), at most.
    pub const MAX_ICON_BYTES: usize = 8 * 1024;
}

/// Whether `name` looks like an Android package name.
pub fn is_package_name(name: &str) -> bool {
    !name.is_empty()
        && name.len() <= 255
        && name.split('.').count() >= 2
        && name.split('.').all(|part| {
            part.chars().next().is_some_and(|c| c.is_ascii_alphabetic())
                && part.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
        })
}

/// Body of `mirror.start`: show me your screen.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MirrorStart {
    /// The longer side, in pixels, at most (the phone scales down).
    pub max_size: u32,
    /// Frames per second, at most.
    pub fps: u32,
    /// Bits per second to aim for.
    pub bitrate: u32,
    /// Also stream the phone's sound, when it can.
    #[serde(default)]
    pub audio: bool,
    /// The PC's number for this mirroring: [`mirror::SCREEN`] for the
    /// phone's screen, any other for an app window.
    #[serde(default)]
    pub session: u32,
    /// An app (package name) to run on a display of its own and show,
    /// instead of the phone's screen (with a session other than SCREEN).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub app: Option<String>,
    /// Keep the phone awake while mirroring its screen (`session == SCREEN`).
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub stay_awake: bool,
    /// Turn the phone's physical screen off while mirroring (`session == SCREEN`, Elevated).
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub screen_off: bool,
    /// Play on phone: show what this PC player (its ID, as in `media.state`)
    /// plays instead of the PC's screen (`session == SCREEN`, sent to a PC
    /// that offered it with `media.watch`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub watch: Option<String>,
    /// Only the phone's sound, no picture (`session == SCREEN`, sent to a
    /// phone that offers [`mirror::SOUND`]). The PC plays it without a window.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub sound_only: bool,
}

impl MirrorStart {
    /// The screen without an app, or an app with a session of its own.
    pub fn is_valid(&self) -> bool {
        if self.sound_only {
            // The phone's own sound: no app, no player, nothing about the screen.
            return self.session == mirror::SCREEN
                && self.audio
                && self.app.is_none()
                && self.watch.is_none()
                && !self.stay_awake
                && !self.screen_off;
        }
        let watch_ok = self
            .watch
            .as_ref()
            .is_none_or(|p| self.app.is_none() && (1..=media_limits::ID_BYTES).contains(&p.len()));
        watch_ok
            && match &self.app {
                None => self.session == mirror::SCREEN,
                Some(app) => {
                    self.session != mirror::SCREEN
                        && is_package_name(app)
                        && !self.stay_awake
                        && !self.screen_off
                }
            }
    }
}

/// Body of `mirror.power`: change `stay_awake` or `screen_off` while mirroring
/// the phone's screen (`session == SCREEN`).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct MirrorPower {
    #[serde(default)]
    pub stay_awake: bool,
    #[serde(default)]
    pub screen_off: bool,
}

/// Which mirroring a `mirror.stop`, `mirror.keyframe` or `mirror.input` is
/// about (its body, or part of it; missing means the screen).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct MirrorSession {
    #[serde(default)]
    pub session: u32,
}

/// Body of `mirror.resize`: resize an app window's display (`session != 0`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct MirrorResize {
    pub session: u32,
    pub width: u32,
    pub height: u32,
}

impl MirrorResize {
    pub fn is_valid(&self) -> bool {
        self.session != mirror::SCREEN
            && (64..=4096).contains(&self.width)
            && (64..=4096).contains(&self.height)
    }
}

/// An app a PC can open in a window (in a `mirror.apps` answer).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhoneApp {
    /// Package name.
    pub pkg: String,
    pub label: String,
    /// A small icon (PNG), at most [`mirror::MAX_ICON_BYTES`].
    #[serde(default, skip_serializing_if = "Option::is_none", with = "serde_bytes")]
    pub icon: Option<Vec<u8>>,
}

impl std::fmt::Debug for PhoneApp {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PhoneApp")
            .field("pkg", &self.pkg)
            .field("icon", &self.icon.as_ref().map(Vec::len))
            .finish_non_exhaustive()
    }
}

/// Body of a `mirror.apps` answer: the phone's apps, by name.
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
pub struct PhoneApps {
    pub apps: Vec<PhoneApp>,
}

/// Body of `mirror.input`: the PC's mouse, keyboard, and gamepad on the mirrored
/// screen. Positions are fractions of the screen (0 at the left or top, 1
/// at the right or bottom), so they hold at any size.
#[derive(Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "lowercase")]
pub enum MirrorInput {
    /// A finger: down, moved, up (the phone turns these into taps, long
    /// presses and swipes).
    Touch { action: TouchAction, x: f32, y: f32 },
    /// The mouse wheel at a point, in notches (positive: down / right).
    Scroll { x: f32, y: f32, dx: f32, dy: f32 },
    /// A key with no text: one of [`mirror_keys`].
    Key { key: String },
    /// Typed text, into what has the focus.
    Text { text: String },
    /// Gamepad controller state (XInput-style buttons bitmask, stick axes, and triggers).
    Gamepad { buttons: u16, lx: i16, ly: i16, rx: i16, ry: i16, lt: u8, rt: u8 },
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum TouchAction {
    Down,
    Move,
    Up,
}

/// Keys `mirror.input` can send.
pub mod mirror_keys {
    pub const BACK: &str = "back";
    pub const HOME: &str = "home";
    pub const RECENTS: &str = "recents";
    pub const ENTER: &str = "enter";
    pub const BACKSPACE: &str = "backspace";
    pub const DELETE: &str = "delete";
    pub const LEFT: &str = "left";
    pub const RIGHT: &str = "right";
    pub const UP: &str = "up";
    pub const DOWN: &str = "down";
    pub const TAB: &str = "tab";
    pub const NOTIFICATIONS: &str = "notifications";
    pub const KEYBOARD_ON: &str = "keyboard_on";
    pub const KEYBOARD_OFF: &str = "keyboard_off";
    /// Copy, cut and select all in the focused text field (the PC's Ctrl+C,
    /// Ctrl+X and Ctrl+A). Phones from before these drop them.
    pub const COPY: &str = "copy";
    pub const CUT: &str = "cut";
    pub const SELECT_ALL: &str = "select_all";
    pub const ALL: &[&str] = &[
        BACK,
        HOME,
        RECENTS,
        ENTER,
        BACKSPACE,
        DELETE,
        LEFT,
        RIGHT,
        UP,
        DOWN,
        TAB,
        NOTIFICATIONS,
        KEYBOARD_ON,
        KEYBOARD_OFF,
        COPY,
        CUT,
        SELECT_ALL,
    ];
}

/// `mirror.input`: the input's fields, and the session when it isn't the
/// screen (phones that predate sessions ignore it).
pub fn mirror_input_envelope(
    input: &MirrorInput,
    session: u32,
) -> Result<crate::Envelope, crate::ProtocolError> {
    let mut env = crate::Envelope::new(types::MIRROR_INPUT, input)?;
    if session != mirror::SCREEN
        && let Some(ciborium::Value::Map(fields)) = env.b.as_mut()
    {
        fields.push((ciborium::Value::Text("session".into()), ciborium::Value::Integer(session.into())));
    }
    Ok(env)
}

/// Never prints typed text (protocol v0 §11).
impl std::fmt::Debug for MirrorInput {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            MirrorInput::Touch { action, .. } => write!(f, "Touch({action:?})"),
            MirrorInput::Scroll { .. } => f.write_str("Scroll"),
            MirrorInput::Key { key } => write!(f, "Key({key})"),
            MirrorInput::Text { text } => write!(f, "Text({} bytes)", text.len()),
            MirrorInput::Gamepad { buttons, .. } => write!(f, "Gamepad({buttons:#06x})"),
        }
    }
}

impl MirrorInput {
    pub fn is_valid(&self) -> bool {
        let on_screen = |v: f32| v.is_finite() && (0.0..=1.0).contains(&v);
        match self {
            MirrorInput::Touch { x, y, .. } => on_screen(*x) && on_screen(*y),
            MirrorInput::Scroll { x, y, dx, dy } => {
                on_screen(*x)
                    && on_screen(*y)
                    && dx.is_finite()
                    && dy.is_finite()
                    && dx.abs() <= 100.0
                    && dy.abs() <= 100.0
            }
            MirrorInput::Key { key } => mirror_keys::ALL.contains(&key.as_str()),
            MirrorInput::Text { text } => !text.is_empty() && text.len() <= mirror::MAX_TEXT_BYTES,
            MirrorInput::Gamepad { .. } => true,
        }
    }
}

/// The format of a mirroring stream (a config packet's data, in CBOR).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MirrorConfig {
    /// `h264`, `h265`, or `av1`.
    pub codec: String,
    pub width: u32,
    pub height: u32,
    /// Which mirroring this stream is (see [`MirrorStart::session`]).
    #[serde(default)]
    pub session: u32,
}

impl MirrorConfig {
    pub fn to_cbor(&self) -> Vec<u8> {
        let mut out = Vec::new();
        let _ = ciborium::into_writer(self, &mut out);
        out
    }

    pub fn from_cbor(bytes: &[u8]) -> Result<MirrorConfig, crate::ProtocolError> {
        ciborium::from_reader(bytes).map_err(|e| crate::ProtocolError::BadMessage(e.to_string()))
    }

    /// A format this version can show: H.264, H.265, or AV1, 1-8192 pixels a side.
    pub fn is_valid(&self) -> bool {
        matches!(self.codec.as_str(), mirror::H264 | mirror::H265 | mirror::AV1)
            && (1..=8192).contains(&self.width)
            && (1..=8192).contains(&self.height)
    }
}

/// The format of a mirrored phone's sound (an audio stream's config
/// packet, in CBOR).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MirrorAudioConfig {
    /// `pcm_s16le`.
    pub codec: String,
    /// Samples per second.
    pub rate: u32,
    pub channels: u8,
}

impl MirrorAudioConfig {
    pub fn to_cbor(&self) -> Vec<u8> {
        let mut out = Vec::new();
        let _ = ciborium::into_writer(self, &mut out);
        out
    }

    pub fn from_cbor(bytes: &[u8]) -> Result<MirrorAudioConfig, crate::ProtocolError> {
        ciborium::from_reader(bytes).map_err(|e| crate::ProtocolError::BadMessage(e.to_string()))
    }

    /// A format this version can play: PCM, 8-96 kHz, mono or stereo.
    pub fn is_valid(&self) -> bool {
        self.codec == mirror::PCM && (8_000..=96_000).contains(&self.rate) && (1..=2).contains(&self.channels)
    }

    /// Bytes in one sample frame (a sample for each channel).
    pub fn frame_bytes(&self) -> usize {
        2 * usize::from(self.channels)
    }
}

// ---- Phone as webcam (docs/protocol/webcam.md) ----

/// Phone as microphone (`docs/protocol/mic.md`).
/// Elevated over USB (`docs/protocol/elevated-usb.md`): a phone without
/// wireless debugging asks the PC it's plugged into to start its Elevated
/// helper over USB debugging.
pub mod elevated {
    /// Offered by PCs that can start a USB-connected phone's helper.
    pub const USB: &str = "elevated.usb";
    /// The only package the PC runs anything for.
    pub const PACKAGE: &str = "app.nectarlink";
    /// The helper the PC starts, with `app_process`.
    pub const HELPER_CLASS: &str = "app.nectarlink.android.elevated.InputServer";
    /// Grants a request may carry, at most.
    pub const MAX_GRANTS: usize = 8;
}

/// Body of `elevated.usb.start`: start the helper from `apk` with `token`,
/// after running `grants` (each one of the phone's own, see [`is_valid_grant`]).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ElevatedUsbStart {
    pub apk: String,
    pub token: String,
    #[serde(default)]
    pub grants: Vec<String>,
}

impl ElevatedUsbStart {
    pub fn is_valid(&self) -> bool {
        is_valid_app_apk(&self.apk)
            && (32..=64).contains(&self.token.len())
            && self.token.bytes().all(|b| b.is_ascii_hexdigit())
            && self.grants.len() <= elevated::MAX_GRANTS
            && self.grants.iter().all(|g| is_valid_grant(g))
    }
}

/// Body of `elevated.usb.ready`: the helper listens on this loopback port.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct ElevatedUsbReady {
    pub port: u16,
}

/// Characters a path or command the PC passes to the phone's shell may use:
/// nothing the shell would read as more than a word.
fn is_shell_word(s: &str) -> bool {
    !s.is_empty() && s.bytes().all(|b| b.is_ascii_alphanumeric() || b"._/=~+-:".contains(&b))
}

/// The app's own installed APK (`pm path` gives `/data/app/<...>/base.apk`).
pub fn is_valid_app_apk(apk: &str) -> bool {
    apk.len() <= 512
        && apk.starts_with("/data/app/")
        && apk.ends_with("/base.apk")
        && !apk.contains("..")
        && apk.contains(elevated::PACKAGE)
        && is_shell_word(apk)
}

/// NectarLink's package. Debug builds of the PC app also accept its local
/// test build (`app.nectarlink.dev`, the `applicationIdSuffix` of a
/// side-by-side build); release builds accept no other package.
pub fn is_own_package(p: &str) -> bool {
    p == elevated::PACKAGE || (cfg!(debug_assertions) && p.strip_prefix(elevated::PACKAGE) == Some(".dev"))
}

/// A grant the phone may ask for itself, and nothing else: a permission or
/// app op for NectarLink's own package, or its own notification listener.
pub fn is_valid_grant(grant: &str) -> bool {
    let words: Vec<&str> = grant.split(' ').collect();
    if !words.iter().all(|w| is_shell_word(w)) {
        return false;
    }
    match words.as_slice() {
        ["pm", "grant", p, perm] => is_own_package(p) && perm.starts_with("android.permission."),
        ["appops", "set", p, op, "allow"] => {
            is_own_package(p) && op.bytes().all(|b| b.is_ascii_uppercase() || b == b'_')
        }
        ["cmd", "notification", "allow_dnd", p] => is_own_package(p),
        ["cmd", "notification", "allow_listener", component] => {
            component.split_once('/').is_some_and(|(p, rest)| is_own_package(p) && !rest.is_empty())
        }
        _ => false,
    }
}

pub mod mic {
    /// Offered by phones that stream their microphone.
    pub const STREAM: &str = "mic.stream";
    /// Offered by PCs that take a phone's microphone.
    pub const LISTEN: &str = "mic.listen";
    pub const SERVICE: &str = "mic";
    pub const OP_PCM: &str = "pcm";
    pub const VERSION: u32 = 1;
    /// Stream reset code: the microphone stopped.
    pub const STOPPED: u32 = 13;
}

pub mod webcam {
    /// Offered by phones that stream their camera as a webcam.
    pub const STREAM: &str = "camera.stream";
    /// Offered by PCs that receive and decode a phone's webcam stream.
    pub const VIRTUAL: &str = "camera.virtual";
    /// Receiver can decode HEVC webcam streams. Absence means H.264 only.
    pub const HEVC: &str = "camera.virtual.hevc";
    /// Offered by PCs where the Windows virtual camera COM add-on is registered.
    pub const ADDON_VCAM: &str = "addon.vcam";
    pub const SERVICE: &str = "webcam";
    pub const OP_VIDEO: &str = "video";
    pub const VERSION: u32 = 1;
    /// Stream reset code: webcam stopped.
    pub const STOPPED: u32 = 12;
    pub const H264: &str = "h264";
    pub const H265: &str = "h265";
    pub const CAMERA_BACK: &str = "back";
    pub const CAMERA_FRONT: &str = "front";
}

fn default_webcam_camera() -> String {
    webcam::CAMERA_BACK.to_owned()
}

fn default_webcam_fps() -> u32 {
    30
}

fn default_webcam_bitrate() -> u32 {
    6_000_000
}

/// Body of `webcam.start`: ask a paired phone to stream its camera (or update
/// camera/resolution while already streaming).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct WebcamStart {
    /// `"back"` or `"front"`.
    #[serde(default = "default_webcam_camera")]
    pub camera: String,
    /// Requested frame width in pixels (e.g. 1280, 1920, 3840).
    pub width: u32,
    /// Requested frame height in pixels (e.g. 720, 1080, 2160).
    pub height: u32,
    /// Target frames per second (`1..=60`).
    #[serde(default = "default_webcam_fps")]
    pub fps: u32,
    /// Target bitrate in bits per second (`100_000..=50_000_000`).
    #[serde(default = "default_webcam_bitrate")]
    pub bitrate: u32,
}

impl Default for WebcamStart {
    fn default() -> Self {
        Self {
            camera: default_webcam_camera(),
            width: 1280,
            height: 720,
            fps: default_webcam_fps(),
            bitrate: default_webcam_bitrate(),
        }
    }
}

impl WebcamStart {
    pub fn is_valid(&self) -> bool {
        (self.camera == webcam::CAMERA_BACK || self.camera == webcam::CAMERA_FRONT)
            && (320..=3840).contains(&self.width)
            && (240..=2160).contains(&self.height)
            && (1..=60).contains(&self.fps)
            && (100_000..=50_000_000).contains(&self.bitrate)
    }
}

/// The format of a webcam stream (a `PacketKind::Config` packet's payload, in CBOR).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct WebcamConfig {
    /// `"h264"` or `"h265"` (only when the receiver advertises webcam::HEVC).
    pub codec: String,
    pub width: u32,
    pub height: u32,
    /// `"back"` or `"front"`.
    #[serde(default = "default_webcam_camera")]
    pub camera: String,
    /// Frames per second.
    #[serde(default = "default_webcam_fps")]
    pub fps: u32,
    /// The highest resolution the camera in use can stream, by its short
    /// side: 2160 when it can do 4K, else 1080. Phones before 0.1.5 don't
    /// say, and fall back to 1080p themselves when asked for 4K it can't do.
    #[serde(default = "default_webcam_max_height")]
    pub max_height: u32,
}

fn default_webcam_max_height() -> u32 {
    2160
}

impl WebcamConfig {
    pub fn to_cbor(&self) -> Vec<u8> {
        let mut out = Vec::new();
        let _ = ciborium::into_writer(self, &mut out);
        out
    }

    pub fn from_cbor(bytes: &[u8]) -> Result<WebcamConfig, crate::ProtocolError> {
        ciborium::from_reader(bytes).map_err(|e| crate::ProtocolError::BadMessage(e.to_string()))
    }

    pub fn is_valid(&self) -> bool {
        matches!(self.codec.as_str(), webcam::H264 | webcam::H265)
            && (1..=8192).contains(&self.width)
            && (1..=8192).contains(&self.height)
            && (self.camera == webcam::CAMERA_BACK || self.camera == webcam::CAMERA_FRONT)
            && (1..=120).contains(&self.fps)
    }
}

// ---- Continuity Camera (docs/protocol/v0.md §Continuity Camera) ----

pub mod continuity_camera {
    /// Offered by phones that can capture a still photo or scan a document on request.
    pub const CAPTURE: &str = "camera.capture";
    /// Offered by PCs that can request and receive Continuity Camera captures.
    pub const RECEIVE: &str = "camera.continuity";

    /// The `stream` header's `svc` for a Continuity Camera result upload.
    pub const SERVICE: &str = "camera";
    /// The `stream` header's `op` for sending a captured photo or scanned document.
    pub const OP_RESULT: &str = "result";
    pub const VERSION: u32 = 1;

    /// Stream frame type sent before the raw image bytes on a `camera` / `result` stream.
    pub const RESULT_META: &str = "camera.capture.meta";

    /// Capture mode string values.
    pub const MODE_PHOTO: &str = "photo";
    pub const MODE_SCAN: &str = "scan";

    /// Maximum image payload size for a Continuity Camera capture (32 MiB).
    pub const MAX_IMAGE_BYTES: u64 = 32 * 1024 * 1024;
    /// Maximum length of a request ID in bytes.
    pub const MAX_ID_BYTES: usize = 64;
    /// Maximum length of a file name in bytes.
    pub const MAX_NAME_BYTES: usize = 255;
}

/// Mode requested for a Continuity Camera capture.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum CameraCaptureMode {
    /// Capture a single high-resolution photo.
    Photo,
    /// Capture and perspective-crop / contrast-enhance a document scan.
    Scan,
}

impl CameraCaptureMode {
    /// Wire/display string (`"photo"` or `"scan"`).
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Photo => continuity_camera::MODE_PHOTO,
            Self::Scan => continuity_camera::MODE_SCAN,
        }
    }

    /// Parses `"photo"` or `"scan"` (case-insensitive).
    #[must_use]
    pub fn parse(raw: &str) -> Option<Self> {
        match raw.trim().to_ascii_lowercase().as_str() {
            continuity_camera::MODE_PHOTO => Some(Self::Photo),
            continuity_camera::MODE_SCAN => Some(Self::Scan),
            _ => None,
        }
    }
}

/// `camera.capture.request`: PC asks a paired phone to open its camera UI and capture a photo or scan.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CameraCaptureRequest {
    pub request_id: String,
    pub mode: CameraCaptureMode,
}

/// `camera.capture.ok`: Phone acknowledges that the capture UI was launched.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CameraCaptureOk {
    pub request_id: String,
}

/// `camera.capture.cancel`: Either side cancels an in-flight capture request.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CameraCaptureCancel {
    pub request_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
}

/// `camera.capture.meta`: Header frame sent on a `camera` / `result` stream before the raw image bytes.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CameraCaptureResultMeta {
    pub request_id: String,
    pub mode: CameraCaptureMode,
    pub file_name: String,
    /// `"image/jpeg"` or `"image/png"`.
    pub mime: String,
    pub size: u64,
    #[serde(default)]
    pub width: u32,
    #[serde(default)]
    pub height: u32,
}

// ---- Messages (docs/protocol/sms.md) ----

pub mod sms {
    /// Offered by phones that share their text messages.
    pub const READ: &str = "sms.read";
    /// Offered by phones that send texts when a PC asks.
    pub const SEND: &str = "sms.send";
    /// Offered by PCs that show text messages.
    pub const SHOW: &str = "sms.show";
    /// Most conversations or messages in one answer.
    pub const MAX_PAGE: u32 = 100;
    /// A text sent from a PC: at most this many bytes.
    pub const MAX_SEND_BYTES: usize = 8 * 1024;
    /// At most this many recipients.
    pub const MAX_RECIPIENTS: usize = 20;
    /// A picture in a message, fetched with `sms.part`: at most this many bytes.
    pub const MAX_PART_BYTES: usize = 900 * 1024;
    /// Most image attachments in one `sms.send` message.
    pub const MAX_ATTACHMENTS: usize = 1;
    /// An image sent with `sms.send` (MMS): at most this many bytes.
    pub const MAX_ATTACHMENT_BYTES: usize = MAX_PART_BYTES;
    /// A contact's photo with a conversation: a JPEG of at most this many bytes.
    pub const MAX_PHOTO_BYTES: usize = 16 * 1024;
}

/// A conversation, as `sms.threads` lists it.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SmsThread {
    pub id: String,
    /// The other people's numbers (more than one: a group).
    pub addresses: Vec<String>,
    /// Their contact names, in the same order (empty when not a contact).
    #[serde(default)]
    pub names: Vec<String>,
    /// The latest message's text (or a description, like "Photo").
    #[serde(default)]
    pub snippet: String,
    /// The latest message, in Unix milliseconds.
    pub date: i64,
    /// Unread messages.
    #[serde(default)]
    pub unread: u32,
    /// The contact's photo (one-person conversations), a JPEG.
    #[serde(default, skip_serializing_if = "Option::is_none", with = "serde_bytes")]
    pub photo: Option<Vec<u8>>,
}

/// Never prints numbers, names or text (protocol v0 §11).
impl std::fmt::Debug for SmsThread {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SmsThread")
            .field("id", &self.id)
            .field("people", &self.addresses.len())
            .field("unread", &self.unread)
            .finish_non_exhaustive()
    }
}

/// A picture (or other attachment) in a message.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SmsPart {
    /// Fetched with `sms.part`.
    pub id: String,
    pub mime: String,
    #[serde(default)]
    pub size: u64,
}

/// A message in a conversation.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SmsMessage {
    pub id: String,
    pub thread: String,
    /// Who sent it (incoming), or the recipient (sent).
    #[serde(default)]
    pub address: String,
    #[serde(default)]
    pub body: String,
    /// Unix milliseconds.
    pub date: i64,
    /// Sent from this phone (false: received).
    #[serde(default)]
    pub outgoing: bool,
    /// For sent messages: `sent`, `pending` or `failed`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub status: Option<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub parts: Vec<SmsPart>,
}

/// Never prints numbers or text (protocol v0 §11).
impl std::fmt::Debug for SmsMessage {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SmsMessage")
            .field("id", &self.id)
            .field("thread", &self.thread)
            .field("outgoing", &self.outgoing)
            .field("parts", &self.parts.len())
            .finish_non_exhaustive()
    }
}

/// Body of `sms.threads`: the latest conversations, newest first.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SmsThreadsGet {
    pub limit: u32,
}

/// Answer to `sms.threads`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SmsThreads {
    pub threads: Vec<SmsThread>,
}

/// Body of `sms.messages`: a conversation's messages before `before`
/// (Unix milliseconds; the latest when missing), newest first.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SmsMessagesGet {
    pub thread: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub before: Option<i64>,
    pub limit: u32,
}

/// Answer to `sms.messages`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SmsMessages {
    pub messages: Vec<SmsMessage>,
}

/// An image attachment sent with `sms.send` (MMS).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SmsAttachment {
    /// `"image/jpeg"` or `"image/png"`.
    pub mime: String,
    #[serde(with = "serde_bytes")]
    pub data: Vec<u8>,
}

impl std::fmt::Debug for SmsAttachment {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SmsAttachment").field("mime", &self.mime).field("bytes", &self.data.len()).finish()
    }
}

impl SmsAttachment {
    pub fn is_valid(&self) -> bool {
        matches!(
            self.mime.as_str(),
            "image/jpeg"
                | "image/png"
                | "image/gif"
                | "image/webp"
                | "audio/mp4"
                | "audio/m4a"
                | "audio/aac"
                | "audio/mpeg"
                | "audio/ogg"
                | "audio/wav"
                | "audio/amr"
                | "audio/3gpp"
        ) && !self.data.is_empty()
            && self.data.len() <= sms::MAX_ATTACHMENT_BYTES
    }
}

/// Body of `sms.send`.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SmsSend {
    pub to: Vec<String>,
    #[serde(default)]
    pub body: String,
    /// Optional image attachment(s) to send as MMS.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub attachments: Vec<SmsAttachment>,
}

/// Never prints numbers or text (protocol v0 §11).
impl std::fmt::Debug for SmsSend {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SmsSend")
            .field("to", &self.to.len())
            .field("bytes", &self.body.len())
            .field("attachments", &self.attachments.len())
            .finish()
    }
}

impl SmsSend {
    pub fn is_valid(&self) -> bool {
        (1..=sms::MAX_RECIPIENTS).contains(&self.to.len())
            && self.to.iter().all(|a| (1..=64).contains(&a.trim().len()))
            && (!self.body.trim().is_empty() || !self.attachments.is_empty())
            && self.body.len() <= sms::MAX_SEND_BYTES
            && self.attachments.len() <= sms::MAX_ATTACHMENTS
            && self.attachments.iter().all(SmsAttachment::is_valid)
    }
}

/// Body of `sms.part`: send this attachment.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SmsPartGet {
    pub id: String,
}

/// Answer to `sms.part`.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SmsPartData {
    pub mime: String,
    #[serde(with = "serde_bytes")]
    pub data: Vec<u8>,
}

impl std::fmt::Debug for SmsPartData {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SmsPartData").field("mime", &self.mime).field("bytes", &self.data.len()).finish()
    }
}

/// Body of `sms.changed`: messages changed in this conversation (or in
/// any, when missing).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SmsChanged {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub thread: Option<String>,
}

// ---- Calls (docs/protocol/calls.md) ----

pub mod calls {
    /// Offered by phones that report their calls.
    pub const STATE: &str = "call.state";
    /// Offered by phones that answer and decline calls when a PC asks.
    pub const CONTROL: &str = "call.control";
    /// Offered by PCs that show calls.
    pub const SHOW: &str = "call.show";
    /// Offered by phones that control a call in progress (mute, speaker,
    /// hold, keypad) when a PC asks.
    pub const IN_CALL: &str = "call.incall";
    /// Offered by phones that list recent calls from the call log.
    pub const LOG: &str = "call.log";
    /// Offered by phones that place calls (or open the dialer) when a PC asks.
    pub const DIAL: &str = "call.dial";
    /// Offered by phones that list their SIMs (`call.sims`) and dial on the
    /// one a PC picks (`call.dial`'s `sim`).
    pub const SIMS: &str = "call.sims";
    /// Most SIMs (phone accounts that place calls) in one answer.
    pub const MAX_SIMS: usize = 8;
    /// A caller's photo: a JPEG of at most this many bytes.
    pub const MAX_PHOTO_BYTES: usize = 64 * 1024;
    /// A contact's photo on a call log entry: a JPEG of at most this many bytes.
    pub const MAX_LOG_PHOTO_BYTES: usize = 16 * 1024;
    /// Most call log entries in one answer.
    pub const MAX_LOG_PAGE: u32 = 100;
    pub const MAX_ID_BYTES: usize = 64;
    pub const MAX_TEXT_BYTES: usize = 256;

    pub const RINGING: &str = "ringing";
    pub const ACTIVE: &str = "active";
    pub const ENDED: &str = "ended";

    pub const DIR_INCOMING: &str = "incoming";
    pub const DIR_OUTGOING: &str = "outgoing";
    pub const DIR_MISSED: &str = "missed";
    pub const DIR_REJECTED: &str = "rejected";

    pub const ANSWER: &str = "answer";
    pub const DECLINE: &str = "decline";
    pub const SILENCE: &str = "silence";
    pub const MUTE: &str = "mute";
    pub const UNMUTE: &str = "unmute";
    pub const SPEAKER: &str = "speaker";
    pub const EARPIECE: &str = "earpiece";
    pub const HOLD: &str = "hold";
    pub const UNHOLD: &str = "unhold";
    /// A keypad tone: `digit` is one of `0`-`9`, `*`, `#`.
    pub const DTMF: &str = "dtmf";
    pub const VOLUME_UP: &str = "volume_up";
    pub const VOLUME_DOWN: &str = "volume_down";
}

/// A call in progress, as the phone controls it (with `call.incall`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub struct CallControls {
    #[serde(default)]
    pub muted: bool,
    #[serde(default)]
    pub speaker: bool,
    #[serde(default)]
    pub held: bool,
    /// The call can be put on hold.
    #[serde(default)]
    pub can_hold: bool,
}

/// Body of `call.state`: a call on the phone started ringing, was
/// answered, or ended.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CallState {
    /// The phone's ID for this call, the same in each of its messages.
    pub id: String,
    /// `ringing`, `active` or `ended`.
    pub state: String,
    /// Incoming (false: the phone's user made the call).
    #[serde(default = "yes")]
    pub incoming: bool,
    /// The caller's number, when the phone knows it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub number: Option<String>,
    /// The contact's name, when the number is a contact.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// The contact's photo (JPEG), with `ringing` only.
    #[serde(default, skip_serializing_if = "Option::is_none", with = "serde_bytes")]
    pub photo: Option<Vec<u8>>,
    /// With `ended`: it rang and nobody answered.
    #[serde(default)]
    pub missed: bool,
    /// With `active`: when it was answered, in Unix milliseconds.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub since: Option<i64>,
    /// With `active`, when the phone controls the call: its mute, speaker
    /// and hold.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub controls: Option<CallControls>,
}

fn yes() -> bool {
    true
}

/// Never prints the number, name or photo (protocol v0 §11).
impl std::fmt::Debug for CallState {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("CallState")
            .field("id", &self.id)
            .field("state", &self.state)
            .field("incoming", &self.incoming)
            .field("missed", &self.missed)
            .finish_non_exhaustive()
    }
}

impl CallState {
    pub fn is_valid(&self) -> bool {
        let text_ok = |t: &Option<String>| t.as_ref().is_none_or(|t| t.len() <= calls::MAX_TEXT_BYTES);
        (1..=calls::MAX_ID_BYTES).contains(&self.id.len())
            && [calls::RINGING, calls::ACTIVE, calls::ENDED].contains(&self.state.as_str())
            && text_ok(&self.number)
            && text_ok(&self.name)
            && self.photo.as_ref().is_none_or(|p| p.len() <= calls::MAX_PHOTO_BYTES)
    }
}

/// Body of `call.action`: answer, decline or silence a ringing call.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CallAction {
    pub id: String,
    pub action: String,
    /// With `dtmf`: the key.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub digit: Option<String>,
}

/// Whether `digit` is a keypad key (`0`-`9`, `*`, `#`).
pub fn is_dtmf_digit(digit: &str) -> bool {
    digit.len() == 1 && digit.chars().all(|c| c.is_ascii_digit() || c == '*' || c == '#')
}

/// One call in the phone's call history (`call.log`).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CallLogEntry {
    pub id: String,
    /// Who called, or who was called (empty when withheld).
    #[serde(default)]
    pub number: String,
    /// The contact's name, when the number is a contact.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// `incoming`, `outgoing`, `missed` or `rejected`.
    pub direction: String,
    /// When the call started, in Unix milliseconds.
    pub date: i64,
    /// Seconds on the call (`0` when missed or not answered).
    #[serde(default)]
    pub duration: u32,
    /// The contact's photo (JPEG, at most 16 KiB).
    #[serde(default, skip_serializing_if = "Option::is_none", with = "serde_bytes")]
    pub photo: Option<Vec<u8>>,
}

/// Never prints the number, name or photo (protocol v0 §11).
impl std::fmt::Debug for CallLogEntry {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("CallLogEntry")
            .field("id", &self.id)
            .field("direction", &self.direction)
            .field("duration", &self.duration)
            .finish_non_exhaustive()
    }
}

/// Body of `call.log`: recent calls before `before` (Unix milliseconds; the
/// latest when missing), newest first.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CallLogGet {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub before: Option<i64>,
    pub limit: u32,
}

/// Answer to `call.log`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CallLog {
    pub entries: Vec<CallLogEntry>,
}

/// Body of `call.log.changed`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct CallLogChanged {}

/// Body of `call.dial`: ask the phone to call `number`, on the SIM `sim`
/// (an `id` from `call.sims`) when given. Phones from before `sim` ignore it
/// and use their own default.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CallDial {
    pub number: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sim: Option<String>,
}

/// Never prints the number (protocol v0 §11).
impl std::fmt::Debug for CallDial {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("CallDial").field("bytes", &self.number.len()).field("sim", &self.sim).finish()
    }
}

impl CallDial {
    pub fn is_valid(&self) -> bool {
        !self.number.trim().is_empty()
            && self.number.len() <= calls::MAX_TEXT_BYTES
            && !self.number.chars().any(char::is_control)
            && self.sim.as_deref().is_none_or(is_valid_sim_id)
    }
}

fn is_valid_sim_id(id: &str) -> bool {
    !id.is_empty() && id.len() <= calls::MAX_ID_BYTES && !id.chars().any(char::is_control)
}

/// One way the phone places calls (`call.sims`): a SIM, or a calling app
/// such as a SIP account. `label` is what Android shows ("SIM 1 · Airtel").
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CallSim {
    pub id: String,
    pub label: String,
}

/// Answer to `call.sims` (an empty body asks): the phone's SIMs, and the
/// one it uses without asking, if it has one.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct CallSims {
    pub sims: Vec<CallSim>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub default: Option<String>,
}

impl CallSims {
    pub fn is_valid(&self) -> bool {
        self.sims.len() <= calls::MAX_SIMS
            && self.sims.iter().all(|s| {
                is_valid_sim_id(&s.id)
                    && s.label.len() <= calls::MAX_TEXT_BYTES
                    && !s.label.chars().any(char::is_control)
            })
            && self.default.as_deref().is_none_or(|d| self.sims.iter().any(|s| s.id == d))
    }
}

// ---- Contacts (docs/protocol/contacts.md) ----

pub mod contacts {
    /// Offered by phones that share their contacts.
    pub const READ: &str = "contacts.read";
    /// Offered by PCs that show contacts.
    pub const SHOW: &str = "contacts.show";
    /// Most contacts in one answer.
    pub const MAX_PAGE: u32 = 200;
    /// A search query: at most this many bytes.
    pub const MAX_QUERY_BYTES: usize = 256;
    /// Most phone numbers on one contact.
    pub const MAX_NUMBERS: usize = 16;
    /// A contact's photo: a JPEG of at most this many bytes.
    pub const MAX_PHOTO_BYTES: usize = 16 * 1024;
}

/// One phone number on a contact.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ContactNumber {
    pub number: String,
    /// Optional type/label, e.g. `"mobile"`, `"home"`, `"work"`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub label: Option<String>,
}

/// Never prints the number or label (protocol v0 §11).
impl std::fmt::Debug for ContactNumber {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ContactNumber").finish_non_exhaustive()
    }
}

/// A contact on the phone (`contacts.list`).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Contact {
    pub id: String,
    pub name: String,
    pub numbers: Vec<ContactNumber>,
    /// Favorite / starred on the phone.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub starred: bool,
    /// Small JPEG thumbnail (at most 16 KiB).
    #[serde(default, skip_serializing_if = "Option::is_none", with = "serde_bytes")]
    pub photo: Option<Vec<u8>>,
}

/// Never prints the name, numbers or photo (protocol v0 §11).
impl std::fmt::Debug for Contact {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Contact")
            .field("id", &self.id)
            .field("numbers", &self.numbers.len())
            .field("starred", &self.starred)
            .finish_non_exhaustive()
    }
}

/// Body of `contacts.list` request.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ContactsListGet {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub query: Option<String>,
    #[serde(default, skip_serializing_if = "is_zero")]
    pub offset: u32,
    pub limit: u32,
}

fn is_zero(n: &u32) -> bool {
    *n == 0
}

/// Never prints the search query (protocol v0 §11).
impl std::fmt::Debug for ContactsListGet {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ContactsListGet")
            .field("has_query", &self.query.is_some())
            .field("offset", &self.offset)
            .field("limit", &self.limit)
            .finish()
    }
}

/// Answer to `contacts.list`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ContactsList {
    pub contacts: Vec<Contact>,
}

/// Body of `contacts.changed`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ContactsChanged {}

// ---- Photos (docs/protocol/photos.md) ----

pub mod photos {
    /// Offered by phones that announce new photos (and can read them).
    pub const READ: &str = "photos.read";
    /// Offered by PCs that show announced photos and the phone's gallery.
    pub const SHOW: &str = "photos.show";
    /// A photo's ID: at most this many bytes.
    pub const MAX_ID_BYTES: usize = 64;
    /// A preview or thumbnail: a JPEG of at most this many bytes.
    pub const MAX_THUMB_BYTES: usize = 96 * 1024;
    /// Most items in one `photos.list` answer.
    pub const MAX_PAGE: u32 = 200;
    /// Most thumbnails requested in one `photos.thumbs` batch.
    pub const MAX_THUMB_BATCH: usize = 24;
    /// Most full items requested in one `photos.get` transfer.
    pub const MAX_GET_ITEMS: usize = 200;
}

/// Body of `photos.new`: a photo or screenshot just appeared on the phone.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhotoNew {
    /// The phone's ID for it; asks for the photo with `photos.get`.
    pub id: String,
    pub name: String,
    pub size: u64,
    /// When it was taken, in Unix seconds.
    pub taken: i64,
    /// A screenshot rather than a photo.
    #[serde(default)]
    pub screenshot: bool,
    /// A small JPEG preview.
    #[serde(with = "serde_bytes")]
    pub thumb: Vec<u8>,
}

/// Never prints the name or picture (protocol v0 §11).
impl std::fmt::Debug for PhotoNew {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PhotoNew")
            .field("id", &self.id)
            .field("size", &self.size)
            .field("screenshot", &self.screenshot)
            .field("thumb", &self.thumb.len())
            .finish_non_exhaustive()
    }
}

impl PhotoNew {
    pub fn is_valid(&self) -> bool {
        is_valid_photo_id(&self.id)
            && is_valid_file_name(&self.name)
            && self.thumb.len() <= photos::MAX_THUMB_BYTES
    }
}

/// Whether a photo ID is 1-64 printable ASCII characters.
pub fn is_valid_photo_id(id: &str) -> bool {
    (1..=photos::MAX_ID_BYTES).contains(&id.len()) && id.bytes().all(|b| b.is_ascii_graphic())
}

/// One album on the phone (`photos.albums.list`).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhotoAlbum {
    /// Album bucket identifier on the phone.
    pub id: String,
    /// Display name, e.g. `"Camera"`, `"Screenshots"`.
    pub name: String,
    /// Number of photos and videos in the album.
    pub count: u32,
    /// Newest item's ID, for its cover thumbnail.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cover: Option<String>,
}

/// Never prints the album's name (protocol v0 §11).
impl std::fmt::Debug for PhotoAlbum {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PhotoAlbum").field("id", &self.id).field("count", &self.count).finish_non_exhaustive()
    }
}

/// Body of `photos.albums` request.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhotoAlbumsGet {}

/// Answer to `photos.albums` (`photos.albums.list`).
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhotoAlbumsList {
    #[serde(default)]
    pub albums: Vec<PhotoAlbum>,
}

/// Body of `photos.list`: photos and videos on the phone (or in `album`),
/// newest first, after the item at (`before`, `before_id`) when given (the
/// last item of the previous page), else from the latest.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhotoListGet {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub album: Option<String>,
    /// The previous page's last `date` (Unix milliseconds).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub before: Option<i64>,
    /// The previous page's last `id`, so items sharing its date aren't
    /// skipped or repeated.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub before_id: Option<String>,
    pub limit: u32,
}

impl std::fmt::Debug for PhotoListGet {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PhotoListGet")
            .field("has_album", &self.album.is_some())
            .field("before", &self.before)
            .field("before_id", &self.before_id)
            .field("limit", &self.limit)
            .finish()
    }
}

/// One photo or video in `photos.items`.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhotoItem {
    pub id: String,
    pub name: String,
    /// When it was taken (Unix milliseconds), or else when it was saved.
    pub date: i64,
    pub size: u64,
    #[serde(default)]
    pub width: u32,
    #[serde(default)]
    pub height: u32,
    /// Video duration in milliseconds (`None` for photos).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub duration: Option<u32>,
    /// Album bucket identifier.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub album: Option<String>,
}

/// Never prints the file name (protocol v0 §11).
impl std::fmt::Debug for PhotoItem {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PhotoItem")
            .field("id", &self.id)
            .field("date", &self.date)
            .field("size", &self.size)
            .field("video", &self.duration.is_some())
            .finish_non_exhaustive()
    }
}

/// Answer to `photos.list` (`photos.items`).
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhotoItems {
    #[serde(default)]
    pub items: Vec<PhotoItem>,
}

/// Body of `photos.thumbs`: ask for small JPEG thumbnails for these IDs.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhotoThumbsGet {
    pub ids: Vec<String>,
}

/// One thumbnail in `photos.thumbs.list`.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhotoThumb {
    pub id: String,
    #[serde(with = "serde_bytes")]
    pub data: Vec<u8>,
}

/// Never prints thumbnail bytes (protocol v0 §11).
impl std::fmt::Debug for PhotoThumb {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PhotoThumb").field("id", &self.id).field("bytes", &self.data.len()).finish()
    }
}

/// Answer to `photos.thumbs` (`photos.thumbs.list`).
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhotoThumbsList {
    #[serde(default)]
    pub thumbs: Vec<PhotoThumb>,
}

/// Body of `photos.get`: send one (`id`) or several (`ids`) photos or videos.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhotoGet {
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub id: String,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub ids: Vec<String>,
}

impl PhotoGet {
    /// Requested item IDs in order: `id` (when set), then `ids`, each once.
    pub fn requested_ids(&self) -> Vec<String> {
        let mut out: Vec<String> = Vec::with_capacity(self.ids.len() + 1);
        for id in std::iter::once(&self.id).chain(&self.ids) {
            if !id.is_empty() && !out.contains(id) {
                out.push(id.clone());
            }
        }
        out
    }
}

/// Body of `photos.sending`, the answer to `photos.get`: the files
/// transfer that brings it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhotoSending {
    pub transfer: String,
}

/// Body of `photos.changed`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhotosChanged {}

/// Body of `link.open`.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LinkOpen {
    pub url: String,
    /// Optional human-readable title (e.g. the active video's title from the sender's media player).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
}

/// Never prints the link or title (protocol v0 §11).
impl std::fmt::Debug for LinkOpen {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("LinkOpen")
            .field("bytes", &self.url.len())
            .field("has_title", &self.title.is_some())
            .finish()
    }
}

/// Limits for `task.notify` (`docs/protocol/actions.md`).
pub mod task_notify {
    /// Maximum UTF-8 bytes in a task identifier.
    pub const MAX_ID_BYTES: usize = 64;
    /// Maximum Unicode scalar values in a task title.
    pub const MAX_TITLE_CHARS: usize = 120;
    /// Maximum concurrent active tasks tracked per Node.
    pub const MAX_ACTIVE: usize = 32;
}

/// Body of `task.notify`: live or completed PC task status sent to the phone.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TaskNotify {
    /// Stable identifier for this watched task on the sender.
    pub id: String,
    /// Human-readable task name (e.g. `"cargo build --release"`).
    pub title: String,
    /// `true` while the task is running; `false` when it has finished or been dismissed.
    pub active: bool,
    /// Elapsed wall-clock time in milliseconds since the task started.
    #[serde(default)]
    pub elapsed_ms: u64,
    /// Process exit code when the task has finished (`active == false`).
    /// When `active == false` and `exit_code == None`, the ongoing notification is dismissed silently.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub exit_code: Option<i32>,
}

/// Never prints the task title in logs (protocol v0 §11).
impl std::fmt::Debug for TaskNotify {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("TaskNotify")
            .field("id", &self.id)
            .field("active", &self.active)
            .field("elapsed_ms", &self.elapsed_ms)
            .field("exit_code", &self.exit_code)
            .finish_non_exhaustive()
    }
}

impl TaskNotify {
    /// Whether `id` and `title` satisfy protocol bounds.
    pub fn is_valid(&self) -> bool {
        let id_ok = (1..=task_notify::MAX_ID_BYTES).contains(&self.id.len())
            && self.id.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'_' | b'-' | b'.' | b':'));
        let title_trimmed = self.title.trim();
        let title_ok = !title_trimmed.is_empty()
            && self.title.chars().count() <= task_notify::MAX_TITLE_CHARS
            && !self.title.chars().any(char::is_control);
        id_ok && title_ok && (!self.active || self.exit_code.is_none())
    }

    /// Clamps and sanitizes a [`TaskNotify`] within protocol bounds, or returns `None` if invalid.
    pub fn sanitized(mut self) -> Option<Self> {
        let id: String = self
            .id
            .bytes()
            .filter(|b| b.is_ascii_alphanumeric() || matches!(b, b'_' | b'-' | b'.' | b':'))
            .take(task_notify::MAX_ID_BYTES)
            .map(char::from)
            .collect();
        if id.is_empty() {
            return None;
        }
        let filtered_title: String = self.title.chars().filter(|c| !c.is_control()).collect();
        let mut title = filtered_title.trim().to_owned();
        truncate_chars(&mut title, task_notify::MAX_TITLE_CHARS);
        if title.is_empty() {
            return None;
        }
        self.id = id;
        self.title = title;
        if self.active {
            self.exit_code = None;
        }
        Some(self)
    }

    /// Formats `elapsed_ms` as `"Took 38s"`, `"Took 4m 12s"`, or `"Took 1h 04m"`.
    pub fn format_took(elapsed_ms: u64) -> String {
        let total_secs = elapsed_ms / 1000;
        let hours = total_secs / 3600;
        let mins = (total_secs % 3600) / 60;
        let secs = total_secs % 60;
        if hours > 0 {
            format!("Took {hours}h {mins:02}m")
        } else if mins > 0 {
            format!("Took {mins}m {secs:02}s")
        } else {
            format!("Took {secs}s")
        }
    }
}

// ---- Files (docs/protocol/files.md) ----

/// The files service and its one operation, for stream headers.
pub mod files {
    pub const SERVICE: &str = "files";
    pub const OP_SEND: &str = "send";
    pub const VERSION: u32 = 1;
    pub const OFFER: &str = "files.offer";
    pub const ACCEPT: &str = "files.accept";
    pub const DONE: &str = "files.done";
    pub const RESUME: &str = "files.resume";
    pub const CANCEL: &str = "files.cancel";
    /// Stream reset code for a cancelled transfer.
    pub const CANCELLED: u32 = 10;
    /// Stream reset code for a manually paused transfer (receiver keeps `.part` files).
    pub const PAUSED: u32 = 11;
    pub const MAX_FILES: usize = 5000;
    pub const MAX_NAME_BYTES: usize = 255;
    /// A file's folder: at most this many bytes and this many levels.
    pub const MAX_FOLDER_BYTES: usize = 1024;
    pub const MAX_FOLDER_DEPTH: usize = 32;
    /// Offered by PCs that save and convert voice recordings (`docs/protocol/recorder.md`).
    pub const RECORDER: &str = "recorder";
    /// Most markers on one voice recording.
    pub const MAX_MARKERS: usize = 256;
    /// Most UTF-8 bytes in a marker's label.
    pub const MAX_MARKER_LABEL_BYTES: usize = 256;
}

/// A timestamped marker placed during a voice recording (`docs/protocol/recorder.md`).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RecordingMarker {
    /// Elapsed milliseconds from the start of the recording (excluding pauses).
    pub at_ms: u64,
    /// Optional user label for the marker.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub label: Option<String>,
}

/// Never prints the marker's label (protocol v0 §11).
impl std::fmt::Debug for RecordingMarker {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("RecordingMarker")
            .field("at_ms", &self.at_ms)
            .field("has_label", &self.label.is_some())
            .finish()
    }
}

impl RecordingMarker {
    pub fn is_valid(&self) -> bool {
        self.label.as_ref().is_none_or(|l| {
            !l.trim().is_empty()
                && l.len() <= files::MAX_MARKER_LABEL_BYTES
                && !l.chars().any(char::is_control)
        })
    }
}

/// One file of an offer.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FileEntry {
    pub name: String,
    pub size: u64,
    /// The folder the file is in when a folder is sent: `/`-separated
    /// names, starting with the sent folder's own (`Trip/Day 1`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub folder: Option<String>,
    /// Optional lowercase 64-character hex BLAKE3 digest of the file's full bytes.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub blake3: Option<String>,
}

/// Never prints the name (protocol v0 §11).
impl std::fmt::Debug for FileEntry {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("FileEntry").field("size", &self.size).finish_non_exhaustive()
    }
}

impl FileEntry {
    pub fn is_valid(&self) -> bool {
        is_valid_file_name(&self.name)
            && self.folder.as_deref().is_none_or(is_valid_folder)
            && self.blake3.as_deref().is_none_or(is_valid_blake3_hex)
    }
}

/// Body of `files.offer`.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FilesOffer {
    pub id: String,
    pub files: Vec<FileEntry>,
    /// True when this transfer is a voice recording (`docs/protocol/recorder.md`).
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub recording: bool,
    /// Timestamped markers placed during the recording.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub markers: Vec<RecordingMarker>,
    /// True when the sender asked the receiver to open this single safe document
    /// with the OS default application once it finishes arriving (Rich Handoff).
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub open_on_arrival: bool,
}

/// Never prints file names (protocol v0 §11).
impl std::fmt::Debug for FilesOffer {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("FilesOffer")
            .field("id", &self.id)
            .field("files", &self.files.len())
            .field("recording", &self.recording)
            .field("markers", &self.markers.len())
            .field("open_on_arrival", &self.open_on_arrival)
            .finish()
    }
}

/// Body of `files.accept`: bytes already received, per file.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FilesAccept {
    pub have: Vec<u64>,
}

/// Body of `files.resume` and `files.cancel` control messages.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FilesControl {
    pub id: String,
}

impl FilesControl {
    pub fn is_valid(&self) -> bool {
        is_valid_transfer_id(&self.id)
    }
}

/// Whether a name is a plain file name the spec allows (no path, no
/// control characters, not `.` or `..`).
pub fn is_valid_file_name(name: &str) -> bool {
    !name.is_empty()
        && name.len() <= files::MAX_NAME_BYTES
        && name != "."
        && name != ".."
        && !name.chars().any(|c| c == '/' || c == '\\' || c.is_control())
}

/// Whether a folder is 1-32 valid names joined by `/`, in at most
/// [`files::MAX_FOLDER_BYTES`].
pub fn is_valid_folder(folder: &str) -> bool {
    folder.len() <= files::MAX_FOLDER_BYTES
        && folder.split('/').count() <= files::MAX_FOLDER_DEPTH
        && folder.split('/').all(is_valid_file_name)
}

/// Whether a string is a 64-character ASCII hexadecimal BLAKE3 digest.
pub fn is_valid_blake3_hex(hex: &str) -> bool {
    hex.len() == 64 && hex.bytes().all(|b| b.is_ascii_hexdigit())
}

/// Whether a transfer ID is 16-64 of `[A-Za-z0-9_-]`.
pub fn is_valid_transfer_id(id: &str) -> bool {
    (16..=64).contains(&id.len()) && id.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-')
}

impl FilesOffer {
    pub fn is_valid(&self) -> bool {
        let files_ok = if self.recording {
            self.files.len() == 1
                && self.files[0].folder.is_none()
                && self.markers.len() <= files::MAX_MARKERS
                && self.markers.iter().all(RecordingMarker::is_valid)
        } else {
            (1..=files::MAX_FILES).contains(&self.files.len()) && self.markers.is_empty()
        };
        is_valid_transfer_id(&self.id) && files_ok && self.files.iter().all(FileEntry::is_valid)
    }

    pub fn total_size(&self) -> u64 {
        self.files.iter().map(|f| f.size).fold(0, u64::saturating_add)
    }
}

// ---- Clipboard (docs/protocol/clipboard.md) ----

/// Largest clipboard text sent or accepted, in UTF-8 bytes.
pub const CLIP_MAX_BYTES: usize = 512 * 1024;

/// Body of `clip.set`.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ClipSet {
    pub text: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub html: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rtf: Option<String>,
}

impl ClipSet {
    /// Whether the text and optional rich-text fields are within the spec's limits.
    pub fn is_valid(&self) -> bool {
        if self.text.is_empty() {
            return false;
        }
        let html_len = self.html.as_ref().map_or(0, String::len);
        let rtf_len = self.rtf.as_ref().map_or(0, String::len);
        self.text.len().saturating_add(html_len).saturating_add(rtf_len) <= CLIP_MAX_BYTES
    }
}

/// Never prints content (protocol v0 §11).
impl std::fmt::Debug for ClipSet {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ClipSet")
            .field("bytes", &self.text.len())
            .field("has_html", &self.html.is_some())
            .field("has_rtf", &self.rtf.is_some())
            .finish()
    }
}

/// Clipboard images, which travel on their own stream.
pub mod clip {
    pub const SERVICE: &str = "clip";
    pub const OP_IMAGE: &str = "image";
    pub const VERSION: u32 = 1;
    pub const IMAGE: &str = "clip.image";
    /// The largest image sent or accepted.
    pub const MAX_IMAGE_BYTES: u64 = 32 * 1024 * 1024;
    /// Image types a receiver accepts.
    pub const IMAGE_TYPES: &[&str] = &["image/png", "image/jpeg"];
}

/// Body of `clip.image`: what follows on the stream.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ClipImage {
    /// `image/png` or `image/jpeg`.
    pub mime: String,
    pub size: u64,
}

impl ClipImage {
    /// Whether the type and size are within the spec's limits.
    pub fn is_valid(&self) -> bool {
        clip::IMAGE_TYPES.contains(&self.mime.as_str()) && (1..=clip::MAX_IMAGE_BYTES).contains(&self.size)
    }
}

/// A paired device identity as stored in trust stores and exchanged in tests.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PeerIdentity {
    pub id: DeviceId,
    pub device: DeviceInfo,
}

/// Limits and wire constants for `remote.*` (`docs/protocol/remote.md`).
pub mod remote {
    /// One-byte QUIC datagram channel tag (`docs/protocol/v0.md` §4).
    pub const DATAGRAM_TAG: u8 = 0x01;
    /// Largest datagram body accepted after [`DATAGRAM_TAG`].
    pub const MAX_DATAGRAM_BYTES: usize = 256;
    /// Largest relative pointer step (`dx` or `dy`), in logical pixels.
    pub const MAX_MOVE_DELTA: f32 = 4000.0;
    /// Largest scroll step (`dx` or `dy`), in wheel notches.
    pub const MAX_SCROLL_DELTA: f32 = 200.0;
    /// Most UTF-8 bytes in one `Text` event.
    pub const MAX_TEXT_BYTES: usize = 256;
    /// Most modifiers on a key press.
    pub const MAX_MODS: usize = 4;
    /// Stream service and operation when falling back from datagrams.
    pub const SERVICE: &str = "remote";
    pub const OP_MOTION: &str = "motion";
    pub const VERSION: u32 = 1;
}

/// A mouse button on the PC (`docs/protocol/remote.md` §3).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum MouseButton {
    Left,
    Right,
    Middle,
}

/// What to do with a [`MouseButton`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ButtonAction {
    Down,
    Up,
    Click,
}

/// A modifier held during a [`RemoteInput::Key`] press.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum KeyMod {
    Ctrl,
    Alt,
    Shift,
    Win,
}

/// A presentation remote action (`docs/protocol/remote.md` §3).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SlideAction {
    Next,
    Previous,
    Start,
    Stop,
    Black,
}

/// Keys and shortcuts accepted by [`RemoteInput::Key`].
pub mod remote_keys {
    use super::KeyMod;

    pub const ENTER: &str = "enter";
    pub const BACKSPACE: &str = "backspace";
    pub const TAB: &str = "tab";
    pub const ESCAPE: &str = "escape";
    pub const SPACE: &str = "space";
    pub const LEFT: &str = "left";
    pub const RIGHT: &str = "right";
    pub const UP: &str = "up";
    pub const DOWN: &str = "down";
    pub const HOME: &str = "home";
    pub const END: &str = "end";
    pub const PAGE_UP: &str = "page_up";
    pub const PAGE_DOWN: &str = "page_down";
    pub const DELETE: &str = "delete";
    pub const F1: &str = "f1";
    pub const F2: &str = "f2";
    pub const F3: &str = "f3";
    pub const F4: &str = "f4";
    pub const F5: &str = "f5";
    pub const F6: &str = "f6";
    pub const F7: &str = "f7";
    pub const F8: &str = "f8";
    pub const F9: &str = "f9";
    pub const F10: &str = "f10";
    pub const F11: &str = "f11";
    pub const F12: &str = "f12";
    pub const WIN: &str = "win";

    pub const NAMED: &[&str] = &[
        ENTER, BACKSPACE, TAB, ESCAPE, SPACE, LEFT, RIGHT, UP, DOWN, HOME, END, PAGE_UP, PAGE_DOWN, DELETE,
        F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, WIN,
    ];

    /// Common shortcut aliases (`mods` must be empty when using an alias).
    pub const COPY: &str = "copy";
    pub const PASTE: &str = "paste";
    pub const CUT: &str = "cut";
    pub const UNDO: &str = "undo";
    pub const SELECT_ALL: &str = "select_all";
    pub const TASK_VIEW: &str = "task_view";
    pub const LOCK: &str = "lock";

    pub const SHORTCUTS: &[&str] = &[COPY, PASTE, CUT, UNDO, SELECT_ALL, TASK_VIEW, LOCK];

    /// Whether `key` and `mods` form a valid [`super::RemoteInput::Key`].
    pub fn is_valid(key: &str, mods: &[KeyMod]) -> bool {
        if mods.len() > super::remote::MAX_MODS {
            return false;
        }
        // Reject duplicate modifiers.
        for (i, m) in mods.iter().enumerate() {
            if mods[i + 1..].contains(m) {
                return false;
            }
        }
        if NAMED.contains(&key) {
            return true;
        }
        if SHORTCUTS.contains(&key) {
            return mods.is_empty();
        }
        // Single ASCII lowercase letter or digit is valid when combined with at
        // least one modifier (e.g. Ctrl+C, Win+L, Alt+1).
        if let [b] = key.as_bytes() {
            return !mods.is_empty() && (b.is_ascii_lowercase() || b.is_ascii_digit());
        }
        false
    }
}

/// An input event sent from a phone to a PC (`docs/protocol/remote.md`).
#[derive(Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "lowercase")]
pub enum RemoteInput {
    /// Relative pointer motion in logical pixels (`dx` right, `dy` down).
    /// Travels in QUIC datagrams (or the `remote/motion` stream), never on the
    /// control stream.
    Move { dx: f32, dy: f32 },
    /// Mouse button press, release or click.
    Button { button: MouseButton, action: ButtonAction },
    /// Smooth or stepped scroll in wheel notches (`dx` right, `dy` vertical).
    Scroll { dx: f32, dy: f32 },
    /// Typed Unicode text.
    Text { text: String },
    /// A named key, modified key, or shortcut.
    Key {
        key: String,
        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        mods: Vec<KeyMod>,
    },
    /// A presentation remote action.
    Slide { action: SlideAction },
    /// Laser pointer position on the PC's primary screen (`0.0..=1.0`).
    Laser {
        on: bool,
        #[serde(default)]
        x: f32,
        #[serde(default)]
        y: f32,
    },
}

/// Never prints typed text (protocol v0 §11).
impl std::fmt::Debug for RemoteInput {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            RemoteInput::Move { dx, dy } => write!(f, "Move({dx}, {dy})"),
            RemoteInput::Button { button, action } => write!(f, "Button({button:?}, {action:?})"),
            RemoteInput::Scroll { dx, dy } => write!(f, "Scroll({dx}, {dy})"),
            RemoteInput::Text { text } => write!(f, "Text({} bytes)", text.len()),
            RemoteInput::Key { key, mods } if mods.is_empty() => write!(f, "Key({key})"),
            RemoteInput::Key { key, mods } => write!(f, "Key({mods:?}+{key})"),
            RemoteInput::Slide { action } => write!(f, "Slide({action:?})"),
            RemoteInput::Laser { on: false, .. } => f.write_str("Laser(off)"),
            RemoteInput::Laser { on: true, x, y } => write!(f, "Laser({x}, {y})"),
        }
    }
}

impl RemoteInput {
    pub fn is_valid(&self) -> bool {
        match self {
            RemoteInput::Move { dx, dy } => {
                dx.is_finite()
                    && dy.is_finite()
                    && dx.abs() <= remote::MAX_MOVE_DELTA
                    && dy.abs() <= remote::MAX_MOVE_DELTA
            }
            RemoteInput::Button { .. } => true,
            RemoteInput::Scroll { dx, dy } => {
                dx.is_finite()
                    && dy.is_finite()
                    && dx.abs() <= remote::MAX_SCROLL_DELTA
                    && dy.abs() <= remote::MAX_SCROLL_DELTA
            }
            RemoteInput::Text { text } => {
                !text.is_empty()
                    && text.len() <= remote::MAX_TEXT_BYTES
                    && !text.chars().any(char::is_control)
            }
            RemoteInput::Key { key, mods } => remote_keys::is_valid(key, mods),
            RemoteInput::Slide { .. } => true,
            RemoteInput::Laser { on, x, y } => {
                x.is_finite()
                    && y.is_finite()
                    && (!*on || ((0.0..=1.0).contains(x) && (0.0..=1.0).contains(y)))
            }
        }
    }

    /// Whether this event may travel in a lossy QUIC datagram.
    pub fn is_datagram_allowed(&self) -> bool {
        matches!(self, RemoteInput::Move { .. } | RemoteInput::Scroll { .. } | RemoteInput::Laser { .. })
    }

    /// Whether this event may travel in a `remote.input` control request.
    /// Pointer motion (`Move`) never uses the control stream.
    pub fn is_control_allowed(&self) -> bool {
        !matches!(self, RemoteInput::Move { .. })
    }

    /// Encodes a datagram prefixed with [`remote::DATAGRAM_TAG`].
    pub fn to_datagram(&self) -> Vec<u8> {
        let mut out = vec![remote::DATAGRAM_TAG];
        let _ = ciborium::into_writer(self, &mut out);
        out
    }

    /// Decodes and validates a datagram prefixed with [`remote::DATAGRAM_TAG`].
    pub fn from_datagram(bytes: &[u8]) -> Result<Self, crate::ProtocolError> {
        if bytes.first().copied() != Some(remote::DATAGRAM_TAG) {
            return Err(crate::ProtocolError::BadMessage("unknown datagram channel tag".into()));
        }
        let body = &bytes[1..];
        if body.is_empty() || body.len() > remote::MAX_DATAGRAM_BYTES {
            return Err(crate::ProtocolError::FrameTooLarge(body.len()));
        }
        let input: Self =
            ciborium::from_reader(body).map_err(|e| crate::ProtocolError::BadMessage(e.to_string()))?;
        if !input.is_valid() || !input.is_datagram_allowed() {
            return Err(crate::ProtocolError::BadMessage("invalid remote input datagram".into()));
        }
        Ok(input)
    }
}

// ---- Phone toggles (docs/protocol/toggles.md) ----

/// Capability IDs for `phone.toggles` and `phone.toggle.set`.
pub mod toggles {
    pub const READ: &str = "toggles.read";
    pub const RINGER: &str = "toggles.ringer";
    pub const VOLUME: &str = "toggles.volume";
    pub const FLASHLIGHT: &str = "toggles.flashlight";
    pub const DND: &str = "toggles.dnd";
    pub const BRIGHTNESS: &str = "toggles.brightness";
    pub const WIFI: &str = "toggles.wifi";
    pub const BLUETOOTH: &str = "toggles.bluetooth";
    pub const SHOW: &str = "toggles.show";
}

/// Toggle IDs in `phone.toggle.set`.
pub mod toggle_ids {
    pub const DND: &str = "dnd";
    pub const RINGER: &str = "ringer";
    pub const FLASHLIGHT: &str = "flashlight";
    pub const VOLUME: &str = "volume";
    pub const BRIGHTNESS: &str = "brightness";
    pub const WIFI: &str = "wifi";
    pub const BLUETOOTH: &str = "bluetooth";
    pub const HOTSPOT: &str = "hotspot";
    pub const PC_ACTIVE: &str = "pc_active";
    pub const ALL: &[&str] =
        &[DND, RINGER, FLASHLIGHT, VOLUME, BRIGHTNESS, WIFI, BLUETOOTH, HOTSPOT, PC_ACTIVE];
}

/// Ringer modes for [`PhoneToggles::ringer`] and `phone.toggle.set` (`id = "ringer"`).
pub mod ringer_modes {
    pub const RING: &str = "ring";
    pub const VIBRATE: &str = "vibrate";
    pub const SILENT: &str = "silent";
}

/// Body of `phone.toggles` (`docs/protocol/toggles.md` §2.1): a phone's
/// current quick settings state.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhoneToggles {
    pub dnd: bool,
    /// `"ring"`, `"vibrate"` or `"silent"`.
    pub ringer: String,
    /// `None` when the phone has no flash unit.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub flashlight: Option<bool>,
    /// Media volume, `0..=100`.
    pub volume: u8,
    /// Screen brightness, `0..=100`.
    pub brightness: u8,
    pub wifi: bool,
    pub bluetooth: bool,
}

impl PhoneToggles {
    pub fn is_valid(&self) -> bool {
        matches!(self.ringer.as_str(), ringer_modes::RING | ringer_modes::VIBRATE | ringer_modes::SILENT)
            && self.volume <= 100
            && self.brightness <= 100
    }

    /// Validates `ringer` and clamps `volume` and `brightness` to `0..=100`.
    pub fn sanitized(mut self) -> Option<Self> {
        if !matches!(self.ringer.as_str(), ringer_modes::RING | ringer_modes::VIBRATE | ringer_modes::SILENT)
        {
            return None;
        }
        self.volume = self.volume.min(100);
        self.brightness = self.brightness.min(100);
        Some(self)
    }
}

/// A toggle value in [`PhoneToggleSet`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(untagged)]
pub enum PhoneToggleValue {
    Bool(bool),
    Level(u8),
    Mode(String),
}

/// Body of `phone.toggle.set` (`docs/protocol/toggles.md` §2.2).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PhoneToggleSet {
    pub id: String,
    pub value: PhoneToggleValue,
}

impl PhoneToggleSet {
    /// Checks that `id` is a known toggle and `value` has the type and range
    /// that toggle accepts.
    pub fn is_valid(&self) -> bool {
        match (self.id.as_str(), &self.value) {
            (
                toggle_ids::DND
                | toggle_ids::FLASHLIGHT
                | toggle_ids::WIFI
                | toggle_ids::BLUETOOTH
                | toggle_ids::HOTSPOT
                | toggle_ids::PC_ACTIVE,
                PhoneToggleValue::Bool(_),
            ) => true,
            (toggle_ids::VOLUME | toggle_ids::BRIGHTNESS, PhoneToggleValue::Level(n)) => *n <= 100,
            (toggle_ids::RINGER, PhoneToggleValue::Mode(m)) => {
                matches!(m.as_str(), ringer_modes::RING | ringer_modes::VIBRATE | ringer_modes::SILENT)
            }
            _ => false,
        }
    }
}

// ---- Deck (docs/protocol/deck.md) ----

pub mod deck {
    /// Offered by PCs that share their Deck layout and live state and run Deck actions.
    pub const ACTIONS: &str = "deck.actions";
    /// Offered by PCs that share their active audio output devices and accept `pc.audio.set`.
    pub const PC_AUDIO: &str = "pc.audio";
    /// Maximum pages in a `DeckLayout`.
    pub const MAX_PAGES: usize = 8;
    /// Maximum tiles on a single `DeckPage`.
    pub const MAX_TILES_PER_PAGE: usize = 24;
    /// Maximum bytes in a page or tile ID.
    pub const MAX_ID_BYTES: usize = 64;
    /// Maximum UTF-8 bytes in a page name or tile label.
    pub const MAX_LABEL_BYTES: usize = 64;
    /// Maximum active audio output devices in a `DeckState`.
    pub const MAX_OUTPUT_DEVICES: usize = 32;
    /// Maximum bytes in an audio endpoint ID.
    pub const MAX_DEVICE_ID_BYTES: usize = 256;
    /// Maximum UTF-8 bytes in an audio endpoint friendly name.
    pub const MAX_DEVICE_NAME_BYTES: usize = 128;
}

/// Action kinds for [`DeckTile::kind`] (`docs/protocol/deck.md` §2.4).
pub mod deck_kinds {
    pub const MEDIA_PLAY_PAUSE: &str = "media_play_pause";
    pub const MEDIA_NEXT: &str = "media_next";
    pub const MEDIA_PREVIOUS: &str = "media_previous";
    pub const VOLUME_UP: &str = "volume_up";
    pub const VOLUME_DOWN: &str = "volume_down";
    pub const VOLUME_MUTE: &str = "volume_mute";
    pub const MIC_MUTE: &str = "mic_mute";
    pub const LOCK_PC: &str = "lock_pc";
    pub const SHOW_DESKTOP: &str = "show_desktop";
    pub const SWITCH_WINDOW: &str = "switch_window";
    pub const SCREENSHOT: &str = "screenshot";
    pub const SHORTCUT: &str = "shortcut";
    pub const OPEN_URL: &str = "open_url";
    pub const TYPE_TEXT: &str = "type_text";
    pub const LAUNCH_APP: &str = "launch_app";
    pub const RUN_COMMAND: &str = "run_command";

    pub const ALL: &[&str] = &[
        MEDIA_PLAY_PAUSE,
        MEDIA_NEXT,
        MEDIA_PREVIOUS,
        VOLUME_UP,
        VOLUME_DOWN,
        VOLUME_MUTE,
        MIC_MUTE,
        LOCK_PC,
        SHOW_DESKTOP,
        SWITCH_WINDOW,
        SCREENSHOT,
        SHORTCUT,
        OPEN_URL,
        TYPE_TEXT,
        LAUNCH_APP,
        RUN_COMMAND,
    ];

    /// Default icon for an action kind.
    pub fn default_icon(kind: &str) -> &'static str {
        use super::deck_icons::*;
        match kind {
            MEDIA_PLAY_PAUSE => PLAY,
            MEDIA_NEXT => SKIP_NEXT,
            MEDIA_PREVIOUS => SKIP_PREVIOUS,
            VOLUME_UP => VOLUME_UP,
            VOLUME_DOWN => VOLUME_DOWN,
            VOLUME_MUTE => VOLUME_OFF,
            MIC_MUTE => MIC,
            LOCK_PC => LOCK,
            SHOW_DESKTOP => DESKTOP,
            SWITCH_WINDOW => SWITCH_WINDOW,
            SCREENSHOT => SCREENSHOT,
            SHORTCUT => SHORTCUT,
            OPEN_URL => GLOBE,
            TYPE_TEXT => TEXT,
            LAUNCH_APP => APP,
            RUN_COMMAND => TERMINAL,
            _ => SPARKLE,
        }
    }

    /// Default color for an action kind.
    pub fn default_color(kind: &str) -> &'static str {
        use super::deck_colors::*;
        match kind {
            MEDIA_PLAY_PAUSE => AMBER,
            MEDIA_NEXT | MEDIA_PREVIOUS => SLATE,
            VOLUME_UP | VOLUME_DOWN | VOLUME_MUTE => TEAL,
            MIC_MUTE => CORAL,
            LOCK_PC => RED,
            SHOW_DESKTOP | SWITCH_WINDOW => BLUE,
            SCREENSHOT => VIOLET,
            SHORTCUT => AMBER,
            OPEN_URL => BLUE,
            TYPE_TEXT => GREEN,
            LAUNCH_APP => TEAL,
            RUN_COMMAND => CORAL,
            _ => AMBER,
        }
    }

    /// Default label for an action kind.
    pub fn default_label(kind: &str) -> &'static str {
        match kind {
            MEDIA_PLAY_PAUSE => "Play / pause",
            MEDIA_NEXT => "Next",
            MEDIA_PREVIOUS => "Previous",
            VOLUME_UP => "Volume up",
            VOLUME_DOWN => "Volume down",
            VOLUME_MUTE => "Mute audio",
            MIC_MUTE => "Mic mute",
            LOCK_PC => "Lock PC",
            SHOW_DESKTOP => "Show desktop",
            SWITCH_WINDOW => "Switch window",
            SCREENSHOT => "Screenshot",
            SHORTCUT => "Shortcut",
            OPEN_URL => "Open website",
            TYPE_TEXT => "Type text",
            LAUNCH_APP => "Launch app",
            RUN_COMMAND => "Run command",
            _ => "Action",
        }
    }
}

/// Fixed icon identifiers for [`DeckTile::icon`] (`docs/protocol/deck.md` §2.4).
pub mod deck_icons {
    pub const PLAY: &str = "play";
    pub const PAUSE: &str = "pause";
    pub const SKIP_NEXT: &str = "skip_next";
    pub const SKIP_PREVIOUS: &str = "skip_previous";
    pub const VOLUME_UP: &str = "volume_up";
    pub const VOLUME_DOWN: &str = "volume_down";
    pub const VOLUME_OFF: &str = "volume_off";
    pub const MIC: &str = "mic";
    pub const MIC_OFF: &str = "mic_off";
    pub const LOCK: &str = "lock";
    pub const DESKTOP: &str = "desktop";
    pub const SWITCH_WINDOW: &str = "switch_window";
    pub const SCREENSHOT: &str = "screenshot";
    pub const SHORTCUT: &str = "shortcut";
    pub const GLOBE: &str = "globe";
    pub const TEXT: &str = "text";
    pub const APP: &str = "app";
    pub const TERMINAL: &str = "terminal";
    pub const SPARKLE: &str = "sparkle";
    pub const STAR: &str = "star";

    pub const ALL: &[&str] = &[
        PLAY,
        PAUSE,
        SKIP_NEXT,
        SKIP_PREVIOUS,
        VOLUME_UP,
        VOLUME_DOWN,
        VOLUME_OFF,
        MIC,
        MIC_OFF,
        LOCK,
        DESKTOP,
        SWITCH_WINDOW,
        SCREENSHOT,
        SHORTCUT,
        GLOBE,
        TEXT,
        APP,
        TERMINAL,
        SPARKLE,
        STAR,
    ];
}

/// Fixed color identifiers for [`DeckTile::color`] (`docs/protocol/deck.md` §2.4).
pub mod deck_colors {
    pub const AMBER: &str = "amber";
    pub const CORAL: &str = "coral";
    pub const RED: &str = "red";
    pub const TEAL: &str = "teal";
    pub const GREEN: &str = "green";
    pub const BLUE: &str = "blue";
    pub const VIOLET: &str = "violet";
    pub const SLATE: &str = "slate";

    pub const ALL: &[&str] = &[AMBER, CORAL, RED, TEAL, GREEN, BLUE, VIOLET, SLATE];
}

/// Whether a Deck page or tile ID is 1..=64 ASCII alphanumeric, `_`, `-`, or `.` characters.
pub fn is_valid_deck_id(id: &str) -> bool {
    (1..=deck::MAX_ID_BYTES).contains(&id.len())
        && id.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'_' | b'-' | b'.'))
}

fn is_valid_deck_label(s: &str) -> bool {
    let trimmed = s.trim();
    !trimmed.is_empty() && s.len() <= deck::MAX_LABEL_BYTES && !s.chars().any(char::is_control)
}

fn sanitize_deck_label(s: &str) -> Option<String> {
    let filtered: String = s.chars().filter(|c| !c.is_control()).collect();
    let trimmed = filtered.trim();
    if trimmed.is_empty() {
        return None;
    }
    let mut end = trimmed.len().min(deck::MAX_LABEL_BYTES);
    while end > 0 && !trimmed.is_char_boundary(end) {
        end -= 1;
    }
    let out = trimmed[..end].trim().to_owned();
    (!out.is_empty()).then_some(out)
}

/// One tile in a [`DeckPage`] (`docs/protocol/deck.md` §2.1).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeckTile {
    pub id: String,
    pub label: String,
    pub icon: String,
    pub color: String,
    pub kind: String,
}

/// Never prints the user label (protocol v0 §11).
impl std::fmt::Debug for DeckTile {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("DeckTile")
            .field("id", &self.id)
            .field("icon", &self.icon)
            .field("color", &self.color)
            .field("kind", &self.kind)
            .finish_non_exhaustive()
    }
}

impl DeckTile {
    pub fn is_valid(&self) -> bool {
        is_valid_deck_id(&self.id)
            && is_valid_deck_label(&self.label)
            && deck_icons::ALL.contains(&self.icon.as_str())
            && deck_colors::ALL.contains(&self.color.as_str())
            && deck_kinds::ALL.contains(&self.kind.as_str())
    }

    pub fn sanitized(self) -> Option<Self> {
        if !is_valid_deck_id(&self.id) || !deck_kinds::ALL.contains(&self.kind.as_str()) {
            return None;
        }
        let raw_label = sanitize_deck_label(&self.label)?;
        let label = match (self.kind.as_str(), raw_label.as_str()) {
            (deck_kinds::MEDIA_PLAY_PAUSE, "Play / Pause") => "Play / pause".into(),
            (deck_kinds::VOLUME_UP, "Volume Up") => "Volume up".into(),
            (deck_kinds::VOLUME_DOWN, "Volume Down") => "Volume down".into(),
            (deck_kinds::VOLUME_MUTE, "Mute Audio") => "Mute audio".into(),
            (deck_kinds::MIC_MUTE, "Mic Mute") => "Mic mute".into(),
            (deck_kinds::SHOW_DESKTOP, "Show Desktop") => "Show desktop".into(),
            (deck_kinds::SWITCH_WINDOW, "Switch Window") => "Switch window".into(),
            (deck_kinds::OPEN_URL, "Open Website") => "Open website".into(),
            (deck_kinds::TYPE_TEXT, "Type Text") => "Type text".into(),
            (deck_kinds::LAUNCH_APP, "Launch App") => "Launch app".into(),
            (deck_kinds::RUN_COMMAND, "Run Command") => "Run command".into(),
            _ => raw_label,
        };
        let icon = if deck_icons::ALL.contains(&self.icon.as_str()) {
            self.icon
        } else {
            deck_kinds::default_icon(&self.kind).into()
        };
        let color = if deck_colors::ALL.contains(&self.color.as_str()) {
            self.color
        } else {
            deck_kinds::default_color(&self.kind).into()
        };
        Some(DeckTile { id: self.id, label, icon, color, kind: self.kind })
    }
}

/// One page of tiles in [`DeckLayout`] (`docs/protocol/deck.md` §2.1).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeckPage {
    pub id: String,
    pub name: String,
    #[serde(default)]
    pub tiles: Vec<DeckTile>,
}

/// Never prints the page name (protocol v0 §11).
impl std::fmt::Debug for DeckPage {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("DeckPage")
            .field("id", &self.id)
            .field("tiles", &self.tiles.len())
            .finish_non_exhaustive()
    }
}

/// Body of `deck.layout`: pages and tiles configured on the PC (`docs/protocol/deck.md` §2.1).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeckLayout {
    pub pages: Vec<DeckPage>,
}

impl DeckLayout {
    pub fn is_valid(&self) -> bool {
        if !(1..=deck::MAX_PAGES).contains(&self.pages.len()) {
            return false;
        }
        let mut page_ids = std::collections::BTreeSet::new();
        let mut tile_ids = std::collections::BTreeSet::new();
        for page in &self.pages {
            if !is_valid_deck_id(&page.id)
                || !is_valid_deck_label(&page.name)
                || page.tiles.len() > deck::MAX_TILES_PER_PAGE
                || !page_ids.insert(page.id.as_str())
            {
                return false;
            }
            for tile in &page.tiles {
                if !tile.is_valid() || !tile_ids.insert(tile.id.as_str()) {
                    return false;
                }
            }
        }
        true
    }

    pub fn sanitized(self) -> Option<Self> {
        let mut page_ids = std::collections::BTreeSet::new();
        let mut tile_ids = std::collections::BTreeSet::new();
        let mut pages = Vec::new();
        for page in self.pages {
            if pages.len() >= deck::MAX_PAGES {
                break;
            }
            if !is_valid_deck_id(&page.id) || !page_ids.insert(page.id.clone()) {
                continue;
            }
            let Some(name) = sanitize_deck_label(&page.name) else {
                continue;
            };
            let mut tiles = Vec::new();
            for tile in page.tiles {
                if tiles.len() >= deck::MAX_TILES_PER_PAGE {
                    break;
                }
                if let Some(clean) = tile.sanitized()
                    && tile_ids.insert(clean.id.clone())
                {
                    tiles.push(clean);
                }
            }
            pages.push(DeckPage { id: page.id, name, tiles });
        }
        (!pages.is_empty()).then_some(DeckLayout { pages })
    }

    /// Finds a tile by ID across all pages.
    pub fn tile(&self, id: &str) -> Option<&DeckTile> {
        self.pages.iter().flat_map(|p| p.tiles.iter()).find(|t| t.id == id)
    }

    /// The default single-page Deck layout (`docs/protocol/deck.md`).
    pub fn default_layout() -> Self {
        let tile = |id: &str, kind: &str| DeckTile {
            id: id.into(),
            label: deck_kinds::default_label(kind).into(),
            icon: deck_kinds::default_icon(kind).into(),
            color: deck_kinds::default_color(kind).into(),
            kind: kind.into(),
        };
        DeckLayout {
            pages: vec![DeckPage {
                id: "main".into(),
                name: "Main".into(),
                tiles: vec![
                    tile("play_pause", deck_kinds::MEDIA_PLAY_PAUSE),
                    tile("prev_track", deck_kinds::MEDIA_PREVIOUS),
                    tile("next_track", deck_kinds::MEDIA_NEXT),
                    tile("vol_down", deck_kinds::VOLUME_DOWN),
                    tile("vol_up", deck_kinds::VOLUME_UP),
                    tile("vol_mute", deck_kinds::VOLUME_MUTE),
                    tile("mic_mute", deck_kinds::MIC_MUTE),
                    tile("show_desktop", deck_kinds::SHOW_DESKTOP),
                    tile("switch_window", deck_kinds::SWITCH_WINDOW),
                    tile("screenshot", deck_kinds::SCREENSHOT),
                    tile("lock_pc", deck_kinds::LOCK_PC),
                ],
            }],
        }
    }
}

impl Default for DeckLayout {
    fn default() -> Self {
        Self::default_layout()
    }
}

/// One active audio output endpoint on the PC (`docs/protocol/deck.md` §2.2).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AudioOutputDevice {
    pub id: String,
    pub name: String,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub is_default: bool,
}

/// Never prints the user's audio device name or system ID in logs (protocol v0 §11).
impl std::fmt::Debug for AudioOutputDevice {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("AudioOutputDevice").field("is_default", &self.is_default).finish_non_exhaustive()
    }
}

impl AudioOutputDevice {
    pub fn is_valid(&self) -> bool {
        let id = self.id.trim();
        let name = self.name.trim();
        !id.is_empty()
            && self.id.len() <= deck::MAX_DEVICE_ID_BYTES
            && !self.id.chars().any(char::is_control)
            && !name.is_empty()
            && self.name.len() <= deck::MAX_DEVICE_NAME_BYTES
            && !self.name.chars().any(char::is_control)
    }

    pub fn sanitized(self) -> Option<Self> {
        let id: String = self.id.chars().filter(|c| !c.is_control()).collect();
        let id = id.trim();
        if id.is_empty() || id.len() > deck::MAX_DEVICE_ID_BYTES {
            return None;
        }
        let name: String = self.name.chars().filter(|c| !c.is_control()).collect();
        let name = name.trim();
        if name.is_empty() {
            return None;
        }
        let mut end = name.len().min(deck::MAX_DEVICE_NAME_BYTES);
        while end > 0 && !name.is_char_boundary(end) {
            end -= 1;
        }
        let name = name[..end].trim().to_owned();
        if name.is_empty() {
            return None;
        }
        Some(AudioOutputDevice { id: id.to_owned(), name, is_default: self.is_default })
    }
}

/// Body of `deck.state`: live PC state reflected on Deck tiles (`docs/protocol/deck.md` §2.2).
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeckState {
    #[serde(default)]
    pub playing: bool,
    #[serde(default)]
    pub volume: u8,
    #[serde(default)]
    pub muted: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mic_muted: Option<bool>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub output_devices: Vec<AudioOutputDevice>,
}

impl DeckState {
    pub fn is_valid(&self) -> bool {
        self.volume <= 100
            && self.output_devices.len() <= deck::MAX_OUTPUT_DEVICES
            && self.output_devices.iter().all(AudioOutputDevice::is_valid)
    }

    pub fn sanitized(mut self) -> Option<Self> {
        self.volume = self.volume.min(100);
        self.output_devices = self
            .output_devices
            .into_iter()
            .filter_map(AudioOutputDevice::sanitized)
            .take(deck::MAX_OUTPUT_DEVICES)
            .collect();
        Some(self)
    }

    /// Friendly name of the default audio output device, if reported.
    pub fn default_output_name(&self) -> Option<&str> {
        self.output_devices
            .iter()
            .find(|d| d.is_default)
            .or_else(|| self.output_devices.first())
            .map(|d| d.name.as_str())
    }

    /// Short live status text for a tile of `kind`, if `kind` is a live tile.
    pub fn tile_status(&self, kind: &str) -> Option<String> {
        match kind {
            deck_kinds::MEDIA_PLAY_PAUSE => {
                Some(if self.playing { "Playing".into() } else { "Paused".into() })
            }
            deck_kinds::VOLUME_UP | deck_kinds::VOLUME_DOWN => Some(if self.muted {
                format!("Muted · {}%", self.volume)
            } else {
                format!("{}%", self.volume)
            }),
            deck_kinds::VOLUME_MUTE => {
                Some(if self.muted { "Muted".into() } else { format!("{}%", self.volume) })
            }
            deck_kinds::MIC_MUTE => match self.mic_muted {
                Some(true) => Some("Muted".into()),
                Some(false) => Some("Live".into()),
                None => Some("No mic".into()),
            },
            _ => None,
        }
    }
}

/// Body of `deck.press`: asks the PC to run a tile's action (`docs/protocol/deck.md` §2.3).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeckPress {
    pub tile: String,
}

impl DeckPress {
    pub fn is_valid(&self) -> bool {
        is_valid_deck_id(&self.tile)
    }
}

/// Body of `pc.audio.set`: asks the PC to change its master speaker volume
/// (`0..=100`) and/or mute state (`docs/protocol/deck.md` §2.5).
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct PcAudioSet {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub volume: Option<u8>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub muted: Option<bool>,
}

impl PcAudioSet {
    pub fn is_valid(&self) -> bool {
        let vol_ok = self.volume.is_none_or(|v| v <= 100 || v == 200 || v == 201);
        (self.volume.is_some() || self.muted.is_some()) && vol_ok
    }
}

// ---- Storage (docs/protocol/storage.md) ----

pub mod storage {
    /// Offered by phones that list folders and read files in shared storage.
    pub const READ: &str = "storage.read";
    /// Offered by phones that create folders, write/upload files, rename and delete entries.
    pub const WRITE: &str = "storage.write";
    /// Offered by PCs that mount phone storage in File Explorer.
    pub const MOUNT: &str = "storage.mount";
    pub const SERVICE: &str = "storage";
    pub const OP_READ: &str = "read";
    pub const OP_WRITE: &str = "write";
    pub const VERSION: u32 = 1;
    /// Maximum UTF-8 bytes in a relative storage path.
    pub const MAX_PATH_BYTES: usize = 1024;
    /// Maximum `/`-separated path segments.
    pub const MAX_SEGMENTS: usize = 32;
    /// Maximum UTF-8 bytes in a single entry name.
    pub const MAX_NAME_BYTES: usize = 255;
    /// Maximum bytes in a write upload ID.
    pub const MAX_ID_BYTES: usize = 64;
}

/// Whether `name` is a valid single storage entry name (`1..=255` UTF-8 bytes,
/// not `"."` or `".."`, no `/`, `\`, NUL, or control characters).
pub fn is_valid_storage_name(name: &str) -> bool {
    (1..=storage::MAX_NAME_BYTES).contains(&name.len())
        && name != "."
        && name != ".."
        && !name.chars().any(|c| c == '/' || c == '\\' || c.is_control())
}

/// Whether `path` is a valid non-empty relative storage path (`"DCIM/Camera"`,
/// `"report.pdf"`): `1..=32` `/`-separated segments, at most 1 024 bytes, no
/// leading or trailing `/`, no `.` or `..` segments, no `\` or control chars.
pub fn is_valid_storage_path(path: &str) -> bool {
    if path.is_empty() || path.len() > storage::MAX_PATH_BYTES || path.starts_with('/') || path.ends_with('/')
    {
        return false;
    }
    let mut count = 0usize;
    for seg in path.split('/') {
        count += 1;
        if count > storage::MAX_SEGMENTS || !is_valid_storage_name(seg) {
            return false;
        }
    }
    count >= 1
}

/// Whether `path` is a valid storage directory path (`""` for the shared root,
/// or a valid relative path).
pub fn is_valid_storage_dir_path(path: &str) -> bool {
    path.is_empty() || is_valid_storage_path(path)
}

/// Whether `id` is a valid upload ID (`1..=64` printable ASCII characters
/// without `/` or `\`).
pub fn is_valid_storage_id(id: &str) -> bool {
    (1..=storage::MAX_ID_BYTES).contains(&id.len())
        && id.bytes().all(|b| (0x21..=0x7e).contains(&b) && b != b'/' && b != b'\\')
}

/// Body of `storage.list` (`docs/protocol/storage.md` §3.1).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StorageList {
    pub path: String,
    /// Entries to skip, for the next page of a folder whose entries don't
    /// fit one answer. Absent (0) from devices before paging, which then get
    /// the first page only, as before.
    #[serde(default, skip_serializing_if = "is_zero_u64")]
    pub offset: u64,
}

fn is_zero_u64(n: &u64) -> bool {
    *n == 0
}

impl std::fmt::Debug for StorageList {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("StorageList").finish_non_exhaustive()
    }
}

impl StorageList {
    pub fn is_valid(&self) -> bool {
        is_valid_storage_dir_path(&self.path)
    }
}

/// One directory entry in `storage.entries` (`docs/protocol/storage.md` §3).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StorageEntry {
    pub name: String,
    pub size: u64,
    /// Last-modified time in Unix milliseconds.
    pub modified: i64,
    pub is_dir: bool,
}

/// Never prints entry names in logs (protocol v0 §11).
impl std::fmt::Debug for StorageEntry {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("StorageEntry")
            .field("size", &self.size)
            .field("modified", &self.modified)
            .field("is_dir", &self.is_dir)
            .finish_non_exhaustive()
    }
}

impl StorageEntry {
    pub fn is_valid(&self) -> bool {
        is_valid_storage_name(&self.name) && self.modified >= 0
    }

    pub fn sanitized(mut self) -> Option<Self> {
        if !is_valid_storage_name(&self.name) {
            return None;
        }
        self.modified = self.modified.max(0);
        if self.is_dir {
            self.size = 0;
        }
        Some(self)
    }
}

/// Body of `storage.entries`: immediate children of a listed folder.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct StorageEntries {
    #[serde(default)]
    pub entries: Vec<StorageEntry>,
    /// More entries follow: ask again with `offset` past these.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub more: bool,
}

/// Body of `storage.read` on a `storage/read` stream (`docs/protocol/storage.md` §4.1).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StorageRead {
    pub path: String,
    #[serde(default)]
    pub offset: u64,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub length: Option<u64>,
}

impl std::fmt::Debug for StorageRead {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("StorageRead")
            .field("offset", &self.offset)
            .field("length", &self.length)
            .finish_non_exhaustive()
    }
}

impl StorageRead {
    pub fn is_valid(&self) -> bool {
        is_valid_storage_path(&self.path)
    }
}

/// Body of `storage.read.meta`: precedes the raw file bytes on a `storage/read` stream.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct StorageReadMeta {
    pub size: u64,
    pub modified: i64,
    pub length: u64,
}

/// Body of `storage.write` on a `storage/write` stream (`docs/protocol/storage.md` §4.2).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StorageWriteOffer {
    pub id: String,
    pub path: String,
    pub size: u64,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub modified: Option<i64>,
}

impl std::fmt::Debug for StorageWriteOffer {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("StorageWriteOffer")
            .field("id", &self.id)
            .field("size", &self.size)
            .finish_non_exhaustive()
    }
}

impl StorageWriteOffer {
    pub fn is_valid(&self) -> bool {
        is_valid_storage_id(&self.id)
            && is_valid_storage_path(&self.path)
            && self.modified.is_none_or(|m| m >= 0)
    }
}

/// Body of `storage.write.accept`: how many bytes the phone already has for this upload.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct StorageWriteAccept {
    pub have: u64,
}

/// Body of `storage.write.done`: sent by the phone after committing the uploaded file.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct StorageWriteDone {
    pub size: u64,
    pub modified: i64,
}

/// Body of `storage.mkdir` (`docs/protocol/storage.md` §3.2).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StorageMkdir {
    pub path: String,
}

impl std::fmt::Debug for StorageMkdir {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("StorageMkdir").finish_non_exhaustive()
    }
}

impl StorageMkdir {
    pub fn is_valid(&self) -> bool {
        is_valid_storage_path(&self.path)
    }
}

/// Body of `storage.rename` (`docs/protocol/storage.md` §3.3).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StorageRename {
    pub from: String,
    pub to: String,
}

impl std::fmt::Debug for StorageRename {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("StorageRename").finish_non_exhaustive()
    }
}

impl StorageRename {
    pub fn is_valid(&self) -> bool {
        is_valid_storage_path(&self.from) && is_valid_storage_path(&self.to) && self.from != self.to
    }
}

/// Body of `storage.delete` (`docs/protocol/storage.md` §3.4).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StorageDelete {
    pub path: String,
    #[serde(default)]
    pub confirmed: bool,
}

impl std::fmt::Debug for StorageDelete {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("StorageDelete").field("confirmed", &self.confirmed).finish_non_exhaustive()
    }
}

impl StorageDelete {
    pub fn is_valid(&self) -> bool {
        is_valid_storage_path(&self.path)
    }
}

/// Body of `storage.changed` (`docs/protocol/storage.md` §3.5).
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StorageChanged {
    pub path: String,
}

impl std::fmt::Debug for StorageChanged {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("StorageChanged").finish_non_exhaustive()
    }
}

impl StorageChanged {
    pub fn is_valid(&self) -> bool {
        is_valid_storage_dir_path(&self.path)
    }
}

#[cfg(test)]
mod tests {
    #[test]
    fn sound_only_is_the_phones_sound_and_nothing_else() {
        let sound = MirrorStart {
            max_size: 0,
            fps: 0,
            bitrate: 0,
            audio: true,
            session: mirror::SCREEN,
            app: None,
            stay_awake: false,
            screen_off: false,
            watch: None,
            sound_only: true,
        };
        assert!(sound.is_valid());
        assert!(!MirrorStart { audio: false, ..sound.clone() }.is_valid(), "the sound is the point");
        assert!(!MirrorStart { session: 2, app: Some("com.example.app".into()), ..sound.clone() }.is_valid());
        assert!(!MirrorStart { watch: Some("Chrome".into()), ..sound.clone() }.is_valid());
        assert!(!MirrorStart { screen_off: true, ..sound.clone() }.is_valid(), "nothing about the screen");
        // It survives the trip, and a request without it is the screen, as before.
        let env = crate::Envelope::new(types::MIRROR_START, &sound).unwrap();
        assert!(env.body::<MirrorStart>().unwrap().sound_only);
        let screen =
            crate::Envelope::new(types::MIRROR_START, &MirrorStart { sound_only: false, ..sound }).unwrap();
        assert!(!screen.body::<MirrorStart>().unwrap().sound_only);
    }

    #[test]
    fn audit_73_validation_rules() {
        // A photo request with both `id` and `ids` asks for all of them, once.
        let get = PhotoGet { id: "a".into(), ids: vec!["b".into(), "a".into(), "c".into()] };
        assert_eq!(get.requested_ids(), ["a", "b", "c"]);
        assert_eq!(PhotoGet { id: String::new(), ids: vec!["b".into()] }.requested_ids(), ["b"]);
        assert!(PhotoGet { id: String::new(), ids: Vec::new() }.requested_ids().is_empty());

        // Dialled numbers: pauses and waits are fine, control characters aren't.
        assert!(CallDial { number: "+1 555 0100,,23#".into(), sim: None }.is_valid());
        assert!(CallDial { number: "555;1".into(), sim: None }.is_valid());
        assert!(!CallDial { number: "555\n0100".into(), sim: None }.is_valid());

        // `plugged` keeps only the documented values.
        let battery = |plugged: &str| Battery {
            level: 50,
            charging: true,
            plugged: Some(plugged.into()),
            full_in: None,
            cell_bars: None,
            cell_type: None,
            wifi_bars: None,
        };
        assert_eq!(battery("usb").sanitized().plugged.as_deref(), Some("usb"));
        assert_eq!(battery("<b>dock</b>").sanitized().plugged, None);

        // A wake target is a unicast adapter address.
        assert!(parse_mac("aa:bb:cc:dd:ee:ff").is_some());
        assert!(parse_mac("01:00:5e:00:00:01").is_none(), "multicast");
        assert!(parse_mac("ff:ff:ff:ff:ff:ff").is_none(), "broadcast");

        // An offered file's name is a plain file name.
        let file = |name: &str| WatchFile { name: name.into(), size: 1, position: 0 };
        assert!(file("Trip: day 1.mp4").is_valid());
        assert!(!file("..").is_valid());
        assert!(!file("a\u{7}b.mp4").is_valid());
    }

    use super::*;
    use crate::Envelope;

    fn info() -> DeviceInfo {
        DeviceInfo {
            name: "Pixel 9".into(),
            kind: DeviceKind::Phone,
            os: "android".into(),
            os_ver: "16".into(),
            model: Some("Google Pixel 9".into()),
            accent: None,
            screen: None,
            install_id: None,
        }
    }

    #[test]
    fn elevated_usb_only_runs_the_apps_own_helper_and_grants() {
        let apk = "/data/app/~~kG3x_Q==/app.nectarlink-Ab1-cD2==/base.apk";
        let start = ElevatedUsbStart {
            apk: apk.into(),
            token: "0123456789abcdef0123456789abcdef0123456789abcdef".into(),
            grants: vec![
                "pm grant app.nectarlink android.permission.WRITE_SECURE_SETTINGS".into(),
                "appops set app.nectarlink RECEIVE_SENSITIVE_NOTIFICATIONS allow".into(),
                "cmd notification allow_dnd app.nectarlink".into(),
                "cmd notification allow_listener app.nectarlink/app.nectarlink.android.notifications.NotificationListener"
                    .into(),
            ],
        };
        assert!(start.is_valid());

        for apk in [
            "/data/app/other.app-1/base.apk",
            "/sdcard/app.nectarlink/base.apk",
            "/data/app/app.nectarlink-1/../../evil/base.apk",
            "/data/app/app.nectarlink-1/base.apk; reboot",
            "/data/app/app.nectarlink-1/base.apk$(id)",
        ] {
            assert!(!ElevatedUsbStart { apk: apk.into(), ..start.clone() }.is_valid(), "{apk}");
        }
        for grant in [
            "pm grant com.other android.permission.WRITE_SECURE_SETTINGS",
            "pm grant app.nectarlink android.permission.X; rm -rf /sdcard",
            "pm grant app.nectarlink android.permission.X && reboot",
            "appops set app.nectarlink.evil SYSTEM_ALERT_WINDOW allow",
            "cmd notification allow_listener com.other/x.Listener",
            "cmd notification allow_dnd com.other",
            "settings put global adb_enabled 1",
            "reboot",
        ] {
            assert!(!ElevatedUsbStart { grants: vec![grant.into()], ..start.clone() }.is_valid(), "{grant}");
        }
        assert!(
            !ElevatedUsbStart { token: "not-hex-token-not-hex-token-not-hex".into(), ..start.clone() }
                .is_valid()
        );
        assert!(!ElevatedUsbStart { grants: vec![start.grants[0].clone(); 9], ..start.clone() }.is_valid());
        // The side-by-side test build grants itself, in debug builds only.
        let dev = ElevatedUsbStart {
            apk: "/data/app/~~kG3x_Q==/app.nectarlink.dev-Ab1-cD2==/base.apk".into(),
            grants: vec![
                "pm grant app.nectarlink.dev android.permission.WRITE_SECURE_SETTINGS".into(),
                "cmd notification allow_listener app.nectarlink.dev/app.nectarlink.android.notifications.NotificationListener".into(),
            ],
            ..start
        };
        assert_eq!(dev.is_valid(), cfg!(debug_assertions));
    }

    #[test]
    fn device_names_are_cleaned_and_capped() {
        assert_eq!(info().sanitized(), info(), "ordinary info is unchanged");

        let mut dev = info();
        // A right-to-left override would show "Pixel\u{202E}gnp.exe" as "Pixelexe.png".
        dev.name = " Pixel\u{202E}gnp.exe\u{0007}\n ".into();
        dev.os_ver = "1".repeat(100);
        dev.model = Some("\u{2066}\u{2069}".into());
        let clean = dev.sanitized();
        assert_eq!(clean.name, "Pixelgnp.exe");
        assert_eq!(clean.os_ver.chars().count(), MAX_DEVICE_OS_CHARS);
        assert_eq!(clean.model, None);

        let long = DeviceInfo { name: "é".repeat(200), ..info() }.sanitized();
        assert_eq!(long.name.chars().count(), MAX_DEVICE_NAME_CHARS);
    }

    #[test]
    fn screen_shape_and_battery_full_in_round_trip_and_sanitize() {
        let screen = ScreenShape {
            v: 1,
            aspect: 0.45,
            corners: Some(ScreenCorners { tl: 0.088, tr: 0.088, br: 0.088, bl: 0.088 }),
            cutouts: vec![ScreenRect { x: 0.46, y: 0.018, w: 0.08, h: 0.036 }],
            cutout_path: Some("M 0.5 0.018 L 0.54 0.036 L 0.5 0.054 L 0.46 0.036 Z".into()),
        };
        let mut dev = info();
        dev.screen = Some(screen.clone());
        let env = Envelope::new(types::EVENT_DEVICE, &dev).unwrap();
        let back: DeviceInfo = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back.clone().sanitized(), dev);

        // Unknown schema version or out-of-range aspect drops screen cleanly.
        assert!(ScreenShape { v: 2, ..screen.clone() }.sanitized().is_none());
        assert!(ScreenShape { aspect: 0.05, ..screen.clone() }.sanitized().is_none());
        assert!(ScreenShape { aspect: f32::NAN, ..screen.clone() }.sanitized().is_none());

        // Malformed SVG path characters or oversized rect coordinates are sanitized.
        let dirty = ScreenShape {
            v: 1,
            aspect: 0.4495,
            corners: Some(ScreenCorners { tl: 0.9, tr: -0.1, br: 0.08, bl: 0.08 }),
            cutouts: vec![
                ScreenRect { x: -0.1, y: 0.02, w: 0.2, h: 0.04 },
                ScreenRect { x: 0.5, y: 0.5, w: 0.0, h: 0.1 },
            ],
            cutout_path: Some("<script>alert(1)</script>".into()),
        }
        .sanitized()
        .unwrap();
        assert_eq!(dirty.corners, Some(ScreenCorners { tl: 0.5, tr: 0.0, br: 0.08, bl: 0.08 }));
        assert_eq!(dirty.cutouts, vec![ScreenRect { x: 0.0, y: 0.02, w: 0.2, h: 0.04 }]);
        assert!(dirty.cutout_path.is_none());

        // Battery with full_in round-trips and sanitizes when not charging or out of range.
        let b = Battery {
            level: 68,
            charging: true,
            plugged: Some("usb".into()),
            full_in: Some(34),
            cell_bars: None,
            cell_type: None,
            wifi_bars: None,
        };
        let env = Envelope::new(types::EVENT_BATTERY, &b).unwrap();
        let back: Battery = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back.sanitized(), b);
        assert_eq!(
            Battery {
                level: 105,
                charging: false,
                plugged: None,
                full_in: Some(25),
                cell_bars: None,
                cell_type: None,
                wifi_bars: None,
            }
            .sanitized(),
            Battery {
                level: 100,
                charging: false,
                plugged: None,
                full_in: None,
                cell_bars: None,
                cell_type: None,
                wifi_bars: None,
            }
        );
    }

    #[test]
    fn battery_signal_strength_round_trips_sanitizes_and_is_backwards_compatible() {
        let valid = Battery {
            level: 85,
            charging: false,
            plugged: None,
            full_in: None,
            cell_bars: Some(4),
            cell_type: Some("5G".into()),
            wifi_bars: Some(3),
        };
        let env = Envelope::new(types::EVENT_BATTERY, &valid).unwrap();
        let back: Battery = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back.sanitized(), valid);

        // Clamping bars > 4 to 4, stripping control characters, trimming, truncating cell_type to 8 chars.
        let dirty = Battery {
            level: 50,
            charging: false,
            plugged: None,
            full_in: None,
            cell_bars: Some(9),
            cell_type: Some("  5G\n\tUltraWideband  ".into()),
            wifi_bars: Some(255),
        }
        .sanitized();
        assert_eq!(dirty.cell_bars, Some(4));
        assert_eq!(dirty.cell_type.as_deref(), Some("5GUltraW"));
        assert_eq!(dirty.wifi_bars, Some(4));

        // Blank or control-only cell_type becomes None.
        let empty_type = Battery {
            level: 50,
            charging: false,
            plugged: None,
            full_in: None,
            cell_bars: Some(0),
            cell_type: Some(" \n\0\t ".into()),
            wifi_bars: Some(0),
        }
        .sanitized();
        assert_eq!(empty_type.cell_bars, Some(0));
        assert_eq!(empty_type.cell_type, None);
        assert_eq!(empty_type.wifi_bars, Some(0));

        // Backwards-compatible decoding when signal fields are omitted on the wire.
        #[derive(Serialize)]
        struct LegacyBattery {
            level: u8,
            charging: bool,
        }
        let legacy_env =
            Envelope::new(types::EVENT_BATTERY, &LegacyBattery { level: 77, charging: false }).unwrap();
        let decoded: Battery = Envelope::from_cbor(&legacy_env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(
            decoded,
            Battery {
                level: 77,
                charging: false,
                plugged: None,
                full_in: None,
                cell_bars: None,
                cell_type: None,
                wifi_bars: None,
            }
        );
        // None signal fields are omitted on the wire.
        let none_env = Envelope::new(types::EVENT_BATTERY, &decoded).unwrap();
        let debug_b = format!("{:?}", none_env.b);
        assert!(
            !debug_b.contains("cell_bars")
                && !debug_b.contains("cell_type")
                && !debug_b.contains("wifi_bars")
        );
    }

    #[test]
    fn hello_round_trips() {
        let hello = Hello {
            proto: 0,
            min: 0,
            app: "0.0.1".into(),
            device: info(),
            caps: vec!["core.ping".into(), "device.battery".into()],
            power: PowerLevel::Elevated,
        };
        let env = Envelope::new(types::HELLO, &hello).unwrap();
        let back: Hello = Envelope::from_cbor(&env.to_cbor()).unwrap().expect_body(types::HELLO).unwrap();
        assert_eq!(back, hello);
    }

    #[test]
    fn unknown_enum_values_are_tolerated() {
        #[derive(Serialize)]
        struct Raw<'a> {
            kind: &'a str,
            power: &'a str,
        }
        #[derive(Deserialize)]
        struct Parsed {
            kind: DeviceKind,
            power: PowerLevel,
        }
        let env = Envelope::new("x", &Raw { kind: "watch", power: "root" }).unwrap();
        let parsed: Parsed = env.body().unwrap();
        assert_eq!(parsed.kind, DeviceKind::Unknown);
        assert_eq!(parsed.power.effective(), PowerLevel::Basic);
    }

    fn notification() -> Notification {
        Notification {
            key: "0|com.example|1|null|10123".into(),
            app: "com.example".into(),
            app_name: "Example".into(),
            title: Some("Sam".into()),
            text: Some("Lunch?".into()),
            sub: None,
            when: 1_760_000_000_000,
            actions: vec![NotificationAction { id: "0".into(), title: "Reply".into(), reply: true }],
            silent: false,
            icon: Some(vec![0x89, b'P', b'N', b'G']),
            image: None,
            live: None,
            conversation: None,
        }
    }

    #[test]
    fn notifications_round_trip_with_binary_icons() {
        let n = notification();
        let env = Envelope::new(types::NOTIFY_POSTED, &n).unwrap();
        // The icon travels as a CBOR byte string, not an array of numbers.
        let icon = match &env.b {
            Some(ciborium::Value::Map(fields)) => fields.iter().find(|(k, _)| k.as_text() == Some("icon")),
            _ => None,
        };
        assert!(matches!(icon, Some((_, ciborium::Value::Bytes(_)))));
        let back: Notification = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back, n);
    }

    #[test]
    fn sanitizing_enforces_the_limits() {
        let mut n = notification();
        n.title = Some("é".repeat(300));
        n.text = Some("  ".into());
        n.actions = (0..8)
            .map(|i| NotificationAction { id: i.to_string(), title: "Go".into(), reply: false })
            .collect();
        n.actions.push(NotificationAction { id: String::new(), title: "No id".into(), reply: false });
        n.icon = Some(vec![0; notify_limits::ICON_BYTES + 1]);
        n.image = Some(vec![0; notify_limits::IMAGE_BYTES + 1]);
        let n = n.sanitized().unwrap();
        assert_eq!(n.title.unwrap().chars().count(), notify_limits::TITLE_CHARS);
        assert_eq!(n.text, None, "blank text is dropped");
        assert_eq!(n.actions.len(), notify_limits::ACTIONS);
        assert_eq!(n.icon, None);
        assert_eq!(n.image, None);
    }

    #[test]
    fn conversation_notifications_are_sanitized_and_hide_content_in_debug() {
        let mut n = notification();
        n.conversation = Some(NotificationConversation {
            v: 1,
            title: "Design Team".into(),
            group: true,
            avatar: Some(vec![0xff, 0xd8]),
            messages: (0..30)
                .map(|i| NotificationChatMessage {
                    sender: Some(format!("Sender {i}")),
                    text: format!("Message {i}"),
                    time: 1_760_000_000_000 + i,
                    self_sent: i % 2 == 0,
                    avatar: Some(vec![0; if i == 29 { notify_limits::AVATAR_BYTES + 1 } else { 4 }]),
                })
                .collect(),
        });
        let shown = format!("{n:?} {:?}", n.conversation);
        assert!(!shown.contains("Design Team") && !shown.contains("Message 29"), "{shown}");
        let clean = n.sanitized().unwrap();
        let conv = clean.conversation.unwrap();
        assert_eq!(conv.messages.len(), notify_limits::CONVERSATION_MESSAGES);
        assert_eq!(conv.messages[0].text, "Message 5", "keeps newest messages");
        assert_eq!(conv.messages[1].sender, None, "self-sent messages drop sender name");
        assert_eq!(conv.messages.last().unwrap().avatar, None, "oversized avatar is dropped");
    }

    #[test]
    fn notifications_without_content_or_key_are_dropped() {
        let mut n = notification();
        n.title = None;
        n.text = Some(" ".into());
        assert_eq!(n.sanitized(), None);
        let mut n = notification();
        n.key = String::new();
        assert_eq!(n.sanitized(), None);
    }

    #[test]
    fn debug_output_hides_content() {
        let shown = format!("{:?}", notification());
        assert!(!shown.contains("Lunch") && !shown.contains("Sam"), "{shown}");
        let action = NotifyAction { key: "k".into(), action: "0".into(), reply: Some("secret".into()) };
        assert!(!format!("{action:?}").contains("secret"));
    }

    #[test]
    fn file_offers_are_validated() {
        let offer = |id: &str, names: &[&str]| FilesOffer {
            id: id.into(),
            files: names
                .iter()
                .map(|n| FileEntry { name: (*n).into(), size: 1, folder: None, blake3: None })
                .collect(),
            recording: false,
            markers: Vec::new(),
            open_on_arrival: false,
        };
        assert!(offer("abcdefghijklmnop", &["photo.jpg", "Résumé (final).pdf"]).is_valid());
        for bad in ["", ".", "..", "a/b", "a\\b", "x\u{0}y", "tab\there"] {
            assert!(!offer("abcdefghijklmnop", &[bad]).is_valid(), "{bad:?}");
        }
        assert!(!offer("short", &["a"]).is_valid(), "IDs are 16+ characters");
        assert!(!offer("abcdefghijklmnop!", &["a"]).is_valid());
        assert!(!offer("abcdefghijklmnop", &[]).is_valid(), "at least one file");
        assert!(!format!("{:?}", offer("abcdefghijklmnop", &["secret.pdf"])).contains("secret"));
    }

    #[test]
    fn file_blake3_and_control_are_validated() {
        let good_hex = "a".repeat(64);
        let offer_with_hash = |blake3: Option<String>| FilesOffer {
            id: "abcdefghijklmnop".into(),
            files: vec![FileEntry { name: "a.bin".into(), size: 10, folder: None, blake3 }],
            recording: false,
            markers: Vec::new(),
            open_on_arrival: false,
        };
        assert!(offer_with_hash(None).is_valid());
        assert!(offer_with_hash(Some(good_hex)).is_valid());
        assert!(offer_with_hash(Some("0123456789abcdefABCDEF".repeat(2) + &"0".repeat(20))).is_valid());
        for bad in ["", "abcd", &"a".repeat(63), &"a".repeat(65), &(String::from("g") + &"a".repeat(63))] {
            assert!(!offer_with_hash(Some(bad.into())).is_valid(), "{bad:?}");
        }
        assert!(FilesControl { id: "abcdefghijklmnop".into() }.is_valid());
        assert!(!FilesControl { id: "short".into() }.is_valid());
        assert!(!FilesControl { id: "abcdefghijklmnop!".into() }.is_valid());
    }

    #[test]
    fn folders_are_validated() {
        let offer = |folder: &str| FilesOffer {
            id: "abcdefghijklmnop".into(),
            files: vec![FileEntry {
                name: "a.jpg".into(),
                size: 1,
                folder: Some(folder.into()),
                blake3: None,
            }],
            recording: false,
            markers: Vec::new(),
            open_on_arrival: false,
        };
        for good in ["Trip", "Trip/Day 1", "Trip/Day 1/raw"] {
            assert!(offer(good).is_valid(), "{good:?}");
        }
        for bad in ["", "/Trip", "Trip/", "Trip//x", "Trip/..", "./x", "a\\b", "x\u{0}"] {
            assert!(!offer(bad).is_valid(), "{bad:?}");
        }
        assert!(!offer(&vec!["d"; files::MAX_FOLDER_DEPTH + 1].join("/")).is_valid());
        // Without a folder or blake3, the fields aren't sent at all.
        let plain = FileEntry { name: "a".into(), size: 1, folder: None, blake3: None };
        let env = Envelope::new("x", &plain).unwrap();
        assert!(!format!("{:?}", env.b).contains("folder"));
        assert!(!format!("{:?}", env.b).contains("blake3"));
        assert!(!format!("{:?}", offer("Secret")).contains("Secret"));
    }

    #[test]
    fn recording_offers_and_markers_are_validated() {
        let rec = FilesOffer {
            id: "abcdefghijklmnop".into(),
            files: vec![FileEntry { name: "Recording.m4a".into(), size: 4096, folder: None, blake3: None }],
            recording: true,
            markers: vec![
                RecordingMarker { at_ms: 1200, label: None },
                RecordingMarker { at_ms: 5400, label: Some("Action item".into()) },
            ],
            open_on_arrival: false,
        };
        assert!(rec.is_valid());
        assert!(!format!("{:?}", rec.markers[1]).contains("Action item"));
        let env = Envelope::new(files::OFFER, &rec).unwrap();
        let back: FilesOffer = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back, rec);

        // Recordings must be a single file without a folder.
        assert!(
            !FilesOffer {
                files: vec![
                    FileEntry { name: "a.m4a".into(), size: 1, folder: None, blake3: None },
                    FileEntry { name: "b.m4a".into(), size: 1, folder: None, blake3: None },
                ],
                ..rec.clone()
            }
            .is_valid()
        );
        assert!(
            !FilesOffer {
                files: vec![FileEntry {
                    name: "a.m4a".into(),
                    size: 1,
                    folder: Some("dir".into()),
                    blake3: None,
                }],
                ..rec.clone()
            }
            .is_valid()
        );
        // Non-recordings cannot carry markers.
        assert!(!FilesOffer { recording: false, ..rec.clone() }.is_valid());
        // Blank or control-character marker labels are rejected.
        assert!(
            !FilesOffer {
                markers: vec![RecordingMarker { at_ms: 0, label: Some("   ".into()) }],
                ..rec.clone()
            }
            .is_valid()
        );
        assert!(
            !FilesOffer {
                markers: vec![RecordingMarker { at_ms: 0, label: Some("bad\nlabel".into()) }],
                ..rec
            }
            .is_valid()
        );
    }

    #[test]
    fn mirror_input_is_checked() {
        let touch = MirrorInput::Touch { action: TouchAction::Down, x: 0.5, y: 1.0 };
        assert!(touch.is_valid());
        let env = Envelope::new(types::MIRROR_INPUT, &touch).unwrap();
        assert_eq!(env.body::<MirrorInput>().unwrap(), touch);
        assert!(!MirrorInput::Touch { action: TouchAction::Up, x: 1.5, y: 0.0 }.is_valid());
        assert!(!MirrorInput::Touch { action: TouchAction::Up, x: f32::NAN, y: 0.0 }.is_valid());
        assert!(MirrorInput::Key { key: "back".into() }.is_valid());
        assert!(!MirrorInput::Key { key: "power".into() }.is_valid());
        for key in [mirror_keys::COPY, mirror_keys::CUT, mirror_keys::SELECT_ALL] {
            assert!(MirrorInput::Key { key: key.into() }.is_valid());
        }
        assert!(!MirrorInput::Text { text: String::new() }.is_valid());
        assert!(!format!("{:?}", MirrorInput::Text { text: "secret".into() }).contains("secret"));
    }

    #[test]
    fn texts_to_send_are_checked() {
        let send =
            SmsSend { to: vec!["+15550100".into()], body: "On my way".into(), attachments: Vec::new() };
        assert!(send.is_valid());
        assert!(!format!("{send:?}").contains("way"));
        assert!(!SmsSend { to: vec![], ..send.clone() }.is_valid());
        assert!(!SmsSend { body: "  ".into(), ..send.clone() }.is_valid());
        assert!(!SmsSend { body: "x".repeat(sms::MAX_SEND_BYTES + 1), ..send.clone() }.is_valid());
        assert!(!SmsSend { to: vec!["1".into(); sms::MAX_RECIPIENTS + 1], ..send.clone() }.is_valid());
        let with_image = SmsSend {
            body: String::new(),
            attachments: vec![SmsAttachment { mime: "image/png".into(), data: vec![1, 2, 3] }],
            ..send.clone()
        };
        assert!(with_image.is_valid(), "an image attachment can be sent without body text");
        let bad_mime = SmsSend {
            attachments: vec![SmsAttachment { mime: "text/plain".into(), data: vec![1] }],
            ..send.clone()
        };
        assert!(!bad_mime.is_valid());
        let oversized = SmsSend {
            attachments: vec![SmsAttachment {
                mime: "image/jpeg".into(),
                data: vec![0; sms::MAX_ATTACHMENT_BYTES + 1],
            }],
            ..send
        };
        assert!(!oversized.is_valid());
    }

    #[test]
    fn calls_are_validated() {
        let call = CallState {
            id: "1".into(),
            state: calls::RINGING.into(),
            incoming: true,
            number: Some("+1 555 0100".into()),
            name: Some("Sam".into()),
            photo: Some(vec![0xff, 0xd8]),
            missed: false,
            since: None,
            controls: None,
        };
        assert!(call.is_valid());
        let shown = format!("{call:?}");
        assert!(!shown.contains("555") && !shown.contains("Sam"), "{shown}");
        assert!(!CallState { state: "on hold".into(), ..call.clone() }.is_valid());
        assert!(!CallState { id: String::new(), ..call.clone() }.is_valid());
        assert!(!CallState { photo: Some(vec![0; calls::MAX_PHOTO_BYTES + 1]), ..call.clone() }.is_valid());
        // Missing fields take their defaults: incoming, not missed.
        let env = Envelope::new("x", &CallState { number: None, name: None, photo: None, ..call }).unwrap();
        let back: CallState = env.body().unwrap();
        assert!(back.incoming && !back.missed && back.number.is_none());
    }

    #[test]
    fn photos_are_validated() {
        let photo = PhotoNew {
            id: "content:42".into(),
            name: "Screenshot_20261006.png".into(),
            size: 1000,
            taken: 1_790_000_000,
            screenshot: true,
            thumb: vec![0xff, 0xd8],
        };
        assert!(photo.is_valid());
        assert!(!format!("{photo:?}").contains("Screenshot_"));
        assert!(!PhotoNew { id: String::new(), ..photo.clone() }.is_valid());
        assert!(!PhotoNew { id: "a b".into(), ..photo.clone() }.is_valid());
        assert!(!PhotoNew { name: "../x.png".into(), ..photo.clone() }.is_valid());
        assert!(!PhotoNew { thumb: vec![0; photos::MAX_THUMB_BYTES + 1], ..photo }.is_valid());
    }

    #[test]
    fn power_level_wire_names() {
        let env = Envelope::new("x", &PowerLevel::NotApplicable).unwrap();
        assert_eq!(env.b, Some(ciborium::Value::Text("n/a".into())));
    }

    #[test]
    fn call_log_dial_and_contacts_round_trip_and_hide_private_fields() {
        let dial = CallDial { number: "+1 555 0100".into(), sim: None };
        assert!(dial.is_valid());
        assert!(!format!("{dial:?}").contains("555"));
        assert!(!CallDial { number: "   ".into(), sim: None }.is_valid());
        assert!(!CallDial { number: "1".repeat(calls::MAX_TEXT_BYTES + 1), sim: None }.is_valid());
        // A SIM to dial on: checked, and absent from older phones' messages.
        assert!(CallDial { number: "555".into(), sim: Some("1".into()) }.is_valid());
        assert!(!CallDial { number: "555".into(), sim: Some(String::new()) }.is_valid());
        assert!(!CallDial { number: "555".into(), sim: Some("a\nb".into()) }.is_valid());
        let old = Envelope::new(types::CALL_DIAL, &CallDial { number: "555".into(), sim: None }).unwrap();
        assert_eq!(old.body::<CallDial>().unwrap().sim, None);
        let sims = CallSims {
            sims: vec![
                CallSim { id: "1".into(), label: "SIM 1 · Airtel".into() },
                CallSim { id: "2".into(), label: "SIM 2 · Jio".into() },
            ],
            default: Some("2".into()),
        };
        assert!(sims.is_valid());
        let env = Envelope::new(types::CALL_SIMS, &sims).unwrap();
        assert_eq!(env.body::<CallSims>().unwrap(), sims);
        assert!(!CallSims { default: Some("3".into()), ..sims.clone() }.is_valid());
        assert!(
            !CallSims { sims: vec![sims.sims[0].clone(); calls::MAX_SIMS + 1], default: None }.is_valid()
        );

        let entry = CallLogEntry {
            id: "10".into(),
            number: "+15550100".into(),
            name: Some("Ada Lovelace".into()),
            direction: calls::DIR_MISSED.into(),
            date: 1_760_000_000_000,
            duration: 0,
            photo: Some(vec![0xff, 0xd8]),
        };
        assert!(!format!("{entry:?}").contains("555") && !format!("{entry:?}").contains("Ada"));
        let env = Envelope::new(types::CALL_LOG, &CallLog { entries: vec![entry.clone()] }).unwrap();
        let back: CallLog = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back.entries, vec![entry]);

        let contact = Contact {
            id: "42".into(),
            name: "Ada Lovelace".into(),
            numbers: vec![ContactNumber { number: "+15550100".into(), label: Some("mobile".into()) }],
            starred: true,
            photo: Some(vec![0xff, 0xd8]),
        };
        assert!(!format!("{contact:?}").contains("Ada") && !format!("{contact:?}").contains("555"));
        let get = ContactsListGet { query: Some("Ada".into()), offset: 0, limit: 50 };
        assert!(!format!("{get:?}").contains("Ada"));
        let env =
            Envelope::new(types::CONTACTS_LIST, &ContactsList { contacts: vec![contact.clone()] }).unwrap();
        let back: ContactsList = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back.contacts, vec![contact]);
    }

    #[test]
    fn gallery_messages_round_trip_and_hide_private_fields() {
        let album = PhotoAlbum {
            id: "b1".into(),
            name: "Private Vacation".into(),
            count: 12,
            cover: Some("p1".into()),
        };
        assert!(!format!("{album:?}").contains("Vacation"));
        let env = Envelope::new(types::PHOTOS_ALBUMS_LIST, &PhotoAlbumsList { albums: vec![album.clone()] })
            .unwrap();
        let back: PhotoAlbumsList = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back.albums, vec![album]);

        let item = PhotoItem {
            id: "p1".into(),
            name: "secret_photo.jpg".into(),
            date: 1_790_000_000_000,
            size: 2048,
            width: 1920,
            height: 1080,
            duration: Some(5000),
            album: Some("b1".into()),
        };
        assert!(!format!("{item:?}").contains("secret_photo"));
        let env = Envelope::new(types::PHOTOS_ITEMS, &PhotoItems { items: vec![item.clone()] }).unwrap();
        let back: PhotoItems = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back.items, vec![item]);

        let thumb = PhotoThumb { id: "p1".into(), data: vec![0xff, 0xd8, 0xff] };
        let env = Envelope::new(types::PHOTOS_THUMBS_LIST, &PhotoThumbsList { thumbs: vec![thumb.clone()] })
            .unwrap();
        let back: PhotoThumbsList = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back.thumbs, vec![thumb]);

        let single = PhotoGet { id: "p1".into(), ids: Vec::new() };
        assert_eq!(single.requested_ids(), vec!["p1".to_owned()]);
        let multi = PhotoGet { id: String::new(), ids: vec!["p1".into(), "p2".into()] };
        assert_eq!(multi.requested_ids(), vec!["p1".to_owned(), "p2".to_owned()]);
    }

    #[test]
    fn remote_input_validates_and_round_trips() {
        // Datagram round-trip for move, scroll, and laser.
        let mv = RemoteInput::Move { dx: 12.5, dy: -8.0 };
        assert!(mv.is_valid() && mv.is_datagram_allowed() && !mv.is_control_allowed());
        let dgram = mv.to_datagram();
        assert_eq!(dgram[0], remote::DATAGRAM_TAG);
        assert_eq!(RemoteInput::from_datagram(&dgram).unwrap(), mv);

        let laser = RemoteInput::Laser { on: true, x: 0.25, y: 0.75 };
        assert_eq!(RemoteInput::from_datagram(&laser.to_datagram()).unwrap(), laser);
        let laser_off = RemoteInput::Laser { on: false, x: 0.0, y: 0.0 };
        assert_eq!(RemoteInput::from_datagram(&laser_off.to_datagram()).unwrap(), laser_off);

        // Button or key in a datagram is rejected.
        let click = RemoteInput::Button { button: MouseButton::Left, action: ButtonAction::Click };
        assert!(click.is_valid() && click.is_control_allowed() && !click.is_datagram_allowed());
        assert!(RemoteInput::from_datagram(&click.to_datagram()).is_err());

        // Bounds checks.
        assert!(!RemoteInput::Move { dx: 5000.0, dy: 0.0 }.is_valid());
        assert!(!RemoteInput::Move { dx: f32::NAN, dy: 0.0 }.is_valid());
        assert!(!RemoteInput::Scroll { dx: 0.0, dy: 250.0 }.is_valid());
        assert!(!RemoteInput::Laser { on: true, x: 1.2, y: 0.5 }.is_valid());
        assert!(!RemoteInput::Laser { on: true, x: -0.1, y: 0.5 }.is_valid());

        // Text and keys.
        let text = RemoteInput::Text { text: "Hello 🐝 नमस्ते".into() };
        assert!(text.is_valid());
        assert!(!format!("{text:?}").contains("Hello"));
        assert!(!RemoteInput::Text { text: String::new() }.is_valid());
        assert!(!RemoteInput::Text { text: "bad\nnewline".into() }.is_valid());
        assert!(!RemoteInput::Text { text: "x".repeat(remote::MAX_TEXT_BYTES + 1) }.is_valid());

        for k in remote_keys::NAMED {
            assert!(RemoteInput::Key { key: (*k).into(), mods: vec![] }.is_valid(), "{k}");
        }
        for s in remote_keys::SHORTCUTS {
            assert!(RemoteInput::Key { key: (*s).into(), mods: vec![] }.is_valid(), "{s}");
            assert!(!RemoteInput::Key { key: (*s).into(), mods: vec![KeyMod::Ctrl] }.is_valid(), "{s}");
        }
        assert!(RemoteInput::Key { key: "c".into(), mods: vec![KeyMod::Ctrl] }.is_valid());
        assert!(RemoteInput::Key { key: "z".into(), mods: vec![KeyMod::Ctrl, KeyMod::Shift] }.is_valid());
        assert!(
            !RemoteInput::Key { key: "c".into(), mods: vec![] }.is_valid(),
            "unmodified letter uses Text"
        );
        assert!(!RemoteInput::Key { key: "c".into(), mods: vec![KeyMod::Ctrl, KeyMod::Ctrl] }.is_valid());
        assert!(!RemoteInput::Key { key: "f13".into(), mods: vec![] }.is_valid());
        assert!(!RemoteInput::Key { key: "power".into(), mods: vec![] }.is_valid());

        // Slide round-trip on the control stream.
        let slide = RemoteInput::Slide { action: SlideAction::Next };
        let env = Envelope::new(types::REMOTE_INPUT, &slide).unwrap();
        assert_eq!(env.body::<RemoteInput>().unwrap(), slide);
    }

    #[test]
    fn phone_toggles_validate_and_round_trip() {
        let state = PhoneToggles {
            dnd: false,
            ringer: ringer_modes::RING.into(),
            flashlight: Some(true),
            volume: 65,
            brightness: 50,
            wifi: true,
            bluetooth: true,
        };
        assert!(state.is_valid());
        let env = Envelope::new(types::PHONE_TOGGLES, &state).unwrap();
        let back: PhoneToggles = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back, state);

        // Without flash hardware, `flashlight` is omitted on the wire.
        let no_flash = PhoneToggles { flashlight: None, ..state.clone() };
        let env = Envelope::new(types::PHONE_TOGGLES, &no_flash).unwrap();
        assert!(!format!("{:?}", env.b).contains("flashlight"));
        let back: PhoneToggles = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back, no_flash);

        // Invalid ringer mode is rejected; out-of-range volume/brightness clamp in sanitized().
        assert!(!PhoneToggles { ringer: "loud".into(), ..state.clone() }.is_valid());
        assert_eq!(PhoneToggles { ringer: "loud".into(), ..state.clone() }.sanitized(), None);
        assert!(!PhoneToggles { volume: 120, ..state.clone() }.is_valid());
        assert_eq!(PhoneToggles { volume: 120, brightness: 200, ..state }.sanitized().unwrap().volume, 100);

        // `phone.toggle.set` validation for every toggle ID and value kind.
        for id in [toggle_ids::DND, toggle_ids::FLASHLIGHT, toggle_ids::WIFI, toggle_ids::BLUETOOTH] {
            let set = PhoneToggleSet { id: id.into(), value: PhoneToggleValue::Bool(true) };
            assert!(set.is_valid(), "{id}");
            let env = Envelope::new(types::PHONE_TOGGLE_SET, &set).unwrap();
            assert_eq!(Envelope::from_cbor(&env.to_cbor()).unwrap().body::<PhoneToggleSet>().unwrap(), set);
            assert!(!PhoneToggleSet { id: id.into(), value: PhoneToggleValue::Level(1) }.is_valid());
            assert!(!PhoneToggleSet { id: id.into(), value: PhoneToggleValue::Mode("on".into()) }.is_valid());
        }
        for id in [toggle_ids::VOLUME, toggle_ids::BRIGHTNESS] {
            for level in [0, 50, 100] {
                let set = PhoneToggleSet { id: id.into(), value: PhoneToggleValue::Level(level) };
                assert!(set.is_valid());
                let env = Envelope::new(types::PHONE_TOGGLE_SET, &set).unwrap();
                assert_eq!(
                    Envelope::from_cbor(&env.to_cbor()).unwrap().body::<PhoneToggleSet>().unwrap(),
                    set
                );
            }
            assert!(!PhoneToggleSet { id: id.into(), value: PhoneToggleValue::Level(101) }.is_valid());
            assert!(!PhoneToggleSet { id: id.into(), value: PhoneToggleValue::Bool(true) }.is_valid());
        }
        for mode in [ringer_modes::RING, ringer_modes::VIBRATE, ringer_modes::SILENT] {
            let set =
                PhoneToggleSet { id: toggle_ids::RINGER.into(), value: PhoneToggleValue::Mode(mode.into()) };
            assert!(set.is_valid());
            let env = Envelope::new(types::PHONE_TOGGLE_SET, &set).unwrap();
            assert_eq!(Envelope::from_cbor(&env.to_cbor()).unwrap().body::<PhoneToggleSet>().unwrap(), set);
        }
        assert!(
            !PhoneToggleSet { id: toggle_ids::RINGER.into(), value: PhoneToggleValue::Mode("mute".into()) }
                .is_valid()
        );
        assert!(!PhoneToggleSet { id: "airplane".into(), value: PhoneToggleValue::Bool(true) }.is_valid());
    }

    #[test]
    fn magic_packet_has_sync_header_and_sixteen_mac_copies() {
        let mac = parse_mac("00-00-5E-00-53-01").unwrap();
        assert_eq!(mac, [0x00, 0x00, 0x5e, 0x00, 0x53, 0x01]);
        assert_eq!(format_mac(&mac), "00:00:5e:00:53:01");
        let pkt = magic_packet(&mac);
        assert_eq!(pkt.len(), 102);
        assert_eq!(&pkt[..6], &[0xff; 6]);
        for i in 0..16 {
            assert_eq!(&pkt[6 + i * 6..12 + i * 6], &mac);
        }
    }

    #[test]
    fn ipv4_broadcast_from_ip_and_prefix() {
        use std::net::Ipv4Addr;
        assert_eq!(ipv4_broadcast(Ipv4Addr::new(192, 168, 1, 42), 24), Some(Ipv4Addr::new(192, 168, 1, 255)));
        assert_eq!(ipv4_broadcast(Ipv4Addr::new(10, 0, 12, 5), 16), Some(Ipv4Addr::new(10, 0, 255, 255)));
        assert_eq!(ipv4_broadcast(Ipv4Addr::new(172, 16, 5, 10), 20), Some(Ipv4Addr::new(172, 16, 15, 255)));
        assert_eq!(ipv4_broadcast(Ipv4Addr::new(192, 168, 10, 1), 30), Some(Ipv4Addr::new(192, 168, 10, 3)));
        // Invalid prefix lengths or non-routable LAN addresses.
        assert_eq!(ipv4_broadcast(Ipv4Addr::new(192, 168, 1, 42), 0), None);
        assert_eq!(ipv4_broadcast(Ipv4Addr::new(192, 168, 1, 42), 31), None);
        assert_eq!(ipv4_broadcast(Ipv4Addr::new(192, 168, 1, 42), 32), None);
        assert_eq!(ipv4_broadcast(Ipv4Addr::UNSPECIFIED, 24), None);
        assert_eq!(ipv4_broadcast(Ipv4Addr::LOCALHOST, 8), None);
        assert_eq!(ipv4_broadcast(Ipv4Addr::new(169, 254, 10, 20), 16), None);
        assert_eq!(ipv4_broadcast(Ipv4Addr::new(224, 0, 0, 1), 24), None);
        assert_eq!(ipv4_broadcast(Ipv4Addr::BROADCAST, 24), None);
    }

    #[test]
    fn wake_info_validates_sanitizes_and_round_trips() {
        let info = PcWakeInfo {
            macs: vec!["00:00:5e:00:53:01".into(), "00:00:5e:00:53:02".into()],
            broadcasts: vec!["192.168.1.255".into()],
        };
        assert!(info.is_valid());
        let debug = format!("{info:?}");
        assert!(!debug.contains("38:a7") && !debug.contains("192.168"), "{debug}");

        let env = Envelope::new(types::PC_WAKE_INFO, &info).unwrap();
        let back: PcWakeInfo = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back, info);

        let stored = info.to_storage_string();
        assert_eq!(PcWakeInfo::from_storage_str(&stored), Some(info.clone()));
        assert_eq!(PcWakeInfo::from_storage_str(""), None);

        // Empty wake_info (sent when pc_actions is turned off) is valid on the wire.
        let empty = PcWakeInfo::default();
        assert!(empty.is_valid());
        assert_eq!(empty.to_storage_string(), "");

        // Invalid MACs and broadcast addresses are rejected by is_valid and stripped by sanitized.
        for bad_mac in [
            "",
            "00:00:00:00:00:00",
            "ff:ff:ff:ff:ff:ff",
            "FF-FF-FF-FF-FF-FF",
            "00:00:5e:00:53",
            "00:00:5e:00:53:01:00",
            "00:00:5e:00:53:zz",
        ] {
            assert!(!PcWakeInfo { macs: vec![bad_mac.into()], broadcasts: vec![] }.is_valid(), "{bad_mac}");
        }
        for bad_ip in ["", "0.0.0.0", "127.0.0.1", "169.254.1.255", "224.0.0.251", "not-an-ip"] {
            assert!(
                !PcWakeInfo { macs: vec!["00:00:5e:00:53:01".into()], broadcasts: vec![bad_ip.into()] }
                    .is_valid(),
                "{bad_ip}"
            );
        }

        let messy = PcWakeInfo {
            macs: vec!["00-00-5E-00-53-01".into(), "00:00:5e:00:53:01".into(), "00:00:00:00:00:00".into()],
            broadcasts: vec!["192.168.1.255".into(), "192.168.1.255".into(), "127.0.0.1".into()],
        }
        .sanitized();
        assert_eq!(messy.macs, vec!["00:00:5e:00:53:01"]);
        assert_eq!(messy.broadcasts, vec!["192.168.1.255"]);
    }

    #[test]
    fn deck_layout_state_and_press_validate_sanitize_and_round_trip() {
        let layout = DeckLayout::default_layout();
        assert!(layout.is_valid());
        assert_eq!(layout.pages.len(), 1);
        assert!(layout.tile("play_pause").is_some());
        assert!(layout.tile("mic_mute").is_some());
        assert!(layout.tile("lock_pc").is_some());
        assert!(layout.tile("screenshot").is_some());
        assert!(layout.tile("show_desktop").is_some());

        // Debug output hides user labels and page names.
        let dbg = format!("{layout:?}");
        assert!(!dbg.contains("Play / pause") && !dbg.contains("Main"), "{dbg}");

        let env = Envelope::new(types::DECK_LAYOUT, &layout).unwrap();
        let back: DeckLayout = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back, layout);

        // Duplicate tile IDs across pages are invalid and deduplicated by sanitized().
        let dup_tile = layout.pages[0].tiles[0].clone();
        let with_dup = DeckLayout {
            pages: vec![
                layout.pages[0].clone(),
                DeckPage { id: "page2".into(), name: "Second".into(), tiles: vec![dup_tile] },
            ],
        };
        assert!(!with_dup.is_valid());
        let clean = with_dup.sanitized().unwrap();
        assert!(clean.is_valid());
        assert!(clean.pages[1].tiles.is_empty());

        // Unknown icon/color fall back to the action kind's default in sanitized().
        let fallback = DeckTile {
            id: "cmd1".into(),
            label: "  Build\nnow  ".into(),
            icon: "unknown_icon".into(),
            color: "unknown_color".into(),
            kind: deck_kinds::RUN_COMMAND.into(),
        }
        .sanitized()
        .unwrap();
        assert_eq!(fallback.label, "Buildnow");
        assert_eq!(fallback.icon, deck_icons::TERMINAL);
        assert_eq!(fallback.color, deck_colors::CORAL);

        // Empty pages list is rejected.
        assert!(!DeckLayout { pages: vec![] }.is_valid());
        assert_eq!(DeckLayout { pages: vec![] }.sanitized(), None);

        // Live state round-trip and status formatting.
        let state = DeckState {
            playing: true,
            volume: 72,
            muted: false,
            mic_muted: Some(true),
            output_devices: vec![
                AudioOutputDevice {
                    id: "out:speakers".into(),
                    name: "Speakers (Realtek Audio)".into(),
                    is_default: true,
                },
                AudioOutputDevice {
                    id: "out:headphones".into(),
                    name: "Headphones".into(),
                    is_default: false,
                },
            ],
        };
        assert!(state.is_valid());
        assert_eq!(state.default_output_name(), Some("Speakers (Realtek Audio)"));
        assert!(!format!("{:?}", state.output_devices[0]).contains("Realtek"));
        assert_eq!(state.tile_status(deck_kinds::MEDIA_PLAY_PAUSE).as_deref(), Some("Playing"));
        assert_eq!(state.tile_status(deck_kinds::VOLUME_UP).as_deref(), Some("72%"));
        assert_eq!(state.tile_status(deck_kinds::MIC_MUTE).as_deref(), Some("Muted"));
        assert_eq!(state.tile_status(deck_kinds::LOCK_PC), None);
        let env = Envelope::new(types::DECK_STATE, &state).unwrap();
        let back: DeckState = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back, state);

        // PC audio set validation and round-trip.
        let audio_set = PcAudioSet { volume: Some(65), muted: Some(false) };
        assert!(audio_set.is_valid());
        let env = Envelope::new(types::PC_AUDIO_SET, &audio_set).unwrap();
        assert_eq!(Envelope::from_cbor(&env.to_cbor()).unwrap().body::<PcAudioSet>().unwrap(), audio_set);
        assert!(!PcAudioSet { volume: None, muted: None }.is_valid());
        assert!(!PcAudioSet { volume: Some(101), muted: None }.is_valid());

        // Press validation.
        let press = DeckPress { tile: "play_pause".into() };
        assert!(press.is_valid());
        let env = Envelope::new(types::DECK_PRESS, &press).unwrap();
        assert_eq!(Envelope::from_cbor(&env.to_cbor()).unwrap().body::<DeckPress>().unwrap(), press);
        assert!(!DeckPress { tile: String::new() }.is_valid());
        assert!(!DeckPress { tile: "bad tile!".into() }.is_valid());
    }

    #[test]
    fn storage_paths_and_messages_validate_and_round_trip() {
        assert!(is_valid_storage_dir_path(""));
        assert!(!is_valid_storage_path(""));
        for good in ["DCIM", "DCIM/Camera/IMG_001.jpg", "Download/Report (2026) ✓.pdf", ".hidden/file.txt"]
        {
            assert!(is_valid_storage_path(good), "{good}");
            assert!(is_valid_storage_dir_path(good), "{good}");
        }
        for bad in [
            "/",
            "/DCIM",
            "DCIM/",
            "DCIM//Camera",
            ".",
            "..",
            "../etc/passwd",
            "DCIM/../secret",
            "DCIM/.",
            "DCIM\\Camera",
            "C:\\Windows",
            "bad\0name",
            "bad\nname",
        ] {
            assert!(!is_valid_storage_path(bad), "{bad}");
            assert!(!is_valid_storage_dir_path(bad), "{bad}");
        }
        let deep = vec!["a"; storage::MAX_SEGMENTS + 1].join("/");
        assert!(!is_valid_storage_path(&deep));
        let long_seg = "x".repeat(storage::MAX_NAME_BYTES + 1);
        assert!(!is_valid_storage_path(&long_seg));

        let entry = StorageEntry {
            name: "photo.jpg".into(),
            size: 123_456,
            modified: 1_750_000_000_000,
            is_dir: false,
        };
        assert!(entry.is_valid());
        assert!(!format!("{entry:?}").contains("photo.jpg"));
        let dir_entry =
            StorageEntry { name: "DCIM".into(), size: 999, modified: -5, is_dir: true }.sanitized().unwrap();
        assert_eq!(dir_entry.size, 0);
        assert_eq!(dir_entry.modified, 0);

        let entries = StorageEntries { entries: vec![entry, dir_entry], more: false };
        let env = Envelope::new(types::STORAGE_ENTRIES, &entries).unwrap();
        let back: StorageEntries = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back, entries);

        let read = StorageRead { path: "DCIM/photo.jpg".into(), offset: 4096, length: Some(65536) };
        assert!(read.is_valid());
        assert!(!format!("{read:?}").contains("photo.jpg"));
        let env = Envelope::new(types::STORAGE_READ, &read).unwrap();
        assert_eq!(Envelope::from_cbor(&env.to_cbor()).unwrap().body::<StorageRead>().unwrap(), read);

        let write = StorageWriteOffer {
            id: "up-1".into(),
            path: "Download/notes.txt".into(),
            size: 512,
            modified: Some(1_750_000_000_000),
        };
        assert!(write.is_valid());
        assert!(!format!("{write:?}").contains("notes.txt"));
        let env = Envelope::new(types::STORAGE_WRITE, &write).unwrap();
        assert_eq!(Envelope::from_cbor(&env.to_cbor()).unwrap().body::<StorageWriteOffer>().unwrap(), write);

        let rename = StorageRename { from: "a.txt".into(), to: "b.txt".into() };
        assert!(rename.is_valid());
        assert!(!StorageRename { from: "a.txt".into(), to: "a.txt".into() }.is_valid());
    }

    #[test]
    fn play_on_phone_messages_validate() {
        let offer = MediaWatch { player: "Chrome".into(), title: Some("A video".into()), file: None };
        assert!(offer.is_valid());
        assert!(!MediaWatch { player: String::new(), title: None, file: None }.is_valid());
        assert!(!MediaWatch { player: "p".repeat(257), title: None, file: None }.is_valid());
        assert!(!MediaWatch { player: "Chrome".into(), title: Some("t".repeat(257)), file: None }.is_valid());

        // A file offer: a plain name and a size; it goes over the wire as is.
        let file = WatchFile { name: "Holiday.mp4".into(), size: 1_000, position: 61_500 };
        let with_file = MediaWatch { player: "vlc.exe".into(), title: None, file: Some(file.clone()) };
        assert!(with_file.is_valid());
        let env = Envelope::new(types::MEDIA_WATCH, &with_file).unwrap();
        assert_eq!(Envelope::from_cbor(&env.to_cbor()).unwrap().body::<MediaWatch>().unwrap(), with_file);
        for bad in [
            WatchFile { name: String::new(), ..file.clone() },
            WatchFile { name: "a/b.mp4".into(), ..file.clone() },
            WatchFile { name: "a\\b.mp4".into(), ..file.clone() },
            WatchFile { size: 0, ..file.clone() },
        ] {
            assert!(!MediaWatch { file: Some(bad.clone()), ..with_file.clone() }.is_valid(), "{bad:?}");
        }

        let screen = MirrorStart {
            max_size: 1280,
            fps: 30,
            bitrate: 4_000_000,
            audio: true,
            session: mirror::SCREEN,
            app: None,
            stay_awake: false,
            screen_off: false,
            watch: Some("Chrome".into()),
            sound_only: false,
        };
        assert!(screen.is_valid());
        // Watching is of the PC's screen session only, never with an app.
        assert!(!MirrorStart { session: 3, ..screen.clone() }.is_valid());
        assert!(
            !MirrorStart { session: 3, app: Some("com.example.app".into()), ..screen.clone() }.is_valid()
        );
        assert!(!MirrorStart { watch: Some(String::new()), ..screen.clone() }.is_valid());
        // Older PCs and phones leave it out.
        let plain = MirrorStart { watch: None, ..screen };
        let mut bytes = Vec::new();
        ciborium::into_writer(&plain, &mut bytes).unwrap();
        let back: MirrorStart = ciborium::from_reader(bytes.as_slice()).unwrap();
        assert_eq!(back, plain);
    }

    #[test]
    fn webcam_messages_validate_and_round_trip() {
        let start = WebcamStart::default();
        assert!(start.is_valid());
        let env = Envelope::new(types::WEBCAM_START, &start).unwrap();
        let back: WebcamStart = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back, start);

        let front_1080 = WebcamStart {
            camera: webcam::CAMERA_FRONT.into(),
            width: 1920,
            height: 1080,
            fps: 30,
            bitrate: 8_000_000,
        };
        assert!(front_1080.is_valid());
        assert!(!WebcamStart { camera: "telephoto".into(), ..start.clone() }.is_valid());
        assert!(!WebcamStart { width: 100, ..start.clone() }.is_valid());
        assert!(!WebcamStart { fps: 0, ..start }.is_valid());

        let cfg = WebcamConfig {
            codec: webcam::H264.into(),
            width: 1280,
            height: 720,
            camera: webcam::CAMERA_BACK.into(),
            fps: 30,
            max_height: 1080,
        };
        assert!(cfg.is_valid());
        assert_eq!(WebcamConfig::from_cbor(&cfg.to_cbor()).unwrap(), cfg);
        let hevc = WebcamConfig { codec: webcam::H265.into(), ..cfg.clone() };
        assert!(hevc.is_valid());
        assert_eq!(WebcamConfig::from_cbor(&hevc.to_cbor()).unwrap(), hevc);
        assert!(!WebcamConfig { codec: "vp8".into(), ..cfg.clone() }.is_valid());
        assert!(!WebcamConfig { width: 0, ..cfg }.is_valid());

        // A phone before 0.1.5 doesn't say what its camera can do: 4K stays offered.
        #[derive(Serialize)]
        struct Before {
            codec: &'static str,
            width: u32,
            height: u32,
            camera: &'static str,
            fps: u32,
        }
        let mut old = Vec::new();
        let before =
            Before { codec: webcam::H264, width: 1920, height: 1080, camera: webcam::CAMERA_FRONT, fps: 30 };
        ciborium::into_writer(&before, &mut old).unwrap();
        assert_eq!(WebcamConfig::from_cbor(&old).unwrap().max_height, 2160);
    }

    #[test]
    fn live_notification_round_trips_and_sanitizes() {
        let live = NotificationLive {
            v: 1,
            progress: Some(72),
            max: Some(100),
            indeterminate: false,
            chip: Some("4 min".into()),
            segments: vec![
                LiveSegment { length: 50, color: Some(0xFF4C_AF50) },
                LiveSegment { length: 50, color: None },
            ],
            points: vec![LivePoint { position: 50, color: Some(0xFFFF_C107) }],
            chronometer: true,
            countdown: true,
        };
        let mut n = notification();
        n.live = Some(live.clone());
        assert!(!format!("{live:?}").contains("4 min"));
        let env = Envelope::new(types::NOTIFY_POSTED, &n).unwrap();
        let back: Notification = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back.sanitized(), Some(n));

        // Unknown schema version or empty live metadata drops cleanly.
        assert!(NotificationLive { v: 2, ..live.clone() }.sanitized().is_none());
        assert!(NotificationLive::default().sanitized().is_none());

        // Indeterminate clears determinate progress/max; progress > max clamps to max.
        let ind = NotificationLive {
            v: 1,
            progress: Some(40),
            max: Some(100),
            indeterminate: true,
            ..Default::default()
        }
        .sanitized()
        .unwrap();
        assert_eq!(ind.progress, None);
        assert_eq!(ind.max, None);
        assert!(ind.indeterminate);

        let clamped = NotificationLive {
            v: 1,
            progress: Some(150),
            max: Some(100),
            chip: Some("  Arriving\nsoon  ".into()),
            segments: vec![LiveSegment { length: 0, color: None }, LiveSegment { length: 100, color: None }],
            countdown: true,
            chronometer: false,
            ..Default::default()
        }
        .sanitized()
        .unwrap();
        assert_eq!(clamped.progress, Some(100));
        assert_eq!(clamped.chip.as_deref(), Some("Arrivingsoon"));
        assert_eq!(clamped.segments, vec![LiveSegment { length: 100, color: None }]);
        assert!(!clamped.countdown);
    }

    #[test]
    fn task_notify_validates_round_trips_and_formats_duration() {
        let running = TaskNotify {
            id: "task-1234".into(),
            title: "cargo build --release".into(),
            active: true,
            elapsed_ms: 38_400,
            exit_code: None,
        };
        assert!(running.is_valid());
        assert!(!format!("{running:?}").contains("cargo build"));
        let env = Envelope::new(types::TASK_NOTIFY, &running).unwrap();
        let back: TaskNotify = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back, running);

        let done = TaskNotify {
            id: "task-1234".into(),
            title: "cargo build --release".into(),
            active: false,
            elapsed_ms: 252_000,
            exit_code: Some(0),
        };
        assert!(done.is_valid());
        assert_eq!(done.clone().sanitized(), Some(done));

        // Active tasks cannot carry an exit code.
        let dirty = TaskNotify { exit_code: Some(1), ..running.clone() };
        assert!(!dirty.is_valid());
        assert_eq!(dirty.sanitized().unwrap().exit_code, None);

        // Blank title or invalid ID is rejected.
        assert!(!TaskNotify { id: "".into(), ..running.clone() }.is_valid());
        assert!(!TaskNotify { title: "   ".into(), ..running }.is_valid());

        assert_eq!(TaskNotify::format_took(38_000), "Took 38s");
        assert_eq!(TaskNotify::format_took(252_000), "Took 4m 12s");
        assert_eq!(TaskNotify::format_took(3_840_000), "Took 1h 04m");
    }

    #[test]
    fn continuity_camera_messages_round_trip() {
        let req = CameraCaptureRequest { request_id: "req-1".into(), mode: CameraCaptureMode::Scan };
        let env = Envelope::new(types::CAMERA_CAPTURE_REQUEST, &req).unwrap();
        let back: CameraCaptureRequest = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back, req);

        let ok = CameraCaptureOk { request_id: "req-1".into() };
        let env_ok = Envelope::new(types::CAMERA_CAPTURE_OK, &ok).unwrap();
        let back_ok: CameraCaptureOk = Envelope::from_cbor(&env_ok.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back_ok, ok);

        let cancel =
            CameraCaptureCancel { request_id: "req-1".into(), reason: Some("user dismissed".into()) };
        let env_cancel = Envelope::new(types::CAMERA_CAPTURE_CANCEL, &cancel).unwrap();
        let back_cancel: CameraCaptureCancel =
            Envelope::from_cbor(&env_cancel.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back_cancel, cancel);

        let meta = CameraCaptureResultMeta {
            request_id: "req-1".into(),
            mode: CameraCaptureMode::Photo,
            file_name: "IMG_20260409.jpg".into(),
            mime: "image/jpeg".into(),
            size: 12345,
            width: 1920,
            height: 1080,
        };
        let env_meta = Envelope::new(continuity_camera::RESULT_META, &meta).unwrap();
        let back_meta: CameraCaptureResultMeta =
            Envelope::from_cbor(&env_meta.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back_meta, meta);
    }

    #[test]
    fn clip_set_rich_text_validates_and_round_trips() {
        let plain = ClipSet { text: "Hello".into(), html: None, rtf: None };
        assert!(plain.is_valid());
        let env_plain = Envelope::new(types::CLIP_SET, &plain).unwrap();
        assert!(!format!("{:?}", env_plain.b).contains("html"));
        assert!(!format!("{:?}", env_plain.b).contains("rtf"));
        let back_plain: ClipSet = Envelope::from_cbor(&env_plain.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back_plain, plain);

        let rich = ClipSet {
            text: "Hello world".into(),
            html: Some("<b>Hello</b> world".into()),
            rtf: Some(r"{\rtf1\ansi\b Hello\b0  world}".into()),
        };
        assert!(rich.is_valid());
        assert!(!format!("{rich:?}").contains("Hello"));
        let env_rich = Envelope::new(types::CLIP_SET, &rich).unwrap();
        let back_rich: ClipSet = Envelope::from_cbor(&env_rich.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back_rich, rich);

        let oversized =
            ClipSet { text: "a".repeat(CLIP_MAX_BYTES), html: Some("<b>a</b>".into()), rtf: None };
        assert!(!oversized.is_valid());
    }

    #[test]
    fn mirror_input_gamepad_round_trips_and_validates() {
        let gp = MirrorInput::Gamepad {
            buttons: 0x1001,
            lx: -12345,
            ly: 23456,
            rx: 0,
            ry: -32768,
            lt: 128,
            rt: 255,
        };
        assert!(gp.is_valid());
        assert_eq!(format!("{gp:?}"), "Gamepad(0x1001)");
        let env = mirror_input_envelope(&gp, mirror::SCREEN).unwrap();
        let back: MirrorInput = Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back, gp);

        let env_app = mirror_input_envelope(&gp, 2).unwrap();
        let back_app: MirrorInput = Envelope::from_cbor(&env_app.to_cbor()).unwrap().body().unwrap();
        assert_eq!(back_app, gp);
    }

    #[test]
    fn fuzz_all_message_bodies_cbor_and_json_10k() {
        fn next_u64(seed: &mut u64) -> u64 {
            *seed ^= *seed << 13;
            *seed ^= *seed >> 7;
            *seed ^= *seed << 17;
            *seed
        }

        let mut seed = 0x9E37_79B9_7F4A_7C15u64;
        let mut buf = Vec::with_capacity(256);
        for i in 0..10_000usize {
            let len = (next_u64(&mut seed) as usize) % 192;
            buf.clear();
            for _ in 0..len {
                buf.push((next_u64(&mut seed) & 0xFF) as u8);
            }
            // Also mix in structured CBOR map prefixes so deeper serde paths run.
            if i % 2 == 1 && !buf.is_empty() {
                buf[0] = 0xA0 | ((buf[0] & 0x0F).min(8));
            }

            if let Ok(env) = Envelope::from_cbor(&buf) {
                let _ = format!("{env:?}");
                let _ = env.body::<Hello>().map(|m| format!("{m:?}"));
                let _ = env.body::<HelloUpdate>().map(|m| format!("{m:?}"));
                let _ = env.body::<DeviceInfo>().map(|m| m.sanitized());
                let _ = env.body::<ScreenShape>().map(|m| m.sanitized());
                let _ = env.body::<Battery>().map(|m| m.sanitized());
                let _ = env.body::<Notification>().map(|m| m.sanitized());
                let _ = env.body::<NotificationLive>().map(|m| m.sanitized());
                let _ = env.body::<ClipSet>().map(|m| (m.is_valid(), format!("{m:?}")));
                let _ = env.body::<MirrorInput>().map(|m| (m.is_valid(), format!("{m:?}")));
                let _ = env.body::<TaskNotify>().map(|m| (m.is_valid(), m.sanitized()));
            }

            // Directly fuzz CBOR deserialization across message body types.
            macro_rules! try_decode {
                ($($ty:ty),+ $(,)?) => {{
                    $(
                        if let Ok(v) = ciborium::from_reader::<$ty, _>(buf.as_slice()) {
                            let _ = format!("{v:?}");
                        }
                    )+
                }};
            }

            match i % 6 {
                0 => try_decode!(Hello, HelloUpdate, DeviceInfo, ScreenShape, Ping, Battery, Ring, ErrorBody),
                1 => try_decode!(StreamHeader, PairRequest, PairAccept, PairCommit, PairNonce, PairReveal),
                2 => try_decode!(
                    Notification,
                    NotificationLive,
                    NotifySnapshot,
                    NotifyKey,
                    NotifyAction,
                    ClipSet
                ),
                3 => try_decode!(MediaPlayer, MediaState, MediaCommand, PcPower, PcWakeInfo),
                4 => try_decode!(
                    MirrorStart,
                    MirrorPower,
                    MirrorSession,
                    MirrorResize,
                    PhoneApp,
                    PhoneApps,
                    MirrorInput
                ),
                _ => try_decode!(
                    MirrorConfig,
                    MirrorAudioConfig,
                    WebcamStart,
                    WebcamConfig,
                    CallState,
                    CallAction,
                    CallLog,
                    CallDial,
                    CallSims,
                    SmsThreads,
                    SmsMessages,
                    SmsSend,
                    ContactsListGet,
                    ContactsList,
                    PhotoNew,
                    PhotoAlbumsList,
                    PhotoListGet,
                    PhotoItems,
                    PhotoThumbsGet,
                    PhotoThumbsList,
                    PhotoGet,
                    LinkOpen,
                    TaskNotify,
                    CameraCaptureRequest,
                    CameraCaptureOk,
                    CameraCaptureCancel,
                    CameraCaptureResultMeta,
                ),
            }
        }
    }

    #[test]
    fn fuzz_screen_shape_decode_and_sanitize_10k() {
        fn next_u64(seed: &mut u64) -> u64 {
            *seed ^= *seed << 13;
            *seed ^= *seed >> 7;
            *seed ^= *seed << 17;
            *seed
        }
        fn next_f32(seed: &mut u64) -> f32 {
            let r = next_u64(seed);
            match r % 10 {
                0 => f32::from_bits(r as u32), // includes NaN, Inf, subnormals
                1 => 0.0,
                2 => -0.0,
                3 => 1.0,
                4 => -1.0,
                5 => ((r >> 8) as f32) / ((u64::MAX >> 8) as f32), // 0.0..=1.0
                6 => (((r >> 8) as f32) / ((u64::MAX >> 8) as f32)) * 6.0 - 0.5, // -0.5..=5.5
                _ => f32::from_bits((r >> 32) as u32),
            }
        }

        let mut seed = 0xD1B5_4A32_D192_ED03u64;
        for i in 0..10_000usize {
            let v = if i % 5 == 0 { (next_u64(&mut seed) % 4) as u32 } else { screen_limits::VERSION };
            let aspect = next_f32(&mut seed);
            let corners = (next_u64(&mut seed) & 1 == 0).then(|| ScreenCorners {
                tl: next_f32(&mut seed),
                tr: next_f32(&mut seed),
                br: next_f32(&mut seed),
                bl: next_f32(&mut seed),
            });
            let cutout_count = (next_u64(&mut seed) % 8) as usize;
            let mut cutouts = Vec::with_capacity(cutout_count);
            for _ in 0..cutout_count {
                cutouts.push(ScreenRect {
                    x: next_f32(&mut seed),
                    y: next_f32(&mut seed),
                    w: next_f32(&mut seed),
                    h: next_f32(&mut seed),
                });
            }
            let cutout_path = match i % 4 {
                0 => None,
                1 => Some("M 0.45 0.01 L 0.55 0.01 Z".to_owned()),
                2 => Some(format!("M {} {} L <script>", next_f32(&mut seed), next_f32(&mut seed))),
                _ => {
                    let len = (next_u64(&mut seed) as usize) % 600;
                    let s: String = (0..len)
                        .map(|_| {
                            let b = (next_u64(&mut seed) & 0x7F) as u8;
                            b as char
                        })
                        .collect();
                    Some(s)
                }
            };

            let shape = ScreenShape { v, aspect, corners, cutouts, cutout_path };
            if let Some(clean) = shape.sanitized() {
                assert_eq!(clean.v, screen_limits::VERSION);
                assert!(clean.aspect.is_finite());
                assert!((screen_limits::MIN_ASPECT..=screen_limits::MAX_ASPECT).contains(&clean.aspect));
                if let Some(c) = clean.corners {
                    for r in [c.tl, c.tr, c.br, c.bl] {
                        assert!(r.is_finite() && (0.0..=screen_limits::MAX_CORNER_RADIUS).contains(&r));
                    }
                }
                assert!(clean.cutouts.len() <= screen_limits::MAX_CUTOUTS);
                for rect in &clean.cutouts {
                    assert!(rect.x.is_finite() && (0.0..=1.0).contains(&rect.x));
                    assert!(rect.y.is_finite() && (0.0..=1.0).contains(&rect.y));
                    assert!(rect.w.is_finite() && rect.w > 0.0 && rect.x + rect.w <= 1.0002);
                    assert!(rect.h.is_finite() && rect.h > 0.0 && rect.y + rect.h <= 1.0002);
                }
                if let Some(ref path) = clean.cutout_path {
                    assert!(!path.is_empty() && path.len() <= screen_limits::MAX_CUTOUT_PATH_BYTES);
                }
                // Idempotence and CBOR round-trip of sanitized ScreenShape.
                let again = clean.clone().sanitized().expect("sanitized shape stays valid");
                assert_eq!(clean, again);
                let mut cbor = Vec::new();
                ciborium::into_writer(&clean, &mut cbor).unwrap();
                let from_cbor: ScreenShape = ciborium::from_reader(cbor.as_slice()).unwrap();
                assert_eq!(from_cbor.sanitized().unwrap(), clean);
            }
        }
    }

    #[test]
    fn wake_relay_and_audio_pcm_cbor_roundtrip() {
        let req =
            WakeRelay { mac: [0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff], broadcast: Some("192.168.1.255".into()) };
        let env = crate::Envelope::new(types::WAKE_RELAY, &req).unwrap();
        let decoded: WakeRelay = crate::Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(decoded, req);

        let frame = AudioPcmFrame { sample_rate: 48_000, channels: 2, pcm: vec![0x01, 0x02, 0x03, 0x04] };
        let env = crate::Envelope::new(types::AUDIO_PCM, &frame).unwrap();
        let decoded: AudioPcmFrame = crate::Envelope::from_cbor(&env.to_cbor()).unwrap().body().unwrap();
        assert_eq!(decoded, frame);
    }
}