QuartzUIProvider: declaration reference

#pragma once

#include "CoreMinimal.h"
#include "Tickable.h"
#include "QuartzUIBindingScope.h"
#include "QuartzUIProviderSchema.h"

#include "QuartzUIProvider.generated.h"

class UQuartzUIProvider;
struct FQuartzUIEndpointResult;

/** Native transient target that intercepts one reflected provider delegate invocation. */
UCLASS(Transient)
class QUARTZUIRUNTIME_API UQuartzUIProviderEventRelay final : public UObject
{
	GENERATED_BODY()

public:
	UFUNCTION()
	void ForwardEvent();

	virtual void ProcessEvent(UFunction* Function, void* Parameters) override;

private:
	UPROPERTY(Transient)
	TWeakObjectPtr<UQuartzUIProvider> Provider;

	int32 EventIndex = INDEX_NONE;
	FName FunctionName;

	friend class UQuartzUIProvider;
};

/**
 * Explicitly registered project-facing data facade reflected into the web contract.
 *
 * Subclass properties are copied into immutable browser snapshots, dynamic delegate
 * properties become events, and public Blueprint-callable functions become validated
 * browser methods. The base scope still owns exact-player lifetime and cancellation.
 */
UCLASS(Abstract, BlueprintType, Blueprintable, EditInlineNew,
	HideFunctions = (BeginBinding, PublishInitialState, EndBinding))
class QUARTZUIRUNTIME_API UQuartzUIProvider : public UQuartzUIBindingScope, public FTickableGameObject
{
	GENERATED_BODY()

public:
	/** Requests an immediate immutable snapshot comparison on the next game-thread tick. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Provider")
	void MarkProviderDirty();

	/** Copies and publishes the current reflected state now when this provider is active. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Provider")
	bool RefreshProvider();

	/** Monotonic for this provider ID across feature replacement in one retained view. */
	UFUNCTION(BlueprintPure, Category = "QuartzUI|Provider")
	int64 GetProviderLifecycleGeneration() const { return ProviderLifecycleGeneration; }

	virtual void Tick(float DeltaTime) override;
	virtual bool IsTickable() const override;
	virtual TStatId GetStatId() const override;
	virtual UWorld* GetTickableGameObjectWorld() const override;

protected:
	/** Automatic comparison period. Zero disables polling; MarkProviderDirty still works. */
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "QuartzUI|Provider", meta = (ClampMin = "0.0", ClampMax = "10.0"))
	float AutoUpdateIntervalSeconds = 1.0f / 30.0f;

	/** Resolve project gameplay sources here. The provider runtime is already initialized. */
	UFUNCTION(BlueprintNativeEvent, Category = "QuartzUI|Provider")
	bool ProviderBound(ULocalPlayer* LocalPlayer, UQuartzUIView* View);
	virtual bool ProviderBound_Implementation(ULocalPlayer* LocalPlayer, UQuartzUIView* View);

	/** Release every project-owned delegate/message handle here. */
	UFUNCTION(BlueprintNativeEvent, Category = "QuartzUI|Provider")
	void ProviderUnbound();
	virtual void ProviderUnbound_Implementation();

	/** Optional periodic project-side state calculation before automatic comparison. */
	UFUNCTION(BlueprintNativeEvent, Category = "QuartzUI|Provider")
	void UpdateProvider(float DeltaSeconds);
	virtual void UpdateProvider_Implementation(float DeltaSeconds);

private:
	virtual bool StartBindingSources(ULocalPlayer* LocalPlayer, UQuartzUIView* View) override final;
	virtual bool BuildInitialState() override final;
	virtual void StopBindingSources() override final;

	bool BuildDescriptor();
	bool BindProviderEvents();
	void UnbindProviderEvents();
	bool BindPresentationEndpoints();
	void UnbindPresentationEndpoints();
	bool PublishAvailability(bool bAvailable);
	bool CanUpdateBoundView() const;
	bool TrySerializeState(FString& OutPayloadJson) const;
	void ForwardEvent(int32 EventIndex, const void* Parameters);
	FQuartzUIEndpointResult HandleMethod(const FString& PayloadJson, int32 MethodIndex);

	FQuartzUIProviderDescriptor Descriptor;
	FString LastStatePayloadJson;
	TArray<const FProperty*> BoundEventProperties;
	TArray<FScriptDelegate> BoundEventDelegates;

	UPROPERTY(Transient)
	TArray<TObjectPtr<UQuartzUIProviderEventRelay>> EventRelays;

	TArray<FString> BoundMethodWires;
	float UpdateAccumulator = 0.0f;
	int64 ProviderLifecycleGeneration = 0;
	bool bProviderSourcesBound = false;
	bool bProviderDirty = true;

	friend class UQuartzUIProviderEventRelay;
	friend class UQuartzUIView;
};