chore: remove dead code and stale doc claims found in multi-agent sweep

Compiler-verified via RUSTFLAGS=--force-warn dead_code plus workspace-wide
reference greps; three parallel audit agents covered the engine crate, the
other eight crates, and Copilot commit-message-vs-diff drift.

Removed:
- replay_overlay/input.rs: 19 orphaned twins (~950 lines) of items also
  defined in mod.rs — the glob re-export made the mod.rs copies win and
  the file-level #![allow(dead_code)] hid the corpses. The live keyboard/
  button handlers and ReplayScrubKeyHold stay; the allow is retired.
- retarget_animation (never called; doc examples were its only refs)
- ScanThemesRequestEvent (never registered/written/read; its doc claimed
  a handle_scan_themes consumer that does not exist)
- _VEC3_REFERENCED workaround const + now-unneeded Vec3 import
- solitaire_data: load_stats/save_stats/time_attack_session_with_now
  default-path wrappers (the _from/_to variants are the live API) and
  surplus re-export names (settings MIN/MAX bounds, token loaders)
- solitaire_core: Session re-export (no external consumer)
- solitaire_wasm: ReplayPlayer::is_finished (no JS caller)
- solitaire_app: build_app wrapper (real entry is run())

Doc fixes:
- audio_plugin: WAV count 5→7, add FoundationCompletedEvent table row,
  drop bogus 'placeholder' label, bevy_kira_audio→kira
- ToastVariant::Warning: variant is live (5 writer plugins); dropped the
  stale allow(dead_code) and its 'currently unused' comment

Deliberately kept: Spider module (staged forward work), WinCascadePlugin
(documented alternative cascade, pending owner decision), SyncCompleteEvent
and solitaire_sync ApiError/merge_at (§8 change-controlled, flagged to owner).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

solitaire_engine/src/card_animation/animation.rs

@@ -18,11 +18,6 @@
 //! The sine term is 0 at `t = 0` and `t = 1` and peaks at `t = 0.5`, so the
 //! card "floats up" in the middle of its travel and lands at its correct rest z.
 //!
-//! # Retargeting
-//!
-//! When a card is redirected mid-flight, call [`retarget_animation`]. It reads
-//! the current interpolated position so the card never snaps.
-//!
 //! # Coexistence with `CardAnim`
 //!
 //! `CardAnimation` and the legacy `CardAnim` can coexist in the same world but
@@ -123,8 +118,6 @@ impl CardAnimation {
     }
 
     /// Returns the current interpolated XY position without advancing time.
-    ///
-    /// Used by [`retarget_animation`] to read mid-flight position cleanly.
     pub fn current_xy(&self) -> Vec2 {
         if self.duration <= 0.0 {
             return self.end;
@@ -135,90 +128,6 @@ impl CardAnimation {
     }
 }
 
-// ---------------------------------------------------------------------------
-// Retarget helper
-// ---------------------------------------------------------------------------
-
-/// Redirects a card to a new destination without snapping or interrupting motion.
-///
-/// Reads the card's current interpolated position (from a live [`CardAnimation`]
-/// if present, or from `Transform` if stationary) and starts a fresh
-/// [`CardAnimation`] from that position. Duration is recalculated from the
-/// remaining distance so short paths stay quick.
-///
-/// # Velocity continuity
-///
-/// When a card is mid-flight, the new animation starts with a small positive
-/// `elapsed` offset (`carry`) derived from how far through the current animation
-/// the card is. This preserves a sense of forward momentum: the new curve does
-/// not restart from zero velocity, avoiding a visible "lurch" when the target
-/// changes rapidly.
-///
-/// The carry is deliberately small (≤ 10 % of the new duration) so that it
-/// never causes a visible position jump — the card's start position is still
-/// read from the current transform.
-///
-/// # Example
-///
-/// ```ignore
-/// // Inside a system that decides to move a card to a new target:
-/// let (entity, transform, anim) = cards.get(card_entity)?;
-/// retarget_animation(
-///     &mut commands,
-///     entity,
-///     anim,            // Option<&CardAnimation>
-///     transform,
-///     Vec2::new(400.0, 200.0),
-///     resting_z,
-///     MotionCurve::SmoothSnap,
-/// );
-/// ```
-pub fn retarget_animation(
-    commands: &mut Commands,
-    entity: Entity,
-    current_anim: Option<&CardAnimation>,
-    transform: &Transform,
-    new_end: Vec2,
-    new_end_z: f32,
-    curve: MotionCurve,
-) {
-    let (current_xy, current_z, momentum_carry) = match current_anim {
-        Some(anim) if anim.duration > 0.0 => {
-            // Estimate how far into the current animation we are and carry
-            // a small fraction of that progress into the new animation.
-            // This avoids restarting from zero velocity and makes the motion
-            // feel continuous when the target changes mid-flight.
-            let t = (anim.elapsed / anim.duration).clamp(0.0, 1.0);
-            // Cap at 10 % of the new animation so there's no visible jump.
-            let carry = (t * 0.12).min(0.10);
-            (anim.current_xy(), transform.translation.z, carry)
-        }
-        _ => (
-            transform.translation.truncate(),
-            transform.translation.z,
-            0.0,
-        ),
-    };
-
-    let distance = current_xy.distance(new_end);
-    let duration = compute_duration(distance);
-
-    commands.entity(entity).insert(CardAnimation {
-        start: current_xy,
-        end: new_end,
-        // Start slightly into the new animation to carry forward momentum.
-        elapsed: momentum_carry * duration,
-        duration,
-        curve,
-        delay: 0.0,
-        start_z: current_z,
-        end_z: new_end_z,
-        z_lift: 8.0,
-        scale_start: 1.0,
-        scale_end: 1.0,
-    });
-}
-
 // ---------------------------------------------------------------------------
 // System
 // ---------------------------------------------------------------------------

solitaire_engine/src/card_animation/mod.rs

@@ -31,28 +31,6 @@
 //! ));
 //! ```
 //!
-//! Retarget a card mid-flight:
-//!
-//! ```ignore
-//! use solitaire_engine::card_animation::retarget_animation;
-//!
-//! fn handle_drop(
-//!     mut commands: Commands,
-//!     q: Query<(Entity, &Transform, Option<&CardAnimation>), With<CardEntity>>,
-//! ) {
-//!     let (entity, transform, anim) = q.get(card_entity).unwrap();
-//!     retarget_animation(
-//!         &mut commands,
-//!         entity,
-//!         anim,
-//!         transform,
-//!         new_target_xy,
-//!         new_target_z,
-//!         MotionCurve::SmoothSnap,
-//!     );
-//! }
-//! ```
-//!
 //! # Win cascade with `Expressive` curve
 //!
 //! The existing `AnimationPlugin` drives the win cascade with `CardAnim`
@@ -80,7 +58,7 @@ pub mod interaction;
 pub mod timing;
 pub mod tuning;
 
-pub use animation::{CardAnimation, retarget_animation, win_scatter_targets};
+pub use animation::{CardAnimation, win_scatter_targets};
 pub use chain::AnimationChain;
 pub use curves::{MotionCurve, sample_curve};
 pub use diagnostics::{FrameTimeDiagnostics, WINDOW_SIZE as DIAG_WINDOW_SIZE};