QuartzUIBindingScope: declaration reference

#pragma once

#include "CoreMinimal.h"
#include "StructUtils/InstancedStruct.h"
#include "UObject/Object.h"
#include "QuartzUIView.h"

#include "QuartzUIBindingScope.generated.h"

class ULocalPlayer;
class UQuartzUIBindingScope;
class UQuartzUISubsystem;
class UQuartzUITypedEndpoint;

/** Lifecycle of one explicitly registered, exact-player gameplay provider. */
UENUM(BlueprintType)
enum class EQuartzUIBindingScopeState : uint8
{
	Detached,
	Attaching,
	WaitingForView,
	Active,
	Detaching
};

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(
	FQuartzUIBindingTokenCancelled,
	FName, Reason);

/**
 * Generation token for asynchronous work started by one binding scope.
 * Tokens become stale before endpoint or gameplay-source teardown begins.
 */
UCLASS(BlueprintType)
class QUARTZUIRUNTIME_API UQuartzUIBindingToken final : public UObject
{
	GENERATED_BODY()

public:
	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scope")
	bool IsCurrent() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scope")
	bool IsCancelled() const { return bCancelled; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scope")
	int64 GetGeneration() const { return Generation; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scope")
	FName GetCancellationReason() const { return CancellationReason; }

	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Binding Scope")
	FQuartzUIBindingTokenCancelled OnCancelled;

private:
	void Initialize(UQuartzUIBindingScope* InScope, int64 InGeneration);
	void Cancel(FName Reason);

	UPROPERTY(Transient)
	TWeakObjectPtr<UQuartzUIBindingScope> Scope;

	UPROPERTY(Transient)
	int64 Generation = 0;

	UPROPERTY(Transient)
	FName CancellationReason;

	UPROPERTY(Transient)
	bool bCancelled = false;

	friend class UQuartzUIBindingScope;
};

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(
	FQuartzUIBindingScopeStateChanged,
	EQuartzUIBindingScopeState, PreviousState,
	EQuartzUIBindingScopeState, NewState);
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(
	FQuartzUIBindingScopeFailed,
	FName, ErrorCode);

/**
 * Atomic lifetime boundary for one project or optional-module gameplay provider.
 *
 * A scope is registered to one exact-player view, binds an explicit endpoint set,
 * owns its gameplay subscriptions, publishes a fresh initial snapshot whenever
 * the retained document becomes ready, and invalidates all asynchronous work by
 * generation before teardown. It never navigates or destroys the retained view.
 */
UCLASS(BlueprintType, Blueprintable, EditInlineNew)
class QUARTZUIRUNTIME_API UQuartzUIBindingScope : public UObject
{
	GENERATED_BODY()

public:
	static constexpr int32 MaxScopesPerView = 32;
	static constexpr int32 MaxEndpoints = 32;
	static constexpr int32 MaxCancellationTokens = 64;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scope")
	FName GetProviderId() const { return ProviderId; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scope")
	EQuartzUIBindingScopeState GetState() const { return State; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scope")
	bool IsActive() const { return State == EQuartzUIBindingScopeState::Active; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scope")
	int64 GetGeneration() const { return Generation; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scope")
	FName GetLastFailure() const { return LastFailure; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scope")
	ULocalPlayer* GetOwningLocalPlayer() const { return OwningLocalPlayer; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scope")
	UQuartzUIView* GetBoundView() const { return BoundView; }

	/** Resolves only the canonical shell owned by this exact local player. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Binding Scope")
	bool AttachToShell(ULocalPlayer* LocalPlayer);

	/** Attaches to the view's exact owner; cross-player ownership is impossible. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Binding Scope")
	bool AttachToView(UQuartzUIView* View);

	/** Idempotent feature/project teardown. Returns true when a live binding was released. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Binding Scope")
	bool Detach();

	/** Adds one explicit endpoint while detached; no runtime class or object scan occurs. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Binding Scope")
	bool AddEndpoint(UQuartzUITypedEndpoint* Endpoint);

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Binding Scope")
	bool RemoveEndpoint(UQuartzUITypedEndpoint* Endpoint);

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scope")
	TArray<UQuartzUITypedEndpoint*> GetEndpoints() const;

	/** Creates bounded work whose validity is tied to the current scope generation. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Binding Scope")
	UQuartzUIBindingToken* CreateCancellationToken();

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scope")
	bool IsGenerationCurrent(int64 CandidateGeneration) const;

	/** Strict USTRUCT publication for the current exact player. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Binding Scope")
	bool PublishState(FName StateName, const FInstancedStruct& Payload);

	/** Native all-or-nothing publication used when a provider context is replaced. */
	bool PublishStatesAtomically(const TMap<FName, FInstancedStruct>& Payloads);

	/** Transient events are accepted only after the initial snapshot barrier. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Binding Scope")
	bool EmitEvent(FName EventName, const FInstancedStruct& Payload);

	template <typename StructType>
	bool PublishState(const FName StateName, const StructType& Payload)
	{
		FInstancedStruct Value;
		Value.InitializeAs<StructType>() = Payload;
		return PublishState(StateName, Value);
	}

	template <typename StructType>
	bool EmitEvent(const FName EventName, const StructType& Payload)
	{
		FInstancedStruct Value;
		Value.InitializeAs<StructType>() = Payload;
		return EmitEvent(EventName, Value);
	}

	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Binding Scope")
	FQuartzUIBindingScopeStateChanged OnStateChanged;

	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Binding Scope")
	FQuartzUIBindingScopeFailed OnFailed;

protected:
	/** Stable provider/domain identifier; independent of any visual widget. */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "QuartzUI|Binding Scope")
	FName ProviderId;

	/** Explicit endpoint instances owned by this provider. */
	UPROPERTY(EditDefaultsOnly, Instanced, BlueprintReadOnly, Category = "QuartzUI|Binding Scope")
	TArray<TObjectPtr<UQuartzUITypedEndpoint>> Endpoints;

	/** Resolve native sources and install subscriptions. Cleanup runs even after partial failure. */
	UFUNCTION(BlueprintNativeEvent, Category = "QuartzUI|Binding Scope")
	bool BeginBinding(ULocalPlayer* LocalPlayer, UQuartzUIView* View);
	virtual bool BeginBinding_Implementation(ULocalPlayer* LocalPlayer, UQuartzUIView* View);

	/** Publish the complete current DTO baseline before the scope becomes active. */
	UFUNCTION(BlueprintNativeEvent, Category = "QuartzUI|Binding Scope")
	bool PublishInitialState();
	virtual bool PublishInitialState_Implementation();

	/** Remove every gameplay delegate/message subscription owned by this scope. */
	UFUNCTION(BlueprintNativeEvent, Category = "QuartzUI|Binding Scope")
	void EndBinding();
	virtual void EndBinding_Implementation();

	/** Optional core-plugin providers may implement their reserved contract surface. */
	virtual bool CanUseReservedContractMessages() const { return false; }

	/** Native template-method seams keep specialized providers from bypassing scope invariants. */
	virtual bool StartBindingSources(ULocalPlayer* LocalPlayer, UQuartzUIView* View);
	virtual bool BuildInitialState();
	virtual void StopBindingSources();

private:
	bool TrySerializeState(
		FName StateName,
		const FInstancedStruct& Payload,
		FString& OutPayloadJson) const;
	bool ValidateEndpointSet(FName& OutError) const;
	bool TryPublishInitialState();
	bool FailAndRollback(FName ErrorCode);
	void TeardownBinding(FName CancellationReason, bool bBroadcastFailure);
	void CancelTokens(FName Reason);
	void AdvanceGeneration();
	void TransitionTo(EQuartzUIBindingScopeState NewState);
	void SetFailure(FName ErrorCode, bool bBroadcast);

	UFUNCTION()
	void HandleViewStateChanged(EQuartzUIViewState PreviousState, EQuartzUIViewState NewState);

	UPROPERTY(Transient)
	EQuartzUIBindingScopeState State = EQuartzUIBindingScopeState::Detached;

	UPROPERTY(Transient)
	int64 Generation = 0;

	UPROPERTY(Transient)
	FName LastFailure;

	UPROPERTY(Transient)
	TObjectPtr<ULocalPlayer> OwningLocalPlayer;

	UPROPERTY(Transient)
	TObjectPtr<UQuartzUIView> BoundView;

	UPROPERTY(Transient)
	TArray<TObjectPtr<UQuartzUITypedEndpoint>> BoundEndpoints;

	UPROPERTY(Transient)
	TArray<TObjectPtr<UQuartzUIBindingToken>> CancellationTokens;

	UPROPERTY(Transient)
	bool bBindingSourcesStarted = false;

	UPROPERTY(Transient)
	bool bPublishingInitialState = false;

	/** Serialized DTOs staged until the complete initial baseline succeeds. */
	TMap<FName, FString> PendingInitialStates;

	friend class UQuartzUIView;
};