#pragma once

// Clean-room implementation for HyperTwist puzzle viewer subsystem — Bound 1
// Lane: cubing/twisty.js (GPL-3.0-or-later — restrictive clean-room lane)
// Implemented from governance docs and abstract idea handoff only.
// No source code inspection. Clean-room workflow only.
// Date: 2026-05-17

#include "CoreMinimal.h"
#include "Kismet/BlueprintFunctionLibrary.h"
#include "HyperTwistSimulation/HyperTwistViewerTypes.h"
#include "HyperTwistViewerLibrary.generated.h"

// ---------------------------------------------------------------------------
// UHyperTwistViewerLibrary
//
// Stateless Blueprint helpers for constructing control requests, reading
// playback state, and formatting control-bar / scrubber output.
//
// Bound 1 scope: construction helpers and string formatters only.
// Easing / animation helpers belong to Bound 2.
// ---------------------------------------------------------------------------

UCLASS()
class UNREALHYPERTWIST_API UHyperTwistViewerLibrary : public UBlueprintFunctionLibrary
{
	GENERATED_BODY()

public:

	// ------------------------------------------------------------------
	// Control request constructors
	// ------------------------------------------------------------------

	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Control")
	static FHyperTwistViewerControlRequest MakePlayRequest();

	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Control")
	static FHyperTwistViewerControlRequest MakePauseRequest();

	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Control")
	static FHyperTwistViewerControlRequest MakeStopRequest();

	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Control")
	static FHyperTwistViewerControlRequest MakeStepForwardRequest();

	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Control")
	static FHyperTwistViewerControlRequest MakeStepBackRequest();

	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Control")
	static FHyperTwistViewerControlRequest MakeSeekRequest(int32 TargetIndex);

	// ------------------------------------------------------------------
	// Move entry construction
	// ------------------------------------------------------------------

	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer")
	static FHyperTwistViewerMoveEntry MakeMoveEntry(
		const FHyperTwistTransformation& Transform,
		const FString& DisplayLabel,
		float HintPositionSeconds
	);

	// ------------------------------------------------------------------
	// Scrubber accessors
	// ------------------------------------------------------------------

	// Returns a normalized position in [0.0, 1.0] for the scrubber widget.
	// Returns 0.0 when the move list is empty.
	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Readout")
	static float GetScrubberNormalizedPosition(const FHyperTwistViewerPlaybackState& State);

	// ------------------------------------------------------------------
	// Label formatters
	// ------------------------------------------------------------------

	// Returns a compact status string suitable for a HUD label.
	// Example: "Playing - 3 / 10 - 0.45s / 1.25s - R"
	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Readout")
	static FString GetControlBarReadout(
		const FHyperTwistViewerPlaybackState& State,
		const FHyperTwistViewerMoveEntry& CurrentEntry
	);

	// Returns the display label from a move entry, or "—" if empty.
	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Readout")
	static FString GetMoveNotationLabel(const FHyperTwistViewerMoveEntry& Entry);

	// Returns a human-readable mode string ("Playing", "Paused", etc.).
	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Readout")
	static FString GetPlaybackModeLabel(EHyperTwistViewerPlaybackMode Mode);

	// Returns a "N / M" step counter string. Returns "— / —" when list is empty.
	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Readout")
	static FString GetStepCounterLabel(const FHyperTwistViewerPlaybackState& State);

	// Returns a "T / D" timeline string using replay-backed milliseconds.
	// Returns "-- / --" when no replay timeline is loaded.
	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Readout")
	static FString GetTimelineLabel(const FHyperTwistViewerPlaybackState& State);

	// ------------------------------------------------------------------
	// Boundary queries
	// ------------------------------------------------------------------

	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Readout")
	static bool IsPlaybackAtStart(const FHyperTwistViewerPlaybackState& State);

	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Readout")
	static bool IsPlaybackAtEnd(const FHyperTwistViewerPlaybackState& State);

	UFUNCTION(BlueprintPure, Category = "HyperTwist|Viewer|Readout")
	static bool IsPlaybackActive(const FHyperTwistViewerPlaybackState& State);
};
