---@meta

---@alias TranslatorType
---|"MainFrame"
---|"ClassTalentFrame"
---|"SpellbookFrame"
---|"NameplateAndUnitFrame"
---|"SpellTooltip"
---|"UnitTooltip"
---|"Subtitles"
---|"NpcMessage"
---|"QuestFrame"

---@alias UIFrameType
---|"Spellbook"
---|"ClassTalent"
---|"Main"
---|"Quest"

---@alias ChangelogEntryColor
---|"purple"
---|"blue"
---|"red"
---|"green"
---|"legendary"

---@class (exact) PlayerData
---@field Name string @The name of the player character.
---@field Realm string @The realm of the player character.
---@field Race string @The race of the player character.
---@field Class string @The class of the player character.
---@field Gender number? @The gender (sex) of the player character.

---@class (exact) AddonData
---@field ReleaseDate number @The release date timestamp obtained from the add-on metadata.
---@field Version string @The version string obtained from the add-on metadata.
---@field VesionStr string @A formatted string representing the version and release date.

---@class WowUkrainizerInternals
---@field PlayerInfo PlayerData @Object containing information about the player character.
---@field AddonInfo AddonData @Object containing common data such as release date and version information.
---@field SettingsProvider SettingsProvider? @Instance of the SettingsProvider. To create instance call CreateSettingsProvider
---@field UntranslatedDataStorage UntranslatedDataStorage? @Singleton instance of the UntranslatedDataStorage. To create instance call CreateUntranslatedDataStorage
---@field IngameDataCacher IngameDataCacher? @Singleton instance of the IngameDataCacher. To create instance call CreateIngameDataCacher
---@field TooltipLineAccessor TooltipLineAccessor @Unified accessor for reading/writing tooltip line FontStrings.

---@class (exact) TranslatedQuestData
---@field ID number The unique identifier of the quest.
---@field Title string The translated title of the quest.
---@field Description string The translated description of the quest.
---@field ObjectivesText string The translated text describing the quest objectives.
---@field ContainsObjectives boolean Indicates whether the quest contains specific objectives.
---@field CompletionText string The translated text displayed upon quest completion.
---@field TargetName string The translated name of the quest target.
---@field TargetDescription string The translated description of the quest target.
---@field TargetCompletedName string The translated name of the quest target upon completion.
---@field TargetCompletedDescription string The translated description of the quest target upon completion.
---@field AreaDescription string The translated description of the quest area.
---@field RewardText string The translated text describing the quest rewards.
---@field ProgressText string The translated text describing quest progress.
---@field IsMtData boolean True if any translated text generated by AI; otherwise false

---@class (exact) TranslatedItemData
---@field Title string The translated title of the item.
---@field Description string The translated description of the item.

--- A single categorized section within a changelog entry.
---@class (exact) ChangelogSection
---@field color ChangelogEntryColor -- Color code for UI display
---@field type string -- The type of change
---@field author string -- The author who made the change
---@field description string -- Full description of the change

--- Changelog entry containing details of changes for a specific version.
---@class (exact) ChangelogEntry
---@field version string -- The version the change was made in
---@field date string -- The date the change was made
---@field title string? -- The title summarizing the change
---@field sections ChangelogSection[] -- One or more categorized change sections

---@class (exact) WowUkrainizerDatabase
---@field Changelogs ChangelogEntry[] Array of changelog entries, newest first
---@field Quests table<integer, string[]>
---@field QuestObjectives table<integer, table<integer, string>>
---@field MTQuests table<integer, string[]>
---@field MTQuestObjectives table<integer, table<integer, string>>
---@field UnitTypes table<integer, string>
---@field UnitRanks table<integer, string>
---@field CommonSpellAttributes table<integer, string>
---@field Specializations table<integer, string>
---@field Classes table<integer, string[]>
---@field Races table<integer, string[]>
---@field ShortRaces table<string, string>
---@field Attributes table<integer, string>
---@field Roles table<integer, string>
---@field SpecializationNotes table<integer, string>
---@field DialogTexts table<integer, string>
---@field AdditionalSpellTips table<integer, string>
---@field GossipTitles table<integer, string>
---@field GossipOptions table<integer, string>
---@field SpellNames table<integer, string>
---@field SpellDescriptions table<integer, string>
---@field MovieSubtitles table<integer, string>
---@field UnitNames table<integer, string|table<string[]>>
---@field UnitSubnames table<integer, string>
---@field ZoneTexts table<integer, string>
---@field GlobalStrings table<integer, string>
---@field Factions table<integer, string>
---@field ItemAttributes table<integer, string>
---@field Items table<integer, string[]>
---@field Waypoints table<integer, string>
-- TODO: @field Voiceover

-- ---------------------------------------------------------------------------
-- Spell tooltip parser shapes (Core/Translators/Tooltips/SpellTooltipTranslator.lua)
-- ---------------------------------------------------------------------------

---@class (exact) TooltipFragment
---@field value string
---@field line integer           @1-based tooltip line index (visible lines only)
---@field right boolean          @true = right text, false = left text
---@field type integer?          @Enum.TooltipDataLineType (spell-like tooltips only)

-- Shared sub-shape used by most SpellBlock fields.
---@class (exact) TooltipLineValue
---@field value string
---@field line integer
---@field right boolean

-- Same as TooltipLineValue but without value (Passive / Upgrade markers).
---@class (exact) TooltipLineMarker
---@field line integer
---@field right boolean

---@class (exact) ResourceLineValue : TooltipLineMarker
---@field values string[]        @Unique resource-cost lines extracted from the fragment

---@class (exact) SpellBlock
---@field ResourceType ResourceLineValue?
---@field Range TooltipLineValue?
---@field Requires TooltipLineValue?
---@field CastTime TooltipLineValue?
---@field Cooldown TooltipLineValue?
---@field CooldownRemaining TooltipLineValue?
---@field MaxCharges TooltipLineValue?
---@field EvokerSpellColor TooltipLineValue?
---@field ReplacedBy TooltipLineValue?
---@field Replaces TooltipLineValue?
---@field Passive TooltipLineMarker?
---@field Upgrade TooltipLineMarker?
---@field AdditionalSpellTips TooltipLineValue[]?
---@field Descriptions TooltipLineValue[]?

---@class (exact) TalentBlock
---@field Rank TooltipLineValue
---@field MinRank string
---@field MaxRank string?        @nil when the NO_MAX rank pattern matched
---@field CurrentRank SpellBlock
---@field NextRankHeader TooltipLineValue?
---@field NextRank SpellBlock?

---@class (exact) CapstoneTier
---@field Header TooltipLineValue
---@field TierNumber integer
---@field CurrentBlock SpellBlock
---@field NextHeader TooltipLineValue?
---@field NextBlock SpellBlock?

---@class (exact) CapstoneBlock
---@field RawTitle string
---@field TitleLine integer
---@field CurrentRank string?
---@field TotalMaxRanks string?
---@field Tiers CapstoneTier[]
---@field Passive TooltipLineMarker?

-- Produced by parseSpellTooltip / parseTalentSpendTooltip / parseTalentCapstoneTooltip.
-- Exactly one of Spell / Talent / Capstone is set.
---@class (exact) SpellTooltipInfo
---@field Name TooltipLineValue
---@field Form TooltipLineValue?
---@field SpellId integer?
---@field Spell SpellBlock?
---@field Talent TalentBlock?
---@field Capstone CapstoneBlock?

-- Addon-local frame (declared in Core/Frames/).
---@type Frame
SubtitlesFrame = nil

-- Immersion (3rd-party addon) globals. Shape is intentionally loose — Immersion's
-- API surface is not stable across versions. Declared here only so hooks compile.
---@type Frame?
ImmersionFrame = nil
---@type table?
ImmersionAPI = nil
---@type Frame?
ImmersionContentFrame = nil
