// Generic parameter threaded through every level of the hierarchy
public abstract class BaseGameController<TInterface> : ServiceKitBehaviour<TInterface>, IGame
    where TInterface : class, IGame

public class BowlingController : BaseGameController<IBowlingController>, IBowlingController

// Clean inheritance, registration intent is explicit
public abstract class BaseGameController : ServiceKitBehaviour, IGame

[Service(typeof(IBowlingController))]
public class BowlingController : BaseGameController, IBowlingController

// Before: two generics, one was just for ServiceKit
public abstract class ScoreService<TService, TScore> : ServiceKitBehaviour<TService>, IScoreService<TScore>
    where TService : class, IScoreService<TScore>
    where TScore : struct

// After: one generic remains — the one that actually matters
public abstract class ScoreService<TScore> : ServiceKitBehaviour, IScoreService<TScore>
    where TScore : struct

[Service(typeof(IMyScoreService))]
public class MyScoreService : ScoreService<int>, IMyScoreService

await _serviceKitLocator.Inject(this)
    .WithErrorHandling()
    .WithTimeout()
    .ExecuteWithCancellationAsync(destroyCancellationToken);

await _serviceKitLocator.InjectAsync(this, destroyCancellationToken);

// Custom configuration when defaults aren't enough
await _serviceKitLocator.Inject(this)
    .WithTimeout(10f)
    .WithErrorHandling(ex => HandleMyError(ex))
    .ExecuteWithCancellationAsync(destroyCancellationToken);

var status = locator.TryResolveService(typeof(IMyService), out var service);

switch (status)
{
    case ServiceResolutionStatus.Ready:           // service is populated
        break;
    case ServiceResolutionStatus.RegisteredNotReady: // registered, still initializing
        break;
    case ServiceResolutionStatus.NotRegistered:      // does not exist
        break;
}

public interface IPlayerService
{
    void SavePlayer();
    void LoadPlayer();
    int GetPlayerLevel();
}

public class PlayerService : IPlayerService
{
    private int _playerLevel = 1;

    public void SavePlayer() => Debug.Log("Player saved!");
    public void LoadPlayer() => Debug.Log("Player loaded!");
    public int GetPlayerLevel() => _playerLevel;
}

public class GameBootstrap : MonoBehaviour
{
    [SerializeField] private ServiceKitLocator _serviceKit;

    private void Awake()
    {
        // Fluent API - register and ready in one chain
        _serviceKit.Register(new PlayerService())
            .As<IPlayerService>()
            .Ready();

        // Multi-type registration - one instance, multiple interfaces
        _serviceKit.Register(new AudioManager())
            .As<IAudioService>()
            .As<IMusicService>()
            .WithTags("audio", "core")
            .Ready();
    }
}

[Service(typeof(IPlayerController))]
public class PlayerController : ServiceKitBehaviour, IPlayerController
{
    [InjectService] private IPlayerService _playerService;

    protected override void InitializeService()
    {
        // Called after all dependencies are injected and ready
        _playerService.LoadPlayer();
    }
}

public class PlayerUI : MonoBehaviour
{
    [SerializeField] private ServiceKitLocator _serviceKit;

    // Mark fields for injection
    [InjectService] private IPlayerService _playerService;

    private async void Awake()
    {
        // One-liner: default timeout, cancellation, and error handling
        await _serviceKit.InjectAsync(this, destroyCancellationToken);

        // Or configure each option with the builder
        // await _serviceKit.Inject(this)
        //     .WithTimeout(5f)
        //     .WithCancellation(destroyCancellationToken)
        //     .WithErrorHandling()
        //     .ExecuteAsync();

        _playerService.LoadPlayer();
    }
}

// Single interface registration
[Service(typeof(IPlayerController))]
public class PlayerController : ServiceKitBehaviour, IPlayerController
{
    [InjectService] private IPlayerService _playerService;

    protected override void InitializeService()
    {
        // Called after dependencies are injected
        _playerService.LoadPlayer();
        Debug.Log("Player controller ready!");
    }
}

// Multiple interface registration - register one instance under multiple types
[Service(typeof(IAudioService), typeof(IMusicService))]
public class AudioManager : ServiceKitBehaviour, IAudioService, IMusicService
{
    public void PlaySound(string id) { /* ... */ }
    public void PlayMusic(string id) { /* ... */ }
}

// No attribute = registers as concrete type
public class GameSettings : ServiceKitBehaviour
{
    public int Volume { get; set; }
    // Accessible via: serviceKit.GetService<GameSettings>()
}

// Same code, different performance characteristics:
await serviceKit.GetServiceAsync<IPlayerService>();

// With UniTask installed:   → Zero allocations, faster execution
// Without UniTask:          → Standard Task performance

// UniTask.WhenAll is more efficient than Task.WhenAll
var (player, inventory, audio) = await UniTask.WhenAll(
    serviceKit.GetServiceAsync<IPlayerService>(),
    serviceKit.GetServiceAsync<IInventoryService>(),
    serviceKit.GetServiceAsync<IAudioService>()
);

// Single interface registration
[Service(typeof(IPlayerController))]
public class PlayerController : ServiceKitBehaviour, IPlayerController
{
    [InjectService] private IPlayerService _playerService;
    [InjectService] private IInventoryService _inventoryService;

    // This is the new hook for your initialization logic.
    // It's called after dependencies are injected, but before this service is marked as "Ready".
    protected override void InitializeService()
    {
        // Safe to access injected services here
        _playerService.LoadPlayer();
        _inventoryService.LoadInventory();

        Debug.Log("Player controller initialized with all dependencies!");
    }

    // For async setup, you can use the async override:
    // Note: Returns UniTask when available, Task otherwise - same code works for both!
    protected override async UniTask InitializeServiceAsync()
    {
        // Example: load data from a web request or file
        await _inventoryService.LoadFromCloudAsync(destroyCancellationToken);
    }

    // Optional: Handle injection failures gracefully
    protected override void HandleDependencyInjectionFailure(Exception exception)
    {
        Debug.LogError($"Failed to initialize player controller: {exception.Message}");

        if (exception is TimeoutException)
        {
            Debug.Log("Services took too long to become available");
        }
        else if (exception is ServiceInjectionException)
        {
            Debug.Log("Required services are not registered or failed to become ready");
            gameObject.SetActive(false); // Disable this component
        }
    }
}

// Multi-type registration - register under multiple interfaces
[Service(typeof(IAudioService), typeof(IMusicService), typeof(ISoundEffects))]
public class UnifiedAudioManager : ServiceKitBehaviour, IAudioService, IMusicService, ISoundEffects
{
    public void PlaySound(string id) { /* ... */ }
    public void PlayMusic(string id) { /* ... */ }
    public void StopAll() { /* ... */ }
}

// Concrete type registration (no attribute needed)
public class GameSettings : ServiceKitBehaviour
{
    public int Volume { get; set; }
    // Registers as typeof(GameSettings)
}

public class GameBootstrap : MonoBehaviour
{
    [SerializeField] private ServiceKitLocator _serviceKit;

    private void Awake()
    {
        // Simple registration
        _serviceKit.Register(new PlayerService())
            .As<IPlayerService>()
            .Ready();

        // Multi-type registration - one instance accessible via multiple interfaces
        _serviceKit.Register(new UnifiedAudioManager())
            .As<IAudioService>()
            .As<IMusicService>()
            .As<ISoundEffects>()
            .Ready();

        // With tags for organization and filtering
        _serviceKit.Register(new AnalyticsService())
            .As<IAnalyticsService>()
            .WithTags("analytics", "third-party")
            .Ready();

        // Circular dependency exemption
        _serviceKit.Register(new EventBus())
            .As<IEventBus>()
            .WithCircularExemption()
            .Ready();

        // Register without making ready (for deferred initialization)
        _serviceKit.Register(new NetworkService())
            .As<INetworkService>()
            .Register();  // Not ready yet - call ReadyService<INetworkService>() later
    }
}

public class LateInitializer : MonoBehaviour
{
    [SerializeField] private ServiceKitLocator _serviceKit;

    private async void Start()
    {
        try
        {
            // Wait up to 10 seconds for the service to be registered AND ready
            var audioService = await _serviceKit.GetServiceAsync<IAudioService>(
                new CancellationTokenSource(TimeSpan.FromSeconds(10)).Token);

            audioService.PlaySound("welcome");
        }
        catch (OperationCanceledException)
        {
            Debug.LogError("Audio service was not available or ready within the timeout period");
        }
    }
}

public class AnalyticsReporter : MonoBehaviour
{
    [InjectService(Required = false)]
    private IAnalyticsService _analyticsService; // Uses intelligent resolution

    [InjectService]
    private IPlayerService _playerService; // Required - will fail if missing

    // ...
}

// Example of a service that needs to be exempted from circular dependency checks
[Service(typeof(ISubordinateService), CircularDependencyExempt = true)]
public class SubordinateService : ServiceKitBehaviour, ISubordinateService
{
    [InjectService] private IManagerService _manager;

    // The service will be registered without being considered in the dependency graph analysis
    // This allows it to participate in circular dependencies safely
}

// Example: Loading an addressable ServiceKitLocator
var handle = Addressables.LoadAssetAsync<ServiceKitLocator>("MyServiceKitLocator");
await handle.Task;
var serviceKitLocator = handle.Result;

// Example: Bootstrapping with addressable ServiceKitLocator
public class AddressableBootstrap : MonoBehaviour
{
    private async void Start()
    {
        // Load the addressable ServiceKitLocator
        var locatorHandle = Addressables.LoadAssetAsync<ServiceKitLocator>("GlobalServiceKitLocator");
        await locatorHandle.Task;
        var serviceKitLocator = locatorHandle.Result;

        // Register global services
        var audioService = new AudioService();
        serviceKitLocator.RegisterService<IAudioService>(audioService);
        serviceKitLocator.ReadyService<IAudioService>();

        // Now load addressable scenes - they will reference the same ServiceKitLocator instance
        // and have access to the IAudioService
        await Addressables.LoadSceneAsync("GameplayScene").Task;
    }
}

[Service(typeof(IPersistentService))]
public class PersistentService : ServiceKitBehaviour, IPersistentService
{
    protected override void InitializeService()
    {
        // Prevent this service from being destroyed when the scene unloads
        DontDestroyOnLoad(gameObject);
    }
}

// Load scenes additively to keep previous scene services active
await Addressables.LoadSceneAsync("AdditiveScene", LoadSceneMode.Additive).Task;

// Fluent Registration (recommended)
IServiceRegistrationBuilder Register<T>(T service) where T : class;
IServiceRegistrationBuilder Register(object service);

// Direct Registration
void RegisterService<T>(T service) where T : class;
void RegisterService(Type serviceType, object service);
void RegisterAndReadyService<T>(T service) where T : class;
void ReadyService<T>() where T : class;
void UnregisterService<T>() where T : class;

// Synchronous Access
T GetService<T>() where T : class;
bool TryGetService<T>(out T service) where T : class;

// Atomic 3-State Resolution
ServiceResolutionStatus TryResolveService(Type serviceType, out object service);
// Returns Ready, RegisteredNotReady, or NotRegistered — single lock, no race conditions

// Asynchronous Access (automatically uses UniTask when available)
Task<T> GetServiceAsync<T>(CancellationToken cancellationToken = default) where T : class;
// Returns UniTask<T> when UniTask package is installed

// Dependency Injection
IServiceInjectionBuilder Inject(object target);

// Tag Queries
IReadOnlyList<ServiceInfo> GetServicesWithTag(string tag);
IReadOnlyList<ServiceInfo> GetServicesWithAnyTag(params string[] tags);
IReadOnlyList<ServiceInfo> GetServicesWithAllTags(params string[] tags);

// Management
IReadOnlyList<ServiceInfo> GetAllServices();

IServiceRegistrationBuilder As<T>() where T : class;       // Register as interface type
IServiceRegistrationBuilder As(Type serviceType);           // Register as runtime type
IServiceRegistrationBuilder WithTags(params string[] tags); // Add tags
IServiceRegistrationBuilder WithTags(params ServiceTag[] tags);
IServiceRegistrationBuilder WithCircularExemption();        // Exempt from circular dependency check
void Register();  // Complete registration (not ready yet)
void Ready();     // Complete registration and mark as ready

IServiceInjectionBuilder WithCancellation(CancellationToken cancellationToken);
IServiceInjectionBuilder WithTimeout(float timeoutSeconds);
IServiceInjectionBuilder WithErrorHandling(Action<Exception> errorHandler);
void Execute(); // Fire-and-forget
Task ExecuteAsync(); // Awaitable (UniTask when available)

// Fastest: TryGetService for hot-path access
if (serviceKit.TryGetService<IPlayerService>(out var service))
{
    service.Update();
}

// Prefer sync GetService when you know the service is ready
var player = serviceKit.GetService<IPlayerService>();

// Use async only when the service may not be ready yet
var player = await serviceKit.GetServiceAsync<IPlayerService>();

// Install UniTask for zero-allocation async and better Unity thread integration

public class AudioManager : ServiceKitBehaviour<IAudioService>, IAudioService
{
    [InjectService] private IConfigService _config;
    public void PlaySound(string id) { /* ... */ }
}

[Service(typeof(IAudioService))]
public class AudioManager : ServiceKitBehaviour, IAudioService
{
    [InjectService] private IConfigService _config;
    public void PlaySound(string id) { /* ... */ }
}

// Before: two generics — TService was just for ServiceKit
public abstract class ScoreService<TService, TScore> : ServiceKitBehaviour<TService>
    where TService : class
    where TScore : struct

// After: keep the functional generic, drop the ServiceKit one
public abstract class ScoreService<TScore> : ServiceKitBehaviour
    where TScore : struct

// Concrete class adds [Service]
[Service(typeof(IMyScoreService))]
public class MyScoreService : ScoreService<int>, IMyScoreService { }

await _serviceKitLocator.InjectServicesAsync(this)
    .WithErrorHandling()
    .WithTimeout()
    .ExecuteWithCancellationAsync(destroyCancellationToken);

await _serviceKitLocator.InjectAsync(this, destroyCancellationToken);

await _serviceKitLocator.Inject(this)
    .WithTimeout(10f)
    .WithErrorHandling(ex => HandleMyError(ex))
    .ExecuteWithCancellationAsync(destroyCancellationToken);

_serviceKit.RegisterService<IAudioService>(audioService);
_serviceKit.ReadyService<IAudioService>();

_serviceKit.Register(audioService).As<IAudioService>().Ready();

[TestFixture]
public class MyServiceTests
{
    private IServiceKitLocator _mockLocator;
    private IServiceInjectionBuilder _mockBuilder;

    [SetUp]
    public void Setup()
    {
        _mockLocator = Substitute.For<IServiceKitLocator>();
        _mockBuilder = Substitute.For<IServiceInjectionBuilder>();

        // Setup fluent API chain
        _mockBuilder.WithCancellation(Arg.Any<CancellationToken>()).Returns(_mockBuilder);
        _mockBuilder.WithTimeout(Arg.Any<float>()).Returns(_mockBuilder);
        _mockBuilder.WithTimeout().Returns(_mockBuilder);
        _mockBuilder.WithErrorHandling(Arg.Any<Action<Exception>>()).Returns(_mockBuilder);
        _mockBuilder.ExecuteAsync().Returns(Task.CompletedTask);
        _mockLocator.Inject(Arg.Any<object>()).Returns(_mockBuilder);
    }

    [Test]
    public async Task MyBehaviour_RegistersService_OnAwake()
    {
        // Arrange
        var go = new GameObject();
        var behaviour = go.AddComponent<MyServiceKitBehaviour>();
        behaviour.UseLocator(_mockLocator);

        // Act
        await behaviour.TestAwake(CancellationToken.None);

        // Assert - ServiceKitBehaviour uses non-generic RegisterService
        _mockLocator.Received(1).RegisterService(typeof(IMyService), Arg.Any<object>(), Arg.Any<string>());
    }
}

[TestFixture]
public class MyServiceIntegrationTests
{
    private ServiceKitLocator _locator;

    [SetUp]
    public void Setup()
    {
        _locator = ScriptableObject.CreateInstance<ServiceKitLocator>();
    }

    [TearDown]
    public void TearDown()
    {
        _locator?.ClearServices();
        if (_locator != null) Object.DestroyImmediate(_locator);
    }

    [Test]
    public void MyBehaviour_RegistersAutomatically_WhenUseLocatorCalled()
    {
        // Arrange - AddComponent triggers Awake, but registration is skipped (no locator yet)
        var go = new GameObject();
        var behaviour = go.AddComponent<MyServiceKitBehaviour>();

        // Act - UseLocator triggers registration automatically
        behaviour.UseLocator(_locator);

        // Assert - Service is now registered
        Assert.IsTrue(_locator.IsServiceRegistered<IMyService>());
    }

    [Test]
    public async Task MyBehaviour_InjectsDependencies_WhenServicesReady()
    {
        // Arrange
        var playerService = new PlayerService();
        _locator.RegisterAndReadyService<IPlayerService>(playerService);

        var go = new GameObject();
        var behaviour = go.AddComponent<MyServiceKitBehaviour>();
        behaviour.UseLocator(_locator);

        // Act - Complete injection manually
        await _locator.Inject(behaviour)
            .WithCancellation(CancellationToken.None)
            .WithTimeout()
            .ExecuteAsync();

        _locator.ReadyService<IMyService>();

        // Assert
        Assert.IsNotNull(behaviour.PlayerService);
        Assert.AreSame(playerService, behaviour.PlayerService);
    }
}

[Service(typeof(IMyService))]
public class MyServiceKitBehaviour : ServiceKitBehaviour, IMyService
{
    [InjectService] private IPlayerService _playerService;

    public IPlayerService PlayerService => _playerService;

    public async Task TestAwake(CancellationToken cancellationToken)
    {
        RegisterServiceWithLocator();

        await Locator.Inject(this)
            .WithCancellation(cancellationToken)
            .WithTimeout()
            .WithErrorHandling(HandleDependencyInjectionFailure)
            .ExecuteAsync();

        await InitializeServiceAsync();
        InitializeService();

        MarkServiceAsReady();
    }
}