Initial commit: pure-Rust cross-platform Insta360 Link controller suite

2026-10-19 17:08:35 -04:00
commit f468c15262
@@ -0,0 +1,18 @@
+[package]
+name = "insta360-link-cli"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+description = "Cross-platform CLI controller for Insta360 Link, Link 2, and Link 2C cameras"
+
+[[bin]]
+name = "insta360-link-ctl"
+path = "src/main.rs"
+
+[dependencies]
+insta360-link-protocol = { path = "../insta360-link-protocol" }
+clap.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+tracing.workspace = true
+tracing-subscriber.workspace = true
@@ -0,0 +1,20 @@
+[package]
+name = "insta360-link-gui"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+description = "Cross-platform pure-Rust desktop GUI controller for Insta360 Link, Link 2, and Link 2C"
+
+[[bin]]
+name = "insta360-link-gui"
+path = "src/main.rs"
+
+[dependencies]
+insta360-link-protocol = { path = "../insta360-link-protocol" }
+eframe.workspace = true
+egui.workspace = true
+image = { version = "0.25", default-features = false, features = ["png"] }
+serde.workspace = true
+serde_json.workspace = true
+tracing.workspace = true
+tracing-subscriber.workspace = true
@@ -0,0 +1,500 @@
+#![allow(dead_code)]
+
+use egui::{ColorImage, Pos2, TextureHandle};
+pub use insta360_link_protocol::*;
+use std::path::PathBuf;
+use std::time::Instant;
+
+/// UI mode matching `Webcam.Controller.curUIMode` (`MainWindow` vs `Toolbar`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum UiMode {
+    MainWindow,
+    Toolbar,
+}
+
+/// Right sidebar tab matching `Settings.qml` (`View`, `Effects`, `More`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RightSidebarTab {
+    View,
+    Effects,
+    More,
+}
+
+/// Active popup in Compact Toolbar Mode (`Toolbar.qml`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ToolbarPopup {
+    None,
+    PtzPanel,
+    TrackMode,
+    VirtualBackground,
+    PictureSetting,
+    GestureCtrl,
+    RemoteCtrl,
+    MoreSetting,
+}
+
+/// Active tab in the Preferences modal (`preference/MoreSettings.qml`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PreferenceTab {
+    General,
+    Hotkeys,
+    About,
+    GetLog,
+}
+
+/// Virtual background mode (`ImageBackground.qml`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BackgroundEffectMode {
+    None,
+    StandardBlur,
+    NaturalBokeh,
+    CustomImage(usize),
+}
+
+/// Resolution & frame rate preset (`DefFormatCombo.qml`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum VideoFormatPreset {
+    Uhd4k30,
+    Fhd1080p60,
+    Fhd1080p30,
+    Hd720p60,
+    Hd720p30,
+    Sd360p30,
+    Vertical1080x1920p30,
+}
+
+impl VideoFormatPreset {
+    pub const ALL: [VideoFormatPreset; 7] = [
+        Self::Uhd4k30,
+        Self::Fhd1080p60,
+        Self::Fhd1080p30,
+        Self::Hd720p60,
+        Self::Hd720p30,
+        Self::Sd360p30,
+        Self::Vertical1080x1920p30,
+    ];
+
+    pub fn label(&self) -> &'static str {
+        match self {
+            Self::Uhd4k30 => "4K 30fps",
+            Self::Fhd1080p60 => "1080p 60fps",
+            Self::Fhd1080p30 => "1080p 30fps",
+            Self::Hd720p60 => "720p 60fps",
+            Self::Hd720p30 => "720p 30fps",
+            Self::Sd360p30 => "360p 30fps",
+            Self::Vertical1080x1920p30 => "1080x1920 30fps",
+        }
+    }
+
+    pub fn dimensions(&self) -> (u32, u32) {
+        match self {
+            Self::Uhd4k30 => (3840, 2160),
+            Self::Fhd1080p60 | Self::Fhd1080p30 => (1920, 1080),
+            Self::Hd720p60 | Self::Hd720p30 => (1280, 720),
+            Self::Sd360p30 => (640, 360),
+            Self::Vertical1080x1920p30 => (1088, 1920),
+        }
+    }
+
+    pub fn fps(&self) -> u32 {
+        match self {
+            Self::Fhd1080p60 | Self::Hd720p60 => 60,
+            _ => 30,
+        }
+    }
+
+    pub fn is_4k(&self) -> bool {
+        matches!(self, Self::Uhd4k30)
+    }
+
+    pub fn is_vertical(&self) -> bool {
+        matches!(self, Self::Vertical1080x1920p30)
+    }
+}
+
+/// Saved PTZ preset item (`PTZControl.qml` repeater item).
+#[derive(Clone)]
+pub struct PtzPresetSlot {
+    pub id: u8,
+    pub name: String,
+    pub saved: bool,
+    pub pan_deg: f32,
+    pub tilt_deg: f32,
+    pub zoom_x: f32,
+    pub host_x: f32,
+    pub host_y: f32,
+    pub mode: VideoMode,
+    pub thumbnail: Option<TextureHandle>,
+    pub raw_thumb: Option<ColorImage>,
+    pub renaming: bool,
+}
+
+/// Saved Color Preset item (`ImageScreen.qml` template repeater item).
+#[derive(Clone)]
+pub struct ColorPresetSlot {
+    pub id: i8,
+    pub name: String,
+    pub saved: bool,
+    pub brightness: i16,
+    pub contrast: u16,
+    pub saturation: u16,
+    pub sharpness: u16,
+    pub wb_auto: bool,
+    pub wb_kelvin: u16,
+    pub auto_exposure: bool,
+    pub ev_comp: f32,
+    pub iso: u16,
+    pub shutter: u32,
+    pub hdr: bool,
+    pub thumbnail: Option<TextureHandle>,
+    pub raw_thumb: Option<ColorImage>,
+    pub renaming: bool,
+}
+
+/// ISO discrete step values matching `Webcam.Controller.camera.isoList` (`ImageScreen.qml`).
+pub const ISO_LIST: [u16; 16] = [
+    100, 125, 160, 200, 250, 320, 400, 500, 640, 800, 1000, 1250, 1600, 2000, 2500, 3200,
+];
+
+/// Shutter speed denominator list (`1/N` seconds) matching `Webcam.Controller.camera.shutterList`.
+pub const SHUTTER_DENOM_LIST: [u32; 20] = [
+    30, 40, 50, 60, 80, 100, 120, 160, 200, 240, 320, 400, 500, 640, 800, 1000, 1600, 2000, 4000,
+    8000,
+];
+
+/// Shared UI & camera state used across `main.rs`, `right_panel.rs`, and `video_engine.rs`.
+pub struct CameraAppState {
+    // Theme & window mode
+    pub is_light_mode: bool,
+    pub ui_mode: UiMode,
+    pub right_tab: RightSidebarTab,
+    pub toolbar_popup: ToolbarPopup,
+    pub show_preferences: bool,
+    pub preference_tab: PreferenceTab,
+    pub show_qr_dialog: bool,
+    pub show_virtual_cam_pop: bool,
+    pub show_camera_log_pop: bool,
+    pub show_factory_reset_pop: bool,
+    pub show_pause_track_overlay: bool,
+    pub show_deskview_pitch_pop: bool,
+
+    // Preview & recording state
+    pub preview_open: bool,
+    pub virtual_camera_enabled: bool,
+    pub format_preset: VideoFormatPreset,
+    pub is_recording: bool,
+    pub recording_started: Option<Instant>,
+    pub screenshot_dir: PathBuf,
+    pub recording_dir: PathBuf,
+    pub toast_message: Option<(String, Instant, bool)>,
+
+    // Device Info & Status
+    pub device_info: DeviceInfo,
+    pub ptz_info: PtzVersionInfo,
+    pub device_status: DeviceStatus,
+
+    // Gimbal / View / PTZ state
+    pub pan_deg: f32,
+    pub tilt_deg: f32,
+    pub zoom_x: f32,        // 1.0 .. 4.0
+    pub roll_deg: f32,      // -1.0 .. +1.0 (tenths of degree in hardware)
+    pub deskview_pitch: i16, // -900 .. 0
+    pub host_ptz_x: f32,    // 0.0 .. 1.0 normalized center X (Link 2C)
+    pub host_ptz_y: f32,    // 0.0 .. 1.0 normalized center Y (Link 2C)
+    pub bias_x: i16,
+    pub bias_y: i16,
+    pub ptz_presets: Vec<PtzPresetSlot>,
+    pub active_preset_id: Option<u8>,
+    pub open_more_positions: bool,
+
+    // Video Mode & Tracking state
+    pub video_mode: VideoMode,
+    pub default_track_mode: u8, // 0 = Single Tracking, 1 = Group Tracking (Link 2)
+    pub ai_zoom_enabled: bool,  // Smart Composition switch
+    pub composition_style: CompositionStyle,
+    pub track_speed: TrackSpeed,
+    pub enable_auto_tracking: bool,
+    pub enable_single_tap_tracking: bool,
+    pub pause_track_enabled: bool,
+    pub forbidden_areas: [ForbiddenAreaInfo; 4],
+    pub tracked_targets: Vec<UvcRect>,
+    pub selected_target_id: i16,
+    pub whiteboard_corners: [Pos2; 4], // normalized [0..1] corners for Smart Whiteboard
+
+    // Color & Exposure state (`ImageScreen.qml`)
+    pub auto_exposure: bool,
+    pub ev_compensation: f32, // -3.0 .. +3.0
+    pub iso_index: usize,     // index into ISO_LIST
+    pub shutter_index: usize, // index into SHUTTER_DENOM_LIST
+    pub spline_points: Vec<(f32, f32)>, // normalized (0..1, 0..1) control points for DefSplineCanvas
+    pub auto_focus: bool,
+    pub manual_focus: u16, // 0..100
+    pub auto_white_balance: bool,
+    pub wb_kelvin: u16,       // 2000..10000
+    pub open_more_color: bool, // Show/Collapse in Color section
+    pub brightness: i16,      // 0..100
+    pub contrast: u16,        // 0..100
+    pub saturation: u16,      // 0..100
+    pub sharpness: u16,       // 0..100
+    pub hdr_enabled: bool,
+    pub anti_flicker: PowerLineFrequency,
+    pub startup_params_enabled: bool,
+    pub color_presets: Vec<ColorPresetSlot>,
+    pub active_color_preset_id: Option<i8>,
+    pub open_more_color_presets: bool,
+
+    // Background, Makeup & Filter state (`ImageBackground.qml`, `ImageBeauty.qml`, `ImageFilter.qml`)
+    pub background_mode: BackgroundEffectMode,
+    pub blur_intensity: u8, // 0..100
+    pub custom_backgrounds: Vec<String>,
+    pub makeup_enabled: bool,
+    pub makeup_intensity: u8, // 0..100
+    pub filter_dropdown_open: bool,
+    pub filter_mode: FilterMode,
+
+    // More Tab state (`MoreSettings.qml`)
+    pub enable_all_gestures: bool,
+    pub use_gesture_palm: bool,
+    pub use_gesture_v: bool,
+    pub use_gesture_l: bool,
+    pub use_gesture_rock: bool,
+    pub use_gesture_ok: bool,
+    pub audio_capture_mode: AudioCaptureMode,
+    pub audio_denoise: bool,
+    pub horizontal_mirror: bool,
+    pub vertical_mirror: bool,
+    pub smart_adjustment: bool,
+    pub horizontal_correction: bool,
+    pub ultimate_privacy: bool,
+    pub privacy_sleep: bool,
+    pub vertical_resolution_mode: bool,
+    pub forced_vertical_lock: bool,
+    pub low_resolution_mode: bool,
+
+    // Real-time hardware sync, continuous PTZ velocity, and AI target polling
+    pub stream_initialized: bool,
+    pub joystick_dragging: bool,
+    pub last_ptz_cmd: (u8, i8, u8, i8),
+    pub last_ptz_send_time: Option<Instant>,
+    pub nudge_stop_at: Option<Instant>,
+    pub pending_ptz_restore: Option<(Instant, i32, i32)>,
+    pub ready_auto_track: bool,
+    pub last_track_poll: Option<Instant>,
+    pub last_hw_sync: Option<Instant>,
+}
+
+impl Default for CameraAppState {
+    fn default() -> Self {
+        let mut ptz_presets = Vec::with_capacity(6);
+        for i in 0..6u8 {
+            ptz_presets.push(PtzPresetSlot {
+                id: i,
+                name: format!("Preset {}", i + 1),
+                saved: i < 2,
+                pan_deg: if i == 0 { 0.0 } else { 22.0 },
+                tilt_deg: if i == 0 { 0.0 } else { -8.0 },
+                zoom_x: if i == 0 { 1.0 } else { 1.5 },
+                host_x: 0.5,
+                host_y: 0.5,
+                mode: VideoMode::Normal,
+                thumbnail: None,
+                raw_thumb: None,
+                renaming: false,
+            });
+        }
+
+        let color_presets = vec![ColorPresetSlot {
+            id: 1,
+            name: "Studio Warm".to_string(),
+            saved: true,
+            brightness: 54,
+            contrast: 52,
+            saturation: 56,
+            sharpness: 50,
+            wb_auto: false,
+            wb_kelvin: 5600,
+            auto_exposure: true,
+            ev_comp: 0.3,
+            iso: 100,
+            shutter: 120,
+            hdr: false,
+            thumbnail: None,
+            raw_thumb: None,
+            renaming: false,
+        }];
+
+        let home = std::env::var("HOME")
+            .or_else(|_| std::env::var("USERPROFILE"))
+            .map(PathBuf::from)
+            .unwrap_or_else(|_| PathBuf::from("."));
+
+        Self {
+            is_light_mode: false,
+            ui_mode: UiMode::MainWindow,
+            right_tab: RightSidebarTab::View,
+            toolbar_popup: ToolbarPopup::None,
+            show_preferences: false,
+            preference_tab: PreferenceTab::General,
+            show_qr_dialog: false,
+            show_virtual_cam_pop: false,
+            show_camera_log_pop: false,
+            show_factory_reset_pop: false,
+            show_pause_track_overlay: false,
+            show_deskview_pitch_pop: false,
+
+            preview_open: true,
+            virtual_camera_enabled: false,
+            format_preset: VideoFormatPreset::Fhd1080p30,
+            is_recording: false,
+            recording_started: None,
+            screenshot_dir: home.join("Pictures"),
+            recording_dir: home.join("Movies"),
+            toast_message: None,
+
+            device_info: DeviceInfo {
+                device_name: "Insta360 Link 2".to_string(),
+                firmware_version: "v2.5.8.8_build1".to_string(),
+                serial_number: "INSTA360SIM0001".to_string(),
+            },
+            ptz_info: PtzVersionInfo {
+                version: "v1.3.1.0_build0".to_string(),
+                pan: 0,
+                tilt: 0,
+                zoom: 100,
+                status: 0,
+            },
+            device_status: DeviceStatus::empty(),
+
+            pan_deg: 0.0,
+            tilt_deg: 0.0,
+            zoom_x: 1.0,
+            roll_deg: 0.0,
+            deskview_pitch: 0,
+            host_ptz_x: 0.5,
+            host_ptz_y: 0.5,
+            bias_x: 0,
+            bias_y: 0,
+            ptz_presets,
+            active_preset_id: Some(0),
+            open_more_positions: false,
+
+            video_mode: VideoMode::Normal,
+            default_track_mode: 0,
+            ai_zoom_enabled: true,
+            composition_style: CompositionStyle::HalfBody,
+            track_speed: TrackSpeed::Normal,
+            enable_auto_tracking: true,
+            enable_single_tap_tracking: true,
+            pause_track_enabled: false,
+            forbidden_areas: [
+                ForbiddenAreaInfo {
+                    enabled: false,
+                    index: 0,
+                    pan_min: -350,
+                    pan_max: -150,
+                    tilt_min: -200,
+                    tilt_max: 200,
+                },
+                ForbiddenAreaInfo {
+                    enabled: false,
+                    index: 1,
+                    pan_min: 150,
+                    pan_max: 350,
+                    tilt_min: -200,
+                    tilt_max: 200,
+                },
+                ForbiddenAreaInfo {
+                    enabled: false,
+                    index: 2,
+                    pan_min: -200,
+                    pan_max: 200,
+                    tilt_min: 100,
+                    tilt_max: 300,
+                },
+                ForbiddenAreaInfo {
+                    enabled: false,
+                    index: 3,
+                    pan_min: -200,
+                    pan_max: 200,
+                    tilt_min: -300,
+                    tilt_max: -100,
+                },
+            ],
+            tracked_targets: Vec::new(),
+            selected_target_id: 0,
+            whiteboard_corners: [
+                Pos2::new(0.18, 0.16),
+                Pos2::new(0.82, 0.16),
+                Pos2::new(0.82, 0.78),
+                Pos2::new(0.18, 0.78),
+            ],
+
+            auto_exposure: true,
+            ev_compensation: 0.0,
+            iso_index: 0,
+            shutter_index: 5, // 1/100s
+            spline_points: vec![(0.0, 0.0), (0.33, 0.33), (0.67, 0.67), (1.0, 1.0)],
+            auto_focus: true,
+            manual_focus: 50,
+            auto_white_balance: true,
+            wb_kelvin: 5000,
+            open_more_color: false,
+            brightness: 50,
+            contrast: 50,
+            saturation: 50,
+            sharpness: 50,
+            hdr_enabled: false,
+            anti_flicker: PowerLineFrequency::Auto,
+            startup_params_enabled: false,
+            color_presets,
+            active_color_preset_id: None,
+            open_more_color_presets: false,
+
+            background_mode: BackgroundEffectMode::None,
+            blur_intensity: 60,
+            custom_backgrounds: vec![
+                "Modern Office".to_string(),
+                "Minimalist Studio".to_string(),
+                "Warm Bookshelf".to_string(),
+            ],
+            makeup_enabled: false,
+            makeup_intensity: 45,
+            filter_dropdown_open: true,
+            filter_mode: FilterMode::None,
+
+            enable_all_gestures: true,
+            use_gesture_palm: true,
+            use_gesture_v: true,
+            use_gesture_l: true,
+            use_gesture_rock: false,
+            use_gesture_ok: false,
+            audio_capture_mode: AudioCaptureMode::VoiceFocus,
+            audio_denoise: true,
+            horizontal_mirror: false,
+            vertical_mirror: false,
+            smart_adjustment: false,
+            horizontal_correction: false,
+            ultimate_privacy: false,
+            privacy_sleep: false,
+            vertical_resolution_mode: false,
+            forced_vertical_lock: false,
+            low_resolution_mode: false,
+
+            stream_initialized: false,
+            joystick_dragging: false,
+            last_ptz_cmd: (0, 0, 0, 0),
+            last_ptz_send_time: None,
+            nudge_stop_at: None,
+            pending_ptz_restore: None,
+            ready_auto_track: false,
+            last_track_poll: None,
+            last_hw_sync: None,
+        }
+    }
+}
+
+impl CameraAppState {
+    pub fn show_toast(&mut self, msg: impl Into<String>, is_error: bool) {
+        self.toast_message = Some((msg.into(), Instant::now(), is_error));
+    }
+}
@@ -0,0 +1,934 @@
+#![allow(dead_code)]
+
+use egui::{
+    Align, Align2, Button, Color32, Context, FontId, Frame, Layout, Margin, Pos2, Rect, Response,
+    RichText, Rounding, Sense, Stroke, Style, Ui, Vec2, Visuals, WidgetInfo, WidgetType,
+};
+
+/// Official Insta360 Link Controller v2.0.2 theme palette (`InsUI.qml`).
+#[derive(Debug, Clone, Copy)]
+pub struct InsTheme {
+    pub is_light_mode: bool,
+    pub brand_green: Color32,
+    pub brand_green_lighter: Color32,
+    pub brand_light: Color32,
+    pub brand_text: Color32,
+    pub bg01: Color32,
+    pub bg02: Color32,
+    pub bg03: Color32,
+    pub bg04: Color32,
+    pub bg05: Color32,
+    pub border01: Color32,
+    pub border02: Color32,
+    pub border03: Color32,
+    pub text01: Color32,
+    pub text02: Color32,
+    pub text03: Color32,
+    pub text04: Color32,
+    pub overlay01: Color32,
+    pub overlay02: Color32,
+    pub overlay03: Color32,
+    pub mask01: Color32,
+    pub error: Color32,
+    pub success: Color32,
+    pub warning: Color32,
+}
+
+impl InsTheme {
+    pub fn new(is_light_mode: bool) -> Self {
+        if is_light_mode {
+            Self {
+                is_light_mode: true,
+                brand_green: Color32::from_rgb(18, 219, 139),
+                brand_green_lighter: Color32::from_rgb(81, 245, 179),
+                brand_light: Color32::from_rgb(240, 255, 249),
+                brand_text: Color32::from_rgb(0, 178, 107),
+                bg01: Color32::from_rgb(229, 229, 229),
+                bg02: Color32::from_rgb(240, 240, 240),
+                bg03: Color32::from_rgb(250, 250, 250),
+                bg04: Color32::from_rgb(255, 255, 255),
+                bg05: Color32::from_rgb(255, 255, 255),
+                border01: Color32::from_rgba_unmultiplied(0, 0, 0, 26),
+                border02: Color32::from_rgba_unmultiplied(0, 0, 0, 46),
+                border03: Color32::from_rgba_unmultiplied(0, 0, 0, 66),
+                text01: Color32::from_rgb(41, 41, 41),
+                text02: Color32::from_rgb(82, 82, 82),
+                text03: Color32::from_rgb(153, 153, 153),
+                text04: Color32::from_rgb(191, 191, 191),
+                overlay01: Color32::from_rgba_unmultiplied(255, 255, 255, 255),
+                overlay02: Color32::from_rgba_unmultiplied(255, 255, 255, 255),
+                overlay03: Color32::from_rgba_unmultiplied(255, 255, 255, 255),
+                mask01: Color32::from_rgba_unmultiplied(0, 0, 0, 153),
+                error: Color32::from_rgb(255, 64, 77),
+                success: Color32::from_rgb(0, 209, 112),
+                warning: Color32::from_rgb(245, 217, 37),
+            }
+        } else {
+            Self {
+                is_light_mode: false,
+                brand_green: Color32::from_rgb(42, 235, 158),
+                brand_green_lighter: Color32::from_rgb(26, 255, 163),
+                brand_light: Color32::from_rgb(47, 51, 49),
+                brand_text: Color32::from_rgb(15, 184, 116),
+                bg01: Color32::from_rgb(33, 33, 33),
+                bg02: Color32::from_rgb(43, 43, 43),
+                bg03: Color32::from_rgb(51, 51, 51),
+                bg04: Color32::from_rgb(56, 56, 56),
+                bg05: Color32::from_rgb(71, 71, 71),
+                border01: Color32::from_rgba_unmultiplied(255, 255, 255, 20),
+                border02: Color32::from_rgba_unmultiplied(255, 255, 255, 36),
+                border03: Color32::from_rgba_unmultiplied(255, 255, 255, 51),
+                text01: Color32::from_rgb(235, 235, 235),
+                text02: Color32::from_rgb(184, 184, 184),
+                text03: Color32::from_rgb(138, 138, 138),
+                text04: Color32::from_rgb(89, 89, 89),
+                overlay01: Color32::from_rgba_unmultiplied(216, 231, 245, 15),
+                overlay02: Color32::from_rgba_unmultiplied(235, 245, 255, 26),
+                overlay03: Color32::from_rgba_unmultiplied(235, 245, 255, 38),
+                mask01: Color32::from_rgba_unmultiplied(0, 0, 0, 153),
+                error: Color32::from_rgb(255, 84, 96),
+                success: Color32::from_rgb(0, 209, 49),
+                warning: Color32::from_rgb(249, 232, 124),
+            }
+        }
+    }
+}
+
+impl Default for InsTheme {
+    fn default() -> Self {
+        Self::new(false)
+    }
+}
+
+/// Configures `egui::Style` and `egui::Visuals` with the official Insta360 Link Controller palette
+/// (`bg01`, `bg02`, `bg03`, `brand_green` accents) and returns the configured `InsTheme`.
+pub fn apply_ins_theme(ctx: &Context, is_light_mode: bool) -> InsTheme {
+    let theme = InsTheme::new(is_light_mode);
+    let mut style: Style = (*ctx.style()).clone();
+    let mut visuals = if is_light_mode {
+        Visuals::light()
+    } else {
+        Visuals::dark()
+    };
+
+    visuals.panel_fill = theme.bg01;
+    visuals.window_fill = theme.bg02;
+    visuals.extreme_bg_color = theme.bg01;
+    visuals.faint_bg_color = theme.bg03;
+
+    visuals.selection.bg_fill = theme.brand_green;
+    visuals.selection.stroke = Stroke::new(
+        1.0_f32,
+        if is_light_mode {
+            Color32::WHITE
+        } else {
+            theme.bg01
+        },
+    );
+    visuals.hyperlink_color = theme.brand_green;
+
+    let r6 = Rounding::same(6.0_f32);
+    let r8 = Rounding::same(8.0_f32);
+
+    visuals.widgets.noninteractive.bg_fill = theme.bg02;
+    visuals.widgets.noninteractive.weak_bg_fill = theme.bg02;
+    visuals.widgets.noninteractive.bg_stroke = Stroke::new(1.0_f32, theme.border01);
+    visuals.widgets.noninteractive.fg_stroke = Stroke::new(1.0_f32, theme.text01);
+    visuals.widgets.noninteractive.rounding = r8;
+
+    visuals.widgets.inactive.bg_fill = theme.bg03;
+    visuals.widgets.inactive.weak_bg_fill = theme.bg03;
+    visuals.widgets.inactive.bg_stroke = Stroke::new(1.0_f32, theme.border01);
+    visuals.widgets.inactive.fg_stroke = Stroke::new(1.0_f32, theme.text02);
+    visuals.widgets.inactive.rounding = r6;
+
+    visuals.widgets.hovered.bg_fill = theme.bg05;
+    visuals.widgets.hovered.weak_bg_fill = theme.bg05;
+    visuals.widgets.hovered.bg_stroke = Stroke::new(1.0_f32, theme.brand_green);
+    visuals.widgets.hovered.fg_stroke = Stroke::new(1.0_f32, theme.text01);
+    visuals.widgets.hovered.rounding = r6;
+
+    visuals.widgets.active.bg_fill = theme.brand_green;
+    visuals.widgets.active.weak_bg_fill = theme.brand_green;
+    visuals.widgets.active.bg_stroke = Stroke::new(1.0_f32, theme.brand_green_lighter);
+    visuals.widgets.active.fg_stroke = Stroke::new(1.0_f32, Color32::WHITE);
+    visuals.widgets.active.rounding = r6;
+
+    visuals.widgets.open.bg_fill = theme.bg04;
+    visuals.widgets.open.weak_bg_fill = theme.bg04;
+    visuals.widgets.open.bg_stroke = Stroke::new(1.0_f32, theme.brand_green);
+    visuals.widgets.open.fg_stroke = Stroke::new(1.0_f32, theme.text01);
+    visuals.widgets.open.rounding = r6;
+
+    style.spacing.item_spacing = Vec2::new(8.0_f32, 6.0_f32);
+    style.spacing.button_padding = Vec2::new(8.0_f32, 5.0_f32);
+    style.visuals = visuals;
+    ctx.set_style(style);
+
+    theme
+}
+
+/// Renders a rounded card container with `fill(theme.bg02)`, `rounding(8.0)`,
+/// and `inner_margin(Margin::symmetric(16.0, 12.0))`.
+pub fn ins_card<R>(
+    ui: &mut Ui,
+    theme: &InsTheme,
+    add_contents: impl FnOnce(&mut Ui) -> R,
+) -> R {
+    Frame::none()
+        .fill(theme.bg02)
+        .rounding(Rounding::same(8.0_f32))
+        .inner_margin(Margin::symmetric(16.0_f32, 12.0_f32))
+        .show(ui, add_contents)
+        .inner
+}
+
+/// Renders a 32px-tall header row with `title` on the left (14.0 strong `theme.text01`)
+/// and an optional `↺` reset button on the right (returns `true` if clicked).
+pub fn ins_section_header(
+    ui: &mut Ui,
+    title: &str,
+    theme: &InsTheme,
+    reset_tooltip: Option<&str>,
+) -> bool {
+    let mut reset_clicked = false;
+    ui.allocate_ui_with_layout(
+        Vec2::new(ui.available_width(), 32.0_f32),
+        Layout::left_to_right(Align::Center),
+        |ui| {
+            ui.label(
+                RichText::new(title)
+                    .size(14.0_f32)
+                    .strong()
+                    .color(theme.text01),
+            );
+            if let Some(tooltip) = reset_tooltip {
+                ui.with_layout(Layout::right_to_left(Align::Center), |ui| {
+                    let btn = ui.add(
+                        Button::new(RichText::new("↺").size(14.0_f32).color(theme.text03))
+                            .frame(false),
+                    );
+                    if !tooltip.is_empty() {
+                        btn.clone().on_hover_text(tooltip);
+                    }
+                    if btn.clicked() {
+                        reset_clicked = true;
+                    }
+                });
+            }
+        },
+    );
+    reset_clicked
+}
+
+/// Draws a 34.0 x 18.0 pill toggle switch (`theme.brand_green` when `*checked`,
+/// `theme.bg05` when false, white circle thumb) and returns `true` if toggled.
+pub fn ins_switch(ui: &mut Ui, checked: &mut bool, enabled: bool, theme: &InsTheme) -> bool {
+    let desired_size = Vec2::new(34.0_f32, 18.0_f32);
+    let (rect, mut response) = ui.allocate_exact_size(
+        desired_size,
+        if enabled {
+            Sense::click()
+        } else {
+            Sense::hover()
+        },
+    );
+    if enabled && response.clicked() {
+        *checked = !*checked;
+        response.mark_changed();
+    }
+    response.widget_info(|| {
+        WidgetInfo::selected(
+            WidgetType::Checkbox,
+            ui.is_enabled() && enabled,
+            *checked,
+            "",
+        )
+    });
+
+    if ui.is_rect_visible(rect) {
+        let how_on = ui.ctx().animate_bool(response.id, *checked);
+        let track_rounding = Rounding::same(rect.height() / 2.0_f32);
+
+        let track_color = if enabled {
+            if *checked {
+                theme.brand_green
+            } else {
+                theme.bg05
+            }
+        } else if *checked {
+            Color32::from_rgba_unmultiplied(
+                theme.brand_green.r(),
+                theme.brand_green.g(),
+                theme.brand_green.b(),
+                100,
+            )
+        } else {
+            theme.border01
+        };
+
+        ui.painter().rect_filled(rect, track_rounding, track_color);
+
+        let thumb_radius = (rect.height() - 4.0_f32) / 2.0_f32;
+        let min_x = rect.min.x + 2.0_f32 + thumb_radius;
+        let max_x = rect.max.x - 2.0_f32 - thumb_radius;
+        let thumb_x = egui::lerp(min_x..=max_x, how_on);
+        let thumb_center = Pos2::new(thumb_x, rect.center().y);
+        let thumb_color = if enabled {
+            Color32::WHITE
+        } else {
+            theme.text04
+        };
+
+        ui.painter()
+            .circle_filled(thumb_center, thumb_radius, thumb_color);
+    }
+
+    response.changed()
+}
+
+/// Full-width row (28px height) with `label` (13.0 `theme.text01`) + optional `?` hover tooltip
+/// on the left, and `ins_switch` on the right. Returns `true` if toggled.
+pub fn ins_switch_row(
+    ui: &mut Ui,
+    label: &str,
+    tooltip: Option<&str>,
+    checked: &mut bool,
+    enabled: bool,
+    theme: &InsTheme,
+) -> bool {
+    let row_height = 28.0_f32;
+    let (row_rect, row_response) = ui.allocate_exact_size(
+        Vec2::new(ui.available_width(), row_height),
+        if enabled {
+            Sense::click()
+        } else {
+            Sense::hover()
+        },
+    );
+
+    let mut toggled = false;
+
+    let switch_width = 34.0_f32;
+    let switch_height = 18.0_f32;
+    let switch_rect = Rect::from_min_size(
+        Pos2::new(
+            row_rect.max.x - switch_width,
+            row_rect.center().y - switch_height / 2.0_f32,
+        ),
+        Vec2::new(switch_width, switch_height),
+    );
+
+    let switch_id = row_response.id.with("switch");
+    let switch_response = ui.interact(
+        switch_rect,
+        switch_id,
+        if enabled {
+            Sense::click()
+        } else {
+            Sense::hover()
+        },
+    );
+
+    if enabled {
+        if switch_response.clicked() {
+            *checked = !*checked;
+            toggled = true;
+        } else if row_response.clicked() {
+            *checked = !*checked;
+            toggled = true;
+        }
+    }
+
+    if ui.is_rect_visible(row_rect) {
+        let text_color = if enabled {
+            theme.text01
+        } else {
+            theme.text04
+        };
+        let text_pos = Pos2::new(row_rect.min.x, row_rect.center().y);
+
+        let label_galley = ui.painter().layout_no_wrap(
+            label.to_string(),
+            FontId::proportional(13.0_f32),
+            text_color,
+        );
+        let label_size = label_galley.size();
+        ui.painter().galley(
+            Pos2::new(text_pos.x, text_pos.y - label_size.y / 2.0_f32),
+            label_galley,
+            text_color,
+        );
+
+        if let Some(tt) = tooltip {
+            let tip_x = text_pos.x + label_size.x + 6.0_f32;
+            let tip_rect = Rect::from_min_size(
+                Pos2::new(tip_x, text_pos.y - 8.0_f32),
+                Vec2::new(16.0_f32, 16.0_f32),
+            );
+            let tip_resp = ui.interact(tip_rect, row_response.id.with("tt"), Sense::hover());
+            let tip_color = if tip_resp.hovered() {
+                theme.text01
+            } else {
+                theme.text03
+            };
+            ui.painter().text(
+                tip_rect.center(),
+                Align2::CENTER_CENTER,
+                "?",
+                FontId::proportional(12.0_f32),
+                tip_color,
+            );
+            if !tt.is_empty() {
+                tip_resp.on_hover_text(tt);
+            }
+        }
+
+        // Render switch
+        let how_on = ui.ctx().animate_bool(switch_id, *checked);
+        let track_rounding = Rounding::same(switch_rect.height() / 2.0_f32);
+        let track_color = if enabled {
+            if *checked {
+                theme.brand_green
+            } else {
+                theme.bg05
+            }
+        } else if *checked {
+            Color32::from_rgba_unmultiplied(
+                theme.brand_green.r(),
+                theme.brand_green.g(),
+                theme.brand_green.b(),
+                100,
+            )
+        } else {
+            theme.border01
+        };
+
+        ui.painter()
+            .rect_filled(switch_rect, track_rounding, track_color);
+
+        let thumb_radius = (switch_rect.height() - 4.0_f32) / 2.0_f32;
+        let min_x = switch_rect.min.x + 2.0_f32 + thumb_radius;
+        let max_x = switch_rect.max.x - 2.0_f32 - thumb_radius;
+        let thumb_x = egui::lerp(min_x..=max_x, how_on);
+        let thumb_center = Pos2::new(thumb_x, switch_rect.center().y);
+        let thumb_color = if enabled {
+            Color32::WHITE
+        } else {
+            theme.text04
+        };
+
+        ui.painter()
+            .circle_filled(thumb_center, thumb_radius, thumb_color);
+    }
+
+    toggled
+}
+
+/// Full-width row (28px height) with optional `icon_prefix` + `label` on the left
+/// and a custom 16x16 rounded checkbox (`theme.brand_green` fill + checkmark when `*checked`)
+/// on the right. Returns `true` if toggled.
+pub fn ins_checkbox_row(
+    ui: &mut Ui,
+    label: &str,
+    icon_prefix: Option<&str>,
+    tooltip: Option<&str>,
+    checked: &mut bool,
+    enabled: bool,
+    theme: &InsTheme,
+) -> bool {
+    let row_height = 28.0_f32;
+    let (row_rect, row_response) = ui.allocate_exact_size(
+        Vec2::new(ui.available_width(), row_height),
+        if enabled {
+            Sense::click()
+        } else {
+            Sense::hover()
+        },
+    );
+
+    let mut toggled = false;
+
+    let box_size = 16.0_f32;
+    let box_rect = Rect::from_min_size(
+        Pos2::new(
+            row_rect.max.x - box_size,
+            row_rect.center().y - box_size / 2.0_f32,
+        ),
+        Vec2::new(box_size, box_size),
+    );
+
+    let box_id = row_response.id.with("cb");
+    let box_response = ui.interact(
+        box_rect,
+        box_id,
+        if enabled {
+            Sense::click()
+        } else {
+            Sense::hover()
+        },
+    );
+
+    if enabled && (box_response.clicked() || row_response.clicked()) {
+        *checked = !*checked;
+        toggled = true;
+    }
+
+    if ui.is_rect_visible(row_rect) {
+        let text_color = if enabled {
+            theme.text01
+        } else {
+            theme.text04
+        };
+        let mut cur_x = row_rect.min.x;
+
+        if let Some(prefix) = icon_prefix {
+            let prefix_galley = ui.painter().layout_no_wrap(
+                prefix.to_string(),
+                FontId::proportional(14.0_f32),
+                theme.text03,
+            );
+            let p_size = prefix_galley.size();
+            ui.painter().galley(
+                Pos2::new(cur_x, row_rect.center().y - p_size.y / 2.0_f32),
+                prefix_galley,
+                theme.text03,
+            );
+            cur_x += p_size.x + 6.0_f32;
+        }
+
+        let label_galley = ui.painter().layout_no_wrap(
+            label.to_string(),
+            FontId::proportional(13.0_f32),
+            text_color,
+        );
+        let label_size = label_galley.size();
+        ui.painter().galley(
+            Pos2::new(cur_x, row_rect.center().y - label_size.y / 2.0_f32),
+            label_galley,
+            text_color,
+        );
+        cur_x += label_size.x + 6.0_f32;
+
+        if let Some(tt) = tooltip {
+            let tip_rect = Rect::from_min_size(
+                Pos2::new(cur_x, row_rect.center().y - 8.0_f32),
+                Vec2::new(16.0_f32, 16.0_f32),
+            );
+            let tip_resp = ui.interact(tip_rect, row_response.id.with("cb_tt"), Sense::hover());
+            let tip_color = if tip_resp.hovered() {
+                theme.text01
+            } else {
+                theme.text03
+            };
+            ui.painter().text(
+                tip_rect.center(),
+                Align2::CENTER_CENTER,
+                "?",
+                FontId::proportional(12.0_f32),
+                tip_color,
+            );
+            if !tt.is_empty() {
+                tip_resp.on_hover_text(tt);
+            }
+        }
+
+        // Draw checkbox indicator
+        let r3 = Rounding::same(3.0_f32);
+        if *checked {
+            let fill = if enabled {
+                theme.brand_green
+            } else {
+                Color32::from_rgba_unmultiplied(
+                    theme.brand_green.r(),
+                    theme.brand_green.g(),
+                    theme.brand_green.b(),
+                    120,
+                )
+            };
+            ui.painter().rect_filled(box_rect, r3, fill);
+
+            // Dark checkmark
+            let check_color = if theme.is_light_mode {
+                Color32::WHITE
+            } else {
+                Color32::from_rgb(20, 20, 20)
+            };
+            let stroke = Stroke::new(1.8_f32, check_color);
+            let p1 = Pos2::new(box_rect.min.x + 3.5_f32, box_rect.min.y + 8.0_f32);
+            let p2 = Pos2::new(box_rect.min.x + 6.5_f32, box_rect.min.y + 11.5_f32);
+            let p3 = Pos2::new(box_rect.min.x + 12.5_f32, box_rect.min.y + 4.5_f32);
+            ui.painter().line_segment([p1, p2], stroke);
+            ui.painter().line_segment([p2, p3], stroke);
+        } else {
+            let bg = if enabled && box_response.hovered() {
+                theme.bg04
+            } else {
+                theme.bg03
+            };
+            let stroke_color = if enabled && box_response.hovered() {
+                theme.brand_green
+            } else {
+                theme.border02
+            };
+            ui.painter().rect_filled(box_rect, r3, bg);
+            ui.painter()
+                .rect_stroke(box_rect, r3, Stroke::new(1.0_f32, stroke_color));
+        }
+    }
+
+    toggled
+}
+
+/// Matches `DefSlider.qml`: top row has `label` on the left (if `Some`) and current value + `unit`
+/// on the right; bottom row has a custom full-width slider track (`theme.brand_green` left of thumb,
+/// `theme.bg05` right of thumb). Returns `true` if changed.
+pub fn ins_slider_i32(
+    ui: &mut Ui,
+    label: Option<&str>,
+    value: &mut i32,
+    min: i32,
+    max: i32,
+    unit: &str,
+    enabled: bool,
+    theme: &InsTheme,
+) -> bool {
+    let mut changed = false;
+    let initial_val = *value;
+
+    ui.vertical(|ui| {
+        // Top row
+        ui.horizontal(|ui| {
+            if let Some(lbl) = label {
+                ui.label(
+                    RichText::new(lbl).size(13.0_f32).color(if enabled {
+                        theme.text02
+                    } else {
+                        theme.text04
+                    }),
+                );
+            }
+            ui.with_layout(Layout::right_to_left(Align::Center), |ui| {
+                let val_str = format!("{}{}", *value, unit);
+                ui.label(
+                    RichText::new(val_str).size(12.0_f32).color(if enabled {
+                        theme.text01
+                    } else {
+                        theme.text04
+                    }),
+                );
+            });
+        });
+
+        // Bottom track
+        let track_height = 16.0_f32;
+        let (track_rect, response) = ui.allocate_exact_size(
+            Vec2::new(ui.available_width(), track_height),
+            if enabled {
+                Sense::click_and_drag()
+            } else {
+                Sense::hover()
+            },
+        );
+
+        let thumb_radius = 6.0_f32;
+        let min_x = track_rect.min.x + thumb_radius;
+        let max_x = track_rect.max.x - thumb_radius;
+        let range = (max - min).max(1) as f32;
+
+        if enabled && (response.clicked() || response.dragged()) {
+            if let Some(pos) = response.interact_pointer_pos() {
+                let norm = ((pos.x - min_x) / (max_x - min_x).max(1.0_f32)).clamp(0.0_f32, 1.0_f32);
+                let new_val = min + (norm * range).round() as i32;
+                let clamped_val = new_val.clamp(min, max);
+                if clamped_val != *value {
+                    *value = clamped_val;
+                    changed = true;
+                }
+            }
+        }
+
+        if ui.is_rect_visible(track_rect) {
+            let norm = ((*value - min) as f32 / range).clamp(0.0_f32, 1.0_f32);
+            let thumb_x = min_x + norm * (max_x - min_x);
+            let bar_y = track_rect.center().y;
+            let bar_h = 3.0_f32;
+            let bar_rounding = Rounding::same(1.5_f32);
+
+            // Left track (brand_green)
+            let left_rect = Rect::from_min_max(
+                Pos2::new(track_rect.min.x, bar_y - bar_h / 2.0_f32),
+                Pos2::new(thumb_x, bar_y + bar_h / 2.0_f32),
+            );
+            ui.painter().rect_filled(
+                left_rect,
+                bar_rounding,
+                if enabled {
+                    theme.brand_green
+                } else {
+                    theme.border01
+                },
+            );
+
+            // Right track (bg05)
+            let right_rect = Rect::from_min_max(
+                Pos2::new(thumb_x, bar_y - bar_h / 2.0_f32),
+                Pos2::new(track_rect.max.x, bar_y + bar_h / 2.0_f32),
+            );
+            ui.painter().rect_filled(right_rect, bar_rounding, theme.bg05);
+
+            // Thumb
+            let thumb_center = Pos2::new(thumb_x, bar_y);
+            let thumb_fill = if enabled {
+                Color32::WHITE
+            } else {
+                theme.text04
+            };
+            ui.painter()
+                .circle_filled(thumb_center, thumb_radius, thumb_fill);
+            ui.painter()
+                .circle_stroke(thumb_center, thumb_radius, Stroke::new(1.0_f32, theme.border03));
+        }
+    });
+
+    changed || *value != initial_val
+}
+
+/// Matches `DefSlider.qml` for `f32`: top row has `label` and formatted value + `unit`;
+/// bottom row has custom track. Returns `true` if changed.
+pub fn ins_slider_f32(
+    ui: &mut Ui,
+    label: Option<&str>,
+    value: &mut f32,
+    min: f32,
+    max: f32,
+    step: f32,
+    decimals: usize,
+    unit: &str,
+    enabled: bool,
+    theme: &InsTheme,
+) -> bool {
+    let mut changed = false;
+    let initial_val = *value;
+
+    ui.vertical(|ui| {
+        // Top row
+        ui.horizontal(|ui| {
+            if let Some(lbl) = label {
+                ui.label(
+                    RichText::new(lbl).size(13.0_f32).color(if enabled {
+                        theme.text02
+                    } else {
+                        theme.text04
+                    }),
+                );
+            }
+            ui.with_layout(Layout::right_to_left(Align::Center), |ui| {
+                let val_str = format!("{:.decimals$}{}", *value, unit);
+                ui.label(
+                    RichText::new(val_str).size(12.0_f32).color(if enabled {
+                        theme.text01
+                    } else {
+                        theme.text04
+                    }),
+                );
+            });
+        });
+
+        // Bottom track
+        let track_height = 16.0_f32;
+        let (track_rect, response) = ui.allocate_exact_size(
+            Vec2::new(ui.available_width(), track_height),
+            if enabled {
+                Sense::click_and_drag()
+            } else {
+                Sense::hover()
+            },
+        );
+
+        let thumb_radius = 6.0_f32;
+        let min_x = track_rect.min.x + thumb_radius;
+        let max_x = track_rect.max.x - thumb_radius;
+        let range = (max - min).max(0.0001_f32);
+
+        if enabled && (response.clicked() || response.dragged()) {
+            if let Some(pos) = response.interact_pointer_pos() {
+                let norm = ((pos.x - min_x) / (max_x - min_x).max(1.0_f32)).clamp(0.0_f32, 1.0_f32);
+                let mut new_val = min + norm * range;
+                if step > 0.0_f32 {
+                    new_val = (new_val / step).round() * step;
+                }
+                let clamped_val = new_val.clamp(min, max);
+                if (clamped_val - *value).abs() > 1e-6_f32 {
+                    *value = clamped_val;
+                    changed = true;
+                }
+            }
+        }
+
+        if ui.is_rect_visible(track_rect) {
+            let norm = ((*value - min) / range).clamp(0.0_f32, 1.0_f32);
+            let thumb_x = min_x + norm * (max_x - min_x);
+            let bar_y = track_rect.center().y;
+            let bar_h = 3.0_f32;
+            let bar_rounding = Rounding::same(1.5_f32);
+
+            // Left track (brand_green)
+            let left_rect = Rect::from_min_max(
+                Pos2::new(track_rect.min.x, bar_y - bar_h / 2.0_f32),
+                Pos2::new(thumb_x, bar_y + bar_h / 2.0_f32),
+            );
+            ui.painter().rect_filled(
+                left_rect,
+                bar_rounding,
+                if enabled {
+                    theme.brand_green
+                } else {
+                    theme.border01
+                },
+            );
+
+            // Right track (bg05)
+            let right_rect = Rect::from_min_max(
+                Pos2::new(thumb_x, bar_y - bar_h / 2.0_f32),
+                Pos2::new(track_rect.max.x, bar_y + bar_h / 2.0_f32),
+            );
+            ui.painter().rect_filled(right_rect, bar_rounding, theme.bg05);
+
+            // Thumb
+            let thumb_center = Pos2::new(thumb_x, bar_y);
+            let thumb_fill = if enabled {
+                Color32::WHITE
+            } else {
+                theme.text04
+            };
+            ui.painter()
+                .circle_filled(thumb_center, thumb_radius, thumb_fill);
+            ui.painter()
+                .circle_stroke(thumb_center, thumb_radius, Stroke::new(1.0_f32, theme.border03));
+        }
+    });
+
+    changed || (*value - initial_val).abs() > 1e-6_f32
+}
+
+/// Renders a tab button (`width x 32.0`, `rounding(6.0)`, `fill(if active { theme.bg03 } else { Color32::TRANSPARENT })`,
+/// text color `if active { theme.brand_green } else { theme.text02 }`). Returns `true` if clicked.
+pub fn ins_tab_button(
+    ui: &mut Ui,
+    label: &str,
+    active: bool,
+    width: f32,
+    theme: &InsTheme,
+) -> bool {
+    let size = Vec2::new(width, 32.0_f32);
+    let (rect, response) = ui.allocate_exact_size(size, Sense::click());
+
+    if ui.is_rect_visible(rect) {
+        let fill = if active {
+            theme.bg03
+        } else if response.hovered() {
+            theme.bg04
+        } else {
+            Color32::TRANSPARENT
+        };
+
+        ui.painter().rect_filled(rect, Rounding::same(6.0_f32), fill);
+
+        let text_color = if active {
+            theme.brand_green
+        } else if response.hovered() {
+            theme.text01
+        } else {
+            theme.text02
+        };
+
+        ui.painter().text(
+            rect.center(),
+            Align2::CENTER_CENTER,
+            label,
+            FontId::proportional(13.0_f32),
+            text_color,
+        );
+    }
+
+    response.clicked()
+}
+
+/// Renders a 74.0 x 52.0 mode button for `BottomControl.qml` with `icon` (18px)
+/// centered above `label` (11.5px), colored `theme.brand_green` when `active` or
+/// `theme.text01` when inactive.
+pub fn ins_bottom_mode_button(
+    ui: &mut Ui,
+    icon: &str,
+    label: &str,
+    active: bool,
+    enabled: bool,
+    theme: &InsTheme,
+) -> Response {
+    let size = Vec2::new(74.0_f32, 52.0_f32);
+    let (rect, response) = ui.allocate_exact_size(
+        size,
+        if enabled {
+            Sense::click()
+        } else {
+            Sense::hover()
+        },
+    );
+
+    if ui.is_rect_visible(rect) {
+        let r6 = Rounding::same(6.0_f32);
+        let bg_fill = if active {
+            theme.brand_light
+        } else if enabled && response.hovered() {
+            theme.bg03
+        } else {
+            Color32::TRANSPARENT
+        };
+
+        ui.painter().rect_filled(rect, r6, bg_fill);
+
+        if active {
+            ui.painter()
+                .rect_stroke(rect, r6, Stroke::new(1.0_f32, theme.brand_green));
+        }
+
+        let main_color = if !enabled {
+            theme.text04
+        } else if active {
+            theme.brand_green
+        } else {
+            theme.text01
+        };
+
+        let label_color = if !enabled {
+            theme.text04
+        } else if active {
+            theme.brand_green
+        } else {
+            theme.text02
+        };
+
+        // Icon at top
+        let icon_pos = Pos2::new(rect.center().x, rect.min.y + 18.0_f32);
+        ui.painter().text(
+            icon_pos,
+            Align2::CENTER_CENTER,
+            icon,
+            FontId::proportional(18.0_f32),
+            main_color,
+        );
+
+        // Label below
+        let label_pos = Pos2::new(rect.center().x, rect.min.y + 38.0_f32);
+        ui.painter().text(
+            label_pos,
+            Align2::CENTER_CENTER,
+            label,
+            FontId::proportional(11.5_f32),
+            label_color,
+        );
+    }
+
+    response
+}
@@ -0,0 +1,180 @@
+#![allow(dead_code)]
+
+use insta360_link_protocol::{
+    ct_selectors, pu_selectors, xu1_selectors, xu2_selectors, CameraModel, DiscoveredCamera,
+    MockCameraTransport, NusbTransport, TransportError, UvcControlPacketHeader,
+    UvcControlTransport, UvcRequest, UvcUnitIds,
+};
+
+/// Unified GUI transport wrapper allowing runtime switching between physical USB cameras
+/// (`NusbTransport`) and stateful in-memory camera simulators (`MockCameraTransport`).
+pub enum GuiTransport {
+    Usb(NusbTransport),
+    Mock(MockCameraTransport),
+}
+
+impl GuiTransport {
+    pub fn is_mock(&self) -> bool {
+        matches!(self, Self::Mock(_))
+    }
+
+    pub fn command_log(&self) -> Option<Vec<(UvcRequest, u8, u8, Vec<u8>)>> {
+        match self {
+            Self::Usb(_) => None,
+            Self::Mock(mock) => Some(mock.command_log()),
+        }
+    }
+}
+
+impl UvcControlTransport for GuiTransport {
+    fn camera_info(&self) -> &DiscoveredCamera {
+        match self {
+            Self::Usb(usb) => usb.camera_info(),
+            Self::Mock(mock) => mock.camera_info(),
+        }
+    }
+
+    fn set_cur(&self, unit_id: u8, selector: u8, data: &[u8]) -> Result<(), TransportError> {
+        match self {
+            Self::Usb(usb) => usb.set_cur(unit_id, selector, data),
+            Self::Mock(mock) => mock.set_cur(unit_id, selector, data),
+        }
+    }
+
+    fn get_req(
+        &self,
+        req: UvcRequest,
+        unit_id: u8,
+        selector: u8,
+        len: usize,
+    ) -> Result<Vec<u8>, TransportError> {
+        match self {
+            Self::Usb(usb) => usb.get_req(req, unit_id, selector, len),
+            Self::Mock(mock) => mock.get_req(req, unit_id, selector, len),
+        }
+    }
+}
+
+/// Target device selection in the GUI header dropdown.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DeviceSelection {
+    Usb(DiscoveredCamera),
+    Simulate(CameraModel),
+}
+
+impl DeviceSelection {
+    pub fn label(&self) -> String {
+        match self {
+            Self::Usb(cam) => format!(
+                "USB: {} (Bus {} Addr {} • 0x{:04x})",
+                cam.name, cam.bus_number, cam.device_address, cam.product_id
+            ),
+            Self::Simulate(model) => format!(
+                "Simulate: {} (0x{:04x})",
+                model.display_name(),
+                model.pid()
+            ),
+        }
+    }
+}
+
+/// Formats a human-readable UVC unit name for the protocol inspector.
+pub fn describe_unit(unit_id: u8, ids: &UvcUnitIds) -> &'static str {
+    if unit_id == ids.input_terminal_id {
+        "IT (Camera Terminal)"
+    } else if unit_id == ids.processing_unit_id {
+        "PU (Processing Unit)"
+    } else if unit_id == ids.extension_unit_id {
+        "XU1 (Insta360 Ext 1)"
+    } else if unit_id == ids.extension_unit2_id {
+        "XU2 (Insta360 Ext 2)"
+    } else {
+        "Unknown Unit"
+    }
+}
+
+/// Formats a human-readable UVC control selector symbol for the protocol inspector.
+pub fn describe_selector(unit_id: u8, selector: u8, ids: &UvcUnitIds) -> &'static str {
+    if unit_id == ids.input_terminal_id {
+        match selector {
+            ct_selectors::AE_MODE => "CT_AE_MODE_CONTROL",
+            ct_selectors::EXPOSURE_TIME_ABSOLUTE => "CT_EXPOSURE_TIME_ABSOLUTE",
+            ct_selectors::FOCUS_ABSOLUTE => "CT_FOCUS_ABSOLUTE",
+            ct_selectors::FOCUS_AUTO => "CT_FOCUS_AUTO",
+            ct_selectors::ZOOM_ABSOLUTE => "CT_ZOOM_ABSOLUTE",
+            ct_selectors::PANTILT_ABSOLUTE => "CT_PANTILT_ABSOLUTE",
+            ct_selectors::PANTILT_RELATIVE => "CT_PANTILT_RELATIVE",
+            ct_selectors::ROLL_ABSOLUTE => "CT_ROLL_ABSOLUTE",
+            _ => "CT_UNKNOWN",
+        }
+    } else if unit_id == ids.processing_unit_id {
+        match selector {
+            pu_selectors::BRIGHTNESS => "PU_BRIGHTNESS_CONTROL",
+            pu_selectors::CONTRAST => "PU_CONTRAST_CONTROL",
+            pu_selectors::POWER_LINE_FREQUENCY => "PU_POWER_LINE_FREQUENCY",
+            pu_selectors::SATURATION => "PU_SATURATION_CONTROL",
+            pu_selectors::SHARPNESS => "PU_SHARPNESS_CONTROL",
+            pu_selectors::WHITE_BALANCE_TEMPERATURE => "PU_WB_TEMPERATURE",
+            pu_selectors::WHITE_BALANCE_TEMPERATURE_AUTO => "PU_WB_TEMPERATURE_AUTO",
+            _ => "PU_UNKNOWN",
+        }
+    } else if unit_id == ids.extension_unit_id {
+        match selector {
+            xu1_selectors::SYSTEM_AND_PRESET_CMD => "XU1_SYSTEM_AND_PRESET_CMD",
+            xu1_selectors::VIDEO_MODE => "XU1_VIDEO_MODE",
+            xu1_selectors::TRACKING_AND_GESTURE => "XU1_TRACKING_AND_GESTURE",
+            xu1_selectors::AUDIO_CONTROL => "XU1_AUDIO_CONTROL",
+            xu1_selectors::TRACK_OBJECT_SELECT => "XU1_TRACK_OBJECT_SELECT",
+            xu1_selectors::TRACK_OBJECT_LIST_V1 => "XU1_TRACK_OBJECT_LIST_V1",
+            xu1_selectors::EXPOSURE_CURVE_AND_ISO => "XU1_EXPOSURE_CURVE_AND_ISO",
+            xu1_selectors::EXPOSURE_COMPENSATION => "XU1_EXPOSURE_COMPENSATION",
+            xu1_selectors::WHITE_BALANCE_EXT => "XU1_WHITE_BALANCE_EXT",
+            xu1_selectors::EXTEND_FUNC_BITMASK => "XU1_EXTEND_FUNC_BITMASK",
+            xu1_selectors::PANTILT_RELATIVE_EXT => "XU1_PANTILT_RELATIVE_EXT",
+            xu1_selectors::DEVICE_STATUS => "XU1_DEVICE_STATUS",
+            xu1_selectors::PTZ_VERSION_AND_ABS => "XU1_PTZ_VERSION_AND_ABS",
+            xu1_selectors::PRESET_POSITION_FLAGS => "XU1_PRESET_POSITION_FLAGS",
+            xu1_selectors::USB_MODE_SWITCH => "XU1_USB_MODE_SWITCH",
+            _ => "XU1_UNKNOWN",
+        }
+    } else if unit_id == ids.extension_unit2_id {
+        match selector {
+            xu2_selectors::GESTURE_BINDING_MAP => "XU2_GESTURE_BINDING_MAP",
+            xu2_selectors::SYSTEM_TIME_AND_IQ => "XU2_SYSTEM_TIME_AND_IQ",
+            xu2_selectors::DEVICE_INFO => "XU2_DEVICE_INFO",
+            xu2_selectors::IMAGE_TEMPLATE_INFO => "XU2_IMAGE_TEMPLATE_INFO",
+            xu2_selectors::IMAGE_TEMPLATE_NAME => "XU2_IMAGE_TEMPLATE_NAME",
+            xu2_selectors::FILTER_MODE => "XU2_FILTER_MODE",
+            xu2_selectors::PRIVACY_AND_FILL_LIGHT => "XU2_PRIVACY_AND_FILL_LIGHT",
+            xu2_selectors::HOST_PTZ => "XU2_HOST_PTZ",
+            xu2_selectors::TRACK_OBJECT_LIST_V2 => "XU2_TRACK_OBJECT_LIST_V2",
+            xu2_selectors::TRACK_FORBIDDEN_AREA => "XU2_TRACK_FORBIDDEN_AREA",
+            xu2_selectors::DEFAULT_TRACK_MODE => "XU2_DEFAULT_TRACK_MODE",
+            xu2_selectors::HORIZONTAL_CORRECTION => "XU2_HORIZONTAL_CORRECTION",
+            xu2_selectors::REAL_ZOOM_AND_UDISK => "XU2_REAL_ZOOM_AND_UDISK",
+            xu2_selectors::REPORT_DATA => "XU2_REPORT_DATA",
+            _ => "XU2_UNKNOWN",
+        }
+    } else {
+        "UNKNOWN_SELECTOR"
+    }
+}
+
+/// Formats a byte slice as space-separated lowercase hex.
+pub fn format_hex(bytes: &[u8]) -> String {
+    bytes
+        .iter()
+        .map(|b| format!("{:02x}", b))
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+/// Computes the UVC setup packet header for display in the Protocol Inspector.
+pub fn packet_header(
+    req: UvcRequest,
+    unit_id: u8,
+    selector: u8,
+    ids: &UvcUnitIds,
+) -> UvcControlPacketHeader {
+    UvcControlPacketHeader::new(req, selector, unit_id, ids.control_interface)
+}
@@ -0,0 +1,17 @@
+[package]
+name = "insta360-link-protocol"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+description = "Pure-Rust cross-platform UVC & Extension Unit protocol library for Insta360 Link, Link 2, and Link 2C webcams"
+
+[dependencies]
+thiserror.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+bitflags.workspace = true
+tracing.workspace = true
+nusb.workspace = true
+
+[target.'cfg(target_os = "linux")'.dependencies]
+libc = "0.2"
@@ -0,0 +1,721 @@
+use crate::types::*;
+use thiserror::Error;
+
+#[derive(Debug, Error, Clone, PartialEq)]
+pub enum CodecError {
+    #[error("payload too short: expected at least {expected} bytes, got {actual}")]
+    PayloadTooShort { expected: usize, actual: usize },
+    #[error("invalid argument: {0}")]
+    InvalidArgument(&'static str),
+}
+
+/// Encodes UVC `bmRequestType`, `bRequest`, `wValue`, `wIndex` for a UVC control transfer
+/// matching `MacUVCCameraControl::SetData` (`0x100192880`) and `GetData` (`0x10019282c`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct UvcControlPacketHeader {
+    pub bm_request_type: u8,
+    pub b_request: u8,
+    pub w_value: u16,
+    pub w_index: u16,
+}
+
+impl UvcControlPacketHeader {
+    pub fn new(req: UvcRequest, control_selector: u8, unit_or_terminal_id: u8, interface_num: u8) -> Self {
+        let bm_request_type = match req {
+            UvcRequest::SetCur => 0x21, // Host-to-device, Class, Interface (`0x0121` in little-endian u16 with bRequest=0x01)
+            _ => 0xa1,                  // Device-to-host, Class, Interface
+        };
+        Self {
+            bm_request_type,
+            b_request: req as u8,
+            w_value: (control_selector as u16) << 8,
+            w_index: ((unit_or_terminal_id as u16) << 8) | (interface_num as u16),
+        }
+    }
+}
+
+// ============================================================================
+// XU1 Selector 0x01: System, Presets, Gimbal Reset, Composition Bias
+// ============================================================================
+
+/// `SetCurPresetPosition(unsigned char)` (`0x100199918`): `[0, index, 0, 0]`
+pub fn encode_set_cur_preset_position(index: u8) -> [u8; 4] {
+    [0x00, index, 0x00, 0x00]
+}
+
+/// `AddPresetPosition(unsigned char)` (`0x1001999b4`): `[1, index, 0, 0]`
+pub fn encode_add_preset_position(index: u8) -> [u8; 4] {
+    [0x01, index, 0x00, 0x00]
+}
+
+/// `DeletePresetPosition(unsigned char)` (`0x100199a54`): `[2, index, 0, 0]`
+pub fn encode_delete_preset_position(index: u8) -> [u8; 4] {
+    [0x02, index, 0x00, 0x00]
+}
+
+/// `ResetGimbal()` (`0x100196fb0`): `[3, 0, 0, 0]`
+pub fn encode_reset_gimbal() -> [u8; 4] {
+    [0x03, 0x00, 0x00, 0x00]
+}
+
+/// `LoadFactoryDefault()` (`0x10019701c`): `[4, 0, 0, 0]`
+pub fn encode_load_factory_default() -> [u8; 4] {
+    [0x04, 0x00, 0x00, 0x00]
+}
+
+/// `SetCompositionBias(short, short)` (`0x10019933c`): `[6, x_lo, x_hi, y_lo, y_hi]`
+pub fn encode_set_composition_bias(x: i16, y: i16) -> [u8; 5] {
+    let xb = x.to_le_bytes();
+    let yb = y.to_le_bytes();
+    [0x06, xb[0], xb[1], yb[0], yb[1]]
+}
+
+/// `EnterTrackForbiddenAreaSetting()` (`0x10019bf74`): `[7, 1, 0, 0]`
+pub fn encode_enter_track_forbidden_area_setting() -> [u8; 4] {
+    [0x07, 0x01, 0x00, 0x00]
+}
+
+/// `ExitTrackForbiddenAreaSetting()` (`0x10019bfb4`): `[8, 1, 0, 0]`
+pub fn encode_exit_track_forbidden_area_setting() -> [u8; 4] {
+    [0x08, 0x01, 0x00, 0x00]
+}
+
+// ============================================================================
+// XU1 Selector 0x02: Video Mode & Auxiliary Data (`0x100197088`, `0x1001978b8`)
+// ============================================================================
+
+pub fn encode_set_video_mode(mode: VideoMode, aux: &VideoModeAuxData, payload_len: usize) -> Vec<u8> {
+    let len = payload_len.clamp(8, 36);
+    let mut buf = vec![0u8; 36];
+    buf[0] = mode as u8;
+    buf[1] = aux.flags;
+    for (i, &val) in aux.rect.iter().enumerate() {
+        let off = 2 + i * 4;
+        buf[off..off + 4].copy_from_slice(&val.to_le_bytes());
+    }
+    buf[18..20].copy_from_slice(&aux.pitch.to_le_bytes());
+    buf[20..22].copy_from_slice(&aux.zoom.to_le_bytes());
+    buf[22..36].copy_from_slice(&aux.extra);
+    if len == 8 && aux.rect == [0, 0, 0, 0] {
+        buf[2..4].copy_from_slice(&aux.pitch.to_le_bytes());
+        buf[4..6].copy_from_slice(&aux.zoom.to_le_bytes());
+    }
+    buf.truncate(len);
+    buf
+}
+
+pub fn decode_get_video_mode(data: &[u8]) -> Result<(VideoMode, VideoModeAuxData), CodecError> {
+    if data.len() < 8 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 8,
+            actual: data.len(),
+        });
+    }
+    let mode = VideoMode::from_u8(data[0]);
+    let mut aux = VideoModeAuxData {
+        flags: data[1],
+        ..Default::default()
+    };
+    if data.len() >= 22 {
+        for i in 0..4 {
+            let off = 2 + i * 4;
+            aux.rect[i] = i32::from_le_bytes([data[off], data[off + 1], data[off + 2], data[off + 3]]);
+        }
+        aux.pitch = i16::from_le_bytes([data[18], data[19]]);
+        aux.zoom = u16::from_le_bytes([data[20], data[21]]);
+    }
+    if data.len() >= 36 {
+        aux.extra.copy_from_slice(&data[22..36]);
+    }
+    Ok((mode, aux))
+}
+
+// ============================================================================
+// XU1 Selector 0x03: Tracking Speed, Composition Style, Gestures, Smart Whiteboard
+// ============================================================================
+
+/// `SetCompositionStyle` (`0x100197498`): 16-byte buffer `[6, style_u8, 0..]`
+pub fn encode_set_composition_style(style: CompositionStyle) -> [u8; 16] {
+    let mut buf = [0u8; 16];
+    buf[0] = 0x06;
+    buf[1] = style as u8;
+    buf
+}
+
+/// `GetCompositionStyle` (`0x10019750c`): reads `data[7]` from 16-byte response
+pub fn decode_get_composition_style(data: &[u8]) -> Result<CompositionStyle, CodecError> {
+    if data.len() < 8 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 8,
+            actual: data.len(),
+        });
+    }
+    Ok(CompositionStyle::from_u8(data[7]))
+}
+
+/// `SetTrackSpeed` (`0x1001975bc`): 16-byte buffer `[5, speed_u8, 0..]`
+pub fn encode_set_track_speed(speed: TrackSpeed) -> [u8; 16] {
+    let mut buf = [0u8; 16];
+    buf[0] = 0x05;
+    buf[1] = speed as u8;
+    buf
+}
+
+/// `GetTrackSpeed` (`0x100197630`): reads `data[6]` from 16-byte response
+pub fn decode_get_track_speed(data: &[u8]) -> Result<TrackSpeed, CodecError> {
+    if data.len() < 7 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 7,
+            actual: data.len(),
+        });
+    }
+    Ok(TrackSpeed::from_u8(data[6]))
+}
+
+/// `ForceSetSmatrWhiteBoard` (`0x1001980d0`): 16-byte buffer `[3, mode_u8, 0..]`
+pub fn encode_force_smart_whiteboard(mode: u8) -> [u8; 16] {
+    let mut buf = [0u8; 16];
+    buf[0] = 0x03;
+    buf[1] = mode;
+    buf
+}
+
+/// `EnableAllGesture` (`0x100197b54`): 16-byte buffer `[0, enable_u8, 0..]`
+pub fn encode_enable_all_gestures(enable: bool) -> [u8; 16] {
+    let mut buf = [0u8; 16];
+    buf[0] = 0x00;
+    buf[1] = u8::from(enable);
+    buf
+}
+
+/// `EnableGestureWork` (`0x100197bc8`):
+/// Reads 6 bytes `[all, ok, palm, l, v, rock]` from selector `0x03`, updates `data[gesture + 1]`,
+/// and writes `[data[0], data[1], data[2], data[3], data[4], data[5], 0..]` (16B).
+pub fn encode_enable_gesture_work(current_6b: &[u8], gesture: Gesture, enable: bool) -> [u8; 16] {
+    let mut buf = [0u8; 16];
+    for i in 0..current_6b.len().min(6) {
+        buf[i] = current_6b[i];
+    }
+    buf[0] = 0x01; // master gesture enable
+    let idx = (gesture as usize) + 1;
+    if idx < 6 {
+        buf[idx] = u8::from(enable);
+    }
+    buf
+}
+
+/// `GetGestureStatus` (`0x100198144`): decodes `[all, ok, palm, l, v, rock]` from selector `0x03`
+pub fn decode_gesture_status(data: &[u8]) -> Result<[(Gesture, bool); 5], CodecError> {
+    if data.len() < 6 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 6,
+            actual: data.len(),
+        });
+    }
+    Ok([
+        (Gesture::Ok, data[1] != 0),
+        (Gesture::Palm, data[2] != 0),
+        (Gesture::LShape, data[3] != 0),
+        (Gesture::VShape, data[4] != 0),
+        (Gesture::Rock, data[5] != 0),
+    ])
+}
+
+// ============================================================================
+// XU1 Selector 0x04: Audio Noise Reduction & Audio Capture Mode (`0x100197798`, `0x10019bf54`)
+// ============================================================================
+
+pub fn encode_audio_control(value: u8) -> [u8; 2] {
+    [value, 0x00]
+}
+
+// ============================================================================
+// XU1 Selector 0x05 & 0x06 / XU2 Selector 0x0a: Track Object Rectangles (`0x100198a38`)
+// ============================================================================
+
+pub fn encode_track_rect(rect: &UvcRect) -> [u8; 10] {
+    let mut buf = [0u8; 10];
+    buf[0..2].copy_from_slice(&rect.x.to_le_bytes());
+    buf[2..4].copy_from_slice(&rect.y.to_le_bytes());
+    buf[4..6].copy_from_slice(&rect.width.to_le_bytes());
+    buf[6..8].copy_from_slice(&rect.height.to_le_bytes());
+    buf[8..10].copy_from_slice(&rect.track_id.to_le_bytes());
+    buf
+}
+
+pub fn decode_track_rect_list(data: &[u8]) -> Vec<UvcRect> {
+    let mut rects = Vec::new();
+    for chunk in data.chunks_exact(10) {
+        let x = i16::from_le_bytes([chunk[0], chunk[1]]);
+        let y = i16::from_le_bytes([chunk[2], chunk[3]]);
+        let width = i16::from_le_bytes([chunk[4], chunk[5]]);
+        let height = i16::from_le_bytes([chunk[6], chunk[7]]);
+        let track_id = i16::from_le_bytes([chunk[8], chunk[9]]);
+        if width > 0 || height > 0 {
+            rects.push(UvcRect {
+                x,
+                y,
+                width,
+                height,
+                track_id,
+            });
+        }
+    }
+    rects
+}
+
+// ============================================================================
+// XU1 Selector 0x07: Exposure Curve, Auto Exposure, ISO (`0x10019aaa0`–`0x10019b7d0`)
+// ============================================================================
+
+pub fn encode_exposure_curve(curve: &ExposureCurve) -> [u8; 259] {
+    let mut buf = [0u8; 259];
+    buf[0] = curve.mode;
+    buf[1..3].copy_from_slice(&curve.iso.to_le_bytes());
+    for (i, &pt) in curve.points.iter().take(128).enumerate() {
+        let off = 3 + i * 2;
+        buf[off..off + 2].copy_from_slice(&pt.to_le_bytes());
+    }
+    buf
+}
+
+pub fn decode_exposure_curve(data: &[u8]) -> Result<ExposureCurve, CodecError> {
+    if data.len() < 3 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 3,
+            actual: data.len(),
+        });
+    }
+    let mode = data[0];
+    let iso = u16::from_le_bytes([data[1], data[2]]);
+    let mut points = Vec::with_capacity(128);
+    for chunk in data[3..].chunks_exact(2).take(128) {
+        points.push(u16::from_le_bytes([chunk[0], chunk[1]]));
+    }
+    Ok(ExposureCurve { mode, iso, points })
+}
+
+// ============================================================================
+// XU1 Selector 0x08: Exposure Compensation (`0x100198f34`)
+// ============================================================================
+
+pub fn encode_exposure_compensation(ev: f32) -> [u8; 4] {
+    ev.to_le_bytes()
+}
+
+pub fn decode_exposure_compensation(data: &[u8]) -> Result<f32, CodecError> {
+    if data.len() < 4 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 4,
+            actual: data.len(),
+        });
+    }
+    Ok(f32::from_le_bytes([data[0], data[1], data[2], data[3]]))
+}
+
+// ============================================================================
+// XU1 Selector 0x0a: Extended Function Bitmask (`0x100199afc`–`0x10019a530`)
+// ============================================================================
+
+/// Encodes `(mask: u32, values: u32)` into the 8-byte payload for XU1 selector `0x0a`.
+/// Verified at `EnableExtendFuncWork` (`0x100199afc`), `EnableVerticalScreen` (`0x10019b7d0`),
+/// and `EnableLowResolution` (`0x10019b854`).
+pub fn encode_extend_func_bitmask(func: ExtendFunction, enable: bool, current_values: u32) -> [u8; 8] {
+    let bit = 1u32 << (func as u8);
+    let new_values = if enable {
+        current_values | bit
+    } else {
+        current_values & !bit
+    };
+    let mut buf = [0u8; 8];
+    buf[0..4].copy_from_slice(&bit.to_le_bytes());
+    buf[4..8].copy_from_slice(&new_values.to_le_bytes());
+    buf
+}
+
+/// Decodes the response from `GetExtendFuncStatus` (`0x100199a20`, XU1 selector `0x1b` or `0x0a`).
+/// Hardware returns a 2-byte `u16` LE bitmask at `data[0..2]` (or 8-byte `(mask, values)` in 8B format).
+pub fn decode_extend_func_status(data: &[u8]) -> Result<Vec<(ExtendFunction, bool)>, CodecError> {
+    if data.len() < 2 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 2,
+            actual: data.len(),
+        });
+    }
+    let bits = if data.len() >= 8 && (data[4] != 0 || data[5] != 0 || (data[0] == 0xff && data[1] == 0xff)) {
+        u32::from_le_bytes([data[4], data[5], data[6], data[7]])
+    } else {
+        u16::from_le_bytes([data[0], data[1]]) as u32
+    };
+    let mut out = Vec::with_capacity(ExtendFunction::ALL.len());
+    for func in ExtendFunction::ALL {
+        let enabled = (bits & (1u32 << (func as u8))) != 0;
+        out.push((func, enabled));
+    }
+    Ok(out)
+}
+
+// ============================================================================
+// XU1 Selector 0x0b: Relative Pan/Tilt (`0x1001990f4`)
+// ============================================================================
+
+pub fn encode_pantilt_relative_ext(pan_speed: u8, pan_dir: i8, tilt_speed: u8, tilt_dir: i8) -> [u8; 4] {
+    let p_dir: u8 = if pan_dir == 0 || pan_speed == 0 {
+        0
+    } else if pan_dir > 0 {
+        1
+    } else {
+        0xff
+    };
+    let t_dir: u8 = if tilt_dir == 0 || tilt_speed == 0 {
+        0
+    } else if tilt_dir > 0 {
+        1
+    } else {
+        0xff
+    };
+    let p_spd = if p_dir == 0 { 1 } else { pan_speed.clamp(1, 10) };
+    let t_spd = if t_dir == 0 { 1 } else { tilt_speed.clamp(1, 10) };
+    [p_dir, p_spd, t_dir, t_spd]
+}
+
+// ============================================================================
+// XU1 Selector 0x0d: PTZ Version & Gimbal Absolute Angles (`0x1001993bc`, `0x1001996cc`)
+// ============================================================================
+
+pub fn decode_ptz_version_and_abs(data: &[u8]) -> Result<PtzVersionInfo, CodecError> {
+    if data.len() < 30 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 30,
+            actual: data.len(),
+        });
+    }
+    let end = data[..20].iter().position(|&b| b == 0).unwrap_or(20);
+    let version = String::from_utf8_lossy(&data[..end]).into_owned();
+    let pan = i16::from_le_bytes([data[20], data[21]]);
+    let tilt = i16::from_le_bytes([data[22], data[23]]);
+    let zoom = u16::from_le_bytes([data[24], data[25]]);
+    let status = data[26];
+    Ok(PtzVersionInfo {
+        version,
+        pan,
+        tilt,
+        zoom,
+        status,
+    })
+}
+
+// ============================================================================
+// XU1 Selector 0x0e: Preset Position Flags (`0x1001997c0`)
+// ============================================================================
+
+pub fn decode_preset_flags(data: &[u8]) -> Result<PresetFlag, CodecError> {
+    if data.len() < 8 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 8,
+            actual: data.len(),
+        });
+    }
+    let mut raw = [0u8; 8];
+    raw.copy_from_slice(&data[..8]);
+    Ok(PresetFlag {
+        slot_mask: raw[0],
+        current_slot: raw[1],
+        max_slots: raw[2].max(6),
+        raw,
+    })
+}
+
+// ============================================================================
+// XU2 Selector 0x02: Timestamp, IQ Switch, Factory Restore (`0x10019bd00`–`0x10019c1ac`)
+// ============================================================================
+
+/// `SetTimestamp(unsigned long long)` (`0x10019be40`): `[1, ts_le[0..8], 0..]` (10 bytes)
+pub fn encode_set_timestamp(timestamp_ms: u64) -> [u8; 10] {
+    let mut buf = [0u8; 10];
+    buf[0] = 0x01;
+    buf[1..9].copy_from_slice(&timestamp_ms.to_le_bytes());
+    buf
+}
+
+/// `SetIQSwitch(int, bool)` (`0x100199ce0`): `[2, mask_u32_le[0..4], 0..]` (10 bytes)
+pub fn encode_set_iq_switch(bit_index: u8, enable: bool, current_mask: u32) -> Result<[u8; 10], CodecError> {
+    if bit_index >= 32 {
+        return Err(CodecError::InvalidArgument("bitset argument out of range"));
+    }
+    let bit = 1u32 << bit_index;
+    let next = if enable {
+        current_mask | bit
+    } else {
+        current_mask & !bit
+    };
+    let mut buf = [0u8; 10];
+    buf[0] = 0x02;
+    buf[1..5].copy_from_slice(&next.to_le_bytes());
+    Ok(buf)
+}
+
+/// `RestoreFactorySet(bool)` (`0x10019c1ac`): `[4, 1, 0..]` if `reboot` else `[5, 1, 0..]` (10 bytes)
+pub fn encode_restore_factory_set(full_reboot: bool) -> [u8; 10] {
+    let mut buf = [0u8; 10];
+    buf[0] = if full_reboot { 0x04 } else { 0x05 };
+    buf[1] = 0x01;
+    buf
+}
+
+// ============================================================================
+// XU2 Selector 0x03: DeviceInfo (`GetDeviceInfo` at `0x100196e74`, 150 bytes)
+// ============================================================================
+
+fn extract_cstr(slice: &[u8]) -> String {
+    let end = slice.iter().position(|&b| b == 0).unwrap_or(slice.len());
+    String::from_utf8_lossy(&slice[..end]).trim().to_string()
+}
+
+pub fn decode_device_info(data: &[u8]) -> Result<DeviceInfo, CodecError> {
+    if data.len() < 150 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 150,
+            actual: data.len(),
+        });
+    }
+    // Hardware layout (`MacUVCCameraExtendController::GetDeviceInfo` at `0x100196904`, >= 161 bytes):
+    // [0x00..0x20] = serial_num (32B, e.g. "0AB586531221284"), [0x20] = need_update (1B),
+    // [0x21..0x61] = device_uuid (64B), [0x61..0xa1] = cur_version (64B, e.g. "v1.4.5.8_build1")
+    if data.len() >= 0xa1 {
+        let sn = extract_cstr(&data[0x00..0x20]);
+        let uuid = extract_cstr(&data[0x21..0x61]);
+        let fw = extract_cstr(&data[0x61..0xa1]);
+        if !fw.is_empty() || !sn.is_empty() || !uuid.is_empty() {
+            return Ok(DeviceInfo {
+                device_name: uuid,
+                firmware_version: fw,
+                serial_number: sn,
+            });
+        }
+    }
+    Ok(DeviceInfo {
+        device_name: extract_cstr(&data[0..50]),
+        firmware_version: extract_cstr(&data[50..100]),
+        serial_number: extract_cstr(&data[100..150]),
+    })
+}
+
+// ============================================================================
+// XU2 Selector 0x04 & 0x05: Image Templates (`0x10019ba4c`–`0x10019bd90`)
+// ============================================================================
+
+pub fn decode_image_template_info(data: &[u8]) -> Result<ImageTemplateInfo, CodecError> {
+    if data.len() < 11 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 11,
+            actual: data.len(),
+        });
+    }
+    let current_id = data[0] as i8;
+    let operation = data[1];
+    let bitmask = u64::from_le_bytes([
+        data[2], data[3], data[4], data[5], data[6], data[7], data[8], data[9],
+    ]);
+    let max_templates = data[10];
+    Ok(ImageTemplateInfo {
+        current_id,
+        operation,
+        bitmask,
+        max_templates,
+    })
+}
+
+pub fn encode_set_image_template(template_id: i8, op: ImageOperation, current_mask: u64, max_templates: u8) -> Result<[u8; 11], CodecError> {
+    if template_id < 0 || (template_id as u8) >= 64 {
+        return Err(CodecError::InvalidArgument("template_id out of range (0..64)"));
+    }
+    let next_mask = match op {
+        ImageOperation::SaveOrUpdate => current_mask | (1u64 << (template_id as u8)),
+        _ => current_mask,
+    };
+    let mut buf = [0u8; 11];
+    buf[0] = template_id as u8;
+    buf[1] = op as u8;
+    buf[2..10].copy_from_slice(&next_mask.to_le_bytes());
+    buf[10] = max_templates;
+    Ok(buf)
+}
+
+pub fn encode_delete_image_template(template_id: i8, current: &ImageTemplateInfo) -> Result<[u8; 11], CodecError> {
+    if template_id < 0 || (template_id as u8) >= 64 {
+        return Err(CodecError::InvalidArgument("template_id out of range (0..64)"));
+    }
+    let next_mask = current.bitmask & !(1u64 << (template_id as u8));
+    let mut buf = [0u8; 11];
+    buf[0] = current.current_id as u8;
+    buf[1] = current.operation;
+    buf[2..10].copy_from_slice(&next_mask.to_le_bytes());
+    buf[10] = current.max_templates;
+    Ok(buf)
+}
+
+pub fn encode_image_template_name(template_id: i8, name: &str) -> [u8; 65] {
+    let mut buf = [0u8; 65];
+    buf[0] = template_id as u8;
+    let bytes = name.as_bytes();
+    let copy_len = bytes.len().min(63);
+    buf[1..1 + copy_len].copy_from_slice(&bytes[..copy_len]);
+    buf
+}
+
+pub fn decode_image_template_name(data: &[u8]) -> Result<(i8, String), CodecError> {
+    if data.len() < 2 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 2,
+            actual: data.len(),
+        });
+    }
+    let id = data[0] as i8;
+    let name = extract_cstr(&data[1..]);
+    Ok((id, name))
+}
+
+// ============================================================================
+// XU2 Selector 0x08: Privacy Mode & Fill Light (`0x10019c0a8`–`0x10019c168`)
+// ============================================================================
+
+pub fn encode_set_privacy_mode(enable: bool) -> [u8; 4] {
+    [0x02, u8::from(enable), 0x00, 0x00]
+}
+
+pub fn decode_privacy_mode(data: &[u8]) -> Result<(i32, bool), CodecError> {
+    if data.len() < 2 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 2,
+            actual: data.len(),
+        });
+    }
+    Ok((data[0] as i32, data[1] != 0))
+}
+
+// ============================================================================
+// XU2 Selector 0x09: Host Digital PTZ (`SetHostPTZ` at `0x10019bec0`)
+// ============================================================================
+
+pub fn encode_host_ptz(info: &HostPtzInfo) -> [u8; 8] {
+    let mut buf = [0u8; 8];
+    buf[0..2].copy_from_slice(&info.x.to_le_bytes());
+    buf[2..4].copy_from_slice(&info.y.to_le_bytes());
+    buf[4..6].copy_from_slice(&info.width.to_le_bytes());
+    buf[6..8].copy_from_slice(&info.height.to_le_bytes());
+    buf
+}
+
+// ============================================================================
+// XU2 Selector 0x01: Gesture Binding Map (`GetGestureBindingMap` / `SetGestureBindingFunc` at `0x100198384`)
+// ============================================================================
+
+pub fn encode_gesture_binding(gesture: Gesture, func: GestureFunction) -> [u8; 16] {
+    let mut buf = [0u8; 16];
+    buf[0] = gesture as u8;
+    buf[1] = func as u8;
+    buf
+}
+
+pub fn decode_gesture_binding_map(data: &[u8]) -> Result<[(Gesture, GestureFunction); 5], CodecError> {
+    if data.len() < 5 {
+        return Err(CodecError::PayloadTooShort {
+            expected: 5,
+            actual: data.len(),
+        });
+    }
+    Ok([
+        (Gesture::Ok, GestureFunction::from_u8(data[0])),
+        (Gesture::Palm, GestureFunction::from_u8(data[1])),
+        (Gesture::LShape, GestureFunction::from_u8(data[2])),
+        (Gesture::VShape, GestureFunction::from_u8(data[3])),
+        (Gesture::Rock, GestureFunction::from_u8(data[4])),
+    ])
+}
+
+// ============================================================================
+// XU2 Selector 0x0b: Tracking Forbidden Areas (`SetTrackForbiddenArea` / `GetTrackForbiddenArea` at `0x10019bff4`)
+// ============================================================================
+
+pub fn encode_forbidden_areas(areas: &[ForbiddenAreaInfo]) -> Vec<u8> {
+    let count = areas.len().clamp(1, 4);
+    let mut buf = vec![0u8; count * 10];
+    for (i, area) in areas.iter().take(count).enumerate() {
+        let off = i * 10;
+        buf[off] = u8::from(area.enabled);
+        buf[off + 1] = area.index;
+        buf[off + 2..off + 4].copy_from_slice(&area.pan_min.to_le_bytes());
+        buf[off + 4..off + 6].copy_from_slice(&area.pan_max.to_le_bytes());
+        buf[off + 6..off + 8].copy_from_slice(&area.tilt_min.to_le_bytes());
+        buf[off + 8..off + 10].copy_from_slice(&area.tilt_max.to_le_bytes());
+    }
+    buf
+}
+
+pub fn decode_forbidden_areas(data: &[u8]) -> Vec<ForbiddenAreaInfo> {
+    let mut out = Vec::new();
+    for chunk in data.chunks_exact(10) {
+        out.push(ForbiddenAreaInfo {
+            enabled: chunk[0] != 0,
+            index: chunk[1],
+            pan_min: i16::from_le_bytes([chunk[2], chunk[3]]),
+            pan_max: i16::from_le_bytes([chunk[4], chunk[5]]),
+            tilt_min: i16::from_le_bytes([chunk[6], chunk[7]]),
+            tilt_max: i16::from_le_bytes([chunk[8], chunk[9]]),
+        });
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ids::CameraModel;
+
+    #[test]
+    fn test_uvc_header_encoding() {
+        let set_hdr = UvcControlPacketHeader::new(UvcRequest::SetCur, 0x02, 0x09, 0x00);
+        assert_eq!(set_hdr.bm_request_type, 0x21);
+        assert_eq!(set_hdr.b_request, 0x01);
+        assert_eq!(set_hdr.w_value, 0x0200);
+        assert_eq!(set_hdr.w_index, 0x0900);
+
+        let get_hdr = UvcControlPacketHeader::new(UvcRequest::GetCur, 0x03, 0x0a, 0x00);
+        assert_eq!(get_hdr.bm_request_type, 0xa1);
+        assert_eq!(get_hdr.b_request, 0x81);
+        assert_eq!(get_hdr.w_value, 0x0300);
+        assert_eq!(get_hdr.w_index, 0x0a00);
+    }
+
+    #[test]
+    fn test_video_mode_payload_lengths() {
+        assert_eq!(CameraModel::Link.video_mode_payload_len(), 8);
+        assert_eq!(CameraModel::Link2.video_mode_payload_len(), 8);
+        assert_eq!(CameraModel::Link2C.video_mode_payload_len(), 36);
+        assert_eq!(CameraModel::Puc3Host.video_mode_payload_len(), 36);
+    }
+
+    #[test]
+    fn test_extend_func_bitmask_roundtrip() {
+        let encoded = encode_extend_func_bitmask(ExtendFunction::Hdr, true, 0);
+        assert_eq!(u32::from_le_bytes(encoded[0..4].try_into().unwrap()), 1 << 2);
+        assert_eq!(u32::from_le_bytes(encoded[4..8].try_into().unwrap()), 1 << 2);
+
+        let decoded = decode_extend_func_status(&encoded).unwrap();
+        let hdr_state = decoded.into_iter().find(|(f, _)| *f == ExtendFunction::Hdr).unwrap().1;
+        assert!(hdr_state);
+    }
+
+    #[test]
+    fn test_device_info_decode() {
+        let mut raw = [0u8; 150];
+        raw[0..15].copy_from_slice(b"Insta360 Link 2");
+        raw[50..65].copy_from_slice(b"v2.5.8.8_build1");
+        raw[100..114].copy_from_slice(b"INK2A240912345");
+        let info = decode_device_info(&raw).unwrap();
+        assert_eq!(info.device_name, "Insta360 Link 2");
+        assert_eq!(info.firmware_version, "v2.5.8.8_build1");
+        assert_eq!(info.serial_number, "INK2A240912345");
+    }
+}
@@ -0,0 +1,291 @@
+use serde::{Deserialize, Serialize};
+
+/// Arashi Vision / Insta360 USB Vendor ID (`0x2e1a` = 11802)
+/// Verified at `MacUVCCameraControlImp::GetUVCCameraList` (`0x100191478`)
+/// and `UVCCameraDeviceWatcherImp::StartWatch` (`0x10019e29c`).
+pub const INSTA360_VENDOR_ID: u16 = 0x2e1a;
+
+/// Supported USB Product IDs for Insta360 Link family cameras.
+/// Verified at `0x100191480` (`0x4c01..=0x4c06`) and `0x100191664` (`0x00c2`),
+/// as well as `UVCCameraExtendControllerImp::FirmwareUpgrade` jump table at `0x10286f37d`.
+pub mod pids {
+    /// Insta360 Link (1st Generation) - `link1`, firmware `a:\Insta360WebCamFW.bin`
+    pub const LINK_1: u16 = 0x4c01;
+    /// Insta360 PUC3 Gimbal - firmware `a:\Insta360PUC3FW_GIMBAL.bin`
+    pub const PUC3_GIMBAL_A: u16 = 0x4c02;
+    /// Insta360 Link 2C (Fixed-lens 4K webcam) - `link2_main`, firmware `a:\Insta360LINK2CFW_HOST.bin`
+    pub const LINK_2C: u16 = 0x4c03;
+    /// Insta360 Link 2 (2nd Gen 2-axis gimbal 4K webcam) - `link2_gimbal`, firmware `a:\Insta360LINK2FW_GIMBAL.bin`
+    pub const LINK_2: u16 = 0x4c04;
+    /// Insta360 PUC3 Host - firmware `a:\Insta360PUC3FW_HOST.bin`
+    pub const PUC3_HOST: u16 = 0x4c05;
+    /// Insta360 PUC3 Gimbal Variant - firmware `a:\Insta360PUC3FW_GIMBAL.bin`
+    pub const PUC3_GIMBAL_B: u16 = 0x4c06;
+    /// Insta360 Link Simple-Class / Firmware Upgrade Mode
+    pub const LINK_SIMPLE_CLASS: u16 = 0x00c2;
+}
+
+/// Extension Unit 1 GUID: `FAF1672D-B71B-4793-8C91-7B1C9B7F95F8`
+/// Verified at CFString `0x102a9d098` and `FindControllerInterfaceForServiceObject` (`0x100191140`).
+/// Mixed-endian USB UVC `guidExtensionCode` 16-byte representation:
+/// `2d 67 f1 fa 1b b7 93 47 8c 91 7b 1c 9b 7f 95 f8`
+pub const XU1_GUID_STR: &str = "FAF1672D-B71B-4793-8C91-7B1C9B7F95F8";
+pub const XU1_GUID_BYTES: [u8; 16] = [
+    0x2d, 0x67, 0xf1, 0xfa, 0x1b, 0xb7, 0x93, 0x47,
+    0x8c, 0x91, 0x7b, 0x1c, 0x9b, 0x7f, 0x95, 0xf8,
+];
+
+/// Extension Unit 2 GUID: `E307E649-4618-A3FF-82FC-2D8B5F216773`
+/// Verified at CFString `0x102a9d0b8` and `FindControllerInterfaceForServiceObject` (`0x100191168`).
+/// Mixed-endian USB UVC `guidExtensionCode` 16-byte representation:
+/// `49 e6 07 e3 18 46 ff a3 82 fc 2d 8b 5f 21 67 73`
+pub const XU2_GUID_STR: &str = "E307E649-4618-A3FF-82FC-2D8B5F216773";
+pub const XU2_GUID_BYTES: [u8; 16] = [
+    0x49, 0xe6, 0x07, 0xe3, 0x18, 0x46, 0xff, 0xa3,
+    0x82, 0xfc, 0x2d, 0x8b, 0x5f, 0x21, 0x67, 0x73,
+];
+
+/// Default UVC unit IDs observed on Insta360 Link family cameras when descriptors are not manually overridden.
+pub const DEFAULT_CONTROL_INTERFACE: u8 = 0;
+pub const DEFAULT_INPUT_TERMINAL_ID: u8 = 1;
+pub const DEFAULT_PROCESSING_UNIT_ID: u8 = 2;
+pub const DEFAULT_EXTENSION_UNIT_ID: u8 = 9;
+pub const DEFAULT_EXTENSION_UNIT2_ID: u8 = 10;
+
+/// Identified Insta360 Link camera model.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum CameraModel {
+    /// Insta360 Link (`0x4c01`)
+    Link,
+    /// Insta360 Link 2 (`0x4c04`)
+    Link2,
+    /// Insta360 Link 2C (`0x4c03`, gimbal-less 4K)
+    Link2C,
+    /// Insta360 PUC3 Gimbal (`0x4c02` / `0x4c06`)
+    Puc3Gimbal(u16),
+    /// Insta360 PUC3 Host (`0x4c05`)
+    Puc3Host,
+    /// Insta360 Link Simple-Class / DFU (`0x00c2`)
+    LinkSimpleClass,
+    /// Unknown Insta360 PID
+    Unknown(u16),
+}
+
+impl CameraModel {
+    pub fn from_pid(pid: u16) -> Self {
+        match pid {
+            pids::LINK_1 => Self::Link,
+            pids::LINK_2C => Self::Link2C,
+            pids::LINK_2 => Self::Link2,
+            pids::PUC3_GIMBAL_A | pids::PUC3_GIMBAL_B => Self::Puc3Gimbal(pid),
+            pids::PUC3_HOST => Self::Puc3Host,
+            pids::LINK_SIMPLE_CLASS => Self::LinkSimpleClass,
+            other => Self::Unknown(other),
+        }
+    }
+
+    pub fn pid(&self) -> u16 {
+        match *self {
+            Self::Link => pids::LINK_1,
+            Self::Link2C => pids::LINK_2C,
+            Self::Link2 => pids::LINK_2,
+            Self::Puc3Gimbal(pid) => pid,
+            Self::Puc3Host => pids::PUC3_HOST,
+            Self::LinkSimpleClass => pids::LINK_SIMPLE_CLASS,
+            Self::Unknown(pid) => pid,
+        }
+    }
+
+    /// Returns the internal model identifier used by `Webcam::CameraInsta::GetCameraModel()` (`0x10005f92c`).
+    pub fn internal_code(&self) -> &'static str {
+        match self {
+            Self::Link | Self::LinkSimpleClass => "link1",
+            Self::Link2C | Self::Puc3Host => "link2_main",
+            Self::Link2 | Self::Puc3Gimbal(_) => "link2_gimbal",
+            Self::Unknown(_) => "unknown",
+        }
+    }
+
+    /// Returns the human-readable display name.
+    pub fn display_name(&self) -> &'static str {
+        match self {
+            Self::Link => "Insta360 Link",
+            Self::Link2 => "Insta360 Link 2",
+            Self::Link2C => "Insta360 Link 2C",
+            Self::Puc3Gimbal(_) => "Insta360 Link 2 Pro (Gimbal)",
+            Self::Puc3Host => "Insta360 Link 2C Pro (Host)",
+            Self::LinkSimpleClass => "Insta360 Link (Firmware Mode)",
+            Self::Unknown(_) => "Insta360 UVC Camera",
+        }
+    }
+
+    /// Returns the target firmware filename on the camera's virtual MSC drive (`0x1001a0a0c`).
+    pub fn firmware_filename(&self) -> Option<&'static str> {
+        match self {
+            Self::Link | Self::LinkSimpleClass => Some(r"a:\Insta360WebCamFW.bin"),
+            Self::Link2 => Some(r"a:\Insta360LINK2FW_GIMBAL.bin"),
+            Self::Link2C => Some(r"a:\Insta360LINK2CFW_HOST.bin"),
+            Self::Puc3Gimbal(_) => Some(r"a:\Insta360PUC3FW_GIMBAL.bin"),
+            Self::Puc3Host => Some(r"a:\Insta360PUC3FW_HOST.bin"),
+            Self::Unknown(_) => None,
+        }
+    }
+
+    /// Whether this camera uses 36-byte extended `SetVideoMode` payloads (`0x1001970f4`: bitmask `0x2b` for `pid - 0x4c01`).
+    /// Wait: in `SetVideoMode` (`0x1001970f4`), if `len == 0x24` and `((1 << (pid - 0x4c01)) & 0x2b) != 0`
+    /// (`0x4c01`, `0x4c02`, `0x4c04`, `0x4c06` = bits 0, 1, 3, 5 = `0b101011` = `0x2b`),
+    /// it sends 8 bytes (`w4 = 8`) instead of 36 bytes (`0x24`), whereas `0x4c03` (Link 2C) and `0x4c05` (PUC3 Host)
+    /// send the full 36-byte `SetVideoMode` buffer!
+    pub fn video_mode_payload_len(&self) -> usize {
+        let pid = self.pid();
+        if (0x4c01..=0x4c06).contains(&pid) {
+            let bit = 1u32 << (pid - 0x4c01);
+            if (bit & 0x2b) != 0 {
+                return 8;
+            }
+        }
+        36
+    }
+}
+
+/// Hardware capability matrix derived from `Webcam::CameraDeviceSupporter::UpdateUIStatus` (`0x10004a8b8`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DeviceCapabilities {
+    pub has_physical_gimbal: bool,
+    pub support_ptz_drag: bool,
+    pub support_auto_framing: bool,
+    pub support_highlighting: bool,
+    pub support_mirror_vertically: bool,
+    pub support_track_speed: bool,
+    pub support_image_template: bool,
+    pub support_privacy_mode: bool,
+    pub support_area_track: bool,
+    pub support_roll_adjustment: bool,
+    pub support_ai_denoise: bool,
+    pub support_sound_wall: bool,
+    pub support_speak_tracking: bool,
+    pub support_auto_track: bool,
+    pub support_smart_adjustment: bool,
+    pub support_audio_capture_mode: bool,
+    pub support_horizontal_correction: bool,
+}
+
+impl DeviceCapabilities {
+    pub fn for_pid(pid: u16) -> Self {
+        let is_not_link2c_or_host = pid != pids::LINK_2C && pid != pids::PUC3_HOST;
+        let is_not_link1 = pid != pids::LINK_1;
+        let is_link2_or_puc3_gimbal = (pid & 0xfffd) == pids::LINK_2; // 0x4c04 or 0x4c06
+        let is_puc3 = pid == pids::PUC3_HOST || pid == pids::PUC3_GIMBAL_B;
+
+        Self {
+            has_physical_gimbal: is_not_link2c_or_host,
+            support_ptz_drag: is_not_link2c_or_host,
+            support_auto_framing: is_not_link1,
+            support_highlighting: is_not_link1,
+            support_mirror_vertically: is_not_link1,
+            support_track_speed: is_not_link2c_or_host,
+            support_image_template: is_not_link1,
+            support_privacy_mode: is_not_link1,
+            support_area_track: is_link2_or_puc3_gimbal,
+            support_roll_adjustment: pid == pids::LINK_1,
+            support_ai_denoise: is_not_link1,
+            support_sound_wall: is_puc3,
+            support_speak_tracking: is_link2_or_puc3_gimbal,
+            support_auto_track: is_not_link2c_or_host,
+            support_smart_adjustment: is_not_link2c_or_host,
+            support_audio_capture_mode: is_not_link1,
+            support_horizontal_correction: pid == pids::LINK_2,
+        }
+    }
+}
+
+/// Discovered UVC unit IDs and interface number for an Insta360 Link camera.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct UvcUnitIds {
+    pub control_interface: u8,
+    pub input_terminal_id: u8,
+    pub processing_unit_id: u8,
+    pub extension_unit_id: u8,
+    pub extension_unit2_id: u8,
+}
+
+impl Default for UvcUnitIds {
+    fn default() -> Self {
+        Self {
+            control_interface: DEFAULT_CONTROL_INTERFACE,
+            input_terminal_id: DEFAULT_INPUT_TERMINAL_ID,
+            processing_unit_id: DEFAULT_PROCESSING_UNIT_ID,
+            extension_unit_id: DEFAULT_EXTENSION_UNIT_ID,
+            extension_unit2_id: DEFAULT_EXTENSION_UNIT2_ID,
+        }
+    }
+}
+
+/// Parses raw USB configuration descriptor bytes to extract UVC Input Terminal, Processing Unit,
+/// and Insta360 Extension Unit 1 & 2 IDs (`FindControllerInterfaceForServiceObject` at `0x100190fe0`).
+pub fn parse_uvc_vc_descriptors(config_desc: &[u8]) -> UvcUnitIds {
+    let mut ids = UvcUnitIds::default();
+    let mut offset = 0usize;
+    let mut in_vc_interface = false;
+
+    while offset + 2 <= config_desc.len() {
+        let b_length = config_desc[offset] as usize;
+        let b_descriptor_type = config_desc[offset + 1];
+        if b_length < 2 || offset + b_length > config_desc.len() {
+            break;
+        }
+        let desc = &config_desc[offset..offset + b_length];
+
+        // USB_DT_INTERFACE = 0x04
+        if b_descriptor_type == 0x04 && desc.len() >= 9 {
+            let b_interface_number = desc[2];
+            let b_interface_class = desc[5];
+            let b_interface_subclass = desc[6];
+            // CC_VIDEO = 0x0e, SC_VIDEOCONTROL = 0x01
+            if b_interface_class == 0x0e && b_interface_subclass == 0x01 {
+                in_vc_interface = true;
+                ids.control_interface = b_interface_number;
+            } else {
+                in_vc_interface = false;
+            }
+        } else if in_vc_interface && b_descriptor_type == 0x24 && desc.len() >= 4 {
+            // CS_INTERFACE = 0x24
+            let b_descriptor_subtype = desc[2];
+            let unit_or_terminal_id = desc[3];
+            match b_descriptor_subtype {
+                // VC_INPUT_TERMINAL = 0x02
+                0x02 if desc.len() >= 6 => {
+                    let w_terminal_type = u16::from_le_bytes([desc[4], desc[5]]);
+                    // ITT_CAMERA = 0x0201
+                    if w_terminal_type == 0x0201 || ids.input_terminal_id == DEFAULT_INPUT_TERMINAL_ID {
+                        ids.input_terminal_id = unit_or_terminal_id;
+                    }
+                }
+                // VC_PROCESSING_UNIT = 0x05
+                0x05 => {
+                    ids.processing_unit_id = unit_or_terminal_id;
+                }
+                // VC_EXTENSION_UNIT = 0x06
+                0x06 if desc.len() >= 20 => {
+                    let guid = &desc[4..20];
+                    if guid == XU1_GUID_BYTES {
+                        ids.extension_unit_id = unit_or_terminal_id;
+                    } else if guid == XU2_GUID_BYTES {
+                        ids.extension_unit2_id = unit_or_terminal_id;
+                    }
+                }
+                _ => {}
+            }
+        }
+
+        offset += b_length;
+    }
+
+    ids
+}
+
+/// Returns true if a `(vendor_id, product_id)` pair is an Insta360 Link family device.
+pub fn is_insta360_link_device(vid: u16, pid: u16) -> bool {
+    vid == INSTA360_VENDOR_ID
+        && ((pids::LINK_1..=pids::PUC3_GIMBAL_B).contains(&pid) || pid == pids::LINK_SIMPLE_CLASS)
+}
@@ -0,0 +1,11 @@
+pub mod codec;
+pub mod controller;
+pub mod ids;
+pub mod transport;
+pub mod types;
+
+pub use codec::*;
+pub use controller::Insta360CameraController;
+pub use ids::*;
+pub use transport::{list_connected_cameras, MockCameraTransport, NusbTransport, TransportError, UvcControlTransport};
+pub use types::*;
@@ -0,0 +1,976 @@
+use crate::codec::UvcControlPacketHeader;
+use crate::ids::*;
+use crate::types::*;
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum TransportError {
+    #[error("USB error: {0}")]
+    Usb(String),
+    #[error("camera not found")]
+    DeviceNotFound,
+    #[error("UVC control unit {0} not available on this device")]
+    MissingUnit(&'static str),
+    #[error("codec error: {0}")]
+    Codec(#[from] crate::codec::CodecError),
+}
+
+/// Abstract cross-platform UVC Control Transfer transport.
+pub trait UvcControlTransport: Send + Sync {
+    /// Returns the discovered metadata for the connected camera.
+    fn camera_info(&self) -> &DiscoveredCamera;
+
+    /// Performs a UVC `SET_CUR` (`bmRequestType = 0x21`, `bRequest = 0x01`) control transfer.
+    fn set_cur(&self, unit_id: u8, selector: u8, data: &[u8]) -> Result<(), TransportError>;
+
+    /// Performs a UVC `GET_*` (`bmRequestType = 0xa1`, `bRequest = 0x81..0x87`) control transfer.
+    fn get_req(
+        &self,
+        req: UvcRequest,
+        unit_id: u8,
+        selector: u8,
+        len: usize,
+    ) -> Result<Vec<u8>, TransportError>;
+
+    /// Queries `GET_LEN` (`0x85`) for a variable-length UVC control selector.
+    fn get_len(&self, unit_id: u8, selector: u8) -> Result<u16, TransportError> {
+        let bytes = self.get_req(UvcRequest::GetLen, unit_id, selector, 2)?;
+        if bytes.len() < 2 {
+            return Ok(0);
+        }
+        Ok(u16::from_le_bytes([bytes[0], bytes[1]]))
+    }
+}
+
+/// Enumerates all connected Insta360 Link family cameras across Linux, Windows, and macOS using `nusb`.
+pub fn list_connected_cameras() -> Result<Vec<DiscoveredCamera>, TransportError> {
+    let devices = nusb::list_devices().map_err(|e| TransportError::Usb(e.to_string()))?;
+    let mut out = Vec::new();
+    for dev in devices {
+        let vid = dev.vendor_id();
+        let pid = dev.product_id();
+        if !is_insta360_link_device(vid, pid) {
+            continue;
+        }
+        let model = CameraModel::from_pid(pid);
+        let name = dev
+            .product_string()
+            .map(|s| s.to_string())
+            .unwrap_or_else(|| model.display_name().to_string());
+        let bus = dev.bus_number();
+        let addr = dev.device_address();
+        let unique_id = format!("0x{:02x}{:02x}{:04x}{:04x}", bus, addr, vid, pid);
+
+        let mut unit_ids = UvcUnitIds::default();
+        if let Ok(opened) = dev.open() {
+            if let Ok(active_cfg) = opened.active_configuration() {
+                // Parse raw configuration descriptor bytes to find exact UVC unit IDs
+                let raw: &[u8] = active_cfg.descriptors().as_bytes();
+                unit_ids = parse_uvc_vc_descriptors(raw);
+            }
+        }
+
+        out.push(DiscoveredCamera {
+            vendor_id: vid,
+            product_id: pid,
+            model,
+            name,
+            unique_id,
+            bus_number: bus,
+            device_address: addr,
+            unit_ids,
+            capabilities: DeviceCapabilities::for_pid(pid),
+        });
+    }
+    Ok(out)
+}
+
+/// Pure-Rust cross-platform USB hardware transport backed by `nusb`
+/// (Linux `uvcvideo` `UVCIOC_CTRL_QUERY` + `usbfs`, Windows `WinUSB`, macOS `IOKit`).
+pub struct NusbTransport {
+    info: DiscoveredCamera,
+    device: nusb::Device,
+    interface: Option<nusb::Interface>,
+    #[cfg(target_os = "linux")]
+    v4l_file: Option<std::fs::File>,
+    timeout: Duration,
+}
+
+#[cfg(target_os = "linux")]
+fn open_linux_v4l2_node(vid: u16, pid: u16) -> Option<std::fs::File> {
+    let vid_hex = format!("{:04x}", vid);
+    let pid_hex = format!("{:04x}", pid);
+    let entries = std::fs::read_dir("/sys/class/video4linux").ok()?;
+    for entry in entries.flatten() {
+        let name = entry.file_name().to_string_lossy().to_string();
+        if !name.starts_with("video") {
+            continue;
+        }
+        let dev_link = entry.path().join("device");
+        let Ok(canon) = std::fs::canonicalize(&dev_link) else {
+            continue;
+        };
+        // Parent directory of the USB interface (`B-P:1.0`) holds `idVendor` and `idProduct`.
+        if let Some(usb_dev_dir) = canon.parent() {
+            let v = std::fs::read_to_string(usb_dev_dir.join("idVendor"))
+                .unwrap_or_default()
+                .trim()
+                .to_lowercase();
+            let p = std::fs::read_to_string(usb_dev_dir.join("idProduct"))
+                .unwrap_or_default()
+                .trim()
+                .to_lowercase();
+            if v == vid_hex && p == pid_hex {
+                let dev_path = format!("/dev/{}", name);
+                if let Ok(file) = std::fs::OpenOptions::new()
+                    .read(true)
+                    .write(true)
+                    .open(&dev_path)
+                {
+                    return Some(file);
+                }
+            }
+        }
+    }
+    None
+}
+
+#[cfg(target_os = "linux")]
+#[repr(C)]
+struct LinuxUvcXuControlQuery {
+    unit: u8,
+    selector: u8,
+    query: u8,
+    size: u16,
+    data: *mut u8,
+}
+
+#[cfg(target_os = "linux")]
+const UVCIOC_CTRL_QUERY: libc::c_ulong = 0xC010_7521;
+
+#[cfg(target_os = "linux")]
+fn linux_uvcioc_ctrl_query(
+    file: &std::fs::File,
+    unit: u8,
+    selector: u8,
+    query: u8,
+    buf: &mut [u8],
+) -> Result<(), TransportError> {
+    use std::os::unix::io::AsRawFd;
+    let mut q = LinuxUvcXuControlQuery {
+        unit,
+        selector,
+        query,
+        size: buf.len() as u16,
+        data: buf.as_mut_ptr(),
+    };
+    let rc = unsafe { libc::ioctl(file.as_raw_fd(), UVCIOC_CTRL_QUERY, &mut q) };
+    if rc < 0 {
+        Err(TransportError::Usb(
+            std::io::Error::last_os_error().to_string(),
+        ))
+    } else {
+        Ok(())
+    }
+}
+
+impl NusbTransport {
+    pub fn open_first() -> Result<Self, TransportError> {
+        let cameras = list_connected_cameras()?;
+        let first = cameras.into_iter().next().ok_or(TransportError::DeviceNotFound)?;
+        Self::open_by_info(first)
+    }
+
+    pub fn open_by_info(mut info: DiscoveredCamera) -> Result<Self, TransportError> {
+        let dev_info = nusb::list_devices()
+            .map_err(|e| TransportError::Usb(e.to_string()))?
+            .find(|d| {
+                d.vendor_id() == info.vendor_id
+                    && d.product_id() == info.product_id
+                    && d.bus_number() == info.bus_number
+                    && d.device_address() == info.device_address
+            })
+            .ok_or(TransportError::DeviceNotFound)?;
+
+        let device = dev_info.open().map_err(|e| TransportError::Usb(e.to_string()))?;
+        if let Ok(cfg) = device.active_configuration() {
+            let raw: &[u8] = cfg.descriptors().as_bytes();
+            info.unit_ids = parse_uvc_vc_descriptors(raw);
+        }
+
+        // Claim the UVC VideoControl interface without detaching the OS kernel UVC video streaming
+        // driver (`uvcvideo` on Linux, `UVCAssistant` on macOS, `usbvideo.sys` on Windows) so that
+        // live webcam video capture and UVC/XU control transfers operate simultaneously.
+        let interface = device
+            .claim_interface(info.unit_ids.control_interface)
+            .ok();
+
+        #[cfg(target_os = "linux")]
+        let v4l_file = open_linux_v4l2_node(info.vendor_id, info.product_id);
+
+        Ok(Self {
+            info,
+            device,
+            interface,
+            #[cfg(target_os = "linux")]
+            v4l_file,
+            timeout: Duration::from_millis(1500),
+        })
+    }
+}
+
+impl UvcControlTransport for NusbTransport {
+    fn camera_info(&self) -> &DiscoveredCamera {
+        &self.info
+    }
+
+    fn set_cur(&self, unit_id: u8, selector: u8, data: &[u8]) -> Result<(), TransportError> {
+        let is_xu = unit_id == self.info.unit_ids.extension_unit_id
+            || unit_id == self.info.unit_ids.extension_unit2_id;
+
+        // Match `MacUVCCameraExtendController::SendCommand` (`0x100195db4`): query `GET_LEN (0x85)`
+        // for Extension Unit selectors and zero-pad the payload to the descriptor's exact wLength.
+        let padded_buf: Vec<u8>;
+        let payload: &[u8] = if is_xu {
+            if let Ok(uvc_len) = self.get_len(unit_id, selector) {
+                let target_len = uvc_len as usize;
+                if target_len > 0 && target_len != data.len() {
+                    let mut b = vec![0u8; target_len];
+                    let copy_n = data.len().min(target_len);
+                    b[..copy_n].copy_from_slice(&data[..copy_n]);
+                    padded_buf = b;
+                    &padded_buf
+                } else {
+                    data
+                }
+            } else {
+                data
+            }
+        } else {
+            data
+        };
+
+        #[cfg(target_os = "linux")]
+        if let Some(v4l) = &self.v4l_file {
+            let mut buf = payload.to_vec();
+            if linux_uvcioc_ctrl_query(v4l, unit_id, selector, UvcRequest::SetCur as u8, &mut buf)
+                .is_ok()
+            {
+                return Ok(());
+            }
+        }
+
+        let hdr = UvcControlPacketHeader::new(
+            UvcRequest::SetCur,
+            selector,
+            unit_id,
+            self.info.unit_ids.control_interface,
+        );
+        let control = nusb::transfer::Control {
+            control_type: nusb::transfer::ControlType::Class,
+            recipient: nusb::transfer::Recipient::Interface,
+            request: hdr.b_request,
+            value: hdr.w_value,
+            index: hdr.w_index,
+        };
+        if let Some(iface) = &self.interface {
+            iface
+                .control_out_blocking(control, payload, self.timeout)
+                .map(|_| ())
+                .map_err(|e| TransportError::Usb(e.to_string()))
+        } else {
+            #[cfg(not(target_os = "windows"))]
+            {
+                self.device
+                    .control_out_blocking(control, payload, self.timeout)
+                    .map(|_| ())
+                    .map_err(|e| TransportError::Usb(e.to_string()))
+            }
+            #[cfg(target_os = "windows")]
+            {
+                Err(TransportError::Usb(
+                    "UVC control interface could not be claimed on Windows".to_string(),
+                ))
+            }
+        }
+    }
+
+    fn get_req(
+        &self,
+        req: UvcRequest,
+        unit_id: u8,
+        selector: u8,
+        len: usize,
+    ) -> Result<Vec<u8>, TransportError> {
+        let is_xu = unit_id == self.info.unit_ids.extension_unit_id
+            || unit_id == self.info.unit_ids.extension_unit2_id;
+
+        // Match `MacUVCCameraExtendController::GetCommand` (`0x1001963d0`): query `GET_LEN (0x85)`
+        // first on Extension Unit `GET_CUR` requests so the buffer matches the firmware's wLength.
+        let actual_len = if is_xu && req == UvcRequest::GetCur {
+            match self.get_len(unit_id, selector) {
+                Ok(uvc_len) if uvc_len > 0 => uvc_len as usize,
+                _ => len,
+            }
+        } else {
+            len
+        };
+
+        #[cfg(target_os = "linux")]
+        if let Some(v4l) = &self.v4l_file {
+            let mut buf = vec![0u8; actual_len];
+            if linux_uvcioc_ctrl_query(v4l, unit_id, selector, req as u8, &mut buf).is_ok() {
+                return Ok(buf);
+            }
+        }
+
+        let hdr = UvcControlPacketHeader::new(
+            req,
+            selector,
+            unit_id,
+            self.info.unit_ids.control_interface,
+        );
+        let mut buf = vec![0u8; actual_len];
+        let control = nusb::transfer::Control {
+            control_type: nusb::transfer::ControlType::Class,
+            recipient: nusb::transfer::Recipient::Interface,
+            request: hdr.b_request,
+            value: hdr.w_value,
+            index: hdr.w_index,
+        };
+        let n = if let Some(iface) = &self.interface {
+            iface
+                .control_in_blocking(control, &mut buf, self.timeout)
+                .map_err(|e| TransportError::Usb(e.to_string()))?
+        } else {
+            #[cfg(not(target_os = "windows"))]
+            {
+                self.device
+                    .control_in_blocking(control, &mut buf, self.timeout)
+                    .map_err(|e| TransportError::Usb(e.to_string()))?
+            }
+            #[cfg(target_os = "windows")]
+            {
+                return Err(TransportError::Usb(
+                    "UVC control interface could not be claimed on Windows".to_string(),
+                ));
+            }
+        };
+        buf.truncate(n);
+        Ok(buf)
+    }
+}
+
+/// Stateful in-memory simulated Insta360 Link / Link 2 / Link 2C camera transport.
+/// Ideal for testing, CI, and interactive GUI exploration when no physical webcam is plugged in.
+#[derive(Clone)]
+pub struct MockCameraTransport {
+    info: DiscoveredCamera,
+    state: Arc<Mutex<MockState>>,
+}
+
+#[derive(Debug, Clone)]
+struct MockState {
+    registers: HashMap<(u8, u8), Vec<u8>>,
+    pan_arcsec: i32,
+    tilt_arcsec: i32,
+    zoom: u16,
+    roll: i16,
+    focus: u16,
+    auto_focus: bool,
+    brightness: i16,
+    contrast: u16,
+    saturation: u16,
+    sharpness: u16,
+    wb_kelvin: u16,
+    wb_auto: bool,
+    power_line: u8,
+    shutter: u32,
+    extend_bits: u32,
+    video_mode: u8,
+    video_aux: [u8; 36],
+    track_speed: u8,
+    composition_style: u8,
+    gestures: [u8; 6],
+    audio_denoise: bool,
+    audio_mode: u8,
+    ev_comp: f32,
+    iso: u16,
+    auto_exposure: bool,
+    filter_mode: u8,
+    privacy_mode: bool,
+    horiz_correction: bool,
+    default_track_mode: u8,
+    preset_mask: u8,
+    current_preset: u8,
+    template_mask: u64,
+    current_template: i8,
+    template_names: HashMap<i8, String>,
+    gesture_bindings: [u8; 5],
+    forbidden_areas: Vec<u8>,
+    command_log: Vec<(UvcRequest, u8, u8, Vec<u8>)>,
+}
+
+impl MockCameraTransport {
+    pub fn new(model: CameraModel) -> Self {
+        let pid = model.pid();
+        let unit_ids = UvcUnitIds::default();
+        let info = DiscoveredCamera {
+            vendor_id: INSTA360_VENDOR_ID,
+            product_id: pid,
+            model,
+            name: format!("{} (Simulated)", model.display_name()),
+            unique_id: format!("mock-0x{:04x}-0x{:04x}", INSTA360_VENDOR_ID, pid),
+            bus_number: 1,
+            device_address: 2,
+            unit_ids,
+            capabilities: DeviceCapabilities::for_pid(pid),
+        };
+        let mut video_aux = [0u8; 36];
+        video_aux[20..22].copy_from_slice(&100u16.to_le_bytes());
+        let state = MockState {
+            registers: HashMap::new(),
+            pan_arcsec: 0,
+            tilt_arcsec: 0,
+            zoom: 100,
+            roll: 0,
+            focus: 50,
+            auto_focus: true,
+            brightness: 50,
+            contrast: 50,
+            saturation: 50,
+            sharpness: 50,
+            wb_kelvin: 5000,
+            wb_auto: true,
+            power_line: 2, // 60Hz
+            shutter: 200,
+            extend_bits: (1 << (ExtendFunction::AutoTracking as u8))
+                | (1 << (ExtendFunction::AllGestures as u8)),
+            video_mode: VideoMode::Normal as u8,
+            video_aux,
+            track_speed: TrackSpeed::Normal as u8,
+            composition_style: CompositionStyle::HalfBody as u8,
+            gestures: [1, 1, 1, 1, 1, 0],
+            audio_denoise: true,
+            audio_mode: AudioCaptureMode::VoiceFocus as u8,
+            ev_comp: 0.0,
+            iso: 100,
+            auto_exposure: true,
+            filter_mode: 0,
+            privacy_mode: false,
+            horiz_correction: pid == pids::LINK_2,
+            default_track_mode: 0,
+            preset_mask: 0b0000_0011,
+            current_preset: 0,
+            template_mask: 0b0000_0010,
+            current_template: 1,
+            template_names: HashMap::from([(1, "Studio Warm".to_string())]),
+            gesture_bindings: [
+                GestureFunction::None as u8,
+                GestureFunction::AutoTracking as u8,
+                GestureFunction::Zoom as u8,
+                GestureFunction::WhiteBoard as u8,
+                GestureFunction::AutoFraming as u8,
+            ],
+            forbidden_areas: vec![0u8; 40],
+            command_log: Vec::new(),
+        };
+        Self {
+            info,
+            state: Arc::new(Mutex::new(state)),
+        }
+    }
+
+    pub fn command_log(&self) -> Vec<(UvcRequest, u8, u8, Vec<u8>)> {
+        self.state.lock().unwrap().command_log.clone()
+    }
+}
+
+impl UvcControlTransport for MockCameraTransport {
+    fn camera_info(&self) -> &DiscoveredCamera {
+        &self.info
+    }
+
+    fn set_cur(&self, unit_id: u8, selector: u8, data: &[u8]) -> Result<(), TransportError> {
+        let mut st = self.state.lock().unwrap();
+        st.command_log
+            .push((UvcRequest::SetCur, unit_id, selector, data.to_vec()));
+        st.registers.insert((unit_id, selector), data.to_vec());
+
+        let ids = self.info.unit_ids;
+        if unit_id == ids.input_terminal_id {
+            match selector {
+                ct_selectors::ZOOM_ABSOLUTE if data.len() >= 2 => {
+                    st.zoom = u16::from_le_bytes([data[0], data[1]]);
+                }
+                ct_selectors::PANTILT_ABSOLUTE if data.len() >= 8 => {
+                    st.pan_arcsec = i32::from_le_bytes([data[0], data[1], data[2], data[3]]);
+                    st.tilt_arcsec = i32::from_le_bytes([data[4], data[5], data[6], data[7]]);
+                }
+                ct_selectors::PANTILT_RELATIVE if data.len() >= 4 => {
+                    let pan_dir = data[0] as i8;
+                    let pan_spd = data[1] as i32;
+                    let tilt_dir = data[2] as i8;
+                    let tilt_spd = data[3] as i32;
+                    st.pan_arcsec = (st.pan_arcsec + (pan_dir as i32) * pan_spd * 3600).clamp(-468000, 468000);
+                    st.tilt_arcsec = (st.tilt_arcsec + (tilt_dir as i32) * tilt_spd * 3600).clamp(-324000, 324000);
+                }
+                ct_selectors::ROLL_ABSOLUTE if data.len() >= 2 => {
+                    st.roll = i16::from_le_bytes([data[0], data[1]]);
+                }
+                ct_selectors::FOCUS_ABSOLUTE if data.len() >= 2 => {
+                    st.focus = u16::from_le_bytes([data[0], data[1]]);
+                }
+                ct_selectors::FOCUS_AUTO if !data.is_empty() => {
+                    st.auto_focus = data[0] != 0;
+                }
+                ct_selectors::EXPOSURE_TIME_ABSOLUTE if data.len() >= 4 => {
+                    st.shutter = u32::from_le_bytes([data[0], data[1], data[2], data[3]]);
+                }
+                _ => {}
+            }
+        } else if unit_id == ids.processing_unit_id {
+            match selector {
+                pu_selectors::BRIGHTNESS if data.len() >= 2 => {
+                    st.brightness = i16::from_le_bytes([data[0], data[1]]);
+                }
+                pu_selectors::CONTRAST if data.len() >= 2 => {
+                    st.contrast = u16::from_le_bytes([data[0], data[1]]);
+                }
+                pu_selectors::SATURATION if data.len() >= 2 => {
+                    st.saturation = u16::from_le_bytes([data[0], data[1]]);
+                }
+                pu_selectors::SHARPNESS if data.len() >= 2 => {
+                    st.sharpness = u16::from_le_bytes([data[0], data[1]]);
+                }
+                pu_selectors::WHITE_BALANCE_TEMPERATURE if data.len() >= 2 => {
+                    st.wb_kelvin = u16::from_le_bytes([data[0], data[1]]);
+                }
+                pu_selectors::WHITE_BALANCE_TEMPERATURE_AUTO if !data.is_empty() => {
+                    st.wb_auto = data[0] != 0;
+                }
+                pu_selectors::POWER_LINE_FREQUENCY if !data.is_empty() => {
+                    st.power_line = data[0];
+                }
+                _ => {}
+            }
+        } else if unit_id == ids.extension_unit_id {
+            match selector {
+                xu1_selectors::SYSTEM_AND_PRESET_CMD if data.len() >= 2 => match data[0] {
+                    0 => st.current_preset = data[1],
+                    1 => {
+                        st.preset_mask |= 1 << (data[1] & 7);
+                        st.current_preset = data[1];
+                    }
+                    2 => st.preset_mask &= !(1 << (data[1] & 7)),
+                    3 => {
+                        st.pan_arcsec = 0;
+                        st.tilt_arcsec = 0;
+                        st.zoom = 100;
+                        st.roll = 0;
+                    }
+                    4 => {
+                        st.brightness = 50;
+                        st.contrast = 50;
+                        st.saturation = 50;
+                        st.sharpness = 50;
+                        st.wb_auto = true;
+                        st.auto_exposure = true;
+                        st.video_mode = 0;
+                    }
+                    _ => {}
+                },
+                xu1_selectors::VIDEO_MODE if !data.is_empty() => {
+                    st.video_mode = data[0];
+                    if data.len() == 8 {
+                        st.video_aux[0] = data[0];
+                        st.video_aux[1] = data[1];
+                        st.video_aux[18..20].copy_from_slice(&data[2..4]);
+                        st.video_aux[20..22].copy_from_slice(&data[4..6]);
+                    } else {
+                        let copy_len = data.len().min(36);
+                        st.video_aux[..copy_len].copy_from_slice(&data[..copy_len]);
+                    }
+                }
+                xu1_selectors::TRACKING_AND_GESTURE if data.len() >= 2 => match data[0] {
+                    0 => st.gestures[0] = data[1],
+                    1 if data.len() >= 6 => st.gestures.copy_from_slice(&data[..6]),
+                    5 => st.track_speed = data[1],
+                    6 => st.composition_style = data[1],
+                    _ => {}
+                },
+                xu1_selectors::AUDIO_CONTROL if !data.is_empty() => {
+                    st.audio_mode = data[0];
+                    if data[0] <= 1 {
+                        st.audio_denoise = data[0] != 0;
+                    }
+                }
+                xu1_selectors::EXPOSURE_CURVE_AND_ISO if data.len() >= 3 => {
+                    st.auto_exposure = data[0] != 0;
+                    st.iso = u16::from_le_bytes([data[1], data[2]]);
+                }
+                xu1_selectors::EXPOSURE_COMPENSATION if data.len() >= 4 => {
+                    st.ev_comp = f32::from_le_bytes([data[0], data[1], data[2], data[3]]);
+                }
+                xu1_selectors::EXTEND_FUNC_BITMASK if data.len() >= 8 => {
+                    st.extend_bits = u32::from_le_bytes([data[4], data[5], data[6], data[7]]);
+                }
+                xu1_selectors::PANTILT_RELATIVE_EXT if data.len() >= 4 => {
+                    let pan_spd = data[0] as i32;
+                    let pan_dir = data[1] as i8 as i32;
+                    let tilt_spd = data[2] as i32;
+                    let tilt_dir = data[3] as i8 as i32;
+                    st.pan_arcsec = (st.pan_arcsec + pan_dir * pan_spd * 3600).clamp(-468000, 468000);
+                    st.tilt_arcsec = (st.tilt_arcsec + tilt_dir * tilt_spd * 3600).clamp(-324000, 324000);
+                }
+                _ => {}
+            }
+        } else if unit_id == ids.extension_unit2_id {
+            match selector {
+                xu2_selectors::GESTURE_BINDING_MAP if data.len() >= 2 => {
+                    let g = data[0] as usize;
+                    if g < 5 {
+                        st.gesture_bindings[g] = data[1];
+                    }
+                }
+                xu2_selectors::TRACK_FORBIDDEN_AREA if !data.is_empty() => {
+                    st.forbidden_areas = data.to_vec();
+                }
+                xu2_selectors::IMAGE_TEMPLATE_INFO if data.len() >= 11 => {
+                    st.current_template = data[0] as i8;
+                    st.template_mask = u64::from_le_bytes(data[2..10].try_into().unwrap());
+                }
+                xu2_selectors::IMAGE_TEMPLATE_NAME if data.len() >= 2 => {
+                    let id = data[0] as i8;
+                    let end = data[1..].iter().position(|&b| b == 0).unwrap_or(data.len() - 1);
+                    let name = String::from_utf8_lossy(&data[1..1 + end]).to_string();
+                    st.template_names.insert(id, name);
+                }
+                xu2_selectors::FILTER_MODE if !data.is_empty() => {
+                    st.filter_mode = data[0];
+                }
+                xu2_selectors::PRIVACY_AND_FILL_LIGHT if data.len() >= 2 => {
+                    if data[0] == 2 {
+                        st.privacy_mode = data[1] != 0;
+                    }
+                }
+                xu2_selectors::DEFAULT_TRACK_MODE if !data.is_empty() => {
+                    st.default_track_mode = data[0];
+                }
+                xu2_selectors::HORIZONTAL_CORRECTION if !data.is_empty() => {
+                    st.horiz_correction = data[0] != 0;
+                }
+                _ => {}
+            }
+        }
+
+        Ok(())
+    }
+
+    fn get_req(
+        &self,
+        req: UvcRequest,
+        unit_id: u8,
+        selector: u8,
+        len: usize,
+    ) -> Result<Vec<u8>, TransportError> {
+        let st = self.state.lock().unwrap();
+        let ids = self.info.unit_ids;
+
+        if req == UvcRequest::GetLen {
+            let l: u16 = if unit_id == ids.extension_unit_id {
+                match selector {
+                    xu1_selectors::SYSTEM_AND_PRESET_CMD => 4,
+                    xu1_selectors::VIDEO_MODE => 36,
+                    xu1_selectors::TRACKING_AND_GESTURE => 16,
+                    xu1_selectors::AUDIO_CONTROL => 2,
+                    xu1_selectors::TRACK_OBJECT_SELECT => 10,
+                    xu1_selectors::TRACK_OBJECT_LIST_V1 => 20,
+                    xu1_selectors::EXPOSURE_CURVE_AND_ISO => 259,
+                    xu1_selectors::EXPOSURE_COMPENSATION => 4,
+                    xu1_selectors::WHITE_BALANCE_EXT => 129,
+                    xu1_selectors::EXTEND_FUNC_BITMASK => 8,
+                    xu1_selectors::PANTILT_RELATIVE_EXT => 4,
+                    xu1_selectors::DEVICE_STATUS => 4,
+                    xu1_selectors::PTZ_VERSION_AND_ABS => 30,
+                    xu1_selectors::PRESET_POSITION_FLAGS => 8,
+                    _ => len as u16,
+                }
+            } else if unit_id == ids.extension_unit2_id {
+                match selector {
+                    xu2_selectors::GESTURE_BINDING_MAP => 16,
+                    xu2_selectors::SYSTEM_TIME_AND_IQ => 10,
+                    xu2_selectors::DEVICE_INFO => 150,
+                    xu2_selectors::IMAGE_TEMPLATE_INFO => 11,
+                    xu2_selectors::IMAGE_TEMPLATE_NAME => 65,
+                    xu2_selectors::FILTER_MODE => 1,
+                    xu2_selectors::PRIVACY_AND_FILL_LIGHT => 4,
+                    xu2_selectors::HOST_PTZ => 8,
+                    xu2_selectors::TRACK_OBJECT_LIST_V2 => 20,
+                    xu2_selectors::TRACK_FORBIDDEN_AREA => 40,
+                    xu2_selectors::DEFAULT_TRACK_MODE => 1,
+                    xu2_selectors::HORIZONTAL_CORRECTION => 1,
+                    xu2_selectors::REAL_ZOOM_AND_UDISK => 4,
+                    _ => len as u16,
+                }
+            } else {
+                len as u16
+            };
+            return Ok(l.to_le_bytes().to_vec());
+        }
+
+        if unit_id == ids.input_terminal_id {
+            match selector {
+                ct_selectors::ZOOM_ABSOLUTE => {
+                    let v: u16 = match req {
+                        UvcRequest::GetMin => 100,
+                        UvcRequest::GetMax => 400,
+                        UvcRequest::GetRes => 1,
+                        UvcRequest::GetDef => 100,
+                        _ => st.zoom,
+                    };
+                    return Ok(v.to_le_bytes().to_vec());
+                }
+                ct_selectors::PANTILT_ABSOLUTE => {
+                    let (p, t): (i32, i32) = match req {
+                        UvcRequest::GetMin => (-468000, -324000),
+                        UvcRequest::GetMax => (468000, 324000),
+                        UvcRequest::GetRes => (3600, 3600),
+                        UvcRequest::GetDef => (0, 0),
+                        _ => (st.pan_arcsec, st.tilt_arcsec),
+                    };
+                    let mut out = [0u8; 8];
+                    out[0..4].copy_from_slice(&p.to_le_bytes());
+                    out[4..8].copy_from_slice(&t.to_le_bytes());
+                    return Ok(out.to_vec());
+                }
+                ct_selectors::ROLL_ABSOLUTE => {
+                    let v: i16 = match req {
+                        UvcRequest::GetMin => -1800,
+                        UvcRequest::GetMax => 1800,
+                        UvcRequest::GetRes => 1,
+                        UvcRequest::GetDef => 0,
+                        _ => st.roll,
+                    };
+                    return Ok(v.to_le_bytes().to_vec());
+                }
+                ct_selectors::FOCUS_ABSOLUTE => {
+                    let v: u16 = match req {
+                        UvcRequest::GetMin => 0,
+                        UvcRequest::GetMax => 100,
+                        UvcRequest::GetRes => 1,
+                        UvcRequest::GetDef => 50,
+                        _ => st.focus,
+                    };
+                    return Ok(v.to_le_bytes().to_vec());
+                }
+                ct_selectors::FOCUS_AUTO => {
+                    return Ok(vec![u8::from(st.auto_focus)]);
+                }
+                ct_selectors::EXPOSURE_TIME_ABSOLUTE => {
+                    let v: u32 = match req {
+                        UvcRequest::GetMin => 10,
+                        UvcRequest::GetMax => 1000,
+                        UvcRequest::GetRes => 1,
+                        UvcRequest::GetDef => 200,
+                        _ => st.shutter,
+                    };
+                    return Ok(v.to_le_bytes().to_vec());
+                }
+                _ => {}
+            }
+        } else if unit_id == ids.processing_unit_id {
+            match selector {
+                pu_selectors::BRIGHTNESS => {
+                    let v: i16 = match req {
+                        UvcRequest::GetMin => 0,
+                        UvcRequest::GetMax => 100,
+                        UvcRequest::GetRes => 1,
+                        UvcRequest::GetDef => 50,
+                        _ => st.brightness,
+                    };
+                    return Ok(v.to_le_bytes().to_vec());
+                }
+                pu_selectors::CONTRAST => {
+                    let v: u16 = match req {
+                        UvcRequest::GetMin => 0,
+                        UvcRequest::GetMax => 100,
+                        UvcRequest::GetRes => 1,
+                        UvcRequest::GetDef => 50,
+                        _ => st.contrast,
+                    };
+                    return Ok(v.to_le_bytes().to_vec());
+                }
+                pu_selectors::SATURATION => {
+                    let v: u16 = match req {
+                        UvcRequest::GetMin => 0,
+                        UvcRequest::GetMax => 100,
+                        UvcRequest::GetRes => 1,
+                        UvcRequest::GetDef => 50,
+                        _ => st.saturation,
+                    };
+                    return Ok(v.to_le_bytes().to_vec());
+                }
+                pu_selectors::SHARPNESS => {
+                    let v: u16 = match req {
+                        UvcRequest::GetMin => 0,
+                        UvcRequest::GetMax => 100,
+                        UvcRequest::GetRes => 1,
+                        UvcRequest::GetDef => 50,
+                        _ => st.sharpness,
+                    };
+                    return Ok(v.to_le_bytes().to_vec());
+                }
+                pu_selectors::WHITE_BALANCE_TEMPERATURE => {
+                    let v: u16 = match req {
+                        UvcRequest::GetMin => 2000,
+                        UvcRequest::GetMax => 10000,
+                        UvcRequest::GetRes => 50,
+                        UvcRequest::GetDef => 5000,
+                        _ => st.wb_kelvin,
+                    };
+                    return Ok(v.to_le_bytes().to_vec());
+                }
+                pu_selectors::WHITE_BALANCE_TEMPERATURE_AUTO => {
+                    return Ok(vec![u8::from(st.wb_auto)]);
+                }
+                pu_selectors::POWER_LINE_FREQUENCY => {
+                    return Ok(vec![st.power_line]);
+                }
+                _ => {}
+            }
+        } else if unit_id == ids.extension_unit_id {
+            match selector {
+                xu1_selectors::VIDEO_MODE => {
+                    let mut out = st.video_aux;
+                    out[0] = st.video_mode;
+                    return Ok(out.to_vec());
+                }
+                xu1_selectors::TRACKING_AND_GESTURE => {
+                    let mut out = [0u8; 16];
+                    out[..6].copy_from_slice(&st.gestures);
+                    out[6] = st.track_speed;
+                    out[7] = st.composition_style;
+                    return Ok(out.to_vec());
+                }
+                xu1_selectors::AUDIO_CONTROL => {
+                    return Ok(vec![st.audio_mode, u8::from(st.audio_denoise)]);
+                }
+                xu1_selectors::EXPOSURE_CURVE_AND_ISO => {
+                    let mut out = vec![0u8; 259];
+                    out[0] = u8::from(st.auto_exposure);
+                    out[1..3].copy_from_slice(&st.iso.to_le_bytes());
+                    return Ok(out);
+                }
+                xu1_selectors::EXPOSURE_COMPENSATION => {
+                    return Ok(st.ev_comp.to_le_bytes().to_vec());
+                }
+                xu1_selectors::EXTEND_FUNC_BITMASK => {
+                    let mut out = [0u8; 8];
+                    out[0..4].copy_from_slice(&0xffff_ffffu32.to_le_bytes());
+                    out[4..8].copy_from_slice(&st.extend_bits.to_le_bytes());
+                    return Ok(out.to_vec());
+                }
+                xu1_selectors::PANTILT_RELATIVE_EXT => {
+                    return Ok(vec![1, 10, 1, 10]);
+                }
+                xu1_selectors::DEVICE_STATUS => {
+                    let mut flags = 0u32;
+                    if st.video_mode == VideoMode::AutoTracking as u8 {
+                        flags |= DeviceStatus::TRACKING_ACTIVE.bits();
+                    }
+                    if st.privacy_mode {
+                        flags |= DeviceStatus::PRIVACY_SLEEP.bits();
+                    }
+                    return Ok(flags.to_le_bytes().to_vec());
+                }
+                xu1_selectors::PTZ_VERSION_AND_ABS => {
+                    let mut out = [0u8; 30];
+                    let ver = b"v1.3.1.0_build0";
+                    out[..ver.len()].copy_from_slice(ver);
+                    let pan_deg10 = (st.pan_arcsec / 360) as i16;
+                    let tilt_deg10 = (st.tilt_arcsec / 360) as i16;
+                    out[20..22].copy_from_slice(&pan_deg10.to_le_bytes());
+                    out[22..24].copy_from_slice(&tilt_deg10.to_le_bytes());
+                    out[24..26].copy_from_slice(&st.zoom.to_le_bytes());
+                    return Ok(out.to_vec());
+                }
+                xu1_selectors::PRESET_POSITION_FLAGS => {
+                    let mut out = [0u8; 8];
+                    out[0] = st.preset_mask;
+                    out[1] = st.current_preset;
+                    out[2] = 6;
+                    return Ok(out.to_vec());
+                }
+                _ => {}
+            }
+        } else if unit_id == ids.extension_unit2_id {
+            match selector {
+                xu2_selectors::GESTURE_BINDING_MAP => {
+                    let mut out = [0u8; 16];
+                    out[..5].copy_from_slice(&st.gesture_bindings);
+                    return Ok(out.to_vec());
+                }
+                xu2_selectors::TRACK_FORBIDDEN_AREA => {
+                    return Ok(st.forbidden_areas.clone());
+                }
+                xu2_selectors::DEVICE_INFO => {
+                    let mut out = [0u8; 150];
+                    let name = self.info.model.display_name().as_bytes();
+                    out[..name.len().min(49)].copy_from_slice(&name[..name.len().min(49)]);
+                    let fw = b"v2.5.8.8_build1";
+                    out[50..50 + fw.len()].copy_from_slice(fw);
+                    let sn = b"INSTA360SIM0001";
+                    out[100..100 + sn.len()].copy_from_slice(sn);
+                    return Ok(out.to_vec());
+                }
+                xu2_selectors::IMAGE_TEMPLATE_INFO => {
+                    let mut out = [0u8; 11];
+                    out[0] = st.current_template as u8;
+                    out[1] = 0;
+                    out[2..10].copy_from_slice(&st.template_mask.to_le_bytes());
+                    out[10] = 10;
+                    return Ok(out.to_vec());
+                }
+                xu2_selectors::IMAGE_TEMPLATE_NAME => {
+                    let mut out = [0u8; 65];
+                    out[0] = st.current_template as u8;
+                    if let Some(name) = st.template_names.get(&st.current_template) {
+                        let b = name.as_bytes();
+                        out[1..1 + b.len().min(63)].copy_from_slice(&b[..b.len().min(63)]);
+                    }
+                    return Ok(out.to_vec());
+                }
+                xu2_selectors::FILTER_MODE => {
+                    return Ok(vec![st.filter_mode]);
+                }
+                xu2_selectors::PRIVACY_AND_FILL_LIGHT => {
+                    return Ok(vec![0, u8::from(st.privacy_mode), 0, 0]);
+                }
+                xu2_selectors::DEFAULT_TRACK_MODE => {
+                    return Ok(vec![st.default_track_mode]);
+                }
+                xu2_selectors::HORIZONTAL_CORRECTION => {
+                    return Ok(vec![u8::from(st.horiz_correction)]);
+                }
+                xu2_selectors::REAL_ZOOM_AND_UDISK => {
+                    let mut out = [0u8; 4];
+                    out[0..2].copy_from_slice(&st.zoom.to_le_bytes());
+                    return Ok(out.to_vec());
+                }
+                _ => {}
+            }
+        }
+
+        if let Some(saved) = st.registers.get(&(unit_id, selector)) {
+            let mut v = saved.clone();
+            v.resize(len, 0);
+            return Ok(v);
+        }
+
+        Ok(vec![0u8; len])
+    }
+}
@@ -0,0 +1,664 @@
+use bitflags::bitflags;
+use serde::{Deserialize, Serialize};
+use crate::ids::{CameraModel, DeviceCapabilities, UvcUnitIds};
+
+/// UVC Class-Specific Request Codes (`MacUVCCameraControl::SetData` / `GetData` at `0x10019282c`)
+/// - `SET_CUR`: `bmRequestType = 0x21`, `bRequest = 0x01` (`w10 = 0x0121`)
+/// - `GET_*`: `bmRequestType = 0xa1`, `bRequest = 0x81..0x87`
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[repr(u8)]
+pub enum UvcRequest {
+    SetCur = 0x01,
+    GetCur = 0x81,
+    GetMin = 0x82,
+    GetMax = 0x83,
+    GetRes = 0x84,
+    GetLen = 0x85,
+    GetInfo = 0x86,
+    GetDef = 0x87,
+}
+
+/// Standard UVC Input Terminal (Camera Terminal) Control Selectors (`MacUVCCameraController`)
+pub mod ct_selectors {
+    /// `CT_AE_MODE_CONTROL` (`0x02`, 1 byte: 1=Manual, 2=Auto, 4=ShutterPriority, 8=AperturePriority)
+    pub const AE_MODE: u8 = 0x02;
+    /// `CT_EXPOSURE_TIME_ABSOLUTE_CONTROL` (`0x04`, 4 bytes)
+    pub const EXPOSURE_TIME_ABSOLUTE: u8 = 0x04;
+    /// `CT_FOCUS_ABSOLUTE_CONTROL` (`0x06`, 2 bytes)
+    pub const FOCUS_ABSOLUTE: u8 = 0x06;
+    /// `CT_FOCUS_AUTO_CONTROL` (`0x08`, 1 byte: 0 or 1)
+    pub const FOCUS_AUTO: u8 = 0x08;
+    /// `CT_ZOOM_ABSOLUTE_CONTROL` (`0x0b`, 2 bytes, typically 100..400)
+    pub const ZOOM_ABSOLUTE: u8 = 0x0b;
+    /// `CT_PANTILT_ABSOLUTE_CONTROL` (`0x0d`, 8 bytes: i32 pan_arcsec, i32 tilt_arcsec)
+    pub const PANTILT_ABSOLUTE: u8 = 0x0d;
+    /// `CT_PANTILT_RELATIVE_CONTROL` (`0x0e`, 4 bytes: i8 pan_dir, u8 pan_speed, i8 tilt_dir, u8 tilt_speed)
+    pub const PANTILT_RELATIVE: u8 = 0x0e;
+    /// `CT_ROLL_ABSOLUTE_CONTROL` (`0x0f`, 2 bytes: i16 roll)
+    pub const ROLL_ABSOLUTE: u8 = 0x0f;
+}
+
+/// Standard UVC Processing Unit Control Selectors (`MacUVCCameraController`)
+pub mod pu_selectors {
+    /// `PU_BRIGHTNESS_CONTROL` (`0x02`, 2 bytes: i16)
+    pub const BRIGHTNESS: u8 = 0x02;
+    /// `PU_CONTRAST_CONTROL` (`0x03`, 2 bytes: u16)
+    pub const CONTRAST: u8 = 0x03;
+    /// `PU_POWER_LINE_FREQUENCY_CONTROL` (`0x05`, 1 byte: 0=Disabled, 1=50Hz, 2=60Hz, 3=Auto)
+    pub const POWER_LINE_FREQUENCY: u8 = 0x05;
+    /// `PU_SATURATION_CONTROL` (`0x07`, 2 bytes: u16)
+    pub const SATURATION: u8 = 0x07;
+    /// `PU_SHARPNESS_CONTROL` (`0x08`, 2 bytes: u16)
+    pub const SHARPNESS: u8 = 0x08;
+    /// `PU_WHITE_BALANCE_TEMPERATURE_CONTROL` (`0x0a`, 2 bytes: u16 Kelvin)
+    pub const WHITE_BALANCE_TEMPERATURE: u8 = 0x0a;
+    /// `PU_WHITE_BALANCE_TEMPERATURE_AUTO_CONTROL` (`0x0b`, 1 byte: 0 or 1)
+    pub const WHITE_BALANCE_TEMPERATURE_AUTO: u8 = 0x0b;
+}
+
+/// Insta360 Extension Unit 1 (`FAF1672D-B71B-4793-8C91-7B1C9B7F95F8`) Control Selectors
+/// Verified across `MacUVCCameraExtendController::*` (`0x100195a18`–`0x10019bd00`).
+pub mod xu1_selectors {
+    /// `0x01`: Preset / Gimbal / PTZ / Factory Reset / Composition Bias / Forbidden Area multiplexed control
+    /// - `[0, index, 0, 0]` (4B): SetCurPresetPosition
+    /// - `[1, index, 0, 0]` (4B): AddPresetPosition
+    /// - `[2, index, 0, 0]` (4B): DeletePresetPosition
+    /// - `[3, 0, 0, 0]` (4B): ResetGimbal (PTZ home)
+    /// - `[4, 0, 0, 0]` (4B): LoadFactoryDefault
+    /// - `[6, x_lo, x_hi, y_lo, y_hi]` (5B): SetCompositionBias (x: i16, y: i16; 0x7fff = reset)
+    /// - `[7, 1, 0, 0]` (4B): EnterTrackForbiddenAreaSetting
+    /// - `[8, 1, 0, 0]` (4B): ExitTrackForbiddenAreaSetting
+    pub const SYSTEM_AND_PRESET_CMD: u8 = 0x01;
+
+    /// `0x02`: Video Mode & Auxiliary Data (`SetVideoMode` / `GetVideoMode`)
+    /// - Set: 8 bytes (Link/Link 2) or 36 bytes (Link 2C/PUC3 Host)
+    /// - Get: 36 bytes (`[mode_u8, flags_u8, x_i32, y_i32, w_i32, h_i32, pitch_i16, zoom_u16, ...]`)
+    pub const VIDEO_MODE: u8 = 0x02;
+
+    /// `0x03`: AI Tracking & Gesture Control
+    /// - `GetGestureStatus` / `EnableAllGesture` / `EnableGestureWork`: 6-byte status (`[all, ok, palm, l, v, rock]`)
+    /// - `ForceSetSmartWhiteBoard(mode)` (`[3, mode_u8, ...]`, 16B)
+    /// - `SetTrackSpeed` / `GetTrackSpeed`: (`[5, speed_u8, ...]`, 16B)
+    /// - `SetCompositionStyle` / `GetCompositionStyle`: (`[6, style_u8, ...]`, 16B)
+    pub const TRACKING_AND_GESTURE: u8 = 0x03;
+
+    /// `0x04`: Audio Noise Reduction & Audio Capture Mode (`2` bytes)
+    /// - `EnableAudioNoiseReduction` / `GetAudioNoiseStatus`: `buf[0] = 0/1`
+    /// - `SetAudioCaptureMode` / `GetAudioCaptureMode`: `buf[0] = mode (1..=5)`
+    pub const AUDIO_CONTROL: u8 = 0x04;
+
+    /// `0x05`: Select Tracked Person / Object Bounding Box (`SetTrackObj`, 10 bytes: `i16 x, y, w, h, id`)
+    pub const TRACK_OBJECT_SELECT: u8 = 0x05;
+
+    /// `0x06`: Detected Trackable Objects List (Link 1: `GetTrackObjLists`, N * 10 bytes of `UVCRect`)
+    pub const TRACK_OBJECT_LIST_V1: u8 = 0x06;
+
+    /// `0x07`: Exposure Curve & Manual Exposure (`GetExpouseCurve` / `SetExpouseCurve` / `EnableAutoExposure` / `GetAutoExposureStatus` / `SetISOValue` / `GetISOValue`, 259 bytes)
+    pub const EXPOSURE_CURVE_AND_ISO: u8 = 0x07;
+
+    /// `0x08`: Exposure Compensation (`SetExposureCompensation` / `GetExposureCompensation`, 4 bytes: `f32` EV)
+    pub const EXPOSURE_COMPENSATION: u8 = 0x08;
+
+    /// `0x09`: White Balance Extended Parameters (`SetWhiteBalanceParam` / `GetWhiteBalanceParam`, 129 bytes)
+    pub const WHITE_BALANCE_EXT: u8 = 0x09;
+
+    /// `0x0a`: Extended Function Bitmask (`EnableExtendFuncWork` / `GetExtendFuncStatus` / `EnableVerticalScreen` / `EnableLowResolution`, 8 bytes: `u32 mask, u32 values`)
+    pub const EXTEND_FUNC_BITMASK: u8 = 0x0a;
+
+    /// `0x0b`: Gimbal Relative Pan/Tilt (`SetPanTiltRelative` / `GetPanTiltRelative`, 4 bytes: `[pan_speed, pan_dir, tilt_speed, tilt_dir]`)
+    pub const PANTILT_RELATIVE_EXT: u8 = 0x0b;
+
+    /// `0x0c`: Device Status Flags (`GetDeviceStatus`, 4 bytes: `u32` bitflags)
+    pub const DEVICE_STATUS: u8 = 0x0c;
+
+    /// `0x0d`: PTZ Version & Gimbal Absolute Position (`GetPTZVersionInfo` / `GetPanTiltAbsoluteValue`, 30 bytes)
+    pub const PTZ_VERSION_AND_ABS: u8 = 0x0d;
+
+    /// `0x0e`: Preset Position Bitflags (`GetCurPresetPositionFlag`, 8 bytes)
+    pub const PRESET_POSITION_FLAGS: u8 = 0x0e;
+
+    /// `0x0f`: Switch to Read-Only Mass Storage Class (`SwitchMscReadOnlyClass`, 4 bytes: `[2, 0, 0, 0]`)
+    /// Also used by `DownloadFileFromCamera` (`[1, 0, 0, 0]`).
+    pub const USB_MODE_SWITCH: u8 = 0x0f;
+}
+
+/// Insta360 Extension Unit 2 (`E307E649-4618-A3FF-82FC-2D8B5F216773`) Control Selectors
+/// Verified across `MacUVCCameraExtendController::*` (`0x100195a18`–`0x10019c478`).
+pub mod xu2_selectors {
+    /// `0x01`: Gesture Binding Map (`GetGestureBindingMap` / `SetGestureBindingFunc`)
+    pub const GESTURE_BINDING_MAP: u8 = 0x01;
+
+    /// `0x02`: Camera System & Timestamp (`SetTimestamp`, `SetIQSwitch`, `RestoreFactorySet`)
+    /// - `[1, ts_le_bytes[0..8], ...]`: SetTimestamp
+    /// - `[2, iq_bitmask_u32_le, ...]`: SetIQSwitch (D0=bit 0, D1=bit 1)
+    /// - `[4, 1, ...]`: RestoreFactorySet(true) (reboot/full)
+    /// - `[5, 1, ...]`: RestoreFactorySet(false) (settings only)
+    pub const SYSTEM_TIME_AND_IQ: u8 = 0x02;
+
+    /// `0x03`: Device Info & Serial Number (`GetDeviceInfo` / `GetSerialNumber`, 150 bytes:
+    /// `[0..50]` device_name, `[50..100]` fw_version, `[100..150]` serial_number)
+    pub const DEVICE_INFO: u8 = 0x03;
+
+    /// `0x04`: Image Template Management (`GetImageTemplateInfo`, `SetImageTemplate`, `DeleteTemplate`, 11 bytes)
+    pub const IMAGE_TEMPLATE_INFO: u8 = 0x04;
+
+    /// `0x05`: Image Template Name (`GetImageTemplateName` / `SetImageTemplateName`, 65 bytes: `[id_i8, name[64]]`)
+    pub const IMAGE_TEMPLATE_NAME: u8 = 0x05;
+
+    /// `0x06`: Image Filter Mode (`SetFilter` / `GetFilter`, 1 byte: `0..=8`)
+    pub const FILTER_MODE: u8 = 0x06;
+
+    /// `0x08`: Fill Light & Privacy Mode (`GetFillLightParam`, `SetPrivacyMode`, `GetPrivacyMode`, 4 bytes)
+    /// - `SetPrivacyMode(enable)`: `[2, enable_u8, 0, 0]`
+    /// - `GetPrivacyMode`: `status = buf[0]`, `enabled = buf[1] != 0`
+    pub const PRIVACY_AND_FILL_LIGHT: u8 = 0x08;
+
+    /// `0x09`: Host Digital PTZ Crop (`SetHostPTZ`, 8 bytes: `u16 x, u16 y, u16 w, u16 h`)
+    pub const HOST_PTZ: u8 = 0x09;
+
+    /// `0x0a`: Detected Trackable Objects List V2 (Link 2 / Link 2C: `GetNewTrackObjLists`)
+    pub const TRACK_OBJECT_LIST_V2: u8 = 0x0a;
+
+    /// `0x0b`: Tracking Forbidden Areas (`SetTrackForbiddenArea`, `GetTrackForbiddenArea`, `EnableTrackForbiddenArea`)
+    pub const TRACK_FORBIDDEN_AREA: u8 = 0x0b;
+
+    /// `0x0c`: Default Track Mode (`SetDefaultTrackMode` / `GetDefaultTrackMode`, 1 byte)
+    pub const DEFAULT_TRACK_MODE: u8 = 0x0c;
+
+    /// `0x0d`: Horizontal Correction (`EnableHorizontalCorrection` / `GetEnableHorizontalCorrection`, 1 byte)
+    pub const HORIZONTAL_CORRECTION: u8 = 0x0d;
+
+    /// `0x0e`: Real Zoom & UDisk Open Count (`GetRealZoomValue`, `GetUDiskOpenCount`, `SetUDiskOpenCount`)
+    pub const REAL_ZOOM_AND_UDISK: u8 = 0x0e;
+
+    /// `0x0f`: Diagnostic Report Data (`GetReportData`)
+    pub const REPORT_DATA: u8 = 0x0f;
+}
+
+/// Discovered Insta360 camera metadata (`UVCCameraInfo` at `0x100191844`).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DiscoveredCamera {
+    pub vendor_id: u16,
+    pub product_id: u16,
+    pub model: CameraModel,
+    pub name: String,
+    pub unique_id: String,
+    pub bus_number: u8,
+    pub device_address: u8,
+    pub unit_ids: UvcUnitIds,
+    pub capabilities: DeviceCapabilities,
+}
+
+/// Range and default metadata for a standard UVC control (`CameraControlInfo` at `0x100193694`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct ControlRange {
+    pub min: i64,
+    pub max: i64,
+    pub step: i64,
+    pub default: i64,
+    pub flags: i64,
+}
+
+/// Relative pan/tilt speed and direction (`CameraControlRelativeInfo` at `0x1001990f4`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct RelativeControl {
+    pub min_speed: u8,
+    pub max_speed: u8,
+    pub step_speed: u8,
+    pub default_speed: u8,
+    pub current_speed: u8,
+    /// Direction: `0` = stop, `1` = positive (right/up), `-1` (or `0xff`) = negative (left/down)
+    pub direction: i8,
+}
+
+/// Camera Video Mode (`VideoMode` in `CameraInsta` at `0x1000601d4`–`0x100060234`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
+#[repr(u8)]
+pub enum VideoMode {
+    #[default]
+    Normal = 0,
+    AutoTracking = 1,
+    WhiteBoard = 4,
+    OverheadShot = 5,
+    DeskView = 6,
+    AutoFraming = 7,
+    SmartWhiteBoard = 8,
+}
+
+impl VideoMode {
+    pub fn from_u8(val: u8) -> Self {
+        match val {
+            0 => Self::Normal,
+            1 => Self::AutoTracking,
+            4 => Self::WhiteBoard,
+            5 => Self::OverheadShot,
+            6 => Self::DeskView,
+            7 => Self::AutoFraming,
+            8 | 10 => Self::SmartWhiteBoard,
+            _ => Self::Normal,
+        }
+    }
+
+    pub fn name(&self) -> &'static str {
+        match self {
+            Self::Normal => "Normal",
+            Self::AutoTracking => "AI Tracking",
+            Self::WhiteBoard => "Whiteboard",
+            Self::OverheadShot => "Overhead",
+            Self::DeskView => "DeskView",
+            Self::AutoFraming => "Auto Framing",
+            Self::SmartWhiteBoard => "Smart Whiteboard",
+        }
+    }
+}
+
+/// Auxiliary data sent/received with `VideoMode` (`VideoModeAuxiliaryData` at `0x100197088` & `0x1001978b8`).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct VideoModeAuxData {
+    pub flags: u8,
+    /// Optional 4-corner or bounding rectangle coordinates (`x, y, width, height` or whiteboard corners)
+    pub rect: [i32; 4],
+    /// DeskView / Host pitch angle (`i16`, e.g., -900..0 or -61926 sentinel)
+    pub pitch: i16,
+    /// Zoom factor (`u16`, default `100`)
+    pub zoom: u16,
+    /// Extra mode-specific bytes (up to 36 bytes total wire payload)
+    pub extra: [u8; 14],
+}
+
+impl Default for VideoModeAuxData {
+    fn default() -> Self {
+        Self {
+            flags: 0,
+            rect: [0, 0, 0, 0],
+            pitch: 0,
+            zoom: 100,
+            extra: [0u8; 14],
+        }
+    }
+}
+
+/// AI Tracking / Framing Composition Style (`CompositionStyle` at `0x100197900` & `PTZControl.qml` line 944).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[repr(u8)]
+pub enum CompositionStyle {
+    Custom = 0,
+    #[default]
+    Head = 1,
+    HalfBody = 2,
+    WholeBody = 3,
+}
+
+impl CompositionStyle {
+    pub fn from_u8(v: u8) -> Self {
+        match v {
+            1 => Self::Head,
+            2 => Self::HalfBody,
+            3 => Self::WholeBody,
+            _ => Self::Head,
+        }
+    }
+}
+
+/// Gimbal AI Tracking Speed (`TrackSpeed` at `0x1001979e4` & `PTZControl.qml` line 1051).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[repr(u8)]
+pub enum TrackSpeed {
+    Fast = 0,
+    #[default]
+    Normal = 1,
+    Slow = 2,
+}
+
+impl TrackSpeed {
+    pub fn from_u8(v: u8) -> Self {
+        match v {
+            0 => Self::Fast,
+            1 => Self::Normal,
+            _ => Self::Slow,
+        }
+    }
+}
+
+/// Extended Function bit indices in XU1 selector `0x0a` (`ExtendFuction` jump table at `0x102864a20`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[repr(u8)]
+pub enum ExtendFunction {
+    /// Bit 0: `ai_zoom_checked_`
+    AiZoom = 0,
+    /// Bit 1: Reserved
+    Reserved1 = 1,
+    /// Bit 2: `enable_hdr_`
+    Hdr = 2,
+    /// Bit 3: `mirror_checked_` (Horizontal Mirror)
+    HorizontalMirror = 3,
+    /// Bit 4: `enable_all_gestures_`
+    AllGestures = 4,
+    /// Bit 5: `enable_vertical_mode_` (9:16 Vertical Resolution)
+    VerticalMode = 5,
+    /// Bit 6: `enable_startup_params_` (Save Startup Parameters to Camera)
+    StartupParams = 6,
+    /// Bit 7: `enable_single_tap_tracking_`
+    SingleTapTracking = 7,
+    /// Bit 8: `enable_auto_tracking_`
+    AutoTracking = 8,
+    /// Bit 9: `smart_adjustment_checked_`
+    SmartAdjustment = 9,
+    /// Bit 10: `forced_vertical_` (Uncropped 9:16 Portrait)
+    ForcedVertical = 10,
+    /// Bit 11: `enable_privacy_mode_` (Ultimate Privacy / 10s Sleep)
+    UltimatePrivacyMode = 11,
+    /// Bit 12: `enable_vertically_mirror_` (Vertical Flip)
+    VerticalMirror = 12,
+    /// Bit 13: `enable_low_resolution_`
+    LowResolution = 13,
+    /// Bit 14: `enable_track_forbidden_area_`
+    TrackForbiddenArea = 14,
+}
+
+impl ExtendFunction {
+    pub const ALL: [ExtendFunction; 14] = [
+        Self::AiZoom,
+        Self::Hdr,
+        Self::HorizontalMirror,
+        Self::AllGestures,
+        Self::VerticalMode,
+        Self::StartupParams,
+        Self::SingleTapTracking,
+        Self::AutoTracking,
+        Self::SmartAdjustment,
+        Self::ForcedVertical,
+        Self::UltimatePrivacyMode,
+        Self::VerticalMirror,
+        Self::LowResolution,
+        Self::TrackForbiddenArea,
+    ];
+
+    pub fn from_u8(v: u8) -> Option<Self> {
+        match v {
+            0 => Some(Self::AiZoom),
+            1 => Some(Self::Reserved1),
+            2 => Some(Self::Hdr),
+            3 => Some(Self::HorizontalMirror),
+            4 => Some(Self::AllGestures),
+            5 => Some(Self::VerticalMode),
+            6 => Some(Self::StartupParams),
+            7 => Some(Self::SingleTapTracking),
+            8 => Some(Self::AutoTracking),
+            9 => Some(Self::SmartAdjustment),
+            10 => Some(Self::ForcedVertical),
+            11 => Some(Self::UltimatePrivacyMode),
+            12 => Some(Self::VerticalMirror),
+            13 => Some(Self::LowResolution),
+            14 => Some(Self::TrackForbiddenArea),
+            _ => None,
+        }
+    }
+}
+
+/// Hand Gesture types (`EnableGestureWork` at `0x100197bc8` and `setUseGesture*` at `0x100067f58`–`0x100068888`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[repr(u8)]
+pub enum Gesture {
+    Ok = 0,
+    Palm = 1,
+    LShape = 2,
+    VShape = 3,
+    Rock = 4,
+}
+
+impl Gesture {
+    pub const ALL: [Gesture; 5] = [
+        Self::Ok,
+        Self::Palm,
+        Self::LShape,
+        Self::VShape,
+        Self::Rock,
+    ];
+}
+
+/// Gesture-bound action (`GestureFunction` in `GetGestureBindingMap` at `0x100198384`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[repr(u8)]
+pub enum GestureFunction {
+    #[default]
+    None = 0,
+    AutoTracking = 1,
+    Zoom = 2,
+    WhiteBoard = 3,
+    AutoFraming = 4,
+}
+
+impl GestureFunction {
+    pub fn from_u8(v: u8) -> Self {
+        match v {
+            1 => Self::AutoTracking,
+            2 => Self::Zoom,
+            3 => Self::WhiteBoard,
+            4 => Self::AutoFraming,
+            _ => Self::None,
+        }
+    }
+}
+
+/// Audio Capture / Microphone Mode (`AudioCaptureMode` at `0x10019bf54` & `0x1000702a8`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[repr(u8)]
+pub enum AudioCaptureMode {
+    /// Voice Focus (Directional beamforming)
+    #[default]
+    VoiceFocus = 1,
+    /// Voice Suppression / Noise Canceling (Wide)
+    VoiceSuppression = 2,
+    /// Original / Music Balance
+    MusicBalance = 3,
+    /// Original Sound
+    Original = 4,
+    /// Sound Wall / Audio Fence (PUC3)
+    SoundWall = 5,
+}
+
+impl AudioCaptureMode {
+    pub fn from_u8(v: u8) -> Self {
+        match v {
+            1 => Self::VoiceFocus,
+            2 => Self::VoiceSuppression,
+            3 => Self::MusicBalance,
+            4 => Self::Original,
+            5 => Self::SoundWall,
+            _ => Self::VoiceFocus,
+        }
+    }
+
+    pub fn name(&self) -> &'static str {
+        match self {
+            Self::VoiceFocus => "Voice Focus",
+            Self::VoiceSuppression => "Noise Suppression",
+            Self::MusicBalance => "Music Balance",
+            Self::Original => "Original Sound",
+            Self::SoundWall => "Sound Wall",
+        }
+    }
+}
+
+/// Power Line Anti-Flicker Frequency (`PowerLineFrequency` at `0x100194ecc`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[repr(u8)]
+pub enum PowerLineFrequency {
+    #[default]
+    Disabled = 0,
+    Hz50 = 1,
+    Hz60 = 2,
+    Auto = 3,
+}
+
+impl PowerLineFrequency {
+    pub fn from_u8(v: u8) -> Self {
+        match v {
+            1 => Self::Hz50,
+            2 => Self::Hz60,
+            3 => Self::Auto,
+            _ => Self::Disabled,
+        }
+    }
+}
+
+/// Hardware Filter Mode (`FilterMode` at `0x10019bdb0` & `0x100096f94`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[repr(u8)]
+pub enum FilterMode {
+    #[default]
+    None = 0,
+    Style1 = 1,
+    Style2 = 2,
+    Fresh = 3,
+     Amber = 4,
+    Film1 = 5,
+    Film2 = 6,
+    Cool = 7,
+    Warm = 8,
+}
+
+impl FilterMode {
+    pub fn from_u8(v: u8) -> Self {
+        match v {
+            1 => Self::Style1,
+            2 => Self::Style2,
+            3 => Self::Fresh,
+            4 => Self::Amber,
+            5 => Self::Film1,
+            6 => Self::Film2,
+            7 => Self::Cool,
+            8 => Self::Warm,
+            _ => Self::None,
+        }
+    }
+}
+
+/// Exposure Curve & Manual ISO/Exposure state (`ExpouseCurve` at `0x10019aaa0`–`0x10019b7d0`).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ExposureCurve {
+    /// `0` = Manual Exposure, `1` = Auto Exposure
+    pub mode: u8,
+    /// Manual ISO value (`u16`, e.g. 100..=3200)
+    pub iso: u16,
+    /// 128-point tone/exposure curve (`[u16; 128]`)
+    pub points: Vec<u16>,
+}
+
+impl Default for ExposureCurve {
+    fn default() -> Self {
+        Self {
+            mode: 1,
+            iso: 100,
+            points: vec![0; 128],
+        }
+    }
+}
+
+/// Extended White Balance Parameters (`WhiteBalanceParam` at `0x10019afe0`–`0x10019b264`).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct WhiteBalanceParam {
+    pub mode: u8,
+    pub gains: Vec<u32>,
+}
+
+/// Camera Device Information (`DeviceInfo` at `0x100196e74`, 150 bytes across three 50-byte ASCII fields).
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct DeviceInfo {
+    pub device_name: String,
+    pub firmware_version: String,
+    pub serial_number: String,
+}
+
+/// PTZ Gimbal Firmware Version & Absolute Pan/Tilt Angles (`PTZVerInfo` at `0x1001993bc`, 30 bytes).
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct PtzVersionInfo {
+    pub version: String,
+    pub pan: i16,
+    pub tilt: i16,
+    pub zoom: u16,
+    pub status: u8,
+}
+
+bitflags! {
+    /// Device runtime status flags (`GetDeviceStatus` at `0x10019b8dc`, 4-byte `u32`).
+    #[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+    pub struct DeviceStatus: u32 {
+        const TRACKING_ACTIVE   = 1 << 0;
+        const WHITEBOARD_ACTIVE = 1 << 1;
+        const GESTURE_DETECTED  = 1 << 2;
+        const PRIVACY_SLEEP     = 1 << 3;
+        const OVERHEAD_MODE     = 1 << 4;
+        const DESKVIEW_MODE     = 1 << 5;
+        const UPGRADING         = 1 << 6;
+    }
+}
+
+/// Bounding rectangle for tracked person/object (`UVCRect` at `0x100198a38`, 10 bytes).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct UvcRect {
+    pub x: i16,
+    pub y: i16,
+    pub width: i16,
+    pub height: i16,
+    pub track_id: i16,
+}
+
+/// Digital Host PTZ crop box (`HostPTZInfo` at `0x10019bec0`, 8 bytes).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct HostPtzInfo {
+    pub x: u16,
+    pub y: u16,
+    pub width: u16,
+    pub height: u16,
+}
+
+impl Default for HostPtzInfo {
+    fn default() -> Self {
+        Self {
+            x: 0,
+            y: 0,
+            width: 5140,
+            height: 5140,
+        }
+    }
+}
+
+/// Tracking Forbidden Area entry (`ForbiddenAreaInfo_s` at `0x10019bff4`, 10 bytes per entry).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct ForbiddenAreaInfo {
+    pub enabled: bool,
+    pub index: u8,
+    pub pan_min: i16,
+    pub pan_max: i16,
+    pub tilt_min: i16,
+    pub tilt_max: i16,
+}
+
+/// Preset slot flags (`PresetFlag` at `0x1001997c0`, 8 bytes).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct PresetFlag {
+    pub slot_mask: u8,
+    pub current_slot: u8,
+    pub max_slots: u8,
+    pub raw: [u8; 8],
+}
+
+/// Image Template Info (`ImageTemplateInfo` at `0x10019ba4c`, 11 bytes).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct ImageTemplateInfo {
+    pub current_id: i8,
+    pub operation: u8,
+    pub bitmask: u64,
+    pub max_templates: u8,
+}
+
+/// Image Template Operation (`ImageOperation` at `0x10019bb08`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[repr(u8)]
+pub enum ImageOperation {
+    None = 0,
+    SaveOrUpdate = 1,
+    Apply = 2,
+}
@@ -0,0 +1,662 @@
+use insta360_link_protocol::*;
+
+/// Builds a synthetic USB Configuration Descriptor containing:
+/// - Standard Interface Descriptor for UVC VideoControl (`bInterfaceNumber = 2`, `CC_VIDEO = 0x0e`, `SC_VIDEOCONTROL = 0x01`)
+/// - `VC_INPUT_TERMINAL` (`bDescriptorSubtype = 0x02`, `bTerminalID = 3`, `wTerminalType = 0x0201` `ITT_CAMERA`)
+/// - `VC_PROCESSING_UNIT` (`bDescriptorSubtype = 0x05`, `bUnitID = 5`)
+/// - `VC_EXTENSION_UNIT` (`bDescriptorSubtype = 0x06`, `bUnitID = 11`) with `XU1_GUID_BYTES`
+/// - `VC_EXTENSION_UNIT` (`bDescriptorSubtype = 0x06`, `bUnitID = 12`) with `XU2_GUID_BYTES`
+/// - Standard Interface Descriptor for UVC VideoStreaming (`bInterfaceNumber = 3`, `CC_VIDEO = 0x0e`, `SC_VIDEOSTREAMING = 0x02`)
+///   followed by a dummy `CS_INTERFACE` descriptor that should be ignored by `parse_uvc_vc_descriptors`.
+#[test]
+fn test_parse_uvc_vc_descriptors_synthetic() {
+    let mut desc = Vec::new();
+
+    // 1. Standard Interface Descriptor (USB_DT_INTERFACE = 0x04): bInterfaceNumber = 2, CC_VIDEO (0x0e), SC_VIDEOCONTROL (0x01)
+    desc.extend_from_slice(&[
+        9,    // bLength
+        0x04, // bDescriptorType = USB_DT_INTERFACE
+        2,    // bInterfaceNumber = 2
+        0,    // bAlternateSetting
+        1,    // bNumEndpoints
+        0x0e, // bInterfaceClass = CC_VIDEO
+        0x01, // bInterfaceSubClass = SC_VIDEOCONTROL
+        0x00, // bInterfaceProtocol
+        0,    // iInterface
+    ]);
+
+    // 2. VC_INPUT_TERMINAL (CS_INTERFACE = 0x24, subtype = 0x02, bTerminalID = 3, wTerminalType = 0x0201 ITT_CAMERA)
+    desc.extend_from_slice(&[
+        18,   // bLength
+        0x24, // bDescriptorType = CS_INTERFACE
+        0x02, // bDescriptorSubtype = VC_INPUT_TERMINAL
+        3,    // bTerminalID = 3
+        0x01, 0x02, // wTerminalType = 0x0201 (ITT_CAMERA)
+        0,    // bAssocTerminal
+        0,    // iTerminal
+        0, 0, 0, 0, 0, 0, 3, 0xff, 0xff, 0x0f,
+    ]);
+
+    // 3. VC_PROCESSING_UNIT (CS_INTERFACE = 0x24, subtype = 0x05, bUnitID = 5)
+    desc.extend_from_slice(&[
+        13,   // bLength
+        0x24, // bDescriptorType = CS_INTERFACE
+        0x05, // bDescriptorSubtype = VC_PROCESSING_UNIT
+        5,    // bUnitID = 5
+        3,    // bSourceID = 3
+        0, 0, // wMaxMultiplier
+        3,    // bControlSize
+        0xff, 0xff, 0x00, // bmControls
+        0,    // iProcessing
+        0,    // bmVideoStandards
+    ]);
+
+    // 4. VC_EXTENSION_UNIT for XU1 (CS_INTERFACE = 0x24, subtype = 0x06, bUnitID = 11, guid = XU1_GUID_BYTES)
+    let mut xu1_desc = vec![
+        24,   // bLength
+        0x24, // bDescriptorType = CS_INTERFACE
+        0x06, // bDescriptorSubtype = VC_EXTENSION_UNIT
+        11,   // bUnitID = 11
+    ];
+    xu1_desc.extend_from_slice(&XU1_GUID_BYTES);
+    xu1_desc.extend_from_slice(&[15, 1, 5, 0]);
+    assert_eq!(xu1_desc.len(), 24);
+    desc.extend_from_slice(&xu1_desc);
+
+    // 5. VC_EXTENSION_UNIT for XU2 (CS_INTERFACE = 0x24, subtype = 0x06, bUnitID = 12, guid = XU2_GUID_BYTES)
+    let mut xu2_desc = vec![
+        24,   // bLength
+        0x24, // bDescriptorType = CS_INTERFACE
+        0x06, // bDescriptorSubtype = VC_EXTENSION_UNIT
+        12,   // bUnitID = 12
+    ];
+    xu2_desc.extend_from_slice(&XU2_GUID_BYTES);
+    xu2_desc.extend_from_slice(&[15, 1, 11, 0]);
+    assert_eq!(xu2_desc.len(), 24);
+    desc.extend_from_slice(&xu2_desc);
+
+    // 6. Standard Interface Descriptor for VideoStreaming (SC_VIDEOSTREAMING = 0x02)
+    // Descriptors inside VideoStreaming must NOT overwrite VC unit IDs.
+    desc.extend_from_slice(&[
+        9,    // bLength
+        0x04, // bDescriptorType = USB_DT_INTERFACE
+        3,    // bInterfaceNumber = 3
+        0,    // bAlternateSetting
+        0,    // bNumEndpoints
+        0x0e, // bInterfaceClass = CC_VIDEO
+        0x02, // bInterfaceSubClass = SC_VIDEOSTREAMING
+        0x00, // bInterfaceProtocol
+        0,    // iInterface
+    ]);
+    desc.extend_from_slice(&[
+        6,    // bLength
+        0x24, // CS_INTERFACE inside VideoStreaming (should be ignored)
+        0x05, // subtype 0x05
+        99,   // would be unit 99 if not ignored
+        0, 0,
+    ]);
+
+    let parsed = parse_uvc_vc_descriptors(&desc);
+    assert_eq!(parsed.control_interface, 2);
+    assert_eq!(parsed.input_terminal_id, 3);
+    assert_eq!(parsed.processing_unit_id, 5);
+    assert_eq!(parsed.extension_unit_id, 11);
+    assert_eq!(parsed.extension_unit2_id, 12);
+}
+
+#[test]
+fn test_camera_models_pids_capabilities_and_video_mode_len() {
+    // Verify Vendor ID and device filter
+    assert_eq!(INSTA360_VENDOR_ID, 0x2e1a);
+    for &pid in &[
+        pids::LINK_1,
+        pids::PUC3_GIMBAL_A,
+        pids::LINK_2C,
+        pids::LINK_2,
+        pids::PUC3_HOST,
+        pids::PUC3_GIMBAL_B,
+        pids::LINK_SIMPLE_CLASS,
+    ] {
+        assert!(is_insta360_link_device(INSTA360_VENDOR_ID, pid));
+        assert!(!is_insta360_link_device(0x1234, pid));
+    }
+    assert!(!is_insta360_link_device(INSTA360_VENDOR_ID, 0x9999));
+
+    // Verify PID -> CameraModel mappings, internal codes, firmware filenames, and SetVideoMode payload lengths
+    let link1 = CameraModel::from_pid(pids::LINK_1);
+    assert_eq!(link1, CameraModel::Link);
+    assert_eq!(link1.pid(), 0x4c01);
+    assert_eq!(link1.internal_code(), "link1");
+    assert_eq!(link1.firmware_filename(), Some(r"a:\Insta360WebCamFW.bin"));
+    assert_eq!(link1.video_mode_payload_len(), 8);
+
+    let puc3_a = CameraModel::from_pid(pids::PUC3_GIMBAL_A);
+    assert_eq!(puc3_a, CameraModel::Puc3Gimbal(0x4c02));
+    assert_eq!(puc3_a.pid(), 0x4c02);
+    assert_eq!(puc3_a.internal_code(), "link2_gimbal");
+    assert_eq!(puc3_a.firmware_filename(), Some(r"a:\Insta360PUC3FW_GIMBAL.bin"));
+    assert_eq!(puc3_a.video_mode_payload_len(), 8);
+
+    let link2c = CameraModel::from_pid(pids::LINK_2C);
+    assert_eq!(link2c, CameraModel::Link2C);
+    assert_eq!(link2c.pid(), 0x4c03);
+    assert_eq!(link2c.internal_code(), "link2_main");
+    assert_eq!(link2c.firmware_filename(), Some(r"a:\Insta360LINK2CFW_HOST.bin"));
+    assert_eq!(link2c.video_mode_payload_len(), 36);
+
+    let link2 = CameraModel::from_pid(pids::LINK_2);
+    assert_eq!(link2, CameraModel::Link2);
+    assert_eq!(link2.pid(), 0x4c04);
+    assert_eq!(link2.internal_code(), "link2_gimbal");
+    assert_eq!(link2.firmware_filename(), Some(r"a:\Insta360LINK2FW_GIMBAL.bin"));
+    assert_eq!(link2.video_mode_payload_len(), 8);
+
+    let puc3_host = CameraModel::from_pid(pids::PUC3_HOST);
+    assert_eq!(puc3_host, CameraModel::Puc3Host);
+    assert_eq!(puc3_host.pid(), 0x4c05);
+    assert_eq!(puc3_host.internal_code(), "link2_main");
+    assert_eq!(puc3_host.firmware_filename(), Some(r"a:\Insta360PUC3FW_HOST.bin"));
+    assert_eq!(puc3_host.video_mode_payload_len(), 36);
+
+    let puc3_b = CameraModel::from_pid(pids::PUC3_GIMBAL_B);
+    assert_eq!(puc3_b, CameraModel::Puc3Gimbal(0x4c06));
+    assert_eq!(puc3_b.pid(), 0x4c06);
+    assert_eq!(puc3_b.internal_code(), "link2_gimbal");
+    assert_eq!(puc3_b.firmware_filename(), Some(r"a:\Insta360PUC3FW_GIMBAL.bin"));
+    assert_eq!(puc3_b.video_mode_payload_len(), 8);
+
+    let dfu = CameraModel::from_pid(pids::LINK_SIMPLE_CLASS);
+    assert_eq!(dfu, CameraModel::LinkSimpleClass);
+    assert_eq!(dfu.pid(), 0x00c2);
+    assert_eq!(dfu.internal_code(), "link1");
+    assert_eq!(dfu.firmware_filename(), Some(r"a:\Insta360WebCamFW.bin"));
+    assert_eq!(dfu.video_mode_payload_len(), 36);
+
+    // Capability matrix assertions (`Webcam::CameraDeviceSupporter::UpdateUIStatus` at `0x10004a8b8`)
+    let cap_link1 = DeviceCapabilities::for_pid(pids::LINK_1);
+    assert!(cap_link1.has_physical_gimbal);
+    assert!(cap_link1.support_roll_adjustment);
+    assert!(!cap_link1.support_auto_framing);
+    assert!(!cap_link1.support_privacy_mode);
+    assert!(!cap_link1.support_audio_capture_mode);
+    assert!(!cap_link1.support_horizontal_correction);
+    assert!(!cap_link1.support_sound_wall);
+
+    let cap_link2 = DeviceCapabilities::for_pid(pids::LINK_2);
+    assert!(cap_link2.has_physical_gimbal);
+    assert!(!cap_link2.support_roll_adjustment);
+    assert!(cap_link2.support_auto_framing);
+    assert!(cap_link2.support_privacy_mode);
+    assert!(cap_link2.support_area_track);
+    assert!(cap_link2.support_speak_tracking);
+    assert!(cap_link2.support_audio_capture_mode);
+    assert!(cap_link2.support_horizontal_correction);
+    assert!(!cap_link2.support_sound_wall);
+
+    let cap_link2c = DeviceCapabilities::for_pid(pids::LINK_2C);
+    assert!(!cap_link2c.has_physical_gimbal);
+    assert!(!cap_link2c.support_ptz_drag);
+    assert!(!cap_link2c.support_track_speed);
+    assert!(cap_link2c.support_auto_framing);
+    assert!(cap_link2c.support_image_template);
+    assert!(cap_link2c.support_privacy_mode);
+    assert!(cap_link2c.support_audio_capture_mode);
+    assert!(!cap_link2c.support_area_track);
+    assert!(!cap_link2c.support_horizontal_correction);
+
+    let cap_puc3_b = DeviceCapabilities::for_pid(pids::PUC3_GIMBAL_B);
+    assert!(cap_puc3_b.has_physical_gimbal);
+    assert!(cap_puc3_b.support_area_track);
+    assert!(cap_puc3_b.support_speak_tracking);
+    assert!(cap_puc3_b.support_sound_wall);
+    assert!(!cap_puc3_b.support_horizontal_correction);
+
+    let cap_puc3_host = DeviceCapabilities::for_pid(pids::PUC3_HOST);
+    assert!(!cap_puc3_host.has_physical_gimbal);
+    assert!(cap_puc3_host.support_sound_wall);
+    assert!(cap_puc3_host.support_auto_framing);
+}
+
+#[test]
+fn test_controller_ptz_presets_and_gimbal_commands() {
+    let mock = MockCameraTransport::new(CameraModel::Link2);
+    let ctrl = Insta360CameraController::new(mock.clone());
+
+    // 1. Absolute Pan/Tilt & Zoom
+    ctrl.set_pantilt_absolute(36000, -18000).unwrap();
+    assert_eq!(ctrl.get_pantilt_absolute().unwrap(), (36000, -18000));
+
+    ctrl.set_zoom(250).unwrap();
+    assert_eq!(ctrl.get_zoom().unwrap(), 250);
+    let zoom_range = ctrl.get_zoom_range().unwrap();
+    assert_eq!((zoom_range.min, zoom_range.max, zoom_range.default), (100, 400, 100));
+
+    // 2. Relative Pan/Tilt (XU1 0x0b: [pan_speed, pan_dir, tilt_speed, tilt_dir])
+    ctrl.set_pantilt_relative_ext(5, -1, 3, 1).unwrap();
+    ctrl.stop_pantilt_relative().unwrap();
+
+    // 3. Presets (XU1 0x01: [sub_op, index, 0, 0])
+    ctrl.add_preset_position(4).unwrap();
+    let flags = ctrl.get_preset_flags().unwrap();
+    assert_ne!(flags.slot_mask & (1 << 4), 0);
+    assert_eq!(flags.current_slot, 4);
+
+    ctrl.recall_preset_position(1).unwrap();
+    assert_eq!(ctrl.get_preset_flags().unwrap().current_slot, 1);
+
+    ctrl.delete_preset_position(4).unwrap();
+    assert_eq!(ctrl.get_preset_flags().unwrap().slot_mask & (1 << 4), 0);
+
+    // 4. Composition bias & Reset Gimbal
+    ctrl.set_composition_bias(-120, 80).unwrap();
+    ctrl.reset_composition_bias().unwrap();
+    ctrl.reset_gimbal().unwrap();
+    assert_eq!(ctrl.get_pantilt_absolute().unwrap(), (0, 0));
+    assert_eq!(ctrl.get_zoom().unwrap(), 100);
+
+    // 5. Host Digital PTZ (XU2 0x09)
+    let host_crop = HostPtzInfo {
+        x: 500,
+        y: 600,
+        width: 2570,
+        height: 2570,
+    };
+    ctrl.set_host_ptz(&host_crop).unwrap();
+
+    // Inspect command log for exact unit IDs, selectors, and payload bytes
+    let log = mock.command_log();
+    assert_eq!(
+        log[0],
+        (
+            UvcRequest::SetCur,
+            DEFAULT_INPUT_TERMINAL_ID,
+            ct_selectors::PANTILT_ABSOLUTE,
+            [36000i32.to_le_bytes(), (-18000i32).to_le_bytes()].concat()
+        )
+    );
+    assert_eq!(
+        log[1],
+        (
+            UvcRequest::SetCur,
+            DEFAULT_INPUT_TERMINAL_ID,
+            ct_selectors::ZOOM_ABSOLUTE,
+            250u16.to_le_bytes().to_vec()
+        )
+    );
+    assert_eq!(
+        log[2],
+        (
+            UvcRequest::SetCur,
+            DEFAULT_EXTENSION_UNIT_ID,
+            xu1_selectors::PANTILT_RELATIVE_EXT,
+            vec![0xff, 5, 1, 3]
+        )
+    );
+    assert_eq!(
+        log[3],
+        (
+            UvcRequest::SetCur,
+            DEFAULT_EXTENSION_UNIT_ID,
+            xu1_selectors::PANTILT_RELATIVE_EXT,
+            vec![0, 1, 0, 1]
+        )
+    );
+    assert_eq!(
+        log[4],
+        (
+            UvcRequest::SetCur,
+            DEFAULT_EXTENSION_UNIT_ID,
+            xu1_selectors::SYSTEM_AND_PRESET_CMD,
+            vec![0x01, 4, 0x00, 0x00]
+        )
+    );
+    assert_eq!(
+        log[5],
+        (
+            UvcRequest::SetCur,
+            DEFAULT_EXTENSION_UNIT_ID,
+            xu1_selectors::SYSTEM_AND_PRESET_CMD,
+            vec![0x00, 1, 0x00, 0x00]
+        )
+    );
+    assert_eq!(
+        log[6],
+        (
+            UvcRequest::SetCur,
+            DEFAULT_EXTENSION_UNIT_ID,
+            xu1_selectors::SYSTEM_AND_PRESET_CMD,
+            vec![0x02, 4, 0x00, 0x00]
+        )
+    );
+    assert_eq!(
+        log[7],
+        (
+            UvcRequest::SetCur,
+            DEFAULT_EXTENSION_UNIT_ID,
+            xu1_selectors::SYSTEM_AND_PRESET_CMD,
+            vec![0x06, (-120i16).to_le_bytes()[0], (-120i16).to_le_bytes()[1], 80, 0]
+        )
+    );
+    assert_eq!(
+        log[8],
+        (
+            UvcRequest::SetCur,
+            DEFAULT_EXTENSION_UNIT_ID,
+            xu1_selectors::SYSTEM_AND_PRESET_CMD,
+            vec![0x06, 0xff, 0x7f, 0xff, 0x7f]
+        )
+    );
+    assert_eq!(
+        log[9],
+        (
+            UvcRequest::SetCur,
+            DEFAULT_EXTENSION_UNIT_ID,
+            xu1_selectors::SYSTEM_AND_PRESET_CMD,
+            vec![0x03, 0x00, 0x00, 0x00]
+        )
+    );
+    assert_eq!(
+        log[10],
+        (
+            UvcRequest::SetCur,
+            DEFAULT_EXTENSION_UNIT2_ID,
+            xu2_selectors::HOST_PTZ,
+            [
+                500u16.to_le_bytes(),
+                600u16.to_le_bytes(),
+                2570u16.to_le_bytes(),
+                2570u16.to_le_bytes()
+            ]
+            .concat()
+        )
+    );
+}
+
+#[test]
+fn test_video_mode_8byte_vs_36byte_and_tracking_gestures() {
+    // 1. Link 2 uses 8-byte SetVideoMode payload
+    let mock_link2 = MockCameraTransport::new(CameraModel::Link2);
+    let ctrl_link2 = Insta360CameraController::new(mock_link2.clone());
+    let aux = VideoModeAuxData {
+        flags: 1,
+        rect: [10, 20, 300, 400],
+        pitch: -450,
+        zoom: 150,
+        extra: [0xaa; 14],
+    };
+    ctrl_link2.set_video_mode(VideoMode::DeskView, &aux).unwrap();
+    let log2 = mock_link2.command_log();
+    assert_eq!(log2.len(), 1);
+    assert_eq!(log2[0].1, DEFAULT_EXTENSION_UNIT_ID);
+    assert_eq!(log2[0].2, xu1_selectors::VIDEO_MODE);
+    assert_eq!(log2[0].3.len(), 8);
+    assert_eq!(log2[0].3[0], VideoMode::DeskView as u8);
+    assert_eq!(log2[0].3[1], 1);
+
+    // 2. Link 2C uses 36-byte SetVideoMode payload
+    let mock_link2c = MockCameraTransport::new(CameraModel::Link2C);
+    let ctrl_link2c = Insta360CameraController::new(mock_link2c.clone());
+    ctrl_link2c.set_video_mode(VideoMode::AutoFraming, &aux).unwrap();
+    let log2c = mock_link2c.command_log();
+    assert_eq!(log2c.len(), 1);
+    assert_eq!(log2c[0].1, DEFAULT_EXTENSION_UNIT_ID);
+    assert_eq!(log2c[0].2, xu1_selectors::VIDEO_MODE);
+    assert_eq!(log2c[0].3.len(), 36);
+    let (decoded_mode, decoded_aux) = ctrl_link2c.get_video_mode().unwrap();
+    assert_eq!(decoded_mode, VideoMode::AutoFraming);
+    assert_eq!(decoded_aux.rect, [10, 20, 300, 400]);
+    assert_eq!(decoded_aux.pitch, -450);
+    assert_eq!(decoded_aux.zoom, 150);
+
+    // 3. Tracking speed, composition style, and gestures on XU1 0x03
+    ctrl_link2.set_track_speed(TrackSpeed::Fast).unwrap();
+    assert_eq!(ctrl_link2.get_track_speed().unwrap(), TrackSpeed::Fast);
+
+    ctrl_link2.set_composition_style(CompositionStyle::WholeBody).unwrap();
+    assert_eq!(ctrl_link2.get_composition_style().unwrap(), CompositionStyle::WholeBody);
+
+    ctrl_link2.set_gesture_enabled(Gesture::VShape, false).unwrap();
+    let gestures = ctrl_link2.get_gesture_status().unwrap();
+    assert_eq!(gestures[3], (Gesture::VShape, false));
+    assert_eq!(gestures[0], (Gesture::Ok, true));
+
+    ctrl_link2.set_all_gestures_enabled(false).unwrap();
+
+    let log2_after = mock_link2.command_log();
+    // TrackSpeed::Fast -> [5, 2, 0..0] (16 bytes)
+    let mut expected_speed = vec![0u8; 16];
+    expected_speed[0] = 0x05;
+    expected_speed[1] = TrackSpeed::Fast as u8;
+    assert_eq!(
+        log2_after[1],
+        (
+            UvcRequest::SetCur,
+            DEFAULT_EXTENSION_UNIT_ID,
+            xu1_selectors::TRACKING_AND_GESTURE,
+            expected_speed
+        )
+    );
+
+    // CompositionStyle::WholeBody -> [6, 2, 0..0] (16 bytes)
+    let mut expected_style = vec![0u8; 16];
+    expected_style[0] = 0x06;
+    expected_style[1] = CompositionStyle::WholeBody as u8;
+    assert_eq!(
+        log2_after[2],
+        (
+            UvcRequest::SetCur,
+            DEFAULT_EXTENSION_UNIT_ID,
+            xu1_selectors::TRACKING_AND_GESTURE,
+            expected_style
+        )
+    );
+}
+
+#[test]
+fn test_image_controls_exposure_wb_audio_filters_templates_and_extend_functions() {
+    let mock = MockCameraTransport::new(CameraModel::Link2);
+    let ctrl = Insta360CameraController::new(mock.clone());
+
+    // 1. Standard Processing Unit (PU) controls
+    ctrl.set_brightness(72).unwrap();
+    assert_eq!(ctrl.get_brightness().unwrap(), 72);
+
+    ctrl.set_contrast(64).unwrap();
+    assert_eq!(ctrl.get_contrast().unwrap(), 64);
+
+    ctrl.set_saturation(80).unwrap();
+    assert_eq!(ctrl.get_saturation().unwrap(), 80);
+
+    ctrl.set_sharpness(45).unwrap();
+    assert_eq!(ctrl.get_sharpness().unwrap(), 45);
+
+    ctrl.set_auto_white_balance(false).unwrap();
+    assert!(!ctrl.get_auto_white_balance().unwrap());
+
+    ctrl.set_white_balance_temperature(6500).unwrap();
+    assert_eq!(ctrl.get_white_balance_temperature().unwrap(), 6500);
+
+    ctrl.set_power_line_frequency(PowerLineFrequency::Hz50).unwrap();
+    assert_eq!(ctrl.get_power_line_frequency().unwrap(), PowerLineFrequency::Hz50);
+
+    // 2. Standard Camera Terminal (CT) focus, roll, shutter
+    ctrl.set_auto_focus(false).unwrap();
+    assert!(!ctrl.get_auto_focus().unwrap());
+    ctrl.set_focus(85).unwrap();
+    assert_eq!(ctrl.get_focus().unwrap(), 85);
+    ctrl.set_roll(-150).unwrap();
+    assert_eq!(ctrl.get_roll().unwrap(), -150);
+    ctrl.set_shutter_speed(500).unwrap();
+    assert_eq!(ctrl.get_shutter_speed().unwrap(), 500);
+
+    // 3. Exposure Curve / Auto Exposure / ISO (XU1 0x07, 259 bytes) & EV Compensation (XU1 0x08, 4 bytes)
+    ctrl.set_auto_exposure(false).unwrap();
+    assert!(!ctrl.get_auto_exposure().unwrap());
+    ctrl.set_iso(800).unwrap();
+    assert_eq!(ctrl.get_iso().unwrap(), 800);
+    ctrl.set_exposure_compensation(-1.5).unwrap();
+    assert!((ctrl.get_exposure_compensation().unwrap() - (-1.5)).abs() < 1e-6);
+
+    // 4. Audio Control (XU1 0x04, 2 bytes)
+    ctrl.set_audio_noise_reduction(false).unwrap();
+    assert!(!ctrl.get_audio_noise_reduction().unwrap());
+    ctrl.set_audio_capture_mode(AudioCaptureMode::MusicBalance).unwrap();
+    assert_eq!(ctrl.get_audio_capture_mode().unwrap(), AudioCaptureMode::MusicBalance);
+
+    // 5. Filter Mode (XU2 0x06, 1 byte)
+    ctrl.set_filter(FilterMode::Amber).unwrap();
+    assert_eq!(ctrl.get_filter().unwrap(), FilterMode::Amber);
+
+    // 6. Privacy Mode (XU2 0x08, 4 bytes) & Horizontal Correction (XU2 0x0d, 1 byte)
+    ctrl.set_privacy_mode(true).unwrap();
+    let (_, priv_enabled) = ctrl.get_privacy_mode().unwrap();
+    assert!(priv_enabled);
+    assert!(ctrl.get_device_status().unwrap().contains(DeviceStatus::PRIVACY_SLEEP));
+
+    ctrl.set_horizontal_correction(false).unwrap();
+    assert!(!ctrl.get_horizontal_correction().unwrap());
+
+    // 7. Image Templates (XU2 0x04 & 0x05)
+    ctrl.set_image_template(3, ImageOperation::SaveOrUpdate).unwrap();
+    ctrl.set_image_template_name(3, "Podcast Look").unwrap();
+    let tmpl_info = ctrl.get_image_template_info().unwrap();
+    assert_eq!(tmpl_info.current_id, 3);
+    assert_ne!(tmpl_info.bitmask & (1 << 3), 0);
+    ctrl.delete_image_template(3).unwrap();
+    assert_eq!(ctrl.get_image_template_info().unwrap().bitmask & (1 << 3), 0);
+
+    // 8. Extended Function Bitmask (XU1 0x0a, 8 bytes: [mask_u32_le, values_u32_le])
+    for &func in &ExtendFunction::ALL {
+        ctrl.set_extend_function(func, true).unwrap();
+        let statuses = ctrl.get_extend_function_status().unwrap();
+        let is_on = statuses.into_iter().find(|(f, _)| *f == func).unwrap().1;
+        assert!(is_on, "expected {:?} to be enabled", func);
+    }
+
+    // Verify specific wire payloads in command_log()
+    let log = mock.command_log();
+    // Find EV compensation command
+    let ev_cmd = log
+        .iter()
+        .find(|(_, u, s, _)| *u == DEFAULT_EXTENSION_UNIT_ID && *s == xu1_selectors::EXPOSURE_COMPENSATION)
+        .expect("EV compensation command logged");
+    assert_eq!(ev_cmd.3, (-1.5f32).to_le_bytes().to_vec());
+
+    // Find Privacy Mode command
+    let priv_cmd = log
+        .iter()
+        .find(|(_, u, s, _)| *u == DEFAULT_EXTENSION_UNIT2_ID && *s == xu2_selectors::PRIVACY_AND_FILL_LIGHT)
+        .expect("Privacy mode command logged");
+    assert_eq!(priv_cmd.3, vec![0x02, 0x01, 0x00, 0x00]);
+
+    // Find Filter Mode command
+    let filter_cmd = log
+        .iter()
+        .find(|(_, u, s, _)| *u == DEFAULT_EXTENSION_UNIT2_ID && *s == xu2_selectors::FILTER_MODE)
+        .expect("Filter mode command logged");
+    assert_eq!(filter_cmd.3, vec![FilterMode::Amber as u8]);
+}
+
+#[test]
+fn test_system_info_tracking_rects_and_mode_switch_commands() {
+    let mock = MockCameraTransport::new(CameraModel::Link2);
+    let ctrl = Insta360CameraController::new(mock.clone());
+
+    // Device Info (XU2 0x03, 150 bytes)
+    let dev_info = ctrl.get_device_info().unwrap();
+    assert_eq!(dev_info.device_name, "Insta360 Link 2");
+    assert_eq!(dev_info.firmware_version, "v2.5.8.8_build1");
+    assert_eq!(dev_info.serial_number, "INSTA360SIM0001");
+
+    // PTZ Version & Angles (XU1 0x0d, 30 bytes)
+    ctrl.set_pantilt_absolute(3600, -7200).unwrap();
+    let ptz_info = ctrl.get_ptz_version_and_angles().unwrap();
+    assert_eq!(ptz_info.version, "v1.3.1.0_build0");
+    assert_eq!(ptz_info.pan, 10);
+    assert_eq!(ptz_info.tilt, -20);
+    assert_eq!(ptz_info.zoom, 100);
+
+    // Select Tracked Object (XU1 0x05, 10 bytes)
+    let target = UvcRect {
+        x: 100,
+        y: 200,
+        width: 300,
+        height: 400,
+        track_id: 7,
+    };
+    ctrl.select_track_object(&target).unwrap();
+
+    // Default Track Mode (XU2 0x0c, 1 byte)
+    ctrl.set_default_track_mode(1).unwrap();
+    assert_eq!(ctrl.get_default_track_mode().unwrap(), 1);
+
+    // System Timestamp, IQ Switch, Factory Restore (XU2 0x02, 10 bytes)
+    ctrl.set_timestamp(0x0102_0304_0506_0708).unwrap();
+    ctrl.set_iq_switch(1, true, 0x01).unwrap();
+    ctrl.restore_factory_settings(true).unwrap();
+    ctrl.restore_factory_settings(false).unwrap();
+
+    // Factory Default (XU1 0x01 sub-opcode 4) & MSC Switch (XU1 0x0f sub-opcode 2)
+    ctrl.load_factory_default().unwrap();
+    ctrl.switch_msc_readonly_class().unwrap();
+
+    let log = mock.command_log();
+    assert!(log.iter().any(|(_, u, s, p)| {
+        *u == DEFAULT_EXTENSION_UNIT_ID
+            && *s == xu1_selectors::TRACK_OBJECT_SELECT
+            && p == &encode_track_rect(&target)
+    }));
+    assert!(log.iter().any(|(_, u, s, p)| {
+        *u == DEFAULT_EXTENSION_UNIT2_ID
+            && *s == xu2_selectors::SYSTEM_TIME_AND_IQ
+            && p[0] == 0x01
+            && &p[1..9] == &0x0102_0304_0506_0708u64.to_le_bytes()
+    }));
+    assert!(log.iter().any(|(_, u, s, p)| {
+        *u == DEFAULT_EXTENSION_UNIT2_ID
+            && *s == xu2_selectors::SYSTEM_TIME_AND_IQ
+            && p == &[0x02, 0x03, 0x00, 0x00, 0x00, 0, 0, 0, 0, 0]
+    }));
+    assert!(log.iter().any(|(_, u, s, p)| {
+        *u == DEFAULT_EXTENSION_UNIT_ID
+            && *s == xu1_selectors::USB_MODE_SWITCH
+            && p == &[0x02, 0x00, 0x00, 0x00]
+    }));
+
+    // Gesture bindings (XU2 selector 0x01)
+    ctrl.set_gesture_binding_func(Gesture::Palm, GestureFunction::AutoFraming)
+        .unwrap();
+    let bindings = ctrl.get_gesture_binding_map().unwrap();
+    assert_eq!(bindings[1], (Gesture::Palm, GestureFunction::AutoFraming));
+
+    // Tracking Forbidden Areas (XU1 selector 0x01 opcodes 7/8 + XU2 selector 0x0b)
+    ctrl.enter_track_forbidden_area_setting().unwrap();
+    let areas = vec![
+        ForbiddenAreaInfo {
+            enabled: true,
+            index: 0,
+            pan_min: -300,
+            pan_max: -100,
+            tilt_min: -150,
+            tilt_max: 150,
+        },
+        ForbiddenAreaInfo {
+            enabled: false,
+            index: 1,
+            pan_min: 100,
+            pan_max: 300,
+            tilt_min: -100,
+            tilt_max: 100,
+        },
+    ];
+    ctrl.set_track_forbidden_areas(&areas).unwrap();
+    let read_areas = ctrl.get_track_forbidden_areas().unwrap();
+    assert_eq!(read_areas, areas);
+    ctrl.exit_track_forbidden_area_setting().unwrap();
+
+    // Real zoom & Fill light param
+    ctrl.set_zoom(250).unwrap();
+    assert_eq!(ctrl.get_real_zoom_value().unwrap(), 250);
+    assert_eq!(ctrl.get_fill_light_param().unwrap(), (0, 0));
+}
+
@@ -0,0 +1,21 @@
+[package]
+name = "insta360-link-server"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+description = "Cross-platform HTTP REST & WebSocket remote control server for Insta360 Link cameras"
+
+[[bin]]
+name = "insta360-link-server"
+path = "src/main.rs"
+
+[dependencies]
+insta360-link-protocol = { path = "../insta360-link-protocol" }
+clap.workspace = true
+tokio.workspace = true
+axum.workspace = true
+tower-http.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+tracing.workspace = true
+tracing-subscriber.workspace = true
@@ -0,0 +1,103 @@
+use clap::{Parser, ValueEnum};
+use insta360_link_protocol::{
+    CameraModel, Insta360CameraController, NusbTransport, UvcControlTransport,
+};
+use insta360_link_server::{build_router, new_mock_state, AppState, ServerTransport};
+use std::net::SocketAddr;
+use std::sync::{Arc, Mutex};
+
+#[derive(Parser, Debug)]
+#[command(
+    name = "insta360-link-server",
+    version,
+    about = "Cross-platform HTTP REST & WebSocket remote control server for Insta360 Link cameras"
+)]
+struct Cli {
+    /// Bind address for HTTP and WebSocket server
+    #[arg(long, default_value = "127.0.0.1:9360", value_name = "ADDR")]
+    bind: SocketAddr,
+
+    /// Run against an in-memory simulated camera model instead of physical USB
+    #[arg(long, value_enum, value_name = "MODEL")]
+    mock: Option<MockModelArg>,
+}
+
+#[derive(Debug, Clone, Copy, ValueEnum)]
+pub enum MockModelArg {
+    #[value(name = "link", alias = "link1")]
+    Link,
+    #[value(name = "link2")]
+    Link2,
+    #[value(name = "link2c")]
+    Link2c,
+}
+
+impl From<MockModelArg> for CameraModel {
+    fn from(val: MockModelArg) -> Self {
+        match val {
+            MockModelArg::Link => CameraModel::Link,
+            MockModelArg::Link2 => CameraModel::Link2,
+            MockModelArg::Link2c => CameraModel::Link2C,
+        }
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| "insta360_link_server=info,tower_http=info".into()),
+        )
+        .init();
+
+    let cli = Cli::parse();
+
+    let state: AppState = match cli.mock {
+        Some(mock_arg) => {
+            let model: CameraModel = mock_arg.into();
+            tracing::info!(
+                "Initializing in-memory simulated camera: {} (PID: 0x{:04x})",
+                model.display_name(),
+                model.pid()
+            );
+            new_mock_state(model)
+        }
+        None => {
+            tracing::info!("Discovering and connecting to physical Insta360 Link camera via USB...");
+            match NusbTransport::open_first() {
+                Ok(usb) => {
+                    let info = usb.camera_info().clone();
+                    tracing::info!(
+                        "Connected to physical camera: {} (Bus {} Addr {} • PID 0x{:04x})",
+                        info.name,
+                        info.bus_number,
+                        info.device_address,
+                        info.product_id
+                    );
+                    let ctrl = Insta360CameraController::new(ServerTransport::Usb(usb));
+                    Arc::new(Mutex::new(ctrl))
+                }
+                Err(e) => {
+                    tracing::warn!(
+                        "Could not open physical Insta360 Link camera: {}. Falling back to simulated Link 2 camera. Pass '--mock <link|link2|link2c>' to select a specific model.",
+                        e
+                    );
+                    new_mock_state(CameraModel::Link2)
+                }
+            }
+        }
+    };
+
+    let router = build_router(state);
+
+    let listener = tokio::net::TcpListener::bind(cli.bind).await?;
+    tracing::info!("Insta360 Link Server listening on http://{}", cli.bind);
+    tracing::info!("Web Remote UI:     http://{}", cli.bind);
+    tracing::info!("WebSocket stream:  ws://{}/ws", cli.bind);
+    tracing::info!("REST State API:    http://{}/api/state", cli.bind);
+
+    axum::serve(listener, router).await?;
+
+    Ok(())
+}
@@ -0,0 +1,575 @@
+use std::collections::HashMap;
+use std::net::SocketAddr;
+
+use insta360_link_protocol::{
+    AudioCaptureMode, CameraModel, CompositionStyle, ExtendFunction, FilterMode, Gesture,
+    GestureFunction, TrackSpeed, VideoMode,
+};
+use insta360_link_server::{
+    build_router, new_mock_state, AudioRequest, CameraStateSnapshot, ImageRequest, ModeRequest,
+    PresetRequest, PtzRequest, SystemRequest, TrackingRequest,
+};
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::{TcpListener, TcpStream};
+
+/// Binds an ephemeral TCP listener on 127.0.0.1:0, attaches the axum router
+/// powered by `new_mock_state(model)`, spawns the server onto the tokio runtime,
+/// and returns the bound socket address.
+async fn start_test_server(model: CameraModel) -> SocketAddr {
+    let state = new_mock_state(model);
+    let app = build_router(state);
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("Failed to bind ephemeral TCP listener");
+    let addr = listener
+        .local_addr()
+        .expect("Failed to retrieve local socket address");
+
+    tokio::spawn(async move {
+        let _ = axum::serve(listener, app).await;
+    });
+
+    addr
+}
+
+/// Sends an HTTP/1.1 request directly over a raw TCP connection (`TcpStream`),
+/// eliminating external HTTP client crate requirements.
+///
+/// Handles chunked reading, `Content-Length` framing, and connection termination.
+/// Returns `(status_code, headers, body)`.
+async fn send_http_request(
+    addr: SocketAddr,
+    method: &str,
+    path: &str,
+    body: Option<&str>,
+) -> (u16, HashMap<String, String>, String) {
+    let mut stream = TcpStream::connect(addr)
+        .await
+        .expect("Failed to connect TCP stream to test server");
+
+    let mut req = format!("{method} {path} HTTP/1.1\r\nHost: {addr}\r\nConnection: close\r\n");
+    if let Some(b) = body {
+        req.push_str("Content-Type: application/json\r\n");
+        req.push_str(&format!("Content-Length: {}\r\n", b.len()));
+    }
+    req.push_str("\r\n");
+    if let Some(b) = body {
+        req.push_str(b);
+    }
+
+    stream
+        .write_all(req.as_bytes())
+        .await
+        .expect("Failed to write HTTP request to TCP stream");
+    stream.flush().await.expect("Failed to flush TCP stream");
+
+    let mut response_buf = Vec::new();
+    let mut chunk = [0u8; 4096];
+    loop {
+        let n = stream
+            .read(&mut chunk)
+            .await
+            .expect("Failed to read HTTP response chunk from TCP stream");
+        if n == 0 {
+            break;
+        }
+        response_buf.extend_from_slice(&chunk[..n]);
+
+        if let Some(pos) = response_buf.windows(4).position(|w| w == b"\r\n\r\n") {
+            let header_str = String::from_utf8_lossy(&response_buf[..pos]);
+            let mut content_len = None;
+            for line in header_str.split("\r\n") {
+                if let Some((k, v)) = line.split_once(':') {
+                    if k.trim().eq_ignore_ascii_case("content-length") {
+                        if let Ok(cl) = v.trim().parse::<usize>() {
+                            content_len = Some(cl);
+                        }
+                    }
+                }
+            }
+            if let Some(cl) = content_len {
+                if response_buf.len() >= pos + 4 + cl {
+                    break;
+                }
+            }
+        }
+    }
+
+    let header_end = response_buf
+        .windows(4)
+        .position(|w| w == b"\r\n\r\n")
+        .expect("Malformed HTTP response: missing header delimiter CRLF CRLF");
+    let header_bytes = &response_buf[..header_end];
+    let body_bytes = &response_buf[header_end + 4..];
+
+    let header_str = std::str::from_utf8(header_bytes).expect("Non-UTF8 HTTP headers");
+    let mut lines = header_str.split("\r\n");
+    let status_line = lines.next().expect("Missing HTTP status line");
+    let status_code: u16 = status_line
+        .split_whitespace()
+        .nth(1)
+        .expect("Missing status code in HTTP status line")
+        .parse()
+        .expect("Invalid integer status code in HTTP response");
+
+    let mut headers = HashMap::new();
+    for line in lines {
+        if let Some((k, v)) = line.split_once(':') {
+            headers.insert(k.trim().to_ascii_lowercase(), v.trim().to_string());
+        }
+    }
+
+    let body_str = String::from_utf8_lossy(body_bytes).to_string();
+    (status_code, headers, body_str)
+}
+
+/// Helper for GET requests.
+async fn send_http_get(addr: SocketAddr, path: &str) -> (u16, HashMap<String, String>, String) {
+    send_http_request(addr, "GET", path, None).await
+}
+
+/// Helper for JSON POST requests.
+async fn send_http_json(
+    addr: SocketAddr,
+    method: &str,
+    path: &str,
+    body: &str,
+) -> (u16, HashMap<String, String>, String) {
+    send_http_request(addr, method, path, Some(body)).await
+}
+
+#[test]
+fn test_request_structs_exports() {
+    // Verify that all documented request structs deserialize properly
+    let _ptz: PtzRequest = serde_json::from_str(
+        r#"{"pan_arcsec": 36000, "tilt_arcsec": -18000, "zoom": 250}"#,
+    )
+    .expect("PtzRequest deserialization failed");
+
+    let _mode: ModeRequest = serde_json::from_str(
+        r#"{"mode": "DeskView", "pitch": -450, "zoom": 150}"#,
+    )
+    .expect("ModeRequest deserialization failed");
+
+    let _preset: PresetRequest = serde_json::from_str(
+        r#"{"action": "save", "index": 3}"#,
+    )
+    .expect("PresetRequest deserialization failed");
+
+    let _img: ImageRequest = serde_json::from_str(
+        r#"{"brightness": 75, "contrast": 65, "wb_auto": false, "wb_kelvin": 5600, "hdr": true, "filter_mode": "Warm"}"#,
+    )
+    .expect("ImageRequest deserialization failed");
+
+    let _track: TrackingRequest = serde_json::from_str(
+        r#"{"track_speed": "Fast", "composition_style": "WholeBody", "gesture_binding": ["Palm", "AutoFraming"]}"#,
+    )
+    .expect("TrackingRequest deserialization failed");
+
+    let _audio: AudioRequest = serde_json::from_str(
+        r#"{"audio_mode": "VoiceSuppression"}"#,
+    )
+    .or_else(|_| serde_json::from_str(r#"{"mode": "VoiceSuppression"}"#))
+    .expect("AudioRequest deserialization failed");
+
+    let _sys: SystemRequest = serde_json::from_str(
+        r#"{"privacy_mode": true, "horizontal_correction": true}"#,
+    )
+    .expect("SystemRequest deserialization failed");
+}
+
+/// 1. GET / returns 200 OK with text/html containing the embedded Web Remote Control UI.
+#[tokio::test]
+async fn test_web_remote_control_ui() {
+    let addr = start_test_server(CameraModel::Link2).await;
+    let (status, headers, body) = send_http_get(addr, "/").await;
+
+    assert_eq!(status, 200, "GET / did not return 200 OK");
+    let content_type = headers
+        .get("content-type")
+        .expect("Missing Content-Type header on GET /");
+    assert!(
+        content_type.contains("text/html"),
+        "Content-Type should be text/html, got '{content_type}'"
+    );
+    assert!(
+        body.contains("<!DOCTYPE html>")
+            || body.contains("<!doctype html>")
+            || body.contains("<html")
+            || body.contains("Insta360"),
+        "GET / body did not contain expected HTML UI content. Body preview: {}",
+        &body[..body.len().min(300)]
+    );
+}
+
+/// 2. GET /api/state returns 200 OK and deserializes cleanly into CameraStateSnapshot
+/// with CameraModel::Link2 and zoom == 100.
+#[tokio::test]
+async fn test_get_api_state_initial() {
+    let addr = start_test_server(CameraModel::Link2).await;
+    let (status, headers, body) = send_http_get(addr, "/api/state").await;
+
+    assert_eq!(status, 200, "GET /api/state did not return 200 OK");
+    let content_type = headers
+        .get("content-type")
+        .expect("Missing Content-Type header on GET /api/state");
+    assert!(
+        content_type.contains("application/json"),
+        "Content-Type should be application/json, got '{content_type}'"
+    );
+
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body)
+        .unwrap_or_else(|e| panic!("Failed to deserialize CameraStateSnapshot: {e}\nPayload: {body}"));
+
+    assert_eq!(snapshot.model, CameraModel::Link2);
+    assert_eq!(snapshot.zoom, 100);
+}
+
+/// 3. POST /api/ptz with {"pan_arcsec": 36000, "tilt_arcsec": -18000, "zoom": 250}
+/// updates pan_arcsec, tilt_arcsec, zoom, and real_zoom.
+#[tokio::test]
+async fn test_post_api_ptz() {
+    let addr = start_test_server(CameraModel::Link2).await;
+
+    let (status, _, _) = send_http_json(
+        addr,
+        "POST",
+        "/api/ptz",
+        r#"{"pan_arcsec": 36000, "tilt_arcsec": -18000, "zoom": 250}"#,
+    )
+    .await;
+    assert_eq!(status, 200, "POST /api/ptz failed");
+
+    let (status, _, body) = send_http_get(addr, "/api/state").await;
+    assert_eq!(status, 200);
+
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body)
+        .expect("Failed to deserialize CameraStateSnapshot after PTZ update");
+
+    assert_eq!(snapshot.pan_arcsec, 36000);
+    assert_eq!(snapshot.tilt_arcsec, -18000);
+    assert_eq!(snapshot.zoom, 250);
+    assert_eq!(snapshot.real_zoom, 250);
+}
+
+/// 4. POST /api/mode with {"mode": "DeskView", "pitch": -450, "zoom": 150}
+/// switches video_mode to VideoMode::DeskView and updates video_aux.pitch to -450.
+#[tokio::test]
+async fn test_post_api_mode() {
+    let addr = start_test_server(CameraModel::Link2).await;
+
+    let (status, _, _) = send_http_json(
+        addr,
+        "POST",
+        "/api/mode",
+        r#"{"mode": "DeskView", "pitch": -450, "zoom": 150}"#,
+    )
+    .await;
+    assert_eq!(status, 200, "POST /api/mode failed");
+
+    let (status, _, body) = send_http_get(addr, "/api/state").await;
+    assert_eq!(status, 200);
+
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body)
+        .expect("Failed to deserialize CameraStateSnapshot after mode update");
+
+    assert_eq!(snapshot.video_mode, VideoMode::DeskView);
+    assert_eq!(snapshot.video_aux.pitch, -450);
+}
+
+/// 5. POST /api/image with {"brightness": 75, "contrast": 65, "wb_auto": false, "wb_kelvin": 5600, "hdr": true, "filter_mode": "Warm"}
+/// updates all image parameters and sets ExtendFunction::Hdr to true.
+#[tokio::test]
+async fn test_post_api_image() {
+    let addr = start_test_server(CameraModel::Link2).await;
+
+    let (status, _, _) = send_http_json(
+        addr,
+        "POST",
+        "/api/image",
+        r#"{"brightness": 75, "contrast": 65, "wb_auto": false, "wb_kelvin": 5600, "hdr": true, "filter_mode": "Warm"}"#,
+    )
+    .await;
+    assert_eq!(status, 200, "POST /api/image failed");
+
+    let (status, _, body) = send_http_get(addr, "/api/state").await;
+    assert_eq!(status, 200);
+
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body)
+        .expect("Failed to deserialize CameraStateSnapshot after image update");
+
+    assert_eq!(snapshot.brightness, 75);
+    assert_eq!(snapshot.contrast, 65);
+    assert_eq!(snapshot.wb_auto, false);
+    assert_eq!(snapshot.wb_kelvin, 5600);
+    assert_eq!(snapshot.filter_mode, FilterMode::Warm);
+
+    let hdr_enabled = snapshot
+        .extend_functions
+        .iter()
+        .any(|(f, en)| *f == ExtendFunction::Hdr && *en);
+    assert!(hdr_enabled, "ExtendFunction::Hdr was not set to true in snapshot.extend_functions");
+}
+
+/// 6. POST /api/tracking with {"track_speed": "Fast", "composition_style": "WholeBody", "gesture_binding": ["Palm", "AutoFraming"]}
+/// updates tracking speed, composition style, and gesture bindings.
+#[tokio::test]
+async fn test_post_api_tracking() {
+    let addr = start_test_server(CameraModel::Link2).await;
+
+    let (status, _, _) = send_http_json(
+        addr,
+        "POST",
+        "/api/tracking",
+        r#"{"track_speed": "Fast", "composition_style": "WholeBody", "gesture_binding": ["Palm", "AutoFraming"]}"#,
+    )
+    .await;
+    assert_eq!(status, 200, "POST /api/tracking failed");
+
+    let (status, _, body) = send_http_get(addr, "/api/state").await;
+    assert_eq!(status, 200);
+
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body)
+        .expect("Failed to deserialize CameraStateSnapshot after tracking update");
+
+    assert_eq!(snapshot.track_speed, TrackSpeed::Fast);
+    assert_eq!(snapshot.composition_style, CompositionStyle::WholeBody);
+
+    let palm_binding = snapshot
+        .gesture_bindings
+        .iter()
+        .find(|(g, _)| *g == Gesture::Palm);
+    assert_eq!(
+        palm_binding.map(|(_, f)| *f),
+        Some(GestureFunction::AutoFraming),
+        "Expected Palm gesture binding to be AutoFraming"
+    );
+}
+
+/// 7. POST /api/preset with {"action": "save", "index": 3} sets bit 3 in preset_flags.slot_mask.
+#[tokio::test]
+async fn test_post_api_preset() {
+    let addr = start_test_server(CameraModel::Link2).await;
+
+    let (status, _, _) = send_http_json(
+        addr,
+        "POST",
+        "/api/preset",
+        r#"{"action": "save", "index": 3}"#,
+    )
+    .await;
+    assert_eq!(status, 200, "POST /api/preset failed");
+
+    let (status, _, body) = send_http_get(addr, "/api/state").await;
+    assert_eq!(status, 200);
+
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body)
+        .expect("Failed to deserialize CameraStateSnapshot after preset update");
+
+    assert_ne!(
+        snapshot.preset_flags.slot_mask & (1 << 3),
+        0,
+        "Bit 3 in preset_flags.slot_mask should be set after saving preset slot 3"
+    );
+}
+
+/// 8. POST /api/audio and POST /api/system update audio_mode, privacy_mode, and horizontal_correction.
+#[tokio::test]
+async fn test_post_api_audio_and_system() {
+    let addr = start_test_server(CameraModel::Link2).await;
+
+    // Audio update
+    let mut audio_res = send_http_json(
+        addr,
+        "POST",
+        "/api/audio",
+        r#"{"audio_mode": "VoiceSuppression"}"#,
+    )
+    .await;
+    if audio_res.0 != 200 {
+        audio_res = send_http_json(
+            addr,
+            "POST",
+            "/api/audio",
+            r#"{"mode": "VoiceSuppression"}"#,
+        )
+        .await;
+    }
+    assert_eq!(audio_res.0, 200, "POST /api/audio failed");
+
+    let (status, _, body) = send_http_get(addr, "/api/state").await;
+    assert_eq!(status, 200);
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body)
+        .expect("Failed to deserialize CameraStateSnapshot after audio update");
+    assert_eq!(snapshot.audio_mode, AudioCaptureMode::VoiceSuppression);
+
+    // System update
+    let (status, _, _) = send_http_json(
+        addr,
+        "POST",
+        "/api/system",
+        r#"{"privacy_mode": true, "horizontal_correction": true}"#,
+    )
+    .await;
+    assert_eq!(status, 200, "POST /api/system failed");
+
+    let (status, _, body) = send_http_get(addr, "/api/state").await;
+    assert_eq!(status, 200);
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body)
+        .expect("Failed to deserialize CameraStateSnapshot after system update");
+    assert!(snapshot.privacy_mode, "privacy_mode should be true");
+    assert!(
+        snapshot.horizontal_correction,
+        "horizontal_correction should be true"
+    );
+}
+
+/// Complete end-to-end integration flow testing all 8 steps sequentially on a single
+/// server instance over TCP sockets.
+#[tokio::test]
+async fn test_server_full_integration_flow() {
+    let addr = start_test_server(CameraModel::Link2).await;
+
+    // 1. GET / returns 200 OK with text/html UI
+    let (status, headers, body) = send_http_get(addr, "/").await;
+    assert_eq!(status, 200);
+    assert!(headers.get("content-type").unwrap().contains("text/html"));
+    assert!(
+        body.contains("<!DOCTYPE html>")
+            || body.contains("<!doctype html>")
+            || body.contains("<html")
+            || body.contains("Insta360")
+    );
+
+    // 2. GET /api/state initial state
+    let (status, _, body) = send_http_get(addr, "/api/state").await;
+    assert_eq!(status, 200);
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body).unwrap();
+    assert_eq!(snapshot.model, CameraModel::Link2);
+    assert_eq!(snapshot.zoom, 100);
+
+    // 3. POST /api/ptz
+    let (status, _, _) = send_http_json(
+        addr,
+        "POST",
+        "/api/ptz",
+        r#"{"pan_arcsec": 36000, "tilt_arcsec": -18000, "zoom": 250}"#,
+    )
+    .await;
+    assert_eq!(status, 200);
+
+    let (_, _, body) = send_http_get(addr, "/api/state").await;
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body).unwrap();
+    assert_eq!(snapshot.pan_arcsec, 36000);
+    assert_eq!(snapshot.tilt_arcsec, -18000);
+    assert_eq!(snapshot.zoom, 250);
+    assert_eq!(snapshot.real_zoom, 250);
+
+    // 4. POST /api/mode
+    let (status, _, _) = send_http_json(
+        addr,
+        "POST",
+        "/api/mode",
+        r#"{"mode": "DeskView", "pitch": -450, "zoom": 150}"#,
+    )
+    .await;
+    assert_eq!(status, 200);
+
+    let (_, _, body) = send_http_get(addr, "/api/state").await;
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body).unwrap();
+    assert_eq!(snapshot.video_mode, VideoMode::DeskView);
+    assert_eq!(snapshot.video_aux.pitch, -450);
+
+    // 5. POST /api/image
+    let (status, _, _) = send_http_json(
+        addr,
+        "POST",
+        "/api/image",
+        r#"{"brightness": 75, "contrast": 65, "wb_auto": false, "wb_kelvin": 5600, "hdr": true, "filter_mode": "Warm"}"#,
+    )
+    .await;
+    assert_eq!(status, 200);
+
+    let (_, _, body) = send_http_get(addr, "/api/state").await;
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body).unwrap();
+    assert_eq!(snapshot.brightness, 75);
+    assert_eq!(snapshot.contrast, 65);
+    assert_eq!(snapshot.wb_auto, false);
+    assert_eq!(snapshot.wb_kelvin, 5600);
+    assert_eq!(snapshot.filter_mode, FilterMode::Warm);
+    assert!(snapshot
+        .extend_functions
+        .iter()
+        .any(|(f, en)| *f == ExtendFunction::Hdr && *en));
+
+    // 6. POST /api/tracking
+    let (status, _, _) = send_http_json(
+        addr,
+        "POST",
+        "/api/tracking",
+        r#"{"track_speed": "Fast", "composition_style": "WholeBody", "gesture_binding": ["Palm", "AutoFraming"]}"#,
+    )
+    .await;
+    assert_eq!(status, 200);
+
+    let (_, _, body) = send_http_get(addr, "/api/state").await;
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body).unwrap();
+    assert_eq!(snapshot.track_speed, TrackSpeed::Fast);
+    assert_eq!(snapshot.composition_style, CompositionStyle::WholeBody);
+    let palm_binding = snapshot
+        .gesture_bindings
+        .iter()
+        .find(|(g, _)| *g == Gesture::Palm);
+    assert_eq!(
+        palm_binding.map(|(_, f)| *f),
+        Some(GestureFunction::AutoFraming)
+    );
+
+    // 7. POST /api/preset
+    let (status, _, _) = send_http_json(
+        addr,
+        "POST",
+        "/api/preset",
+        r#"{"action": "save", "index": 3}"#,
+    )
+    .await;
+    assert_eq!(status, 200);
+
+    let (_, _, body) = send_http_get(addr, "/api/state").await;
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body).unwrap();
+    assert_ne!(snapshot.preset_flags.slot_mask & (1 << 3), 0);
+
+    // 8. POST /api/audio and POST /api/system
+    let mut audio_res = send_http_json(
+        addr,
+        "POST",
+        "/api/audio",
+        r#"{"audio_mode": "VoiceSuppression"}"#,
+    )
+    .await;
+    if audio_res.0 != 200 {
+        audio_res = send_http_json(
+            addr,
+            "POST",
+            "/api/audio",
+            r#"{"mode": "VoiceSuppression"}"#,
+        )
+        .await;
+    }
+    assert_eq!(audio_res.0, 200);
+
+    let (status, _, _) = send_http_json(
+        addr,
+        "POST",
+        "/api/system",
+        r#"{"privacy_mode": true, "horizontal_correction": true}"#,
+    )
+    .await;
+    assert_eq!(status, 200);
+
+    let (_, _, body) = send_http_get(addr, "/api/state").await;
+    let snapshot: CameraStateSnapshot = serde_json::from_str(&body).unwrap();
+    assert_eq!(snapshot.audio_mode, AudioCaptureMode::VoiceSuppression);
+    assert!(snapshot.privacy_mode);
+    assert!(snapshot.horizontal_correction);
+}