hojicha_core/

core.rs

//! Core traits and types for the Elm Architecture
//!
//! This module contains the foundational traits and types that implement
//! The Elm Architecture (TEA) pattern in Hojicha.
//!
//! ## The Elm Architecture
//!
//! TEA is a pattern for organizing interactive applications with:
//! - **Unidirectional data flow**: Events flow through update to modify state
//! - **Pure functions**: Update and view are pure, side effects use commands
//! - **Clear separation**: Model (state), Update (logic), View (presentation)
//!
//! ## Core Components
//!
//! ### Model Trait
//! Your application struct implements this trait:
//! ```
//! # use hojicha_core::{Model, Cmd, Event};
//! struct MyApp {
//!     counter: i32,
//! }
//!
//! impl Model for MyApp {
//!     type Message = MyMessage;
//!     
//!     fn update(&mut self, event: Event<Self::Message>) -> Cmd<Self::Message> {
//!         // Handle events and return commands
//!         Cmd::noop()
//!     }
//!     
//!     fn view(&self) -> String {
//!         // Render the UI
//!         format!("Counter: {}", self.counter)
//!     }
//! }
//! # enum MyMessage {}
//! ```
//!
//! ### Commands
//! Commands represent side effects that produce messages:
//! ```
//! # use hojicha_core::Cmd;
//! # enum Msg { DataLoaded(String) }
//! let cmd: Cmd<Msg> = Cmd::new(|| {
//!     // Perform side effect
//!     let data = std::fs::read_to_string("data.txt").ok()?;
//!     Some(Msg::DataLoaded(data))
//! });
//! ```

use crate::event::Event;
use std::fmt::Debug;

/// Type alias for exec process callback function
type ExecCallback<M> = Box<dyn Fn(Option<i32>) -> M + Send>;

/// Type alias for exec process details
type ExecDetails<M> = (String, Vec<String>, ExecCallback<M>);

/// A message that can be sent to update the model.
///
/// Messages are typically enums that represent different events
/// or state changes in your application.
/// Marker trait for messages that can be sent through the system.
///
/// Types implementing this trait must be Send + 'static to work
/// with the async runtime.
pub trait Message: Send + 'static {}

// Blanket implementation - any type that is Send + 'static can be a Message.
// This is appropriate because Message is purely a marker trait with no behavior.
impl<T: Send + 'static> Message for T {}

/// The core trait for your application's model.
///
/// Your model should implement this trait to define how it:
/// - Initializes (`init`)
/// - Updates in response to messages (`update`)
/// - Renders to the screen (`view`)
///
/// ## Method Requirements
///
/// ### `init()` - Optional Initialization
/// The `init()` method is **optional** because many models don't need special
/// initialization logic. The default implementation returns `Cmd::noop()`,
/// which starts the event loop immediately without side effects.
///
/// **Override `init()` when you need to:**
/// - Load configuration or data files at startup
/// - Start background timers or periodic tasks
/// - Fetch initial data from external APIs
/// - Set up subscriptions to external data streams
///
/// **Use the default when:**
/// - Your model starts with static data
/// - No external setup is required
/// - All state is initialized through your struct's constructor
///
/// ### `update()` and `view()` - Required Core Methods
/// These methods are **required** because they form the core of the Elm Architecture:
///
/// - **`update()`**: The state transition function. Must handle all events and
///   return appropriate commands. This is where your business logic lives.
/// - **`view()`**: The rendering function. Must render the current state to
///   the terminal. This is where your UI layout is defined.
///
/// ## Complete Working Example
///
/// Here's a full counter application showing all lifecycle methods with proper imports:
///
/// ```rust
/// use hojicha_core::{Model, Cmd, Event, Key, commands};
/// use std::time::Duration;
///
/// // Your application state
/// #[derive(Debug)]
/// struct CounterApp {
///     count: i32,
///     last_action: String,
///     timer_active: bool,
/// }
///
/// // All possible messages your app can receive
/// #[derive(Debug, Clone)]
/// enum CounterMessage {
///     Increment,
///     Decrement,
///     Reset,
///     TimerTick,
///     LoadConfig(String),
/// }
///
/// impl CounterApp {
///     fn new() -> Self {
///         Self {
///             count: 0,
///             last_action: "Started".to_string(),
///             timer_active: false,
///         }
///     }
/// }
///
/// impl Model for CounterApp {
///     type Message = CounterMessage;
///
///     fn init(&mut self) -> Cmd<Self::Message> {
///         // Initialize by loading config and starting a timer
///         commands::batch(vec![
///             // Load configuration file
///             Cmd::new(|| {
///                 let config = std::fs::read_to_string("config.txt")
///                     .unwrap_or_else(|_| "Default config".to_string());
///                 Some(CounterMessage::LoadConfig(config))
///             }),
///             // Start a timer that ticks every 5 seconds
///             commands::every(Duration::from_secs(5), |_| CounterMessage::TimerTick)
///         ])
///     }
///
///     fn update(&mut self, event: Event<Self::Message>) -> Cmd<Self::Message> {
///         match event {
///             // Handle keyboard input
///             Event::Key(key) => match key.key {
///                 Key::Char('q') | Key::Esc => {
///                     // Quit the application
///                     commands::quit()
///                 }
///                 Key::Char('+') | Key::Up => {
///                     self.count += 1;
///                     self.last_action = "Incremented".to_string();
///                     Cmd::noop() // Continue running
///                 }
///                 Key::Char('-') | Key::Down => {
///                     self.count -= 1;
///                     self.last_action = "Decremented".to_string();
///                     Cmd::noop()
///                 }
///                 Key::Char('r') => {
///                     self.count = 0;
///                     self.last_action = "Reset".to_string();
///                     Cmd::noop()
///                 }
///                 Key::Char('t') => {
///                     self.timer_active = !self.timer_active;
///                     self.last_action = format!("Timer {}",
///                         if self.timer_active { "started" } else { "stopped" });
///                     Cmd::noop()
///                 }
///                 _ => Cmd::noop() // Ignore other keys
///             },
///
///             // Handle application messages
///             Event::User(msg) => match msg {
///                 CounterMessage::Increment => {
///                     self.count += 1;
///                     self.last_action = "Auto-incremented".to_string();
///                     Cmd::noop()
///                 }
///                 CounterMessage::Decrement => {
///                     self.count -= 1;
///                     self.last_action = "Auto-decremented".to_string();
///                     Cmd::noop()
///                 }
///                 CounterMessage::Reset => {
///                     self.count = 0;
///                     self.last_action = "Auto-reset".to_string();
///                     Cmd::noop()
///                 }
///                 CounterMessage::TimerTick => {
///                     if self.timer_active {
///                         self.count += 1;
///                         self.last_action = "Timer tick".to_string();
///                     }
///                     Cmd::noop()
///                 }
///                 CounterMessage::LoadConfig(config) => {
///                     self.last_action = format!("Config loaded: {}", config);
///                     Cmd::noop()
///                 }
///             },
///
///             // Handle other events
///             Event::Tick => Cmd::noop(),
///             Event::Resize { width: _, height: _ } => {
///                 self.last_action = "Window resized".to_string();
///                 Cmd::noop()
///             }
///             _ => Cmd::noop(),
///         }
///     }
///
///     fn view(&self) -> String {
///         format!(
///             "Counter Application\n\
///              \n\
///              Count: {}\n\
///              Last Action: {}\n\
///              Timer: {}\n\
///              \n\
///              Controls:\n\
///              +/↑  - Increment\n\
///              -/↓  - Decrement\n\
///              r    - Reset\n\
///              t    - Toggle timer\n\
///              q/Esc - Quit",
///             self.count,
///             self.last_action,
///             if self.timer_active { "Active" } else { "Inactive" }
///         )
///     }
/// }
///
/// // Usage in main function:
/// // let mut app = CounterApp::new();
/// // hojicha::run(app).unwrap();
/// ```
///
/// ## Simple Examples
///
/// ### Basic Model (No Initialization)
/// ```
/// # use hojicha_core::{Model, Cmd, Event};
/// struct Counter { value: i32 }
///
/// impl Model for Counter {
///     type Message = CounterMsg;
///     
///     // Using default init() - no override needed
///     
///     fn update(&mut self, event: Event<Self::Message>) -> Cmd<Self::Message> {
///         // Handle events...
///         Cmd::noop()
///     }
///     
///     fn view(&self) -> String {
///         format!("Count: {}", self.value)
///     }
/// }
/// # enum CounterMsg {}
/// ```
///
/// ### Model with Initialization
/// ```
/// # use hojicha_core::{Model, Cmd, Event, commands};
/// # use std::time::Duration;
/// struct App { status: String }
///
/// impl Model for App {
///     type Message = AppMsg;
///     
///     fn init(&mut self) -> Cmd<Self::Message> {
///         // Override init() to start a timer
///         commands::every(Duration::from_secs(1), |_| AppMsg::Tick)
///     }
///     
///     fn update(&mut self, event: Event<Self::Message>) -> Cmd<Self::Message> {
///         // Handle events...
///         Cmd::noop()
///     }
///     
///     fn view(&self) -> String {
///         format!("Status: {}", self.status)
///     }
/// }
/// # enum AppMsg { Tick }
/// ```
pub trait Model: Sized {
    /// The type of messages this model can receive
    type Message: Message;

    /// Initialize the model and return a command to run
    ///
    /// This method is called once when the program starts. Use it to:
    /// - Load initial data
    /// - Start timers
    /// - Perform initial setup
    ///
    /// Returns:
    /// - `Cmd::noop()` - Start the event loop without any initial command
    /// - Any other command - Execute the command before starting the event loop
    ///
    /// # Example
    /// ```
    /// # use hojicha_core::{Model, Cmd, commands};
    /// # use std::time::Duration;
    /// # struct MyApp;
    /// # enum Msg { Tick }
    /// # impl Model for MyApp {
    /// #     type Message = Msg;
    /// fn init(&mut self) -> Cmd<Self::Message> {
    ///     // Start a timer that ticks every second
    ///     commands::every(Duration::from_secs(1), |_| Msg::Tick)
    /// }
    /// #     fn update(&mut self, _: hojicha_core::Event<Self::Message>) -> Cmd<Self::Message> { Cmd::noop() }
    /// #     fn view(&self) -> String { String::new() }
    /// # }
    /// ```
    fn init(&mut self) -> Cmd<Self::Message> {
        Cmd::noop()
    }

    /// Update the model based on a message and return a command
    ///
    /// This is the heart of your application logic. Handle events here and
    /// update your model's state accordingly.
    ///
    /// Returns:
    /// - `Cmd::noop()` - Continue running without executing any command
    /// - `commands::quit()` - Exit the program
    /// - Any other command - Execute the command and continue
    ///
    /// # Example
    /// ```
    /// # use hojicha_core::{Model, Cmd, Event, Key, commands};
    /// # struct Counter { value: i32 }
    /// # enum Msg { Increment, Decrement }
    /// # impl Model for Counter {
    /// #     type Message = Msg;
    /// fn update(&mut self, event: Event<Self::Message>) -> Cmd<Self::Message> {
    ///     match event {
    ///         Event::Key(key) if key.key == Key::Char('q') => {
    ///             commands::quit()
    ///         }
    ///         Event::User(Msg::Increment) => {
    ///             self.value += 1;
    ///             Cmd::noop()
    ///         }
    ///         Event::User(Msg::Decrement) => {
    ///             self.value -= 1;
    ///             Cmd::noop()
    ///         }
    ///         _ => Cmd::noop()
    ///     }
    /// }
    /// #     fn view(&self) -> String { String::new() }
    /// # }
    /// ```
    fn update(&mut self, msg: Event<Self::Message>) -> Cmd<Self::Message>;

    /// Render the model to a string
    ///
    /// This method is called after each update to render your UI.
    /// Return a string with ANSI escape codes for terminal rendering.
    ///
    /// # Example
    /// ```
    /// # use hojicha_core::Model;
    /// # struct MyApp { message: String }
    /// # impl Model for MyApp {
    /// #     type Message = ();
    /// #     fn update(&mut self, _: hojicha_core::Event<Self::Message>) -> hojicha_core::Cmd<Self::Message> { hojicha_core::Cmd::noop() }
    /// fn view(&self) -> String {
    ///     format!("My App\n{}", self.message)
    /// }
    /// # }
    /// ```
    fn view(&self) -> String;
}

/// A command is an asynchronous operation that produces a message.
///
/// Commands are used for side effects like:
/// - HTTP requests
/// - File I/O
/// - Timers
/// - Any async operation
pub struct Cmd<M: Message> {
    inner: CmdInner<M>,
}

// Type aliases for complex command types
type AsyncFuture<M> = Box<dyn std::future::Future<Output = Option<M>> + Send>;
type CommandFn<M> = Box<dyn FnOnce() -> Option<M> + Send>;
type FallibleFn<M> = Box<dyn FnOnce() -> crate::Result<Option<M>> + Send>;

pub(crate) enum CmdInner<M: Message> {
    /// No operation - continue running without doing anything
    NoOp,
    /// A simple function command
    Function(CommandFn<M>),
    /// A function command that can return errors
    Fallible(FallibleFn<M>),
    /// An external process command
    ExecProcess {
        program: String,
        args: Vec<String>,
        callback: ExecCallback<M>,
    },
    /// Quit the program
    Quit,
    /// Execute multiple commands concurrently
    Batch(Vec<Cmd<M>>),
    /// Execute multiple commands sequentially
    Sequence(Vec<Cmd<M>>),
    /// Execute after a delay
    Tick {
        duration: std::time::Duration,
        callback: Box<dyn FnOnce() -> M + Send>,
    },
    /// Execute repeatedly at intervals
    Every {
        duration: std::time::Duration,
        callback: Box<dyn FnOnce(std::time::Instant) -> M + Send>,
    },
    /// Execute an async future
    Async(AsyncFuture<M>),
}

impl<M: Message> Cmd<M> {
    /// Create a new command from a function
    ///
    /// Note: If the function returns `None`, consider using `Cmd::noop()` instead
    /// for better performance and clearer intent.
    ///
    /// # Example
    /// ```
    /// # use hojicha_core::Cmd;
    /// # enum Msg { DataLoaded(String) }
    /// let cmd: Cmd<Msg> = Cmd::new(|| {
    ///     // Perform a side effect
    ///     let data = std::fs::read_to_string("config.json").ok()?;
    ///     Some(Msg::DataLoaded(data))
    /// });
    /// ```
    pub fn new<F>(f: F) -> Self
    where
        F: FnOnce() -> Option<M> + Send + 'static,
    {
        Cmd {
            inner: CmdInner::Function(Box::new(f)),
        }
    }

    /// Create a new fallible command that can return errors
    ///
    /// Use this when your command might fail and you want to handle errors gracefully.
    ///
    /// # Example
    /// ```
    /// # use hojicha_core::{Cmd, Result};
    /// # enum Msg { ConfigLoaded(String) }
    /// let cmd: Cmd<Msg> = Cmd::fallible(|| {
    ///     let data = std::fs::read_to_string("config.json")?;
    ///     Ok(Some(Msg::ConfigLoaded(data)))
    /// });
    /// ```
    pub fn fallible<F>(f: F) -> Self
    where
        F: FnOnce() -> crate::Result<Option<M>> + Send + 'static,
    {
        Cmd {
            inner: CmdInner::Fallible(Box::new(f)),
        }
    }

    /// Returns a no-op command that continues running without doing anything
    ///
    /// This is the idiomatic way to return "no command" from `update()`.
    /// The program will continue running without executing any side effects.
    ///
    /// # Example
    /// ```
    /// # use hojicha_core::{Model, Cmd, Event};
    /// # struct MyApp;
    /// # impl Model for MyApp {
    /// #     type Message = ();
    /// #     fn update(&mut self, event: Event<Self::Message>) -> Cmd<Self::Message> {
    ///         match event {
    ///             Event::Tick => {
    ///                 // Update internal state but don't trigger side effects
    ///                 Cmd::noop()
    ///             }
    ///             _ => Cmd::noop()
    ///         }
    /// #     }
    /// #     fn view(&self) -> String { String::new() }
    /// # }
    /// ```
    #[must_use]
    pub fn noop() -> Self {
        Cmd {
            inner: CmdInner::NoOp,
        }
    }

    /// Returns a no-op command that continues running without doing anything
    ///
    /// # Deprecated
    /// This method is deprecated. Use `Cmd::noop()` instead for clearer intent.
    /// The name "none" was confusing because it returns `Some(Cmd)` rather than `None`.
    ///
    /// # Example
    /// ```
    /// # use hojicha_core::Cmd;
    /// # enum Msg {}
    /// // Old way (deprecated):
    /// let cmd: Cmd<Msg> = Cmd::noop();
    ///
    /// // New way (preferred):
    /// let cmd: Cmd<Msg> = Cmd::noop();
    /// ```
    #[deprecated(
        since = "0.2.1",
        note = "Use Cmd::noop() instead. The name 'none' was confusing."
    )]
    #[must_use]
    pub fn none() -> Self {
        Self::noop()
    }

    /// Internal method
    #[doc(hidden)]
    pub fn exec_process<F>(program: String, args: Vec<String>, callback: F) -> Self
    where
        F: Fn(Option<i32>) -> M + Send + 'static,
    {
        Cmd {
            inner: CmdInner::ExecProcess {
                program,
                args,
                callback: Box::new(callback),
            },
        }
    }

    /// Create a batch command that executes commands concurrently
    /// Internal method
    #[doc(hidden)]
    #[must_use]
    pub fn batch(cmds: Vec<Cmd<M>>) -> Self {
        Cmd {
            inner: CmdInner::Batch(cmds),
        }
    }

    /// Create a sequence command that executes commands in order
    /// Internal method
    #[doc(hidden)]
    #[must_use]
    pub fn sequence(cmds: Vec<Cmd<M>>) -> Self {
        Cmd {
            inner: CmdInner::Sequence(cmds),
        }
    }

    /// Create a quit command
    ///
    /// # Deprecated
    /// This method is deprecated. Use `commands::quit()` instead for consistency.
    ///
    /// # Example
    /// ```no_run
    /// # use hojicha_core::{Cmd, commands};
    /// # enum Msg {}
    /// // Old way (deprecated):
    /// let cmd: Cmd<Msg> = Cmd::quit();
    ///
    /// // New way (preferred):
    /// let cmd: Cmd<Msg> = commands::quit();
    /// ```
    #[deprecated(since = "0.2.1", note = "Use commands::quit() instead for consistency")]
    #[must_use]
    pub fn quit() -> Self {
        Cmd {
            inner: CmdInner::Quit,
        }
    }

    /// Create a tick command
    ///
    /// # Deprecated
    /// This method is deprecated. Use `commands::tick()` instead for consistency.
    ///
    /// # Example
    /// ```no_run
    /// # use hojicha_core::{Cmd, commands};
    /// # use std::time::Duration;
    /// # enum Msg { Tick }
    /// // Old way (deprecated):
    /// let cmd: Cmd<Msg> = Cmd::tick(Duration::from_secs(1), || Msg::Tick);
    ///
    /// // New way (preferred):
    /// let cmd: Cmd<Msg> = commands::tick(Duration::from_secs(1), || Msg::Tick);
    /// ```
    #[deprecated(since = "0.2.1", note = "Use commands::tick() instead for consistency")]
    pub fn tick<F>(duration: std::time::Duration, callback: F) -> Self
    where
        F: FnOnce() -> M + Send + 'static,
    {
        Cmd {
            inner: CmdInner::Tick {
                duration,
                callback: Box::new(callback),
            },
        }
    }

    /// Create an every command
    ///
    /// # Deprecated
    /// This method is deprecated. Use `commands::every()` instead for consistency.
    ///
    /// # Example
    /// ```no_run
    /// # use hojicha_core::{Cmd, commands};
    /// # use std::time::{Duration, Instant};
    /// # enum Msg { Tick(Instant) }
    /// // Old way (deprecated):
    /// let cmd: Cmd<Msg> = Cmd::every(Duration::from_secs(1), |instant| Msg::Tick(instant));
    ///
    /// // New way (preferred):
    /// let cmd: Cmd<Msg> = commands::every(Duration::from_secs(1), |instant| Msg::Tick(instant));
    /// ```
    #[deprecated(
        since = "0.2.1",
        note = "Use commands::every() instead for consistency"
    )]
    pub fn every<F>(duration: std::time::Duration, callback: F) -> Self
    where
        F: FnOnce(std::time::Instant) -> M + Send + 'static,
    {
        Cmd {
            inner: CmdInner::Every {
                duration,
                callback: Box::new(callback),
            },
        }
    }

    /// Create an async command
    /// Internal method
    #[doc(hidden)]
    pub fn async_cmd<Fut>(future: Fut) -> Self
    where
        Fut: std::future::Future<Output = Option<M>> + Send + 'static,
    {
        Cmd {
            inner: CmdInner::Async(Box::new(future)),
        }
    }

    /// Execute the command and return its message
    /// Internal method
    #[doc(hidden)]
    pub fn execute(self) -> crate::Result<Option<M>> {
        match self.inner {
            CmdInner::Function(func) => Ok(func()),
            CmdInner::Fallible(func) => func(),
            CmdInner::ExecProcess {
                program,
                args,
                callback,
            } => {
                // In the real implementation, this would be handled by the runtime
                // For now, we'll just run it directly
                use std::process::Command;
                let output = Command::new(&program).args(&args).status();
                let exit_code = output.ok().and_then(|status| status.code());
                Ok(Some(callback(exit_code)))
            }
            CmdInner::NoOp => {
                // NoOp commands don't produce messages, just continue running
                Ok(None)
            }
            CmdInner::Quit => {
                // Quit commands don't produce messages, they're handled specially
                Ok(None)
            }
            CmdInner::Batch(_) | CmdInner::Sequence(_) => {
                // These are handled specially by the CommandExecutor
                Ok(None)
            }
            CmdInner::Tick { .. } | CmdInner::Every { .. } | CmdInner::Async(_) => {
                // These are handled specially by the CommandExecutor with async runtime
                Ok(None)
            }
        }
    }

    /// Execute the command and return its message (for testing only)
    #[doc(hidden)]
    pub fn test_execute(self) -> crate::Result<Option<M>> {
        self.execute()
    }

    /// Check if this is an exec process command
    /// Check if this is an exec process command
    #[must_use]
    pub fn is_exec_process(&self) -> bool {
        matches!(self.inner, CmdInner::ExecProcess { .. })
    }

    /// Check if this is a no-op command
    #[must_use]
    pub fn is_noop(&self) -> bool {
        matches!(self.inner, CmdInner::NoOp)
    }

    /// Check if this is a quit command
    #[must_use]
    pub fn is_quit(&self) -> bool {
        matches!(self.inner, CmdInner::Quit)
    }

    /// Extract exec process details if this is an exec process command
    #[allow(clippy::type_complexity)]
    /// Internal method
    #[doc(hidden)]
    #[must_use]
    pub fn take_exec_process(self) -> Option<ExecDetails<M>> {
        match self.inner {
            CmdInner::ExecProcess {
                program,
                args,
                callback,
            } => Some((program, args, callback)),
            _ => None,
        }
    }

    /// Transform the messages produced by this command
    ///
    /// This is essential for component composition, allowing child components
    /// to produce commands that can be lifted to parent message types.
    ///
    /// # Example
    /// ```
    /// # use hojicha_core::Cmd;
    /// # #[derive(Clone, Debug)]
    /// # enum ChildMsg { Click }
    /// # #[derive(Clone, Debug)]
    /// # enum ParentMsg { Child(ChildMsg) }
    /// let child_cmd: Cmd<ChildMsg> = Cmd::new(|| Some(ChildMsg::Click));
    /// let parent_cmd: Cmd<ParentMsg> = child_cmd.map(ParentMsg::Child);
    /// ```
    pub fn map<N, F>(self, f: F) -> Cmd<N>
    where
        N: Message,
        F: Fn(M) -> N + Send + Sync + 'static + Clone,
    {
        // Wrap in Arc to make cloning cheaper for batch/sequence operations
        let f = std::sync::Arc::new(f);
        self.map_with_arc(f)
    }

    /// Internal method for mapping with Arc-wrapped function
    fn map_with_arc<N, F>(self, f: std::sync::Arc<F>) -> Cmd<N>
    where
        N: Message,
        F: Fn(M) -> N + Send + Sync + 'static,
    {
        match self.inner {
            CmdInner::NoOp => Cmd {
                inner: CmdInner::NoOp,
            },
            CmdInner::Quit => Cmd {
                inner: CmdInner::Quit,
            },

            CmdInner::Function(func) => {
                let f = f.clone(); // Cheap Arc clone
                Cmd {
                    inner: CmdInner::Function(Box::new(move || func().map(move |m| f(m)))),
                }
            }

            CmdInner::Fallible(func) => {
                let f = f.clone(); // Cheap Arc clone
                Cmd {
                    inner: CmdInner::Fallible(Box::new(move || {
                        func().map(|opt| opt.map(move |m| f(m)))
                    })),
                }
            }

            CmdInner::ExecProcess {
                program,
                args,
                callback,
            } => {
                let f = f.clone(); // Cheap Arc clone
                Cmd {
                    inner: CmdInner::ExecProcess {
                        program,
                        args,
                        callback: Box::new(move |code| f(callback(code))),
                    },
                }
            }

            CmdInner::Batch(cmds) => {
                let mapped_cmds = cmds
                    .into_iter()
                    .map(|cmd| {
                        cmd.map_with_arc(f.clone()) // Cheap Arc clone
                    })
                    .collect();
                Cmd {
                    inner: CmdInner::Batch(mapped_cmds),
                }
            }

            CmdInner::Sequence(cmds) => {
                let mapped_cmds = cmds
                    .into_iter()
                    .map(|cmd| {
                        cmd.map_with_arc(f.clone()) // Cheap Arc clone
                    })
                    .collect();
                Cmd {
                    inner: CmdInner::Sequence(mapped_cmds),
                }
            }

            CmdInner::Tick { duration, callback } => {
                let f = f.clone(); // Cheap Arc clone
                Cmd {
                    inner: CmdInner::Tick {
                        duration,
                        callback: Box::new(move || f(callback())),
                    },
                }
            }

            CmdInner::Every { duration, callback } => {
                let f = f.clone(); // Cheap Arc clone
                Cmd {
                    inner: CmdInner::Every {
                        duration,
                        callback: Box::new(move |instant| f(callback(instant))),
                    },
                }
            }

            CmdInner::Async(_future) => {
                // Mapping async futures requires complex type gymnastics with Pin
                // Since async commands are primarily created through spawn() which
                // already allows specifying the message type, and map() is rarely
                // needed for async commands in practice, we return a no-op here.
                // Users should use spawn() with the appropriate message type instead.
                Cmd {
                    inner: CmdInner::NoOp,
                }
            }
        }
    }

    /// Check if this is a batch command
    /// Internal method
    #[doc(hidden)]
    #[must_use]
    pub fn is_batch(&self) -> bool {
        matches!(self.inner, CmdInner::Batch(_))
    }

    /// Take the batch commands (consumes the command)
    /// Internal method
    #[doc(hidden)]
    #[must_use]
    pub fn take_batch(self) -> Option<Vec<Cmd<M>>> {
        match self.inner {
            CmdInner::Batch(cmds) => Some(cmds),
            _ => None,
        }
    }

    /// Check if this is a sequence command
    /// Internal method
    #[doc(hidden)]
    #[must_use]
    pub fn is_sequence(&self) -> bool {
        matches!(self.inner, CmdInner::Sequence(_))
    }

    /// Take the sequence commands (consumes the command)
    /// Internal method
    #[doc(hidden)]
    #[must_use]
    pub fn take_sequence(self) -> Option<Vec<Cmd<M>>> {
        match self.inner {
            CmdInner::Sequence(cmds) => Some(cmds),
            _ => None,
        }
    }

    /// Internal method
    #[doc(hidden)]
    #[must_use]
    pub fn is_tick(&self) -> bool {
        matches!(self.inner, CmdInner::Tick { .. })
    }

    /// Internal method
    #[doc(hidden)]
    #[must_use]
    pub fn is_every(&self) -> bool {
        matches!(self.inner, CmdInner::Every { .. })
    }

    /// Internal method
    #[doc(hidden)]
    #[must_use]
    pub fn take_tick(self) -> Option<(std::time::Duration, Box<dyn FnOnce() -> M + Send>)> {
        match self.inner {
            CmdInner::Tick { duration, callback } => Some((duration, callback)),
            _ => None,
        }
    }

    #[allow(clippy::type_complexity)]
    /// Internal method
    #[doc(hidden)]
    #[must_use]
    pub fn take_every(
        self,
    ) -> Option<(
        std::time::Duration,
        Box<dyn FnOnce(std::time::Instant) -> M + Send>,
    )> {
        match self.inner {
            CmdInner::Every { duration, callback } => Some((duration, callback)),
            _ => None,
        }
    }

    /// Internal method
    #[doc(hidden)]
    #[must_use]
    pub fn is_async(&self) -> bool {
        matches!(self.inner, CmdInner::Async(_))
    }

    /// Internal method
    #[doc(hidden)]
    #[must_use]
    pub fn take_async(self) -> Option<Box<dyn std::future::Future<Output = Option<M>> + Send>> {
        match self.inner {
            CmdInner::Async(future) => Some(future),
            _ => None,
        }
    }

    /// Inspect this command for debugging
    ///
    /// This allows you to observe command execution without modifying behavior.
    ///
    /// # Example
    /// ```no_run
    /// # use hojicha_core::Cmd;
    /// # #[derive(Clone)]
    /// # struct Msg;
    /// let cmd: Cmd<Msg> = Cmd::noop()
    ///     .inspect(|cmd| println!("Executing command: {:?}", cmd));
    /// ```
    #[must_use]
    pub fn inspect<F>(self, f: F) -> Self
    where
        F: FnOnce(&Self),
    {
        f(&self);
        self
    }

    /// Conditionally inspect this command
    ///
    /// Only runs the inspection function if the condition is true.
    ///
    /// # Example
    /// ```
    /// # use hojicha_core::Cmd;
    /// # enum Msg { Data(String) }
    /// # let debug_mode = true;
    /// let cmd: Cmd<Msg> = Cmd::new(|| Some(Msg::Data("test".into())))
    ///     .inspect_if(debug_mode, |cmd| {
    ///         eprintln!("Debug: executing {}", cmd.debug_name());
    ///     });
    /// ```
    #[must_use]
    pub fn inspect_if<F>(self, condition: bool, f: F) -> Self
    where
        F: FnOnce(&Self),
    {
        if condition {
            f(&self);
        }
        self
    }

    /// Get a string representation of the command type for debugging
    ///
    /// # Example
    /// ```
    /// # use hojicha_core::{Cmd, commands};
    /// # enum Msg { Tick }
    /// # use std::time::Duration;
    /// let cmd: Cmd<Msg> = commands::tick(Duration::from_secs(1), || Msg::Tick);
    /// assert_eq!(cmd.debug_name(), "Tick");
    ///
    /// let noop: Cmd<Msg> = Cmd::noop();
    /// assert_eq!(noop.debug_name(), "NoOp");
    /// ```
    #[must_use]
    pub fn debug_name(&self) -> &'static str {
        match self.inner {
            CmdInner::Function(_) => "Function",
            CmdInner::Fallible(_) => "Fallible",
            CmdInner::ExecProcess { .. } => "ExecProcess",
            CmdInner::NoOp => "NoOp",
            CmdInner::Quit => "Quit",
            CmdInner::Batch(_) => "Batch",
            CmdInner::Sequence(_) => "Sequence",
            CmdInner::Tick { .. } => "Tick",
            CmdInner::Every { .. } => "Every",
            CmdInner::Async(_) => "Async",
        }
    }

    // Command Composition Helpers

    /// Chain this command with another, running them sequentially
    ///
    /// The second command will only run after the first completes.
    /// This is equivalent to `sequence(vec![self, other])`.
    ///
    /// # Example
    /// ```
    /// use hojicha_core::{Cmd, Message};
    ///
    /// #[derive(Debug, Clone)]
    /// enum Msg {
    ///     First,
    ///     Second,
    /// }
    ///
    /// let cmd: Cmd<Msg> = Cmd::new(|| Some(Msg::First))
    ///     .then(Cmd::new(|| Some(Msg::Second)));
    /// ```
    #[must_use]
    pub fn then(self, other: Cmd<M>) -> Cmd<M> {
        if self.is_noop() {
            return other;
        }
        if other.is_noop() {
            return self;
        }
        Cmd::sequence(vec![self, other])
    }

    /// Combine this command with another, running them concurrently
    ///
    /// Both commands will run at the same time.
    /// This is equivalent to `batch(vec![self, other])`.
    ///
    /// # Example
    /// ```
    /// use hojicha_core::{Cmd, Message};
    /// use std::time::Duration;
    ///
    /// #[derive(Debug, Clone)]
    /// enum Msg {
    ///     Tick1,
    ///     Tick2,
    /// }
    ///
    /// let cmd: Cmd<Msg> = Cmd::tick(Duration::from_secs(1), || Msg::Tick1)
    ///     .and(Cmd::tick(Duration::from_secs(2), || Msg::Tick2));
    /// ```
    #[must_use]
    pub fn and(self, other: Cmd<M>) -> Cmd<M> {
        if self.is_noop() {
            return other;
        }
        if other.is_noop() {
            return self;
        }
        Cmd::batch(vec![self, other])
    }

    /// Execute this command only if a condition is met
    ///
    /// If the condition is false, returns `Cmd::noop()`.
    ///
    /// # Example
    /// ```
    /// use hojicha_core::{Cmd, Message};
    ///
    /// #[derive(Debug, Clone)]
    /// enum Msg {
    ///     Action,
    /// }
    ///
    /// let enabled = true;
    /// let cmd: Cmd<Msg> = Cmd::new(|| Some(Msg::Action))
    ///     .when(enabled);
    /// ```
    #[must_use]
    pub fn when(self, condition: bool) -> Cmd<M> {
        if condition {
            self
        } else {
            Cmd::noop()
        }
    }

    /// Execute this command unless a condition is met
    ///
    /// If the condition is true, returns `Cmd::noop()`.
    ///
    /// # Example
    /// ```
    /// use hojicha_core::{Cmd, Message};
    ///
    /// #[derive(Debug, Clone)]
    /// enum Msg {
    ///     Action,
    /// }
    ///
    /// let disabled = false;
    /// let cmd: Cmd<Msg> = Cmd::new(|| Some(Msg::Action))
    ///     .unless(disabled);
    /// ```
    #[must_use]
    pub fn unless(self, condition: bool) -> Cmd<M> {
        self.when(!condition)
    }
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use crate::event::Event;

    // Test model
    #[derive(Clone)]
    struct Counter {
        value: i32,
    }

    #[derive(Debug, Clone, PartialEq)]
    enum Msg {
        Increment,
        Decrement,
        SetValue(i32),
        Noop,
    }

    impl Model for Counter {
        type Message = Msg;

        fn init(&mut self) -> Cmd<Self::Message> {
            Cmd::new(|| Some(Msg::SetValue(0)))
        }

        fn update(&mut self, msg: Event<Self::Message>) -> Cmd<Self::Message> {
            if let Event::User(msg) = msg {
                match msg {
                    Msg::Increment => {
                        self.value += 1;
                        Cmd::new(move || Some(Msg::Noop))
                    }
                    Msg::Decrement => {
                        self.value -= 1;
                        Cmd::new(move || Some(Msg::Noop))
                    }
                    Msg::SetValue(v) => {
                        self.value = v;
                        Cmd::noop()
                    }
                    Msg::Noop => Cmd::noop(),
                }
            } else {
                Cmd::noop()
            }
        }

        fn view(&self) -> String {
            format!("Count: {}", self.value)
        }
    }

    #[test]
    fn test_model_update() {
        let mut model = Counter { value: 0 };

        model.update(Event::User(Msg::Increment));
        assert_eq!(model.value, 1);

        model.update(Event::User(Msg::Decrement));
        assert_eq!(model.value, 0);
    }

    #[test]
    fn test_cmd_creation() {
        let cmd = Cmd::new(|| Some(Msg::Increment));
        let msg = cmd.test_execute().unwrap();
        assert!(matches!(msg, Some(Msg::Increment)));
    }

    #[test]
    fn test_cmd_noop() {
        let cmd: Cmd<Msg> = Cmd::noop();
        assert!(cmd.is_noop());
    }

    #[test]
    fn test_cmd_none_deprecated() {
        #[allow(deprecated)]
        let cmd: Cmd<Msg> = Cmd::noop();
        assert!(cmd.is_noop());
    }

    #[test]
    fn test_cmd_fallible_success() {
        let cmd = Cmd::fallible(|| Ok(Some(Msg::Increment)));
        let result = cmd.test_execute();
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), Some(Msg::Increment));
    }

    #[test]
    fn test_cmd_fallible_error() {
        let cmd: Cmd<Msg> =
            Cmd::fallible(|| Err(crate::Error::from(std::io::Error::other("test error"))));
        let result = cmd.test_execute();
        assert!(result.is_err());
    }

    #[test]
    fn test_cmd_exec_process() {
        let cmd = Cmd::exec_process("echo".to_string(), vec!["test".to_string()], |_| {
            Msg::Increment
        });
        assert!(cmd.is_exec_process());

        let exec_details = cmd.take_exec_process();
        assert!(exec_details.is_some());
        let (program, args, _) = exec_details.unwrap();
        assert_eq!(program, "echo");
        assert_eq!(args, vec!["test"]);
    }

    #[test]
    fn test_cmd_debug() {
        let cmd = Cmd::new(|| Some(Msg::Increment));
        let debug_str = format!("{cmd:?}");
        assert!(debug_str.contains("Cmd"));
    }

    #[test]
    fn test_command_composition_helpers() {
        // Test `then` chaining
        let cmd1: Cmd<Msg> = Cmd::new(|| Some(Msg::Increment));
        let cmd2: Cmd<Msg> = Cmd::new(|| Some(Msg::Decrement));
        let chained = cmd1.then(cmd2);
        assert!(chained.is_sequence());

        // Test `and` batching
        let cmd1: Cmd<Msg> = Cmd::new(|| Some(Msg::Increment));
        let cmd2: Cmd<Msg> = Cmd::new(|| Some(Msg::Decrement));
        let batched = cmd1.and(cmd2);
        assert!(batched.is_batch());

        // Test `when` conditional - true case
        let cmd: Cmd<Msg> = Cmd::new(|| Some(Msg::Increment));
        let enabled = cmd.when(true);
        assert!(!enabled.is_noop());

        // Test `when` conditional - false case
        let cmd: Cmd<Msg> = Cmd::new(|| Some(Msg::Increment));
        let disabled = cmd.when(false);
        assert!(disabled.is_noop());

        // Test `unless` conditional - false case
        let cmd: Cmd<Msg> = Cmd::new(|| Some(Msg::Increment));
        let enabled = cmd.unless(false);
        assert!(!enabled.is_noop());

        // Test `unless` conditional - true case
        let cmd: Cmd<Msg> = Cmd::new(|| Some(Msg::Increment));
        let disabled = cmd.unless(true);
        assert!(disabled.is_noop());

        // Test optimization - noop.then(cmd)
        let noop: Cmd<Msg> = Cmd::noop();
        let cmd: Cmd<Msg> = Cmd::new(|| Some(Msg::Increment));
        let result = noop.then(cmd);
        assert!(!result.is_sequence()); // Should just return cmd
        assert!(!result.is_noop());

        // Test optimization - cmd.then(noop)
        let cmd: Cmd<Msg> = Cmd::new(|| Some(Msg::Increment));
        let noop: Cmd<Msg> = Cmd::noop();
        let result = cmd.then(noop);
        assert!(!result.is_sequence()); // Should just return cmd
        assert!(!result.is_noop());

        // Test optimization - noop.and(cmd)
        let noop: Cmd<Msg> = Cmd::noop();
        let cmd: Cmd<Msg> = Cmd::new(|| Some(Msg::Increment));
        let result = noop.and(cmd);
        assert!(!result.is_batch()); // Should just return cmd
        assert!(!result.is_noop());

        // Test optimization - cmd.and(noop)
        let cmd: Cmd<Msg> = Cmd::new(|| Some(Msg::Increment));
        let noop: Cmd<Msg> = Cmd::noop();
        let result = cmd.and(noop);
        assert!(!result.is_batch()); // Should just return cmd
        assert!(!result.is_noop());
    }

    #[test]
    fn test_model_init() {
        let mut model = Counter { value: 5 };
        let cmd = model.init();
        assert!(!cmd.is_noop());

        let result = cmd.test_execute().unwrap();
        assert_eq!(result, Some(Msg::SetValue(0)));
    }
}