QuartzUIApp: declaration reference

#pragma once

#include "CoreMinimal.h"
#include "Engine/DataAsset.h"
#include "QuartzUILoadRecovery.h"
#include "QuartzUIReadiness.h"

#include "QuartzUIApp.generated.h"

class UQuartzUIProjectContractAsset;
class UQuartzUIProvider;
class UQuartzUIProviderSet;

/** Selects the immutable cooked root that owns an app's non-UAsset web files. */
UENUM(BlueprintType)
enum class EQuartzUIAppResourceOwner : uint8
{
	/** Compatibility-only product fixtures shipped inside QuartzUI. */
	PluginFixture UMETA(DisplayName = "Plugin fixture"),

	/** Production files beneath the game's Content/QuartzUI directory. */
	Project UMETA(DisplayName = "Project")
};

/** Native source of truth for one packaged web application entry point. */
USTRUCT(BlueprintType)
struct QUARTZUIRUNTIME_API FQuartzUIAppDefinition
{
	GENERATED_BODY()

	/** Lowercase DNS label used as the isolated <id>.quartzui.test origin. */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|App")
	FName AppId = TEXT("mvp");

	/** Root owner. Production apps are project-owned; plugin ownership is reserved for fixtures. */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|App")
	EQuartzUIAppResourceOwner ResourceOwner = EQuartzUIAppResourceOwner::PluginFixture;

	/** Directory below the selected owner's cooked root. Empty selects that root. */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|App")
	FString PackagedRoot;

	/** HTML document below PackagedRoot opened for this view. */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|App")
	FString EntryPage = TEXT("index.html");

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

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

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Interaction")
	bool bAllowTextSelection = false;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Rendering")
	bool bEnableSceneBackdrop = true;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Recovery", meta = (ClampMin = "0", ClampMax = "8"))
	int32 MaxLoadRecoveryAttempts = FQuartzUILoadRecoveryPolicy::DefaultMaxAttempts;

	/**
	 * Shows the native full-surface recovery panel when this view fails.
	 * Optional passive overlays can disable it to fail transparent while still
	 * reporting failure through the normal view lifecycle and diagnostics.
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Recovery")
	bool bShowLoadRecoveryUI = true;

	/** Bounded wait after document load for the generated native/JavaScript contract handshake. */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "QuartzUI|Recovery", meta = (ClampMin = "0.1", ClampMax = "30.0"))
	float HandshakeTimeoutSeconds = FQuartzUIReadinessPolicy::DefaultHandshakeTimeoutSeconds;
};

/** Explicit per-app choices that override shareable project rendering defaults. */
USTRUCT(BlueprintType)
struct QUARTZUIRUNTIME_API FQuartzUIAppProjectOverrides
{
	GENERATED_BODY()

	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults")
	bool bOverrideBrowserFrameRate = false;

	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults")
	bool bOverrideTransparency = false;

	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults")
	bool bOverrideTextSelection = false;

	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults")
	bool bOverrideSceneBackdrop = false;

	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults")
	bool bOverrideLoadRecoveryAttempts = false;

	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults")
	bool bOverrideHandshakeTimeout = false;
};

/** Bounded validation shared by assets, runtime views, resource origins, and tests. */
class QUARTZUIRUNTIME_API FQuartzUIAppPolicy final
{
public:
	static constexpr int32 MaxRegisteredApps = 64;
	static constexpr int32 MaxRelativePathLength = 512;

	/**
	 * Returns the lowercase wire/path representation of an app ID.
	 *
	 * FName comparisons are case-insensitive and ToString() can inherit the
	 * display casing of an earlier name in the process. App origins and cooked
	 * paths must never depend on that process-global display casing.
	 */
	static FString GetCanonicalAppId(FName AppId);
	static bool IsValidAppId(FName AppId);
	static bool TryNormalizeDefinition(
		const FQuartzUIAppDefinition& Definition,
		FQuartzUIAppDefinition& OutNormalized,
		FString& OutError);
	static bool TryBuildResourcePath(
		const FString& PackagedRoot,
		const FString& RelativePath,
		FString& OutResourcePath,
		FString& OutError);
	static FQuartzUIAppDefinition MakeLegacyDefinition(FName AppId);

private:
	static bool TryNormalizeRelativePath(
		const FString& Value,
		bool bAllowEmpty,
		FString& OutNormalized,
		FString& OutError);
};

/** Project-authored Blueprint/C++ asset for a packaged app/view entry. */
UCLASS(BlueprintType)
class QUARTZUIRUNTIME_API UQuartzUIAppAsset final : public UDataAsset
{
	GENERATED_BODY()

public:
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|App")
	FQuartzUIAppDefinition Definition;

	/**
	 * Selects which app-definition presentation/recovery fields beat project
	 * defaults when this asset is resolved through UQuartzUIProjectSettings.
	 * Identity, ownership, roots, and entry are always app-specific. Security
	 * and cook invariants are never overrideable here.
	 */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Project Defaults")
	FQuartzUIAppProjectOverrides ProjectOverrides;

	/**
	 * Explicit, ordered contract fragments used only by this app. Empty keeps
	 * the immutable middleware core contract, including for loading/fixture apps.
	 */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Contract", meta = (AllowedClasses = "/Script/QuartzUIRuntime.QuartzUIProjectContractAsset"))
	TArray<TSoftObjectPtr<UQuartzUIProjectContractAsset>> RegisteredProjectContracts;

	/**
	 * Explicit data-facade classes for this app. Their supported UPROPERTY,
	 * delegate, and UFUNCTION surface is generated automatically.
	 */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Providers")
	TArray<TSoftClassPtr<UQuartzUIProvider>> RegisteredProviders;

	/**
	 * Reusable provider collections participating in this app's exact contract
	 * closure. OnShellReady sets are also instantiated for the canonical shell.
	 */
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "QuartzUI|Providers")
	TArray<TSoftObjectPtr<UQuartzUIProviderSet>> RegisteredProviderSets;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|App")
	bool IsDefinitionValid(FString& OutError) const;

	/** Cook-generated wire metadata, including stable reflected display names. */
	UPROPERTY()
	TMap<FString, FString> CookedContractMetadata;

#if WITH_EDITOR
private:
	virtual void PreSave(FObjectPreSaveContext SaveContext) override;
	virtual void CookAdditionalFilesOverride(
		const TCHAR* PackageFilename,
		const ITargetPlatform* TargetPlatform,
		TFunctionRef<void(const TCHAR* Filename, void* Data, int64 Size)> WriteAdditionalFile) override;
#endif
};