QuartzUIView: declaration reference

#pragma once

#include "CoreMinimal.h"
#include "UObject/Object.h"
#include "QuartzUIActions.h"
#include "QuartzUIApp.h"
#include "QuartzUICoreContract.h"
#include "QuartzUIProjectContract.h"

#include "QuartzUIView.generated.h"

class ULocalPlayer;
class UQuartzUIBindingScope;
class UQuartzUIBridge;
class UQuartzUIProvider;
class UQuartzUIProviderSet;
class UQuartzUISubsystem;
class UQuartzUITypedEndpoint;
class UQuartzUIWidget;
class UQuartzUITextureResources;
class UQuartzUIWorldSurfaceComponent;
class FQuartzUI;
struct FQuartzUIDirectWorldSurfaceTestAccess;
struct FQuartzUIEndpointResult;

/** Explicit lifecycle for one logical QuartzUI application view. */
UENUM(BlueprintType)
enum class EQuartzUIViewState : uint8
{
	Created,
	Loading,
	Ready,
	Suspended,
	Failed,
	Closing,
	Closed
};

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(
	FQuartzUIViewStateChanged,
	EQuartzUIViewState, PreviousState,
	EQuartzUIViewState, NewState);
DECLARE_DYNAMIC_MULTICAST_DELEGATE(FQuartzUIViewBoundActionsChanged);

/**
 * Client-only logical browser session owned by UQuartzUISubsystem.
 * Browser/widget attachment is a later slice; this object establishes stable
 * identity, exact local-player ownership, and deterministic lifecycle first.
 */
UCLASS(BlueprintType)
class QUARTZUIRUNTIME_API UQuartzUIView final : public UObject
{
	GENERATED_BODY()

public:
	UFUNCTION(BlueprintPure, Category = "QuartzUI|View")
	FGuid GetViewId() const { return ViewId; }

	/** Lazily creates this view's bounded, static Unreal texture snapshot cache. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Textures")
	UQuartzUITextureResources* GetTextureResources();

	UFUNCTION(BlueprintPure, Category = "QuartzUI|View")
	FName GetAppId() const { return AppDefinition.AppId; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|View")
	FQuartzUIAppDefinition GetAppDefinition() const { return AppDefinition; }

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

	/** In-memory CEF request-context identity shared only by this local player's views. */
	const FString& GetBrowserContextId() const { return BrowserContextId; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|View")
	EQuartzUIViewState GetState() const { return State; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|View")
	FString GetFailureReason() const { return FailureReason; }

	/** Exact app-scoped generated identity accepted by this view's bridge. */
	UFUNCTION(BlueprintPure, Category = "QuartzUI|Contract")
	FString GetContractHash() const { return ResolvedContract.ContractHash; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Contract")
	bool HasProjectContracts() const { return ResolvedContract.bHasProjectContracts; }

	bool IsContractMessageExact(
		EQuartzUIContractMessageKind Kind,
		FName Name,
		const UScriptStruct* PayloadType,
		const UScriptStruct* ResultType = nullptr) const;

	/** Retains and binds one explicit Action/Request endpoint to this logical view. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Project Endpoints")
	bool BindTypedEndpoint(UQuartzUITypedEndpoint* Endpoint);

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Project Endpoints")
	bool UnbindTypedEndpoint(FName EndpointName);

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Project Endpoints")
	UQuartzUITypedEndpoint* GetTypedEndpoint(FName EndpointName) const;

	void ClearTypedEndpoints();

	/** Returns one explicitly registered gameplay provider for this exact view. */
	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scopes")
	UQuartzUIBindingScope* GetBindingScope(FName ProviderId) const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Binding Scopes")
	int32 GetBindingScopeCount() const { return BindingScopes.Num(); }

	/** Exact-class registration check shared by generation and provider runtime attachment. */
	bool IsProviderClassRegistered(const UClass* ProviderClass) const;

	/** Copy of the exact provider-class allowlist compiled into this app contract. */
	UFUNCTION(BlueprintPure, Category = "QuartzUI|Providers")
	TArray<TSubclassOf<UQuartzUIProvider>> GetRegisteredProviderClasses() const;

	/** Detaches provider scopes before releasing any remaining standalone endpoints. */
	void ClearBindingScopes();

	UFUNCTION(BlueprintPure, Category = "QuartzUI|View")
	bool IsTerminal() const { return State == EQuartzUIViewState::Closed; }

	bool IsPresentationAttached() const { return PresentationObject.IsValid(); }

	UQuartzUIWidget* GetPresentationWidget() const;

	/** C++ presentation-neutral bridge used by providers and typed endpoints. */
	UQuartzUIBridge* GetPresentationBridge() const;

	/** C++ lifecycle hook used by the owning subsystem. */
	UObject* GetPresentationObject() const { return PresentationObject.Get(); }

	/** Sends coalesced object state through the attached presentation bridge. */
	bool PublishStateSnapshot(const FString& StateName, const FString& PayloadJson = TEXT("{}"));

	/** Native atomic publication for a complete named-state baseline. */
	bool PublishStateSnapshots(const TMap<FString, FString>& Snapshots);

	/** Sends a transient object event through the attached presentation bridge. */
	bool EmitEvent(const FString& EventName, const FString& PayloadJson = TEXT("{}"));

	/** Attempts to drain this view's ready outbound bridge immediately on the game thread. */
	bool FlushOutboundMessagesNow();

	/** Replaces this view's bounded contextual action catalog atomically. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Actions")
	bool SetBoundActions(const TArray<FQuartzUIBoundAction>& Actions);

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Actions")
	TArray<FQuartzUIBoundAction> GetBoundActions() const { return BoundActions; }

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Actions")
	void ClearBoundActions();

	/** Registers one Blueprint callback in this view's bounded named-action allowlist. */
	bool RegisterNamedAction(FName ActionName, const FQuartzUINamedActionHandler& Handler);

	/** C++ equivalent of RegisterNamedAction. */
	bool RegisterNativeNamedAction(FName ActionName, const FQuartzUINativeNamedActionHandler& Handler);

	bool UnregisterNamedAction(FName ActionName);
	bool IsNamedActionRegistered(FName ActionName) const;
	void ClearNamedActions();

	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|View")
	FQuartzUIViewStateChanged OnStateChanged;

	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Actions")
	FQuartzUIViewBoundActionsChanged OnBoundActionsChanged;

	/** Fired only after a strictly decoded action passes this view's explicit allowlist. */
	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Actions")
	FQuartzUIActionReceived OnAction;

private:
	UPROPERTY(Transient)
	TObjectPtr<UQuartzUITextureResources> TextureResources;
	friend class UQuartzUISubsystem;
	friend class UQuartzUIWidget;
	friend class UQuartzUIWorldSurfaceComponent;

	void Initialize(
		FGuid InViewId,
		const FQuartzUIAppDefinition& InAppDefinition,
		ULocalPlayer* InOwningLocalPlayer,
		const FString& InBrowserContextId,
		const FQuartzUIResolvedAppContract& InResolvedContract);
	bool TransitionTo(EQuartzUIViewState NewState, const FString& InFailureReason = FString());
	static bool CanTransition(EQuartzUIViewState From, EQuartzUIViewState To);
	bool TryAttachPresentation(UObject* Presentation);
	void DetachPresentation(UObject* Presentation);
	bool PublishBoundActions();
	bool PublishSimpleShellState(const FQuartzUIShellStateContract& ShellState);
	bool GetSimpleShellState(FQuartzUIShellStateContract& OutShellState) const;
	void RestoreSimpleGameUIBindings();
	void RestoreTypedEndpointBindings();
	void RestoreProviderBindings();
	void SetProviderUpdatesThrottled(bool bThrottled);
	bool AreProviderUpdatesThrottled() const { return bProviderUpdatesThrottled; }
	bool BindTypedEndpointInternal(UQuartzUITypedEndpoint* Endpoint, bool bAllowReservedCoreName);
	bool BindCoreTypedEndpoint(UQuartzUITypedEndpoint* Endpoint);
	bool RegisterBindingScope(UQuartzUIBindingScope* Scope);
	void UnregisterBindingScope(UQuartzUIBindingScope* Scope);
	int64 AdvanceProviderLifecycleGeneration(FName ProviderId, const UClass* ProviderClass);
	void RefreshBlueprintActionRetention();
	FQuartzUIEndpointResult HandleNamedActionRequest(const FString& PayloadJson);
	FQuartzUIEndpointResult HandleSoundRequest(const FString& PayloadJson);

	UPROPERTY(Transient)
	FGuid ViewId;

	UPROPERTY(Transient)
	FQuartzUIAppDefinition AppDefinition;

	UPROPERTY(Transient)
	TObjectPtr<ULocalPlayer> OwningLocalPlayer;

	UPROPERTY(Transient)
	FString BrowserContextId;

	UPROPERTY(Transient)
	EQuartzUIViewState State = EQuartzUIViewState::Created;

	UPROPERTY(Transient)
	FString FailureReason;

	FQuartzUIResolvedAppContract ResolvedContract;

	/** Keeps Blueprint/project DTO owners resident for the lifetime of this view. */
	UPROPERTY(Transient)
	TArray<TObjectPtr<UQuartzUIProjectContractAsset>> ContractAssets;

	/** Keeps Blueprint-generated provider classes resident with the resolved view contract. */
	UPROPERTY(Transient)
	TArray<TObjectPtr<UClass>> ProviderClasses;

	/** Keeps soft-loaded provider-set assets resident with the resolved app closure. */
	UPROPERTY(Transient)
	TArray<TObjectPtr<UQuartzUIProviderSet>> ProviderSets;

	/** Survives feature-owned provider replacement while this retained view lives. */
	TMap<FName, int64> ProviderLifecycleGenerations;
	bool bProviderUpdatesThrottled = false;

	UPROPERTY(Transient)
	TWeakObjectPtr<UObject> PresentationObject;

	UPROPERTY(Transient)
	TArray<FQuartzUIBoundAction> BoundActions;

	UPROPERTY(Transient)
	FString BoundActionsPayloadJson = TEXT("{\"actions\":[]}");

	UPROPERTY(Transient)
	FQuartzUIShellStateContract SimpleShellState;

	UPROPERTY(Transient)
	bool bHasSimpleShellState = false;

	TMap<FName, FQuartzUINamedActionHandler> BlueprintNamedActionHandlers;
	TMap<FName, FQuartzUINativeNamedActionHandler> NativeNamedActionHandlers;

	/** Dynamic-delegate copies keep Blueprint callback targets visible to GC. */
	UPROPERTY(Transient)
	TArray<FQuartzUINamedActionHandler> BlueprintNamedActionRetention;

	UPROPERTY(Transient)
	TMap<FName, TObjectPtr<UQuartzUITypedEndpoint>> TypedEndpoints;

	/** Strong retention makes the exact view the owner of every active provider lifetime. */
	UPROPERTY(Transient)
	TMap<FName, TObjectPtr<UQuartzUIBindingScope>> BindingScopes;

	friend class FQuartzUI;
	friend class UQuartzUIBindingScope;
	friend class UQuartzUIProvider;
	friend struct FQuartzUIDirectWorldSurfaceTestAccess;
};