refactor(Common): Enhance effect system with Arc support and add TreeView DTO

This commit refines Land's core effect execution system and adds a missing DTO for TreeView configuration:

1. **Effect System Enhancements:**
   - Renamed `TCapability` to `TCapabilityProvider` in `ApplicationRunTime` and `ExecuteEffect` to clarify its role
   - Added `From<CommonError>` bound to effect errors for standardized error handling
   - Implemented blanket `ApplicationRunTime` for `Arc<TRunTime>` enabling shared runtime references
   - Added `HasEnvironment` implementation for `Arc<T>` simplifying environment access
   - Updated `Requires` trait documentation to reflect capability semantics

2. **TreeView DTO Addition:**
   - Added `TreeViewOptionsDTO` with serializable flags (`CanSelectMany`, `HasHandleDrag`, `HasHandleDrop`)
   - Organized DTO module structure by moving options to dedicated file

These changes directly support Land's declarative effect architecture:
- The runtime improvements enable `Mountain` to handle shared state more efficiently using Arc
- Standardized error conversion ensures consistent error handling across all effect executions
- The new DTO enables `Cocoon` to properly configure TreeViews through the `vine.proto` IPC layer
- File organization aligns with Land's strict DTO management strategy

BREAKING CHANGE: Effect methods now require `TError: From<CommonError>` and use raw trait objects in `Requires` bounds instead of Arc-wrapped types. Implementations must adjust capability dependencies accordingly.

Author: NikolaRHristov

Cargo.toml

@@ -6,7 +6,7 @@ toml = { workspace = true }
 async-trait = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
-thiserror.workspace = true
+thiserror = { workspace = true }
 url = { workspace = true }
 
 [features]

Source/Effect/ApplicationRunTime.rs

@@ -1,38 +1,49 @@
 //! # ApplicationRunTime Trait
 //!
-//! Defines the `ApplicationRunTime` trait, which specifies the contract for any
-//! "engine" responsible for executing `ActionEffect`s.
+//! Defines the core `ApplicationRunTimeTrait`, which is the contract for any
+//! "engine" capable of executing `ActionEffect`s.
 
 use std::sync::Arc;
 
 use async_trait::async_trait;
 
 use super::ActionEffect::ActionEffect;
-use crate::Environment::{HasEnvironment::HasEnvironment, Requires::Requires};
+use crate::{
+	Environment::{HasEnvironment::HasEnvironment, Requires::Requires},
+	Error::CommonError::CommonError,
+};
 
-/// A trait that defines the core contract for an application's runtime engine.
-///
-/// An `ApplicationRunTime` is the component that bridges the declarative world
-/// of `ActionEffect`s with the concrete world of execution. It is responsible
-/// for taking an effect, providing it with the necessary capabilities from its
-/// `Environment`, and running the resulting asynchronous operation to
-/// completion.
+/// The core trait for any runtime capable of executing `ActionEffect`s.
 #[async_trait]
 pub trait ApplicationRunTime: HasEnvironment + Send + Sync + 'static {
-	/// Executes an `ActionEffect` that requires a specific capability from the
-	/// environment.
+	/// Executes an effect using the environment provided by the runtime.
 	///
-	/// This method is the heart of the effect execution system. It dynamically
-	/// resolves the required capability (e.g., a trait object like
-	/// `Arc<dyn FileSystemReader>`) from its managed environment and provides
-	/// it to the effect's encapsulated function, which is then awaited.
-	async fn Run<TCapability, TError, TOutput>(
+	/// The runtime is responsible for acquiring the necessary capability from
+	/// its environment and passing it to the effect's execution logic.
+	async fn Run<TCapabilityProvider, TError, TOutput>(
 		&self,
-		Effect:ActionEffect<Arc<TCapability>, TError, TOutput>,
+		Effect:ActionEffect<Arc<TCapabilityProvider>, TError, TOutput>,
 	) -> Result<TOutput, TError>
 	where
-		TCapability: ?Sized + Send + Sync,
-		Self::EnvironmentType: Requires<Arc<TCapability>>,
-		TError: Send + Sync + 'static,
+		TCapabilityProvider: ?Sized + Send + Sync + 'static,
+		Self::EnvironmentType: Requires<TCapabilityProvider>,
+		TError: From<CommonError> + Send + Sync + 'static,
 		TOutput: Send + Sync + 'static;
 }
+
+/// A blanket implementation that allows a shared `Arc` of a runtime to also be
+/// used as a runtime.
+#[async_trait]
+impl<TRunTime:ApplicationRunTime> ApplicationRunTime for Arc<TRunTime> {
+	async fn Run<TCapabilityProvider, TError, TOutput>(
+		&self,
+		Effect:ActionEffect<Arc<TCapabilityProvider>, TError, TOutput>,
+	) -> Result<TOutput, TError>
+	where
+		TCapabilityProvider: ?Sized + Send + Sync + 'static,
+		Self::EnvironmentType: Requires<TCapabilityProvider>,
+		TError: From<CommonError> + Send + Sync + 'static,
+		TOutput: Send + Sync + 'static, {
+		(**self).Run(Effect).await
+	}
+}

Source/Effect/ExecuteEffect.rs

@@ -6,7 +6,7 @@
 use std::sync::Arc;
 
 use super::{ActionEffect::ActionEffect, ApplicationRunTime::ApplicationRunTime};
-use crate::Environment::Requires::Requires;
+use crate::{Environment::Requires::Requires, Error::CommonError::CommonError};
 
 /// A generic effect execution helper that takes a runtime and an effect, and
 /// executes the effect using that runtime.
@@ -24,15 +24,15 @@ use crate::Environment::Requires::Requires;
 ///     ExecuteEffect(RunTime, ReadEffect).await
 /// }
 /// ```
-pub async fn ExecuteEffect<TRunTime, TCapability, TError, TOutput>(
+pub async fn ExecuteEffect<TRunTime, TCapabilityProvider, TError, TOutput>(
 	RunTime:Arc<TRunTime>,
-	Effect:ActionEffect<Arc<TCapability>, TError, TOutput>,
+	Effect:ActionEffect<Arc<TCapabilityProvider>, TError, TOutput>,
 ) -> Result<TOutput, TError>
 where
 	TRunTime: ApplicationRunTime,
-	TCapability: ?Sized + Send + Sync,
-	TRunTime::EnvironmentType: Requires<Arc<TCapability>>,
-	TError: Send + Sync + 'static,
+	TCapabilityProvider: ?Sized + Send + Sync + 'static,
+	TRunTime::EnvironmentType: Requires<TCapabilityProvider>,
+	TError: From<CommonError> + Send + Sync + 'static,
 	TOutput: Send + Sync + 'static, {
 	// The RunTime::Run method expects an effect whose closure takes the capability.
 	// This now matches perfectly.

Source/Environment/HasEnvironment.rs

@@ -20,3 +20,13 @@ pub trait HasEnvironment {
 	/// Gets a shared, reference-counted pointer to the environment.
 	fn GetEnvironment(&self) -> Arc<Self::EnvironmentType>;
 }
+
+/// A blanket implementation for `Arc<T>`. This allows code to treat
+/// an `Arc<TRunTime>` as if it were `TRunTime` for the purpose of getting the
+/// environment. This is required by the blanket `impl ApplicationRunTime for
+/// Arc<TRunTime>` which has a `where Self: HasEnvironment` bound.
+impl<T:HasEnvironment> HasEnvironment for Arc<T> {
+	type EnvironmentType = T::EnvironmentType;
+
+	fn GetEnvironment(&self) -> Arc<Self::EnvironmentType> { (**self).GetEnvironment() }
+}

Source/Environment/Requires.rs

@@ -17,7 +17,7 @@ use super::Environment::Environment;
 /// to perform its operation.
 ///
 /// The `Capability` is typically a trait object, such as
-/// `Arc<dyn FileSystemReader>`.
+/// `dyn FileSystemReader`.
 pub trait Requires<Capability:?Sized>: Environment {
 	/// Returns the required capability from the environment, wrapped in an
 	/// `Arc` for safe, shared ownership.

Source/TreeView/DTO/TreeViewOptionsDTO.rs

@@ -0,0 +1,20 @@
+//! # TreeViewOptionsDTO
+//!
+//! Defines the Data Transfer Object for a tree view's configuration options.
+
+#![allow(non_snake_case, non_camel_case_types)]
+
+use serde::{Deserialize, Serialize};
+
+/// A struct that holds the configuration options for a tree view instance
+/// registered by an extension.
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(rename_all = "PascalCase")]
+pub struct TreeViewOptionsDTO {
+	#[serde(default)]
+	pub CanSelectMany:bool,
+	#[serde(default)]
+	pub HasHandleDrag:bool,
+	#[serde(default)]
+	pub HasHandleDrop:bool,
+}

Source/TreeView/DTO/mod.rs

@@ -6,8 +6,7 @@
 #![allow(non_snake_case, non_camel_case_types)]
 
 pub mod TreeItemDTO;
+pub mod TreeViewOptionsDTO;
+
 // mod RevealOptionsDTO; // Placeholder for future DTOs
 // mod TreeViewBadgeDTO;
-// mod TreeViewOptionsDTO;
-
-// pub use self::TreeItemDTO::TreeItemDTO;