QuartzUIReadiness: declaration reference

#pragma once

#include "CoreMinimal.h"

/** One-navigation gate: readiness emits once after document load and contract handshake. */
class QUARTZUIRUNTIME_API FQuartzUIReadinessGate final
{
public:
	void Reset()
	{
		bDocumentLoaded = false;
		bContractReady = false;
		bReadyEmitted = false;
		bFailed = false;
	}

	bool MarkDocumentLoaded()
	{
		bDocumentLoaded = true;
		return TryEmitReady();
	}

	bool MarkContractReady()
	{
		bContractReady = true;
		return TryEmitReady();
	}

	/** Enters the terminal failure state once for the current navigation. */
	bool MarkFailed()
	{
		if (bReadyEmitted || bFailed)
		{
			return false;
		}
		bFailed = true;
		return true;
	}

	bool IsReady() const { return bReadyEmitted; }
	bool IsFailed() const { return bFailed; }

private:
	bool TryEmitReady()
	{
		if (bReadyEmitted || bFailed || !bDocumentLoaded || !bContractReady)
		{
			return false;
		}
		bReadyEmitted = true;
		return true;
	}

	bool bDocumentLoaded = false;
	bool bContractReady = false;
	bool bReadyEmitted = false;
	bool bFailed = false;
};

/** Public bounds and deterministic timeout semantics for the readiness handshake. */
class QUARTZUIRUNTIME_API FQuartzUIReadinessPolicy final
{
public:
	static constexpr float MinHandshakeTimeoutSeconds = 0.1f;
	static constexpr float MaxHandshakeTimeoutSeconds = 30.0f;
	static constexpr float DefaultHandshakeTimeoutSeconds = 5.0f;

	static bool IsValidHandshakeTimeout(const float TimeoutSeconds)
	{
		return FMath::IsFinite(TimeoutSeconds)
			&& TimeoutSeconds >= MinHandshakeTimeoutSeconds
			&& TimeoutSeconds <= MaxHandshakeTimeoutSeconds;
	}

	static float ClampHandshakeTimeout(const float TimeoutSeconds)
	{
		return FMath::IsFinite(TimeoutSeconds)
			? FMath::Clamp(TimeoutSeconds, MinHandshakeTimeoutSeconds, MaxHandshakeTimeoutSeconds)
			: DefaultHandshakeTimeoutSeconds;
	}

	static bool HasTimedOut(const double ElapsedSeconds, const float TimeoutSeconds)
	{
		return FMath::Max(0.0, ElapsedSeconds) >= static_cast<double>(TimeoutSeconds);
	}
};

/** One active-time countdown; suspension pauses it and expiry emits once. */
class QUARTZUIRUNTIME_API FQuartzUIHandshakeTimer final
{
public:
	void Reset()
	{
		bActive = false;
		ElapsedSeconds = 0.0;
		TimeoutSeconds = FQuartzUIReadinessPolicy::DefaultHandshakeTimeoutSeconds;
	}

	void Start(const float InTimeoutSeconds)
	{
		bActive = true;
		ElapsedSeconds = 0.0;
		TimeoutSeconds = FQuartzUIReadinessPolicy::ClampHandshakeTimeout(InTimeoutSeconds);
	}

	void Stop() { bActive = false; }

	bool Advance(const double DeltaSeconds, const bool bSuspended)
	{
		if (!bActive || bSuspended)
		{
			return false;
		}
		ElapsedSeconds += FMath::Max(0.0, DeltaSeconds);
		if (!FQuartzUIReadinessPolicy::HasTimedOut(ElapsedSeconds, TimeoutSeconds))
		{
			return false;
		}
		bActive = false;
		return true;
	}

	bool IsActive() const { return bActive; }
	double GetElapsedSeconds() const { return ElapsedSeconds; }

private:
	bool bActive = false;
	double ElapsedSeconds = 0.0;
	float TimeoutSeconds = FQuartzUIReadinessPolicy::DefaultHandshakeTimeoutSeconds;
};