From e8e810d1ffb78a6d88a1161ca81e594d4d984450 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Thu, 15 Oct 2026 02:33:09 +0200 Subject: [PATCH] feat(M5.4): enforce absolute-control pickup Tests: cargo test --locked -p fader-core --all-targets Lint: cargo clippy --locked -p fader-core --all-targets -- -D warnings --- core/src/lib.rs | 2 + core/src/pickup.rs | 97 ++++++++++++++++++++++++++++++++++++++++++++ core/tests/pickup.rs | 68 +++++++++++++++++++++++++++++++ 3 files changed, 167 insertions(+) create mode 100644 core/src/pickup.rs create mode 100644 core/tests/pickup.rs diff --git a/core/src/lib.rs b/core/src/lib.rs index ecbf463..d58379e 100644 --- a/core/src/lib.rs +++ b/core/src/lib.rs @@ -16,6 +16,7 @@ mod group; mod id; mod matching; mod mute; +mod pickup; mod revision; mod routing; mod server; @@ -33,6 +34,7 @@ pub use matching::{ SelectorKind, StreamHandle, StreamMetadata, }; pub use mute::{MuteIntent, MutePlanner, mute_view}; +pub use pickup::{Pickup, PickupError, PickupState}; pub use revision::{BackendEpoch, Revision}; pub use routing::{Routing, RoutingError, Target}; pub use server::{ diff --git a/core/src/pickup.rs b/core/src/pickup.rs new file mode 100644 index 0000000..36ca44d --- /dev/null +++ b/core/src/pickup.rs @@ -0,0 +1,97 @@ +use crate::Gain; +use thiserror::Error; + +/// Observable state of one non-motorized absolute control. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum PickupState { + /// No live target is available, such as while offline or disconnected. + Unavailable, + /// Input is inhibited until the physical position reaches the live target. + Waiting, + /// Physical movement is allowed to emit volume commands. + Tracking, +} + +/// Invalid pickup tolerance. +#[derive(Clone, Copy, Debug, Error, PartialEq)] +#[error("pickup tolerance {0} must be finite and within 0..=1")] +pub struct PickupError(f64); + +/// Pickup state for one non-motorized absolute control. +/// +/// Arming deliberately forgets the prior physical sample. This prevents an +/// external change, reconnect, rebind, or another surface's write from using a +/// stale position to cross a new target. +#[derive(Clone, Debug)] +pub struct Pickup { + tolerance: f64, + target: Option, + previous: Option, + state: PickupState, +} + +impl Pickup { + /// Constructs pickup with a normalized crossing tolerance. + pub fn new(tolerance: f64) -> Result { + if !tolerance.is_finite() || !(0.0..=1.0).contains(&tolerance) { + return Err(PickupError(tolerance)); + } + Ok(Self { + tolerance, + target: None, + previous: None, + state: PickupState::Unavailable, + }) + } + + /// Arms against the newest observed target without emitting a command. + /// Targets above the physical range are reachable at its upper endpoint. + pub fn arm(&mut self, observed: Gain) { + self.target = Some(if observed > Gain::UNITY { + Gain::UNITY + } else { + observed + }); + self.previous = None; + self.state = PickupState::Waiting; + } + + /// Makes input unavailable and discards all physical history. + pub fn disconnect(&mut self) { + self.target = None; + self.previous = None; + self.state = PickupState::Unavailable; + } + + /// Processes one normalized physical position. + /// + /// Returns a command value only after entering the tolerance window or + /// crossing the target between two consecutive samples. + pub fn input(&mut self, position: Gain) -> Option { + match self.state { + PickupState::Unavailable => None, + PickupState::Tracking => Some(position), + PickupState::Waiting => { + let target = self.target?; + let within = (position.get() - target.get()).abs() <= self.tolerance; + let crossed = self.previous.is_some_and(|previous| { + (previous < target && position > target) + || (previous > target && position < target) + }); + self.previous = Some(position); + if within || crossed { + self.state = PickupState::Tracking; + Some(position) + } else { + None + } + } + } + } + + /// Current pickup state for TUI and feedback views. + #[must_use] + pub const fn state(&self) -> PickupState { + self.state + } +} diff --git a/core/tests/pickup.rs b/core/tests/pickup.rs new file mode 100644 index 0000000..752af4e --- /dev/null +++ b/core/tests/pickup.rs @@ -0,0 +1,68 @@ +use fader_core::{Gain, Pickup, PickupState}; + +fn gain(value: f64) -> Gain { + Gain::new(value).unwrap() +} + +#[test] +fn startup_position_cannot_jump_audio_until_the_target_is_crossed() { + let mut pickup = Pickup::new(0.02).unwrap(); + pickup.arm(gain(0.7)); + + assert_eq!(pickup.input(gain(0.1)), None); + assert_eq!(pickup.input(gain(0.6)), None); + assert_eq!(pickup.input(gain(0.71)), Some(gain(0.71))); + assert_eq!(pickup.state(), PickupState::Tracking); + assert_eq!(pickup.input(gain(0.4)), Some(gain(0.4))); +} + +#[test] +fn crossing_activates_even_when_no_sample_lands_inside_tolerance() { + let mut pickup = Pickup::new(0.01).unwrap(); + pickup.arm(gain(0.5)); + + assert_eq!(pickup.input(gain(0.3)), None); + assert_eq!(pickup.input(gain(0.8)), Some(gain(0.8))); +} + +#[test] +fn external_change_and_reconnect_discard_the_old_physical_position() { + let mut pickup = Pickup::new(0.02).unwrap(); + pickup.arm(gain(0.5)); + assert_eq!(pickup.input(gain(0.5)), Some(gain(0.5))); + + pickup.arm(gain(0.8)); + assert_eq!(pickup.input(gain(0.4)), None); + assert_eq!(pickup.input(gain(0.81)), Some(gain(0.81))); + + pickup.disconnect(); + assert_eq!(pickup.state(), PickupState::Unavailable); + assert_eq!(pickup.input(gain(0.2)), None); + pickup.arm(gain(0.3)); + assert_eq!(pickup.input(gain(0.2)), None); +} + +#[test] +fn another_surface_move_rearms_pickup_and_amplified_targets_use_the_endpoint() { + let mut left = Pickup::new(0.02).unwrap(); + let mut right = Pickup::new(0.02).unwrap(); + left.arm(gain(0.4)); + right.arm(gain(0.4)); + assert_eq!(left.input(gain(0.4)), Some(gain(0.4))); + + right.arm(gain(0.8)); + assert_eq!(right.input(gain(0.1)), None); + assert_eq!(right.input(gain(0.8)), Some(gain(0.8))); + left.arm(gain(0.8)); + assert_eq!(left.input(gain(0.4)), None); + + left.arm(gain(1.5)); + assert_eq!(left.input(Gain::UNITY), Some(Gain::UNITY)); +} + +#[test] +fn tolerance_must_be_a_finite_normalized_distance() { + assert!(Pickup::new(-0.1).is_err()); + assert!(Pickup::new(1.1).is_err()); + assert!(Pickup::new(f64::NAN).is_err()); +}