QuartzUIBridge: declaration reference

#pragma once

#include "CoreMinimal.h"
#include "WebJSFunction.h"
#include "QuartzUIProtocol.h"

#include "QuartzUIBridge.generated.h"

/** Bounded object response returned by a registered game/UI endpoint. */
USTRUCT(BlueprintType)
struct QUARTZUIRUNTIME_API FQuartzUIEndpointResult
{
	GENERATED_BODY()

	UPROPERTY(BlueprintReadWrite, Category = "QuartzUI|Bridge")
	bool bSuccess = true;

	/** Must be a JSON object when bSuccess is true. */
	UPROPERTY(BlueprintReadWrite, Category = "QuartzUI|Bridge")
	FString PayloadJson = TEXT("{}");

	/** Lowercase dotted stable code when bSuccess is false. */
	UPROPERTY(BlueprintReadWrite, Category = "QuartzUI|Bridge")
	FString ErrorCode;

	UPROPERTY(BlueprintReadWrite, Category = "QuartzUI|Bridge")
	FString ErrorMessage;
};

class UQuartzUIBridge;

/** One pending Blueprint/C++ completion capability; never exposed to JavaScript. */
UCLASS(BlueprintType)
class QUARTZUIRUNTIME_API UQuartzUIEndpointRequest final : public UObject
{
	GENERATED_BODY()

public:
	const FString& GetCorrelationId() const { return CorrelationId; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Bridge")
	const FString& GetEndpointName() const { return EndpointName; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Bridge")
	bool IsPending() const { return bPending; }

	/** Resolves the browser Promise once; payload must be bounded object JSON. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Bridge")
	bool CompleteSuccess(const FString& PayloadJson = TEXT("{}"));

	/** Rejects the browser Promise once with a project-owned stable error. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Bridge")
	bool CompleteFailure(const FString& ErrorCode, const FString& ErrorMessage);

private:
	void Initialize(UQuartzUIBridge* InBridge, const FString& InCorrelationId, const FString& InEndpointName);
	void MarkCompleted();

	UPROPERTY(Transient)
	TWeakObjectPtr<UQuartzUIBridge> Bridge;

	UPROPERTY(Transient)
	FString CorrelationId;

	UPROPERTY(Transient)
	FString EndpointName;

	UPROPERTY(Transient)
	bool bPending = false;

	friend class UQuartzUIBridge;
};

/** Synchronous Blueprint endpoint handler. Create Event supplies this delegate to UQuartzUIWidget. */
DECLARE_DYNAMIC_DELEGATE_RetVal_OneParam(FQuartzUIEndpointResult, FQuartzUIEndpointHandler, const FString&, PayloadJson);

/** Asynchronous Blueprint handler; retain and complete Request after game work finishes. */
DECLARE_DYNAMIC_DELEGATE_TwoParams(
	FQuartzUIAsyncEndpointHandler,
	const FString&, PayloadJson,
	UQuartzUIEndpointRequest*, Request);

/** Synchronous native endpoint handler for Slate and C++ integrations. */
DECLARE_DELEGATE_RetVal_OneParam(FQuartzUIEndpointResult, FQuartzUINativeEndpointHandler, const FString&);
DECLARE_DELEGATE_TwoParams(FQuartzUINativeAsyncEndpointHandler, const FString&, UQuartzUIEndpointRequest*);
DECLARE_DELEGATE_TwoParams(FQuartzUIAsyncResponseHandler, bool, const FString&);
DECLARE_DELEGATE_OneParam(FQuartzUIOutboundMessageHandler, const FString&);
DECLARE_DELEGATE_TwoParams(FQuartzUIBackNavigationResultHandler, int64, bool);
DECLARE_DELEGATE_OneParam(FQuartzUIClientReadyFailureHandler, const FString&);

struct FQuartzUIPendingAsyncRequest
{
	FString EndpointName;
	int64 SessionId = 0;
	double DeadlineSeconds = 0.0;
	FQuartzUIAsyncResponseHandler ResponseHandler;
};

struct FQuartzUIAsyncTickerState;
struct FQuartzUIStateFlushTickerState;

/**
 * The single per-view UObject exposed to JavaScript as window.ue.quartzui.
 * Only Request is reflected; gameplay objects are never bound into the page.
 */
UCLASS(BlueprintType)
class QUARTZUIRUNTIME_API UQuartzUIBridge final : public UObject
{
	GENERATED_BODY()

public:
	UQuartzUIBridge(const FObjectInitializer& ObjectInitializer = FObjectInitializer::Get());

	static constexpr int32 MaxRegisteredEndpoints = 64;
	static constexpr int32 MaxStateSnapshots = FQuartzUIProtocolV1::MaxStatePatchEntries;
	static constexpr int32 MaxPendingEvents = 64;
	static constexpr int32 MaxPendingAsyncRequests = 32;
	static constexpr float MinAsyncTimeoutSeconds = 0.05f;
	static constexpr float MaxAsyncTimeoutSeconds = 30.0f;

	/** Called by Unreal's JavaScript proxy. Resolves or rejects the returned JavaScript Promise exactly once. */
	UFUNCTION()
	void Request(const FString& EnvelopeJson, FWebJSResponse Response);

	/** Starts a new security/session boundary for the target document. */
	void BeginNavigation(const FString& Url);
	/** Sets this view's exact generated contract before navigation/handshake. */
	bool SetContractHash(const FString& InContractHash);
	const FString& GetContractHash() const { return ContractHash; }
	/** Replaces the default MVP origin with the exact packaged app owned by this view. */
	bool SetAllowedPackagedOrigin(const FString& Origin);
	/** Restricts all document frames to this view's packaged or active Editor origin. */
	bool IsDocumentNavigationAllowed(const FString& Url) const;

#if WITH_EDITOR
	/** Allows one validated Editor Vite origin; this method and state do not exist in packaged builds. */
	bool SetAllowedDevelopmentOrigin(const FString& Origin);
#endif

	/** Native, deterministic dispatch entry point used by Request and automation. */
	bool TryHandleRequest(const FString& EnvelopeJson, FString& OutResponseJson);

	/** Registers a Blueprint-owned handler. The web page cannot call this non-reflected method. */
	bool RegisterEndpoint(const FString& EndpointName, const FQuartzUIEndpointHandler& Handler);

	/** Registers a C++ handler. Names are unique across Blueprint and native handlers. */
	bool RegisterNativeEndpoint(const FString& EndpointName, const FQuartzUINativeEndpointHandler& Handler);

	/** Registers a bounded Blueprint async handler without exposing it to JavaScript. */
	bool RegisterAsyncEndpoint(
		const FString& EndpointName,
		const FQuartzUIAsyncEndpointHandler& Handler,
		float TimeoutSeconds = 5.0f);

	/** Native async equivalent. Completion may occur on a later game-thread tick. */
	bool RegisterNativeAsyncEndpoint(
		const FString& EndpointName,
		const FQuartzUINativeAsyncEndpointHandler& Handler,
		float TimeoutSeconds = 5.0f);

	bool UnregisterEndpoint(const FString& EndpointName);
	void ClearEndpoints();
	bool IsEndpointRegistered(const FString& EndpointName) const;
	int32 GetRegisteredEndpointCount() const;
	int32 GetPendingAsyncRequestCount() const { return PendingAsyncRequests.Num(); }

	/** Deterministic async dispatch boundary used by Request and automation. */
	bool TryHandleAsyncRequest(
		const FString& EnvelopeJson,
		const FQuartzUIAsyncResponseHandler& ResponseHandler,
		bool& bOutWasAsyncEndpoint,
		FString& OutImmediateResponseJson);

	/** Coalesces the latest named object snapshot and replays it after navigation. */
	bool PublishStateSnapshot(const FString& StateName, const FString& PayloadJson);

	/** Validates and commits a complete named-state baseline atomically. */
	bool PublishStateSnapshots(const TMap<FString, FString>& Snapshots);

	/** Emits one transient object event now or queues it until the page handshakes. */
	bool EmitEvent(const FString& EventName, const FString& PayloadJson);

	/**
	 * Attempts to drain retained state and queued events immediately on the game thread.
	 * Returns true only when the ready, active bridge has no outbound work left.
	 */
	bool FlushOutboundMessagesNow();

	void SetOutboundMessageHandler(const FQuartzUIOutboundMessageHandler& Handler);
	void ClearOutboundMessageHandler();
	/** Notifies the native presentation once when this document completes a valid ping. */
	void SetClientReadyHandler(const FSimpleDelegate& Handler) { ClientReadyHandler = Handler; }
	void ClearClientReadyHandler() { ClientReadyHandler.Unbind(); }
	/** Notifies the presentation once when this document submits an invalid readiness ping. */
	void SetClientReadyFailureHandler(const FQuartzUIClientReadyFailureHandler& Handler) { ClientReadyFailureHandler = Handler; }
	void ClearClientReadyFailureHandler() { ClientReadyFailureHandler.Unbind(); }
	/** Pauses JavaScript delivery while retaining bounded latest-state/event queues. */
	bool SetOutboundSuspended(bool bSuspended);
	bool IsOutboundSuspended() const { return bOutboundSuspended; }
	bool IsOutboundClientReady() const { return bOutboundClientReady; }
	int32 GetStateSnapshotCount() const { return StateSnapshots.Num(); }
	int32 GetPendingEventCount() const { return PendingEvents.Num(); }

	/** Installs the one reserved renderer endpoint; it is not part of the gameplay endpoint registry. */
	void SetSceneBackdropHandler(const FQuartzUINativeEndpointHandler& Handler) { SceneBackdropHandler = Handler; }
	void ClearSceneBackdropHandler() { SceneBackdropHandler.Unbind(); }
	/** Installs the browser-owned platform announcement endpoint. */
	void SetAccessibilityAnnouncementHandler(const FQuartzUINativeEndpointHandler& Handler) { AccessibilityAnnouncementHandler = Handler; }
	void ClearAccessibilityAnnouncementHandler() { AccessibilityAnnouncementHandler.Unbind(); }
	/** Installs the one reserved, strictly decoded named UI-action endpoint. */
	void SetNamedActionHandler(const FQuartzUINativeEndpointHandler& Handler) { NamedActionHandler = Handler; }
	void ClearNamedActionHandler() { NamedActionHandler.Unbind(); }
	/** Installs the reserved exact-player semantic UI-sound endpoint. */
	void SetSoundRequestHandler(const FQuartzUINativeEndpointHandler& Handler) { SoundRequestHandler = Handler; }
	void ClearSoundRequestHandler() { SoundRequestHandler.Unbind(); }

	/**
	 * Offers one Back request to the ready packaged page. Only one request may be
	 * pending per document; the caller owns the bounded native fallback timer.
	 */
	bool RequestBackNavigation(int64 RequestId, const FQuartzUIBackNavigationResultHandler& Handler);
	void CancelBackNavigationRequest();
	bool HasPendingBackNavigationRequest() const { return PendingBackRequestId > 0; }

	bool IsAvailable() const { return bAvailable; }
	int64 GetSessionId() const { return SessionId; }
	const FString& GetDocumentUrl() const { return DocumentUrl; }
	int64 GetSucceededRequestCount() const { return SucceededRequests; }
	int64 GetFailedRequestCount() const { return FailedRequests; }
	int64 GetPublishedStateSnapshotCount() const { return PublishedStateSnapshots; }
	int64 GetDispatchedStatePatchCount() const { return DispatchedStatePatches; }
	int64 GetDispatchedStateValueCount() const { return DispatchedStateValues; }
	int64 GetCoalescedStateWriteCount() const { return CoalescedStateWrites; }
	int64 GetEmittedEventCount() const { return EmittedEvents; }
	int64 GetStateBackpressureRejectionCount() const { return StateBackpressureRejections; }
	int64 GetEventBackpressureRejectionCount() const { return EventBackpressureRejections; }
	int64 GetStartedAsyncRequestCount() const { return StartedAsyncRequests; }
	int64 GetTimedOutAsyncRequestCount() const { return TimedOutAsyncRequests; }
	int64 GetAsyncBackpressureRejectionCount() const { return AsyncBackpressureRejections; }

	virtual void BeginDestroy() override;

private:
	friend struct FQuartzUIProviderRuntimeTestAccess;
	bool CanRegisterEndpoint(const FString& EndpointName, bool bAllowReservedCoreName = false) const;
	bool RegisterCoreNativeEndpoint(
		const FString& EndpointName,
		const FQuartzUINativeEndpointHandler& Handler);
	bool RegisterCoreNativeAsyncEndpoint(
		const FString& EndpointName,
		const FQuartzUINativeAsyncEndpointHandler& Handler,
		float TimeoutSeconds);
	bool TryDispatchEndpoint(const FQuartzUIRequestEnvelope& RequestEnvelope, FString& OutResponseJson);
	bool MakeFailure(
		const FString& CorrelationId,
		const FString& ErrorCode,
		const FString& ErrorMessage,
		FString& OutResponseJson);
	void RecordResult(bool bSucceeded);
	int64 NextOutboundSequence();
	bool TryCreateOutbound(
		EQuartzUIOutboundMessageType Type,
		const FString& Name,
		const FString& PayloadJson,
		FQuartzUIOutboundEnvelope& OutEnvelope);
	bool DispatchOutbound(const FQuartzUIOutboundEnvelope& Envelope);
	bool DispatchNextStatePatch();
	void FlushOutbound();
	bool HandleStateFlushTicker(float DeltaTime);
	void EnsureStateFlushTicker();
	void StopStateFlushTicker();
	FQuartzUIEndpointResult HandleBackNavigationResult(const FString& PayloadJson);
	bool CompleteAsyncRequest(UQuartzUIEndpointRequest* Request, const FQuartzUIEndpointResult& Result);
	bool CancelAsyncRequest(
		const FString& CorrelationId,
		const FString& ErrorCode,
		const FString& ErrorMessage);
	void CancelAsyncRequestsForEndpoint(
		const FString& EndpointName,
		const FString& ErrorCode,
		const FString& ErrorMessage);
	void CancelAllAsyncRequests(const FString& ErrorCode, const FString& ErrorMessage);
	bool TickAsyncRequests(double CurrentTimeSeconds);
	bool HandleAsyncTicker(float DeltaTime);
	void EnsureAsyncTicker();
	void StopAsyncTicker();
	void NotifyClientReadyFailure(const FString& ErrorCode);

	FString DocumentUrl;
	FString ContractHash;
	FString AllowedPackagedOrigin = TEXT("https://mvp.quartzui.test");
#if WITH_EDITOR
	FString AllowedDevelopmentOrigin;
#endif
	int64 SessionId = 0;
	int64 SucceededRequests = 0;
	int64 FailedRequests = 0;
	int64 PublishedStateSnapshots = 0;
	int64 DispatchedStatePatches = 0;
	int64 DispatchedStateValues = 0;
	int64 CoalescedStateWrites = 0;
	int64 EmittedEvents = 0;
	int64 StateBackpressureRejections = 0;
	int64 EventBackpressureRejections = 0;
	int64 StartedAsyncRequests = 0;
	int64 TimedOutAsyncRequests = 0;
	int64 AsyncBackpressureRejections = 0;
	bool bAvailable = false;
	TMap<FString, FQuartzUIEndpointHandler> BlueprintEndpointHandlers;
	TMap<FString, FQuartzUINativeEndpointHandler> NativeEndpointHandlers;
	TMap<FString, FQuartzUIAsyncEndpointHandler> BlueprintAsyncEndpointHandlers;
	TMap<FString, FQuartzUINativeAsyncEndpointHandler> NativeAsyncEndpointHandlers;
	TMap<FString, float> AsyncEndpointTimeouts;
	TMap<FString, FQuartzUIPendingAsyncRequest> PendingAsyncRequests;

	UPROPERTY(Transient)
	TMap<FString, TObjectPtr<UQuartzUIEndpointRequest>> PendingAsyncRequestObjects;

	TSharedPtr<FQuartzUIAsyncTickerState> AsyncTickerState;
	TSharedPtr<FQuartzUIStateFlushTickerState> StateFlushTickerState;
	bool bInsideAsyncTick = false;
	bool bInsideStateFlushTick = false;
	FQuartzUINativeEndpointHandler SceneBackdropHandler;
	FQuartzUINativeEndpointHandler AccessibilityAnnouncementHandler;
	FQuartzUINativeEndpointHandler NamedActionHandler;
	FQuartzUINativeEndpointHandler SoundRequestHandler;
	FQuartzUIBackNavigationResultHandler BackNavigationResultHandler;
	TMap<FString, FQuartzUIOutboundEnvelope> StateSnapshots;
	TSet<FString> DirtyStateNames;
	TArray<FQuartzUIOutboundEnvelope> PendingEvents;
	FQuartzUIOutboundMessageHandler OutboundMessageHandler;
	FSimpleDelegate ClientReadyHandler;
	FQuartzUIClientReadyFailureHandler ClientReadyFailureHandler;
	int64 OutboundSequence = 0;
	bool bOutboundClientReady = false;
	bool bClientReadyFailureNotified = false;
	bool bOutboundSuspended = false;
	int64 PendingBackRequestId = 0;
	int64 PendingBackSessionId = 0;

	friend class UQuartzUIEndpointRequest;
	friend class UQuartzUITypedEndpoint;
	friend class UQuartzUIWidget;
	friend struct FQuartzUIBridgeReservedEndpointTestAccess;
	friend class FQuartzUIBridgeAsyncEndpointTest;
	friend class FQuartzUIBridgeOutboundStateAndEventTest;
};