QuartzUIWidget: declaration reference

#pragma once

#include "Components/Widget.h"
#include "QuartzUIApp.h"
#include "QuartzUIBridge.h"
#include "QuartzUIDiagnostics.h"
#include "QuartzUILoadRecovery.h"
#include "QuartzUIPresentationTarget.h"

#include "QuartzUIWidget.generated.h"

class UQuartzUIView;
class UQuartzUITypedEndpoint;
class SWidget;
enum class EWebBrowserConsoleLogSeverity;

DECLARE_DYNAMIC_MULTICAST_DELEGATE(FQuartzUILoadEvent);
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FQuartzUITextEvent, const FText&, Text);

/** UMG-facing QuartzUI control backed by SQuartzUIBrowser. */
UCLASS(BlueprintType, meta = (DisplayName = "QuartzUI"))
class QUARTZUIRUNTIME_API UQuartzUIWidget final
	: public UWidget
	, public IQuartzUIPresentationTarget
{
	GENERATED_BODY()

public:
	virtual UQuartzUIBridge* GetQuartzUIPresentationBridge() const override;
	virtual void DetachQuartzUIPresentation(UQuartzUIView* ExpectedView) override;

	/** Configures a standalone presentation before its Slate browser is constructed. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|App")
	bool ConfigureStandaloneApp(const FQuartzUIAppDefinition& Definition);

	/** Attaches this presentation to one live logical view. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|View")
	bool AttachToView(UQuartzUIView* View);

	/** Releases the browser presentation without closing the logical view. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|View")
	void DetachFromView();

	UFUNCTION(BlueprintPure, Category = "QuartzUI|View")
	UQuartzUIView* GetAttachedView() const { return AttachedView.Get(); }

	bool LoadUrl(const FString& Url);

	/** Navigates to a packaged app resource such as https://mvp.quartzui.test/index.html. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI")
	bool LoadPluginPage(FName AppId, const FString& RelativePath);

	/** Builds a canonical packaged resource URL for Blueprint and C++ callers. */
	static FString MakePluginUrl(FName AppId, const FString& RelativePath);

	bool LoadHtml(const FString& Html, const FString& DummyUrl = TEXT("about:blank"));

#if WITH_EDITOR
	/** Updates this live view to the exact Editor-activated loopback origin. C++ tooling only. */
	bool SetEditorDevelopmentOrigin(const FString& Origin);
#endif

	UFUNCTION(BlueprintCallable, Category = "QuartzUI")
	void Reload();

	/** Retries the failed document only while this view has retry budget remaining. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Recovery")
	bool RetryFailedLoad();

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Recovery")
	EQuartzUILoadRecoveryState GetLoadRecoveryState() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Recovery")
	int32 GetConsecutiveLoadRecoveryAttempts() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Recovery")
	int32 GetMaxLoadRecoveryAttempts() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Recovery")
	float GetHandshakeTimeoutSeconds() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Recovery")
	bool IsLoadRecoveryVisible() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Recovery")
	bool ShouldShowLoadRecoveryUI() const { return bShowLoadRecoveryUI; }

	void ExecuteJavaScript(const FString& Script);

	/** Controls normal document selection. Inputs, textareas, and contenteditable controls remain selectable. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Interaction")
	void SetAllowTextSelection(bool bAllow);

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Interaction")
	bool IsTextSelectionAllowed() const { return bAllowTextSelection; }

	/** Diagnostic: UE's platform text-input/IME system is bound to this live Chromium view. */
	bool IsInputMethodSystemBound() const;

	/** Enables GPU scene filtering for packaged HTML elements marked data-quartzui-backdrop. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Rendering")
	void SetSceneBackdropEnabled(bool bEnabled);

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Rendering")
	bool IsSceneBackdropEnabled() const { return bEnableSceneBackdrop; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Rendering")
	bool SupportsTransparency() const { return bSupportsTransparency; }

	/** Suspends Chromium rendering and coalesces bridge output until resumed. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Lifecycle")
	bool SetRuntimeSuspended(bool bSuspended);

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Lifecycle")
	bool IsRuntimeSuspended() const { return bRuntimeSuspended; }

	/** True only after this document loaded and its generated contract matched native. */
	UFUNCTION(BlueprintPure, Category = "QuartzUI|Lifecycle")
	bool IsQuartzUIReady() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI")
	FText GetTitleText() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI")
	FString GetUrl() const;

	/** Returns this view's physical raster estimate, load timings, and activity counters. */
	UFUNCTION(BlueprintPure, Category = "QuartzUI|Diagnostics")
	FQuartzUIViewStats GetDiagnostics() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Bridge")
	bool IsBridgeAvailable() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Bridge")
	int64 GetBridgeSessionId() const;

	/** Coalesces and delivers the latest named object state to this page. */
	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);

	/** Delivers one transient object event or queues it until the page handshakes. */
	bool EmitBridgeEvent(const FString& EventName, const FString& PayloadJson = TEXT("{}"));

	/** Registers one synchronous, object-JSON Blueprint handler on this browser view. */
	bool RegisterBridgeEndpoint(const FString& EndpointName, FQuartzUIEndpointHandler Handler);

	/** Native equivalent for C++ owners using the UMG widget. */
	bool RegisterNativeBridgeEndpoint(const FString& EndpointName, const FQuartzUINativeEndpointHandler& Handler);

	/** Native logical-view hook for the reserved quartzui.action endpoint. */
	bool SetNamedActionHandler(const FQuartzUINativeEndpointHandler& Handler);
	void ClearNamedActionHandler();

	/** Registers bounded async Blueprint work; complete the supplied request token once. */
	bool RegisterAsyncBridgeEndpoint(
		const FString& EndpointName,
		FQuartzUIAsyncEndpointHandler Handler,
		float TimeoutSeconds = 5.0f);

	/** Native async equivalent for C++ owners using the UMG widget. */
	bool RegisterNativeAsyncBridgeEndpoint(
		const FString& EndpointName,
		const FQuartzUINativeAsyncEndpointHandler& Handler,
		float TimeoutSeconds = 5.0f);

	/** Native-only web-first Back negotiation used by the exact-player layer host. */
	bool RequestBackNavigation(int64 RequestId, const FQuartzUIBackNavigationResultHandler& Handler);
	void CancelBackNavigationRequest();

	bool UnregisterBridgeEndpoint(const FString& EndpointName);

	void ClearBridgeEndpoints();

	bool IsBridgeEndpointRegistered(const FString& EndpointName) const;

	static FQuartzUIEndpointResult MakeBridgeSuccess(const FString& PayloadJson = TEXT("{}"));

	static FQuartzUIEndpointResult MakeBridgeFailure(const FString& ErrorCode, const FString& ErrorMessage);

	const FString& GetInitialPage() const { return InitialPage; }

	FName GetInitialAppId() const { return InitialAppId; }

	/** Native-only access to the actual focusable Chromium Slate widget. */
	TSharedPtr<SWidget> GetFocusableSlateWidget() const;

	/** Native layer-host boundary; prevents a hidden browser retaining a pressed pointer. */
	bool CancelInputCapture();

	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Events")
	FQuartzUILoadEvent OnLoadCompleted;

	/** Fired once per document after both browser load and bridge contract readiness. */
	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Events")
	FQuartzUILoadEvent OnReady;

	/** Fired once with a stable code when the loaded document cannot complete readiness. */
	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Events")
	FQuartzUITextEvent OnReadyError;

	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Events")
	FQuartzUILoadEvent OnLoadError;

	/** Fired after an explicit bounded retry successfully loads the document. */
	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Events")
	FQuartzUILoadEvent OnLoadRecovered;

	/** Fired once when the configured manual retry budget is consumed. */
	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Events")
	FQuartzUILoadEvent OnLoadRecoveryExhausted;

	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Events")
	FQuartzUITextEvent OnTitleChanged;

	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Events")
	FQuartzUITextEvent OnUrlChanged;

	/** Fired after an untrusted document or popup destination is denied. */
	UPROPERTY(BlueprintAssignable, Category = "QuartzUI|Security")
	FQuartzUITextEvent OnNavigationBlocked;

	virtual void ReleaseSlateResources(bool bReleaseChildren) override;
	/** Native embedding seam. Rectangles are normalized to this browser's full document viewport. */
	bool SetPointerInputRegions(const TArray<FBox2D>& Regions);
	bool IsPointerOverInputRegion() const;

#if WITH_EDITOR
	virtual const FText GetPaletteCategory() override;
#endif

protected:
	virtual TSharedRef<SWidget> RebuildWidget() override;

	UPROPERTY(EditAnywhere, Category = "QuartzUI")
	FString InitialPage = TEXT("index.html");

	UPROPERTY(EditAnywhere, Category = "QuartzUI")
	FName InitialAppId = TEXT("mvp");

	/** Optional absolute URL override, primarily for a future localhost development mode. */
	UPROPERTY(EditAnywhere, Category = "QuartzUI")
	FString InitialUrl;

	UPROPERTY(EditAnywhere, Category = "QuartzUI")
	bool bSupportsTransparency = true;

	UPROPERTY(EditAnywhere, Category = "QuartzUI", meta = (ClampMin = "1", ClampMax = "120"))
	int32 BrowserFrameRate = 60;

	/** Off by default so the document behaves like game UI instead of a general-purpose browser. */
	UPROPERTY(EditAnywhere, Category = "QuartzUI|Interaction")
	bool bAllowTextSelection = false;

	/** Native scene backdrop is opt-out; it costs nothing when the document declares no regions. */
	UPROPERTY(EditAnywhere, Category = "QuartzUI|Rendering")
	bool bEnableSceneBackdrop = true;

	/** Maximum consecutive manual retries for one failed navigation. */
	UPROPERTY(EditAnywhere, Category = "QuartzUI|Recovery", meta = (ClampMin = "0", ClampMax = "8"))
	int32 MaxLoadRecoveryAttempts = FQuartzUILoadRecoveryPolicy::DefaultMaxAttempts;

	/** Keeps optional passive views transparent instead of showing a full-surface failure panel. */
	UPROPERTY(EditAnywhere, Category = "QuartzUI|Recovery")
	bool bShowLoadRecoveryUI = true;

	/** Seconds after document load before a missing QuartzUI contract handshake fails visibly. */
	UPROPERTY(EditAnywhere, Category = "QuartzUI|Recovery", meta = (ClampMin = "0.1", ClampMax = "30.0"))
	float HandshakeTimeoutSeconds = FQuartzUIReadinessPolicy::DefaultHandshakeTimeoutSeconds;

	UPROPERTY(Transient)
	bool bRuntimeSuspended = false;

private:
	bool RegisterCoreNativeBridgeEndpoint(
		const FString& EndpointName,
		const FQuartzUINativeEndpointHandler& Handler);
	bool RegisterCoreNativeAsyncBridgeEndpoint(
		const FString& EndpointName,
		const FQuartzUINativeAsyncEndpointHandler& Handler,
		float TimeoutSeconds);

	void HandleLoadStarted();
	void HandleLoadCompleted();
	void HandleReady();
	void HandleReadyError(const FText& Text);
	void HandleLoadError();
	void HandleLoadRecovered();
	void HandleLoadRecoveryExhausted();
	void HandleTitleChanged(const FText& Text);
	void HandleUrlChanged(const FText& Text);
	void HandleNavigationBlocked(const FText& Text);
	void HandleConsoleMessage(
		const FString& Message,
		const FString& Source,
		int32 Line,
		EWebBrowserConsoleLogSeverity Severity);

	TSharedPtr<class SQuartzUIBrowser> BrowserWidget;
	bool bHasConstructedPresentation = false;

	UPROPERTY(Transient)
	TWeakObjectPtr<UQuartzUIView> AttachedView;

	friend class UQuartzUITypedEndpoint;
	friend struct FQuartzUIProviderRuntimeTestAccess;
};