Core.lua

local AddOnName, KeystonePolaris = ...;

local _G = _G;
-- Cache frequently used global functions for better performance
local pairs, select = pairs, select
local C_Scenario = _G.C_Scenario
local C_ScenarioInfo = _G.C_ScenarioInfo

-- Initialize Ace3 libraries
local AceAddon = LibStub("AceAddon-3.0")
KeystonePolaris = AceAddon:NewAddon(KeystonePolaris, AddOnName, "AceConsole-3.0", "AceEvent-3.0");

-- Initialize changelog
KeystonePolaris.Changelog = {}

KeystonePolaris.isMidnight = select(4, GetBuildInfo()) >= 120000

KeystonePolaris.DEFAULT_FONT_FLAG_PRESET = "outline_slug"

local FONT_FLAG_OPTIONS = {
    { key = "none", flags = "", labelKey = "FONT_FLAG_NONE" },
    { key = "slug", flags = "SLUG", labelKey = "FONT_FLAG_SLUG" },
    { key = "outline_slug", flags = "OUTLINE, SLUG", labelKey = "FONT_FLAG_OUTLINE_SLUG" },
    { key = "monochrome", flags = "MONOCHROME", labelKey = "FONT_FLAG_MONOCHROME" },
    { key = "outline", flags = "OUTLINE", labelKey = "FONT_FLAG_OUTLINE" },
    { key = "thickoutline", flags = "THICKOUTLINE", labelKey = "FONT_FLAG_THICKOUTLINE" },
    { key = "outline_monochrome", flags = "OUTLINE, MONOCHROME", labelKey = "FONT_FLAG_OUTLINE_MONOCHROME" },
    { key = "thickoutline_monochrome", flags = "THICKOUTLINE, MONOCHROME", labelKey = "FONT_FLAG_THICKOUTLINE_MONOCHROME" },
}

local FONT_FLAG_PRESETS = {}
KeystonePolaris.fontFlagPresetSorting = {}
for _, entry in ipairs(FONT_FLAG_OPTIONS) do
    FONT_FLAG_PRESETS[entry.key] = entry.flags
    KeystonePolaris.fontFlagPresetSorting[#KeystonePolaris.fontFlagPresetSorting + 1] = entry.key
end

function KeystonePolaris:GetFontFlagsPreset()
    local stored = self.db and self.db.profile and self.db.profile.text and self.db.profile.text.fontFlags
    if stored and FONT_FLAG_PRESETS[stored] ~= nil then
        return stored
    end
    return self.DEFAULT_FONT_FLAG_PRESET
end

function KeystonePolaris:GetFontFlags()
    return FONT_FLAG_PRESETS[self:GetFontFlagsPreset()]
end

function KeystonePolaris:GetFontFlagSelectValues()
    local L = self.L
    local vals = {}
    for _, entry in ipairs(FONT_FLAG_OPTIONS) do
        vals[entry.key] = L[entry.labelKey]
    end
    return vals
end

-- Define constants
KeystonePolaris.constants = {
    mediaPath = "Interface\\AddOns\\" .. AddOnName .. "\\media\\"
}

-- Track the last routes update version for prompting users
KeystonePolaris.lastRoutesUpdate = "3.11" -- Set to true when routes have been updated

-- Table to store dungeons with changed routes
KeystonePolaris.CHANGED_ROUTES_DUNGEONS = {
    ["NPX"] = true, -- Nexus-Point Xenas
}

-- Initialize Ace3 configuration libraries
local AceConfig = LibStub("AceConfig-3.0")
local AceConfigDialog = LibStub("AceConfigDialog-3.0")

-- Initialize LibSharedMedia for font and texture support
KeystonePolaris.LSM = LibStub('LibSharedMedia-3.0');

-- Get localization table
local L = LibStub("AceLocale-3.0"):GetLocale(AddOnName, true)
KeystonePolaris.L = L

local LDB = LibStub("LibDataBroker-1.1", true)
local LDBIcon = LibStub("LibDBIcon-1.0", true)
-- One-shot marker used to re-enable mob percentages when the Blizzard API returned.
local MOB_PERCENTAGES_REENABLE_MIGRATION = "3.8"

local function Lerp(a, b, t)
    return a + (b - a) * t
end

local function GradientText(text)
    local len = text and #text or 0
    if len == 0 then return "" end
    local colors = {
        {1, 0.2, 0.2},   -- red
        {1, 0.55, 0},    -- orange
        {1, 0.9, 0.2},   -- yellow
    }
    local out = {}
    for i = 1, len do
        local t = (len == 1) and 0 or (i - 1) / (len - 1)
        local c1, c2, lt
        if t <= 0.5 then
            c1, c2, lt = colors[1], colors[2], t * 2
        else
            c1, c2, lt = colors[2], colors[3], (t - 0.5) * 2
        end
        local r = Lerp(c1[1], c2[1], lt)
        local g = Lerp(c1[2], c2[2], lt)
        local b = Lerp(c1[3], c2[3], lt)
        out[i] = string.format("|cff%02x%02x%02x%s|r",
            math.floor((r * 255) + 0.5),
            math.floor((g * 255) + 0.5),
            math.floor((b * 255) + 0.5),
            text:sub(i, i))
    end
    return table.concat(out)
end

local function BuildModulesOverviewDescription()
    local featureIcon = "|TInterface\\OptionsFrame\\UI-OptionsFrame-NewFeatureIcon:14:14:0:0|t"
    local intro = L["MODULES_SUMMARY_INTRO"]
    local mobPercentagesTitle = L["MOB_PERCENTAGES"]
    local mobPercentagesDesc = L["MODULES_SUMMARY_MOB_PERCENTAGES_DESC"]
    local groupReminderTitle = L["KPL_GR_HEADER"]
    local groupReminderDesc = L["MODULES_SUMMARY_GROUP_REMINDER_DESC"]

    return table.concat({
        intro,
        "",
        featureIcon .. " |cffffd100" .. mobPercentagesTitle .. "|r",
        "   |cff9d9d9d" .. mobPercentagesDesc .. "|r",
        "",
        featureIcon .. " |cffffd100" .. groupReminderTitle .. "|r",
        "   |cff9d9d9d" .. groupReminderDesc .. "|r",
    }, "\n")
end

function KeystonePolaris:GetGradientAddonName()
    if not self._gradientAddonName then
        self._gradientAddonName = GradientText("Keystone Polaris")
    end
    return self._gradientAddonName
end

function KeystonePolaris:GetGradientAddonNameFromSecondLetter()
    if not self._gradientAddonNameFromSecond then
        local name = "Keystone Polaris"
        local first = name:sub(1, 1)
        local rest = name:sub(2)
        self._gradientAddonNameFromSecond = first .. GradientText(rest)
    end
    return self._gradientAddonNameFromSecond
end

function KeystonePolaris:GetChatPrefix(bracketed, plain)
    local name = plain and "Keystone Polaris" or self:GetGradientAddonName()
    if bracketed then
        if plain then
            return "[" .. name .. "]"
        end
        return "|cffffd100[|r" .. name .. "|cffffd100]|r"
    end
    return name
end

function KeystonePolaris.ColorizeCommands(_, text)
    if type(text) ~= "string" then return text end
    local knownSubCommands = {
        help = true,
        reminder = true,
        changelog = true,
    }
    local out = {}
    local index = 1
    while true do
        local startPos, endPos, cmd = text:find("(/%w+)", index)
        if not startPos then
            table.insert(out, text:sub(index))
            break
        end
        table.insert(out, text:sub(index, startPos - 1))
        local subStart, subEnd, subWord = text:find("%s+(%w+)", endPos + 1)
        if subStart == endPos + 1 and subWord and knownSubCommands[subWord] then
            table.insert(out, "|cffffd100" .. cmd .. text:sub(subStart, subEnd) .. "|r")
            index = subEnd + 1
        else
            table.insert(out, "|cffffd100" .. cmd .. "|r")
            index = endPos + 1
        end
    end
    return table.concat(out)
end

function KeystonePolaris:PrintLoadMessage()
    if not (self.db and self.db.profile and self.db.profile.general) then return end
    if self.db.profile.general.disableLoginMessage then return end

    local prefix = (self.GetChatPrefix and self:GetChatPrefix()) or "Keystone Polaris"
    local body = self:ColorizeCommands(
        L["ADDON_LOADED_MSG"]
            or "loaded, type /kpl to open settings, or /kpl help to show the list of commands available."
    )
    local message = prefix .. " " .. body
    if DEFAULT_CHAT_FRAME and DEFAULT_CHAT_FRAME.AddMessage then
        DEFAULT_CHAT_FRAME:AddMessage(message)
    else
        print(message)
    end
end

local function EnsureMinimapSettings(self)
    if not (self.db and self.db.profile and self.db.profile.general) then return end
    local general = self.db.profile.general
    general.minimap = general.minimap or {}
    if general.minimap.minimapPos == nil and general.minimapAngle ~= nil then
        general.minimap.minimapPos = general.minimapAngle
    end
    if general.minimap.hide == nil then
        general.minimap.hide = not general.showMinimapIcon
    end
    if general.minimap.showInCompartment == nil then
        general.minimap.showInCompartment = general.showCompartmentIcon ~= false
    end
end

local function EnsureAddonCompartmentLoaded()
    if _G.AddonCompartmentFrame then return end
    if C_AddOns and C_AddOns.LoadAddOn then
        C_AddOns.LoadAddOn("Blizzard_AddonCompartment")
    end
end

local function CleanupCompartmentEntries(self)
    local compartmentFrame = _G.AddonCompartmentFrame
    if not compartmentFrame or not compartmentFrame.registeredAddons then return end
    local label = (self.GetGradientAddonName and self:GetGradientAddonName()) or "Keystone Polaris"
    for i = #compartmentFrame.registeredAddons, 1, -1 do
        local entry = compartmentFrame.registeredAddons[i]
        if entry and (entry.text == AddOnName or entry.text == label) then
            table.remove(compartmentFrame.registeredAddons, i)
        end
    end
    if compartmentFrame.UpdateDisplay then
        compartmentFrame:UpdateDisplay()
    end
end

local function UpdateCompartmentEntryLabel(self)
    local compartmentFrame = _G.AddonCompartmentFrame
    if not compartmentFrame or not compartmentFrame.registeredAddons then return end
    local label = (self.GetGradientAddonName and self:GetGradientAddonName()) or "Keystone Polaris"
    for i = 1, #compartmentFrame.registeredAddons do
        local entry = compartmentFrame.registeredAddons[i]
        if entry and entry.text == AddOnName then
            entry.text = label
            entry.icon = entry.icon or "Interface\\AddOns\\KeystonePolaris\\icon.png"
            if compartmentFrame.UpdateDisplay then
                compartmentFrame:UpdateDisplay()
            end
            return
        end
    end
end

function KeystonePolaris:UpdateMinimapIconVisibility()
    if not LDBIcon then return end
    EnsureMinimapSettings(self)
    if not (self.db and self.db.profile and self.db.profile.general) then return end
    local general = self.db.profile.general
    local hide = not general.showMinimapIcon
    general.minimap.hide = hide
    if hide then
        LDBIcon:Hide(AddOnName)
    else
        LDBIcon:Show(AddOnName)
    end
end

function KeystonePolaris:InitializeMinimapIcon()
    if self._minimapIconInitialized or not (LDB and LDBIcon) then return end
    EnsureMinimapSettings(self)

    if not self._ldbObject then
        self._ldbObject = LDB:NewDataObject(AddOnName, {
            type = "launcher",
            text = (self.GetGradientAddonName and self:GetGradientAddonName()),
            icon = "Interface\\AddOns\\KeystonePolaris\\icon.png",
            parent = "KeystonePolaris",
            OnClick = function()
                if self.ToggleConfig then
                    self:ToggleConfig()
                end
            end,
            -- Use GameTooltip via OnEnter/OnLeave instead of OnTooltipShow:
            -- LibDBIconTooltip (GameTooltipTemplate) often has a missing/transparent
            -- backdrop on Midnight and with tooltip-skinning addons.
            OnEnter = function(frame)
                GameTooltip:SetOwner(frame, "ANCHOR_LEFT")
                GameTooltip:AddLine("Keystone Polaris")
                GameTooltip:AddLine("Click to open options", 1, 1, 1)
                GameTooltip:Show()
            end,
            OnLeave = function()
                GameTooltip:Hide()
            end,
        })
    end

    LDBIcon:Register(AddOnName, self._ldbObject, self.db.profile.general.minimap)
    self._minimapIconInitialized = true
    self:UpdateMinimapIconVisibility()
end

function KeystonePolaris:UpdateCompartmentIconVisibility()
    if not (self.db and self.db.profile and self.db.profile.general) then return end
    local show = self.db.profile.general.showCompartmentIcon ~= false
    if not LDBIcon then return end
    EnsureAddonCompartmentLoaded()
    if not _G.AddonCompartmentFrame then
        if not self._pendingCompartmentUpdate and C_Timer and C_Timer.After then
            self._pendingCompartmentUpdate = true
            C_Timer.After(1, function()
                self._pendingCompartmentUpdate = false
                if self.UpdateCompartmentIconVisibility then
                    self:UpdateCompartmentIconVisibility()
                end
            end)
        end
        return
    end
    EnsureMinimapSettings(self)
    if self.db.profile.general.minimap then
        self.db.profile.general.minimap.showInCompartment = show
    end
    if LDBIcon.RemoveButtonFromCompartment then
        LDBIcon:RemoveButtonFromCompartment(AddOnName)
    end
    CleanupCompartmentEntries(self)
    if show and LDBIcon.AddButtonToCompartment then
        LDBIcon:AddButtonToCompartment(AddOnName)
        UpdateCompartmentEntryLabel(self)
    end
end

-- Initialize dungeons table to store all dungeon data
KeystonePolaris.DUNGEONS = {}


-- Track current dungeon and section
KeystonePolaris.currentDungeonID = 0
KeystonePolaris.currentSection = 1
KeystonePolaris.currentSectionOrder = nil
KeystonePolaris.currentMilestoneInformState = {}

-- Called when the addon is first loaded
function KeystonePolaris:OnInitialize()
    -- Initialize the database first with AceDB
    self.db = LibStub("AceDB-3.0"):New("KeystonePolarisDB", self.defaults, "Default")

    local general = self.db.profile.general
    -- Capture before CheckForNewRoutes overwrites lastVersionCheck on first install.
    self._hadPriorVersionCheck = (general.lastVersionCheck or "") ~= ""

    -- Force-enable the returning feature once per profile, then keep user choice afterwards.
    if general.mobPercentagesMigrationVersion ~= MOB_PERCENTAGES_REENABLE_MIGRATION then
        self.db.profile.mobPercentages = self.db.profile.mobPercentages or {}
        self.db.profile.mobPercentages.enabled = true
        general.mobPercentagesMigrationVersion = MOB_PERCENTAGES_REENABLE_MIGRATION
    end

    -- Migrate prefixColor from general.mainDisplay to color.prefix
    local oldPrefix = self.db.profile.general.mainDisplay.prefixColor
    if oldPrefix then
        if not self.db.profile.color.prefix then
            self.db.profile.color.prefix = oldPrefix
        end
        self.db.profile.general.mainDisplay.prefixColor = nil
    end

    -- Load dungeon data from expansion modules
    self:LoadExpansionDungeons()

    -- Generate changelog for display in options
    self:GenerateChangelog()
    self:GenerateAbout()

    -- Check if a new season has started
    self:CheckForNewSeason()

    -- Check if routes have been updated in a new version
    self:CheckForNewRoutes()

    -- Initialize Display (Frames, Overlay, Anchors) - Modules/DisplayFrame.lua
    if self.InitializeDisplay then
        self:InitializeDisplay()
    end

    if self.InitializeProgressBar then
        self:InitializeProgressBar()
    end

    self:InitializeMinimapIcon()
    self:UpdateCompartmentIconVisibility()

    self.db.RegisterCallback(self, "OnProfileChanged", "RefreshForActiveProfile")
    self.db.RegisterCallback(self, "OnProfileCopied", "RefreshForActiveProfile")

    -- Register options with Ace3 config system
    local optionsAddonName = (self.GetGradientAddonNameFromSecondLetter and self:GetGradientAddonNameFromSecondLetter()) or "Keystone Polaris"
    local optionsAddonDisplayName = (self.GetGradientAddonName and self:GetGradientAddonName()) or optionsAddonName
    local modulesSummaryDescription = BuildModulesOverviewDescription(L)
    AceConfig:RegisterOptionsTable(AddOnName, {
        name = optionsAddonDisplayName,
        type = "group",
        args = {
            general = {
                name = L["TEXT_DISPLAY"],
                type = "group",
                order = 1,
                childGroups = "tree",
                args = {
                    disclaimerHeader = {
                        order = 0,
                        type = "header",
                        name = "|TInterface\\OptionsFrame\\UI-OptionsFrame-NewFeatureIcon:16:16:0:0|t " .. L["COMPATIBILITY_WARNING"],
                    },
                    warningMessage = {
                        name = L["COMPATIBILITY_WARNING_MESSAGE_CORE"],
                        type = "description",
                        order = 0.15,
                        width = "full",
                        fontSize = "medium",
                    },
                    display = self:GetDisplayOptions(),
                    appearance = self:GetAppearanceOptions(),
                    positioning = self:GetPositioningOptions(),
                }
            },
            progressBar = self:GetProgressBarOptions(),
            informGroup = self:GetInformGroupOptions(),
            modules = {
                name = L["MODULES"],
                type = "group",
                order = 6,
                childGroups = "tree",
                args = {
                    modulesSummaryHeader = {
                        order = 0,
                        type = "header",
                        name = L["MODULES_SUMMARY_HEADER"] or L["MODULES"],
                    },
                    modulesSummaryDescription = {
                        order = 1,
                        type = "description",
                        name = modulesSummaryDescription,
                        fontSize = "medium",
                    },
                    mobPercentages = self:GetMobPercentagesOptions(),
                    groupReminder = self:GetGroupReminderOptions(),
                }
            },
            interface = self:GetInterfaceOptions(),
            advanced = self:GetAdvancedOptions(),

        }
    })
    AceConfig:RegisterOptionsTable(AddOnName .. "_Changelog", self.changelogOptions)
    AceConfig:RegisterOptionsTable(AddOnName .. "_About", self.aboutOptions)

    local profileOptions = self:GetProfileOptions()
    AceConfig:RegisterOptionsTable(AddOnName .. "_Profiles", profileOptions)

    self.optionsCategoryId = select(2, AceConfigDialog:AddToBlizOptions(AddOnName, optionsAddonName))
    self.changelogCategoryId = select(2, AceConfigDialog:AddToBlizOptions(AddOnName .. "_Changelog", L["Changelog"], optionsAddonName))
    self.aboutCategoryId = select(2, AceConfigDialog:AddToBlizOptions(AddOnName .. "_About", L["ABOUT"], optionsAddonName))
    self.profilesCategoryId = select(2, AceConfigDialog:AddToBlizOptions(AddOnName .. "_Profiles", profileOptions.name, optionsAddonName))

    -- Defer so the chat frame is ready (OnInitialize is too early for reliable chat).
    local function printStartupChatMessages()
        if self.PrintLoadMessage then
            self:PrintLoadMessage()
        end
        if self.MaybeAnnounceAddonUpdate then
            self:MaybeAnnounceAddonUpdate()
        end
    end
    if C_Timer and C_Timer.After then
        C_Timer.After(2, printStartupChatMessages)
    else
        printStartupChatMessages()
    end

    -- Register chat command and events
    self:RegisterChatCommand('kpl', 'ToggleConfig')
    self:RegisterChatCommand('polaris', 'ToggleConfig')

    -- Initialize mob percentages module if enabled
    if self.db.profile.mobPercentages and self.db.profile.mobPercentages.enabled then
        self:InitializeMobPercentages()
    end

    -- Initialize group reminder module if enabled
    if self.db.profile.groupReminder and self.db.profile.groupReminder.enabled then
        self:InitializeGroupReminder()
    end
end

-- Open configuration panel when command is used
function KeystonePolaris:ToggleConfig(input)
    local optionsAddonName = (self.GetGradientAddonNameFromSecondLetter and self:GetGradientAddonNameFromSecondLetter()) or "Keystone Polaris"
    local trim = _G.strtrim or function(value)
        return (value:gsub("^%s+", ""):gsub("%s+$", ""))
    end
    local command = trim(input or ""):lower()
    if command == "help" or command == "?" then
        if self.ShowHelp then self:ShowHelp() end
        return
    end
    if command == "changelog" then
        if Settings and Settings.OpenToCategory then
            Settings.OpenToCategory(self.changelogCategoryId or self.optionsCategoryId or optionsAddonName)
        end
        return
    end
    if command == "reminder" then
        self:ShowLastGroupReminder()
        return
    end

    Settings.OpenToCategory(self.optionsCategoryId or optionsAddonName)
end

function KeystonePolaris:ShowHelp()
    local header = L["COMMANDS_HEADER"] or "Commands"
    local prefix = (self.GetChatPrefix and self:GetChatPrefix(false)) or "[Keystone Polaris]"
    local lines = {
        L["COMMANDS_HELP_OPEN"] or "/kpl or /polaris - Open options",
        L["COMMANDS_HELP_CHANGELOG"] or "/kpl changelog or /polaris changelog - Open changelog",
        L["COMMANDS_HELP_REMINDER"] or "/kpl reminder - Show last group reminder",
        L["COMMANDS_HELP_HELP"] or "/kpl help - Show this help",
    }
    local function addMessage(message)
        if DEFAULT_CHAT_FRAME and DEFAULT_CHAT_FRAME.AddMessage then
            DEFAULT_CHAT_FRAME:AddMessage(message)
        else
            print(message)
        end
    end
    addMessage(prefix .. " " .. header)
    for _, line in ipairs(lines) do
        addMessage(self:ColorizeCommands(line))
    end
end

-- Refresh the addon display (called when options change)
function KeystonePolaris:Refresh()
    if self.UpdateColorCache then self:UpdateColorCache() end
    if self.UpdatePercentageText then self:UpdatePercentageText() end
    if self.ApplyTextLayout then self:ApplyTextLayout() end
    if self.AdjustDisplayFrameSize then self:AdjustDisplayFrameSize() end
end

-- Handler for addon compartment button click
_G.KeystonePolaris_OnAddonCompartmentClick = function()
    KeystonePolaris:ToggleConfig()
end

-- Build logical section order for the given dungeon, using advanced bossOrder when available
function KeystonePolaris:GetDungeonSectionOrder(dungeonId, dungeonKey)
    local dungeon = dungeonId and self.DUNGEONS[dungeonId]
    if not dungeon then return nil end

    local numBosses = #dungeon
    if numBosses == 0 then return nil end

    local order = {}
    dungeonKey = dungeonKey or (self.GetDungeonKeyById and self:GetDungeonKeyById(dungeonId)) or nil
    local useAdvancedRoutes = self.db and self.db.profile and self.db.profile.general
        and self.db.profile.general.advancedOptionsEnabled
    if useAdvancedRoutes and dungeonKey and self.db and self.db.profile
        and self.db.profile.advanced and self.db.profile.advanced[dungeonKey] then
        local adv = self.db.profile.advanced[dungeonKey]
        local advOrder = adv.bossOrder
        if type(advOrder) == "table" then
            local valid = true
            for i = 1, numBosses do
                local idx = advOrder[i]
                if type(idx) ~= "number" or idx < 1 or idx > numBosses then
                    valid = false
                    break
                end
                order[i] = math.floor(idx)
            end
            if valid then
                return order
            end
        end
    end

    -- Fallback: order by required percentage ascending.
    for i = 1, numBosses do
        order[i] = i
    end
    table.sort(order, function(a, b)
        local da = dungeon[a]
        local db = dungeon[b]
        local pa = da and da[2] or 0
        local pb = db and db[2] or 0
        if pa == pb then
            return a < b
        end
        return pa < pb
    end)

    return order
end

function KeystonePolaris:BuildSectionOrder(dungeonId)
    self.currentSectionOrder = self:GetDungeonSectionOrder(dungeonId)
end

-- Initialize dungeon tracking when entering a dungeon
function KeystonePolaris:InitiateDungeon()
    local currentDungeonId = C_ChallengeMode.GetActiveChallengeMapID()
    -- Return if not in a dungeon or already tracking this dungeon
    if currentDungeonId == nil or currentDungeonId == self.currentDungeonID then return end

    -- Set current dungeon and reset to first section
    self.currentDungeonID = currentDungeonId
    self.currentSection = 1
    if type(self.currentMilestoneInformState) ~= "table" then
        self.currentMilestoneInformState = {}
    end
    self.currentMilestoneInformState[self.currentDungeonID] = {}
    if type(self.currentMilestoneTriggerState) ~= "table" then
        self.currentMilestoneTriggerState = {}
    end
    self.currentMilestoneTriggerState[self.currentDungeonID] = {}
    if type(self.currentMilestoneCompletionState) ~= "table" then
        self.currentMilestoneCompletionState = {}
    end
    self.currentMilestoneCompletionState[self.currentDungeonID] = {}

    local dungeon = self.DUNGEONS[self.currentDungeonID]
    if dungeon then
        for i = 1, #dungeon do
            if dungeon[i] then
                dungeon[i][4] = false
            end
        end
    end

    self:BuildSectionOrder(self.currentDungeonID)
end

-- Get the current enemy forces percentage from the scenario UI
function KeystonePolaris.GetCurrentPercentage(_)
    -- Mirror WarpDeplete logic: scan criteria and use weighted progress with the
    local stepCount = select(3, C_Scenario.GetStepInfo())
    if not stepCount or stepCount <= 0 then return 0 end

    local bestTotal = 0
    local bestCurrent = 0
    for i = 1, stepCount do
        local info = C_ScenarioInfo.GetCriteriaInfo(i)
        if info and info.isWeightedProgress and info.totalQuantity and info.totalQuantity > 0 then
            local currentCount = type(info.quantityString) == "string"
                and (tonumber(info.quantityString:match("%d+")) or 0)
                or (tonumber(info.quantity) or 0)
            if info.totalQuantity > bestTotal then
                bestTotal = info.totalQuantity
                bestCurrent = currentCount
            end
        end
    end

    if bestTotal > 0 then
        return (bestCurrent / bestTotal) * 100
    end
    return 0
end

-- Retrieve raw Enemy Forces counts: current and total. Returns 0,0 if unavailable.
function KeystonePolaris.GetCurrentForcesInfo(_)
    local stepCount = select(3, C_Scenario.GetStepInfo())
    if not stepCount or stepCount <= 0 then return 0, 0 end

    local bestTotal = 0
    local bestCurrent = 0
    for i = 1, stepCount do
        local info = C_ScenarioInfo.GetCriteriaInfo(i)
        if info and info.isWeightedProgress and info.totalQuantity and info.totalQuantity > 0 then
            local currentCount = type(info.quantityString) == "string"
                and (tonumber(info.quantityString:match("%d+")) or 0)
                or (tonumber(info.quantity) or 0)
            if info.totalQuantity > bestTotal then
                bestTotal = info.totalQuantity
                bestCurrent = currentCount
            end
        end
    end

    return bestCurrent, bestTotal
end

-- Get data for the current section of the dungeon
function KeystonePolaris:GetDungeonData()
    local dungeon = self.DUNGEONS[self.currentDungeonID]
    if not dungeon then
        return nil
    end

    if not self.currentSectionOrder then
        if self.currentDungeonID then
            self:BuildSectionOrder(self.currentDungeonID)
        end
    end

    local order = self.currentSectionOrder
    if not order then
        return nil
    end

    local sectionIndex = order[self.currentSection]
    if not sectionIndex or not dungeon[sectionIndex] then
        return nil
    end

    local dungeonData = dungeon[sectionIndex]
    return {
        kind = "boss",
        bossIndex = sectionIndex,
        bossID = dungeonData[1],
        neededPercent = dungeonData[2] or 0,
        shouldInform = dungeonData[3] ~= false,
        haveInformed = dungeonData[4] == true,
    }
end

local function NormalizeMilestoneText(value)
    if type(value) ~= "string" then
        return ""
    end
    local trim = value:match("^%s*(.-)%s*$")
    return trim:lower()
end

local function TrimString(value)
    if type(value) ~= "string" then
        return ""
    end
    return value:match("^%s*(.-)%s*$") or ""
end

local function getPlayerUiMapID()
    if C_Map and C_Map.GetBestMapForUnit then
        return C_Map.GetBestMapForUnit("player")
    end
end

local function mapMatchesMilestoneTrigger(currentMapID, targetMapID, triggerType)
    currentMapID = tonumber(currentMapID)
    targetMapID = tonumber(targetMapID)
    if not currentMapID or not targetMapID then
        return false
    end

    if triggerType == "subzone" then
        return currentMapID == targetMapID
    end

    local mapID = currentMapID
    while mapID do
        if mapID == targetMapID then
            return true
        end
        local info = C_Map and C_Map.GetMapInfo and C_Map.GetMapInfo(mapID)
        mapID = info and info.parentMapID
    end

    return false
end

function KeystonePolaris.GetLocalizedMapName(uiMapID)
    uiMapID = tonumber(uiMapID)
    if not uiMapID or not C_Map or not C_Map.GetMapInfo then
        return nil
    end
    if C_Map.RequestPreloadMap then
        C_Map.RequestPreloadMap(uiMapID)
    end
    local info = C_Map.GetMapInfo(uiMapID)
    return info and info.name
end

function KeystonePolaris.GetLocalizedAreaName(areaID)
    areaID = tonumber(areaID)
    if not areaID or not C_Map or not C_Map.GetAreaInfo then
        return nil
    end
    return C_Map.GetAreaInfo(areaID)
end

local function areaMatchesMilestoneTrigger(targetAreaID, triggerType)
    targetAreaID = tonumber(targetAreaID)
    if not targetAreaID then
        return false
    end

    local targetName = KeystonePolaris.GetLocalizedAreaName(targetAreaID)
    if not targetName or targetName == "" then
        return false
    end

    local currentText
    if triggerType == "zone" then
        currentText = GetZoneText()
    else
        currentText = GetSubZoneText()
    end

    return NormalizeMilestoneText(currentText) == NormalizeMilestoneText(targetName)
end

function KeystonePolaris.GetMilestoneTriggerDisplayText(milestone)
    if type(milestone) ~= "table" then
        return ""
    end
    local matchAreaID = tonumber(milestone.matchAreaID)
    if matchAreaID then
        local name = KeystonePolaris.GetLocalizedAreaName(matchAreaID)
        if name and name ~= "" then
            return name
        end
    end
    local matchMapID = tonumber(milestone.matchMapID)
    if matchMapID then
        local name = KeystonePolaris.GetLocalizedMapName(matchMapID)
        if name and name ~= "" then
            return name
        end
    end
    return tostring(milestone.matchText or "")
end

-- No direct C_Map.GetBestAreaForUnit; use exploration area IDs at player position.
local function resolveAreaIDAtPlayer(subzoneText)
    local target = NormalizeMilestoneText(subzoneText)
    if target == "" then
        return nil
    end
    if not C_Map or not C_Map.GetBestMapForUnit or not C_Map.GetPlayerMapPosition then
        return nil
    end
    if not C_MapExplorationInfo or not C_MapExplorationInfo.GetExploredAreaIDsAtPosition then
        return nil
    end

    local mapID = C_Map.GetBestMapForUnit("player")
    if not mapID then
        return nil
    end

    local pos = C_Map.GetPlayerMapPosition(mapID, "player")
    if not pos then
        return nil
    end

    local areaIDs = C_MapExplorationInfo.GetExploredAreaIDsAtPosition(mapID, pos)
    if type(areaIDs) ~= "table" then
        return nil
    end

    for _, areaID in ipairs(areaIDs) do
        local name = KeystonePolaris.GetLocalizedAreaName(areaID)
        if name and NormalizeMilestoneText(name) == target then
            return tonumber(areaID)
        end
    end

    return nil
end

local function resolveUiMapIDForZone(zoneText)
    local target = NormalizeMilestoneText(zoneText)
    if target == "" then
        return nil
    end
    if not C_Map or not C_Map.GetBestMapForUnit or not C_Map.GetMapInfo then
        return nil
    end

    local mapID = C_Map.GetBestMapForUnit("player")
    while mapID do
        local name = KeystonePolaris.GetLocalizedMapName(mapID)
        if name and NormalizeMilestoneText(name) == target then
            return mapID
        end
        local info = C_Map.GetMapInfo(mapID)
        mapID = info and info.parentMapID
    end

    return nil
end

function KeystonePolaris:CaptureMilestoneTrigger(milestone, triggerType)
    if type(milestone) ~= "table" then
        return false
    end

    triggerType = tostring(triggerType or "none"):lower()
    milestone.matchAreaID = nil
    milestone.matchMapID = nil
    milestone.matchText = ""

    local captured = false
    if triggerType == "subzone" then
        local subzoneText = GetSubZoneText()
        local areaID = resolveAreaIDAtPlayer(subzoneText)
        if areaID then
            milestone.matchAreaID = areaID
            captured = true
        else
            milestone.matchText = tostring(subzoneText or "")
        end
    elseif triggerType == "zone" then
        local zoneText = GetZoneText()
        local uiMapID = resolveUiMapIDForZone(zoneText)
        if uiMapID then
            milestone.matchMapID = uiMapID
            captured = true
        else
            milestone.matchText = tostring(zoneText or "")
        end
    end

    if not captured then
        local prefix = (self.GetChatPrefix and self:GetChatPrefix()) or "Keystone Polaris"
        local warnText = L and L["MILESTONE_CAPTURE_FALLBACK_WARN"]
        if warnText and warnText ~= "" then
            print(prefix .. ": " .. warnText)
        end
    end

    return captured
end

function KeystonePolaris.IsSectionTriggerMet(_, section)
    if type(section) ~= "table" then
        return false
    end

    if section.kind == "boss" then
        local info = section.bossID and C_ScenarioInfo.GetCriteriaInfo(section.bossID) or nil
        return info and info.completed or false
    end

    local triggerType = tostring(section.triggerType or "none"):lower()
    if triggerType == "none" then
        return true
    end

    local isMatched = KeystonePolaris:IsMilestoneTriggerMatchedNow(section)

    if isMatched and section.kind == "milestone" and KeystonePolaris.MarkMilestoneTriggered then
        KeystonePolaris:MarkMilestoneTriggered(section)
    end

    if section.kind == "milestone" and KeystonePolaris.HasMilestoneTriggered then
        return KeystonePolaris:HasMilestoneTriggered(section)
    end

    return isMatched
end

function KeystonePolaris.IsMilestoneTriggerMatchedNow(_, section)
    if type(section) ~= "table" then
        return false
    end

    local triggerType = tostring(section.triggerType or "none"):lower()
    if triggerType == "none" then
        return true
    end

    local matchAreaID = tonumber(section.matchAreaID)
    if matchAreaID then
        return areaMatchesMilestoneTrigger(matchAreaID, triggerType)
    end

    local matchMapID = tonumber(section.matchMapID)
    if matchMapID then
        if mapMatchesMilestoneTrigger(getPlayerUiMapID(), matchMapID, triggerType) then
            return true
        end
        local targetName = KeystonePolaris.GetLocalizedMapName(matchMapID)
        if targetName and targetName ~= "" then
            local currentText
            if triggerType == "zone" then
                currentText = GetZoneText()
            else
                currentText = GetSubZoneText()
            end
            return NormalizeMilestoneText(currentText) == NormalizeMilestoneText(targetName)
        end
        return false
    end

    local target = NormalizeMilestoneText(section.matchText)
    if target == "" then
        return false
    end

    local currentText
    if triggerType == "zone" then
        currentText = GetZoneText()
    else
        currentText = GetSubZoneText()
    end

    return NormalizeMilestoneText(currentText) == target
end

function KeystonePolaris:MarkSectionInformed(section)
    if type(section) ~= "table" then return end
    if section.kind == "boss" then
        local dungeon = self.DUNGEONS[self.currentDungeonID]
        local idx = section.bossIndex
        if dungeon and idx and dungeon[idx] then
            dungeon[idx][4] = true
        end
        section.haveInformed = true
        return
    end

    if section.kind == "milestone" then
        if type(self.currentMilestoneInformState) ~= "table" then
            self.currentMilestoneInformState = {}
        end
        local dungeonState = self.currentMilestoneInformState[self.currentDungeonID]
        if type(dungeonState) ~= "table" then
            dungeonState = {}
            self.currentMilestoneInformState[self.currentDungeonID] = dungeonState
        end
        local runtimeKey = tostring(section.runtimeKey or section.milestoneIndex or "")
        if runtimeKey ~= "" then
            dungeonState[runtimeKey] = true
        end
        section.haveInformed = true
    end
end

function KeystonePolaris:MarkMilestoneTriggered(section)
    if type(section) ~= "table" or section.kind ~= "milestone" then return end

    if type(self.currentMilestoneTriggerState) ~= "table" then
        self.currentMilestoneTriggerState = {}
    end
    local dungeonState = self.currentMilestoneTriggerState[self.currentDungeonID]
    if type(dungeonState) ~= "table" then
        dungeonState = {}
        self.currentMilestoneTriggerState[self.currentDungeonID] = dungeonState
    end

    local runtimeKey = tostring(section.runtimeKey or section.milestoneIndex or "")
    if runtimeKey ~= "" then
        dungeonState[runtimeKey] = true
    end
end

function KeystonePolaris:HasMilestoneTriggered(section)
    if type(section) ~= "table" or section.kind ~= "milestone" then return false end
    if type(self.currentMilestoneTriggerState) ~= "table" then return false end

    local dungeonState = self.currentMilestoneTriggerState[self.currentDungeonID]
    if type(dungeonState) ~= "table" then return false end

    local runtimeKey = tostring(section.runtimeKey or section.milestoneIndex or "")
    return runtimeKey ~= "" and dungeonState[runtimeKey] == true or false
end

function KeystonePolaris:MarkMilestoneCompletionShown(section)
    if type(section) ~= "table" or section.kind ~= "milestone" then return end

    if type(self.currentMilestoneCompletionState) ~= "table" then
        self.currentMilestoneCompletionState = {}
    end
    local dungeonState = self.currentMilestoneCompletionState[self.currentDungeonID]
    if type(dungeonState) ~= "table" then
        dungeonState = {}
        self.currentMilestoneCompletionState[self.currentDungeonID] = dungeonState
    end

    local runtimeKey = tostring(section.runtimeKey or section.milestoneIndex or "")
    if runtimeKey ~= "" then
        dungeonState[runtimeKey] = true
    end
end

function KeystonePolaris:HasMilestoneCompletionShown(section)
    if type(section) ~= "table" or section.kind ~= "milestone" then return false end
    if type(self.currentMilestoneCompletionState) ~= "table" then return false end

    local dungeonState = self.currentMilestoneCompletionState[self.currentDungeonID]
    if type(dungeonState) ~= "table" then return false end

    local runtimeKey = tostring(section.runtimeKey or section.milestoneIndex or "")
    return runtimeKey ~= "" and dungeonState[runtimeKey] == true or false
end

function KeystonePolaris:ResetMilestoneRuntimeState(dungeonId)
    if not dungeonId then return end

    if type(self.currentMilestoneTriggerState) ~= "table" then
        self.currentMilestoneTriggerState = {}
    end
    self.currentMilestoneTriggerState[dungeonId] = {}

    if type(self.currentMilestoneCompletionState) ~= "table" then
        self.currentMilestoneCompletionState = {}
    end
    self.currentMilestoneCompletionState[dungeonId] = {}

    if type(self.currentMilestoneInformState) ~= "table" then
        self.currentMilestoneInformState = {}
    end
    self.currentMilestoneInformState[dungeonId] = {}

    if self.currentDungeonID == dungeonId then
        self._milestoneDoneTextUntil = nil
    end
end

function KeystonePolaris:GetSortedMilestones(dungeonId)
    local dungeonKey = self.GetDungeonKeyById and self:GetDungeonKeyById(dungeonId) or nil
    local advancedData = dungeonKey and self.db and self.db.profile and self.db.profile.advanced and self.db.profile.advanced[dungeonKey] or nil
    if type(advancedData) ~= "table" or type(advancedData.milestones) ~= "table" then
        return {}
    end

    if type(self.currentMilestoneInformState) ~= "table" then
        self.currentMilestoneInformState = {}
    end
    local dungeonState = self.currentMilestoneInformState[dungeonId]
    if type(dungeonState) ~= "table" then
        dungeonState = {}
        self.currentMilestoneInformState[dungeonId] = dungeonState
    end

    local milestones = {}
    for milestoneIndex, milestone in ipairs(advancedData.milestones) do
        if type(milestone) == "table" then
            local triggerType = tostring(milestone.triggerType or "none"):lower()
            if triggerType ~= "none" and triggerType ~= "zone" and triggerType ~= "subzone" then
                triggerType = "none"
            end
            local runtimeKey = tostring(milestone.id or milestoneIndex)
            milestones[#milestones + 1] = {
                kind = "milestone",
                milestoneIndex = milestoneIndex,
                runtimeKey = runtimeKey,
                label = tostring(milestone.label or ""),
                neededPercent = tonumber(milestone.thresholdPercent) or 0,
                shouldInform = triggerType ~= "none" and milestone.inform == true,
                haveInformed = dungeonState[runtimeKey] == true,
                triggerType = triggerType,
                matchAreaID = tonumber(milestone.matchAreaID),
                matchMapID = tonumber(milestone.matchMapID),
                matchText = tostring(milestone.matchText or ""),
                informSuffix = tostring(milestone.informSuffix or ""),
                creationOrder = tonumber(milestone.creationOrder) or milestoneIndex,
            }
        end
    end

    table.sort(milestones, function(left, right)
        local leftPct = tonumber(left.neededPercent) or 0
        local rightPct = tonumber(right.neededPercent) or 0
        if leftPct ~= rightPct then
            return leftPct < rightPct
        end
        local leftCreation = tonumber(left.creationOrder) or 0
        local rightCreation = tonumber(right.creationOrder) or 0
        if leftCreation ~= rightCreation then
            return leftCreation < rightCreation
        end
        return (tonumber(left.milestoneIndex) or 0) < (tonumber(right.milestoneIndex) or 0)
    end)

    return milestones
end

function KeystonePolaris:GetActiveMilestone(dungeonId, currentPercentage, maxThresholdPercent)
    local milestones = self:GetSortedMilestones(dungeonId)
    for _, milestone in ipairs(milestones) do
        local neededPercent = tonumber(milestone.neededPercent) or 0
        if not (maxThresholdPercent and neededPercent > (tonumber(maxThresholdPercent) or 0)) then
            local remainingPercent = neededPercent - (tonumber(currentPercentage) or 0)
            if remainingPercent < 0.05 and remainingPercent > 0 then
                remainingPercent = 0
            end
            local triggerMet
            local triggerMatchedNow
            if milestone.triggerType == "none" then
                triggerMet = remainingPercent <= 0
                triggerMatchedNow = triggerMet
            else
                triggerMatchedNow = self:IsMilestoneTriggerMatchedNow(milestone)
                if triggerMatchedNow and self.MarkMilestoneTriggered then
                    self:MarkMilestoneTriggered(milestone)
                end
                triggerMet = self:HasMilestoneTriggered(milestone)
            end

            if not (remainingPercent <= 0 and triggerMet) then
                milestone.remainingPercent = math.max(0, remainingPercent)
                milestone.triggerMet = triggerMet
                milestone.triggerMatchedNow = triggerMatchedNow
                return milestone
            end
        end
    end
    return nil
end

function KeystonePolaris:GetJustCompletedMilestone(dungeonId, currentPercentage, maxThresholdPercent)
    local milestones = self:GetSortedMilestones(dungeonId)
    for _, milestone in ipairs(milestones) do
        local neededPercent = tonumber(milestone.neededPercent) or 0
        if not (maxThresholdPercent and neededPercent > (tonumber(maxThresholdPercent) or 0)) then
            local remainingPercent = neededPercent - (tonumber(currentPercentage) or 0)
            if remainingPercent < 0.05 and remainingPercent > 0 then
                remainingPercent = 0
            end
            local triggerMet
            local triggerMatchedNow
            if milestone.triggerType == "none" then
                triggerMet = remainingPercent <= 0
                triggerMatchedNow = triggerMet
            else
                triggerMatchedNow = self:IsMilestoneTriggerMatchedNow(milestone)
                if triggerMatchedNow and self.MarkMilestoneTriggered then
                    self:MarkMilestoneTriggered(milestone)
                end
                triggerMet = self:HasMilestoneTriggered(milestone)
            end

            if remainingPercent <= 0 and triggerMet then
                if not self:HasMilestoneCompletionShown(milestone) then
                    self:MarkMilestoneCompletionShown(milestone)
                    milestone.remainingPercent = 0
                    milestone.triggerMet = triggerMet
                    milestone.triggerMatchedNow = triggerMatchedNow
                    return milestone
                end
            end
        end
    end

    return nil
end

function KeystonePolaris:BuildInformMessage(percentage, suffixOverride)
    local percentageStr = string.format("%.2f%%", tonumber(percentage) or 0)
    local prefix = (self.GetChatPrefix and self:GetChatPrefix(true, true)) or "[Keystone Polaris]"
    local baseMessage = prefix .. ": " .. L["WE_STILL_NEED"] .. " " .. percentageStr

    local suffix = suffixOverride
    suffix = TrimString(suffix)
    if suffix ~= "" then
        baseMessage = baseMessage .. " " .. suffix
    end

    return baseMessage
end

function KeystonePolaris:GetProfileOptions()
    local profileOptions = LibStub("AceDBOptions-3.0"):GetOptionsTable(self.db)
    local args = CopyTable(profileOptions.args)

    args.shareHeader = {
        order = 85,
        type = "header",
        name = L["PROFILE_SHARE_HEADER"],
    }
    args.shareDesc = {
        order = 86,
        type = "description",
        name = L["PROFILE_SHARE_DESC"],
        fontSize = "medium",
    }
    args.exportProfileFull = {
        order = 87,
        type = "execute",
        name = L["EXPORT_PROFILE_FULL"],
        desc = L["EXPORT_PROFILE_FULL_DESC"],
        func = function()
            self:ExportProfileSettings("full")
        end,
    }
    args.exportProfileSettings = {
        order = 88,
        type = "execute",
        name = L["EXPORT_PROFILE_SETTINGS"],
        desc = L["EXPORT_PROFILE_SETTINGS_DESC"],
        func = function()
            self:ExportProfileSettings("settings")
        end,
    }
    args.importProfile = {
        order = 89,
        type = "execute",
        name = L["IMPORT_PROFILE"],
        desc = L["IMPORT_PROFILE_DESC"],
        func = function()
            self:ShowProfileImportDialog()
        end,
    }

    profileOptions.args = args
    return profileOptions
end

function KeystonePolaris:RefreshForActiveProfile()
    if self.UpdateDungeonData then self:UpdateDungeonData() end
    if self.currentDungeonID and self.BuildSectionOrder then
        self:BuildSectionOrder(self.currentDungeonID)
    end
    LibStub("AceConfigRegistry-3.0"):NotifyChange(AddOnName)
    LibStub("AceConfigRegistry-3.0"):NotifyChange(AddOnName .. "_Profiles")
    if self.UpdatePercentageText then self:UpdatePercentageText() end
    if self.RefreshProgressBar then self:RefreshProgressBar() end
    if self.UpdateMinimapIconVisibility then self:UpdateMinimapIconVisibility() end
    if self.UpdateCompartmentIconVisibility then self:UpdateCompartmentIconVisibility() end

    if self.db.profile.mobPercentages and self.db.profile.mobPercentages.enabled then
        if self.InitializeMobPercentages then self:InitializeMobPercentages() end
    end
    if self.db.profile.groupReminder and self.db.profile.groupReminder.enabled then
        if self.InitializeGroupReminder then self:InitializeGroupReminder() end
    end
end

-- Called when the addon is enabled
function KeystonePolaris:OnEnable()
    -- Ensure display exists and is visible
    if self.CreateDisplayFrame then
        self:CreateDisplayFrame()
    end

    -- Mythic+ mode triggers
    self:RegisterEvent("CHALLENGE_MODE_START")
    self:RegisterEvent("CHALLENGE_MODE_COMPLETED")

	-- Scenario triggers
	self:RegisterEvent("SCENARIO_POI_UPDATE")
	self:RegisterEvent("SCENARIO_CRITERIA_UPDATE")

    self:RegisterEvent("PLAYER_ENTERING_WORLD")
    self:RegisterEvent("ZONE_CHANGED")
    self:RegisterEvent("ZONE_CHANGED_INDOORS")
    self:RegisterEvent("ZONE_CHANGED_NEW_AREA")
    self:RegisterEvent("PLAYER_MAP_CHANGED")

    -- Extra refresh triggers for dynamic current pull percent
    if self.InitializePullTracker then
        self:InitializePullTracker()
    end

    -- Force an initial update
    if self.UpdatePercentageText then
        self:UpdatePercentageText()
    end
    if self.UpdateProgressBar then
        self:UpdateProgressBar()
    end
end

-- Event handler for POI updates (boss positions)
function KeystonePolaris:SCENARIO_POI_UPDATE()
    if self._QueuePullUpdate then self:_QueuePullUpdate() end
end

-- Event handler for criteria updates (enemy forces percentage changes)
-- This event fires once per mob killed, so debouncing is critical to avoid
-- hanging the game when a large pack dies all at once.
function KeystonePolaris:SCENARIO_CRITERIA_UPDATE()
    if self._QueuePullUpdate then self:_QueuePullUpdate() end
    if self.UpdateProgressBar then self:UpdateProgressBar() end
end

-- Event handler for starting a Mythic+ dungeon
function KeystonePolaris:CHALLENGE_MODE_START()
    if self._positioningMode and self.ExitPositioningMode then self:ExitPositioningMode(true) end
    if self._testMode and self.DisableTestMode then self:DisableTestMode("started dungeon") end
    self.currentDungeonID = nil

    self:InitiateDungeon()
    if self.HideInformButton then self:HideInformButton() end
    if self.PrepareInformMacro then
        C_Timer.After(5, function()
            if self.PrepareInformMacro then
                self:PrepareInformMacro(nil) -- init macro without fake percent text
            end
        end)
    end
    if self.UpdatePercentageText then self:UpdatePercentageText() end
    if self.UpdateProgressBar then self:UpdateProgressBar() end
end

function KeystonePolaris:CHALLENGE_MODE_COMPLETED()
    self.currentDungeonID = nil
    if self.HideInformButton then self:HideInformButton() end
    if self.progressBarFrame then
        self.progressBarFrame:Hide()
        self._progressBarDungeonKey = nil
    end
end

-- Event handler for entering the world or changing zones
function KeystonePolaris:PLAYER_ENTERING_WORLD()
    if self._testMode and self.DisableTestMode then self:DisableTestMode("changed zone") end
    self:InitiateDungeon()
    if self.HideInformButton then self:HideInformButton() end
    if self.PrepareInformMacro then
        -- Utilise le message par défaut (WE_STILL_NEED + % fictif)
        C_Timer.After(10, function()
            if self.PrepareInformMacro then
                self:PrepareInformMacro(nil)
            end
        end)
    end
end

function KeystonePolaris:ZONE_CHANGED()
    if self.UpdatePercentageText then self:UpdatePercentageText() end
end

function KeystonePolaris:ZONE_CHANGED_INDOORS()
    if self.UpdatePercentageText then self:UpdatePercentageText() end
end

function KeystonePolaris:ZONE_CHANGED_NEW_AREA()
    if self.UpdatePercentageText then self:UpdatePercentageText() end
end

function KeystonePolaris:PLAYER_MAP_CHANGED()
    if self.UpdatePercentageText then self:UpdatePercentageText() end
end

-- Update dungeon data with advanced options if enabled
function KeystonePolaris:UpdateDungeonData()
    if self.db.profile.general.advancedOptionsEnabled then
        for dungeonId, dungeonData in pairs(self.DUNGEONS) do
            local dungeonKey = self:GetDungeonKeyById(dungeonId)
            if dungeonKey then
                local advancedData = self.db.profile.advanced[dungeonKey]
                local defaultBosses = self.GlobalDungeonLookup
                    and self.GlobalDungeonLookup[dungeonKey]
                    and self.GlobalDungeonLookup[dungeonKey].bosses
                for i, bossData in ipairs(dungeonData) do
                    local bossNumStr = self:GetBossNumberString(i)

                    local pct = advancedData and advancedData["Boss" .. bossNumStr] or nil
                    local inform = advancedData and advancedData["Boss" .. bossNumStr .. "Inform"] or nil

                    if pct == nil and defaultBosses and defaultBosses[i] then
                        pct = defaultBosses[i][2]
                    end
                    if inform == nil and defaultBosses and defaultBosses[i] then
                        inform = defaultBosses[i][3]
                    end

                    if pct ~= nil then
                        bossData[2] = pct
                    end
                    if inform ~= nil then
                        bossData[3] = inform
                    end
                    bossData[4] = false -- Reset informed status
                end
            end
        end
    end
end