Core.lua

local addonName, Addon = ...

_G.NSRTCountdownCompanion = Addon

local abs = math.abs
local floor = math.floor
local max = math.max
local min = math.min
local pairs = pairs
local tonumber = tonumber
local tostring = tostring
local type = type



local function CanonicalNumber(value, fallback)
    local number = tonumber(value)
    if number == nil then number = tonumber(fallback) or 0 end
    local text = ("%.3f"):format(number):gsub("0+$", ""):gsub("%.$", "")
    return text ~= "" and text or "0"
end

local function TrimText(value)
    value = tostring(value or "")
    if strtrim then return strtrim(value) end
    return value:match("^%s*(.-)%s*$") or value
end

local defaults = {
    schemaVersion = 13,
    soundChannel = "Master",
    theme = "arcane",
    useDefaultWhenNSRTCountdownMissing = false,
    defaultCountdown = 5,
    assignments = {},
    abilityRenames = {},
    encounterAssignments = {},
    noteAssignments = {},
    knownSpells = {},
    manualSpells = {},
}

Addon.activeCountdowns = {}
Addon.initialized = false
Addon.debugEnabled = false
Addon.loadedNoteCache = { personal = "", shared = "" }

local function ApplyDefaults(target, source)
    for key, value in pairs(source) do
        if type(value) == "table" then
            if type(target[key]) ~= "table" then
                target[key] = {}
            end
            ApplyDefaults(target[key], value)
        elseif target[key] == nil then
            target[key] = value
        end
    end
end

function Addon:Print(message)
    DEFAULT_CHAT_FRAME:AddMessage("|cFF00FFFFNSRT CC:|r " .. tostring(message))
end

function Addon:Debug(message)
    if self.debugEnabled == true then
        self:Print("|cFFAAAAAA[debug]|r " .. tostring(message))
    end
end

function Addon:GetCurrentSpecID()
    local specIndex = GetSpecialization and GetSpecialization()
    if not specIndex then return nil end
    return select(1, GetSpecializationInfo(specIndex))
end

function Addon:GetCurrentClass()
    return select(2, UnitClass("player"))
end

function Addon:GetSpellData(spellID)
    spellID = tonumber(spellID)
    if not spellID then return nil end

    local info = C_Spell and C_Spell.GetSpellInfo and C_Spell.GetSpellInfo(spellID)
    if info then
        return {
            id = spellID,
            name = info.name or ("Spell " .. spellID),
            icon = info.iconID or 134400,
        }
    end

    local name, _, icon = GetSpellInfo and GetSpellInfo(spellID)
    if name then
        return { id = spellID, name = name, icon = icon or 134400 }
    end
end

-- NSRT normally resolves a missing countdown tag from its Spell/Text Countdown
-- settings while processing a reminder. Some callback and test paths expose the
-- reminder before that resolved value is copied onto info, so mirror NSRT's
-- inheritance rule here instead of incorrectly treating the countdown as absent.
function Addon:GetReminderCountdown(info)
    if type(info) ~= "table" then return nil, "invalid reminder" end

    -- false or zero means the countdown is deliberately disabled. Only nil means
    -- the note omitted the tag and should inherit NSRT's current setting.
    if info.countdown ~= nil then
        local explicit = tonumber(info.countdown)
        explicit = explicit and floor(explicit + 0.5)
        if explicit and explicit > 0 then
            return explicit, "reminder countdown"
        end
        return nil, "countdown disabled"
    end

    local settings = _G.NSRT and _G.NSRT.ReminderSettings
    local settingName = info.spellID and "SpellCountdown" or "TextCountdown"
    local inherited = settings and tonumber(settings[settingName])
    inherited = inherited and floor(inherited + 0.5)
    if inherited and inherited > 0 then
        return inherited, "NSRT " .. settingName
    end

    return nil, "NSRT " .. settingName .. " disabled"
end


function Addon:GetPlayerTagContext()
    local specID = self:GetCurrentSpecID()
    local playerName = UnitName and UnitName("player") or ""
    local nickname = playerName
    if _G.NSAPI and type(_G.NSAPI.GetName) == "function" then
        local ok, value = pcall(_G.NSAPI.GetName, _G.NSAPI, "player", "GlobalNickNames")
        if ok and value and value ~= "" then nickname = value end
    end

    local role = UnitGroupRolesAssigned and UnitGroupRolesAssigned("player") or "NONE"
    local classID = select(3, UnitClass("player"))
    local subgroup = 1
    if _G.NSRT and type(_G.NSRT.GetSubGroup) == "function" then
        local ok, value = pcall(_G.NSRT.GetSubGroup, _G.NSRT, "player")
        if ok and tonumber(value) then subgroup = tonumber(value) end
    end

    local melee = false
    if _G.NSRT and type(_G.NSRT.meleetable) == "table" and specID then
        melee = _G.NSRT.meleetable[specID] and true or false
    elseif self.MELEE_SPECS and specID then
        melee = self.MELEE_SPECS[specID] and true or false
    end
    if tostring(role):lower() == "tank" then melee = true end

    return {
        name = tostring(playerName or ""):lower(),
        nickname = tostring(nickname or ""):lower(),
        role = tostring(role or ""):lower(),
        classID = classID and tostring(classID) or nil,
        specID = specID and tostring(specID) or nil,
        subgroup = "group" .. tostring(subgroup or 1),
        position = melee and "melee" or "ranged",
    }
end

-- Mirrors NSRT's own TagMatchesPlayer function so the Current Note page shows
-- exactly the reminders NSRT considers personal to this character.
function Addon:TagMatchesPlayer(tagText)
    if type(tagText) ~= "string" or tagText == "" then return false end
    local context = self:GetPlayerTagContext()
    local lowered = tagText:lower()
    local tags = {}
    for token in lowered:gmatch("(%S+)") do
        tags[TrimText(token)] = true
    end

    local ignoreEveryone = _G.NSRT and _G.NSRT.ReminderSettings
        and _G.NSRT.ReminderSettings.IgnoreEveryone
    return (lowered == "everyone" and not ignoreEveryone)
        or (context.name ~= "" and tags[context.name])
        or (context.nickname ~= "" and tags[context.nickname])
        or (context.role ~= "" and tags[context.role])
        or (context.specID and tags[context.specID])
        or (context.classID and tags[context.classID])
        or (context.subgroup and tags[context.subgroup])
        or (context.position and tags[context.position])
        or false
end

function Addon:GetNSRTProfileKey()
    local characterName, realm = UnitFullName and UnitFullName("player")
    if not realm and GetNormalizedRealmName then realm = GetNormalizedRealmName() end
    if characterName and realm then return characterName .. "-" .. realm end
end

local function AddUniqueNoteSource(result, seen, key, name, value)
    if type(value) ~= "string" then return end
    local text = TrimText(value)
    if text == "" or seen[text] then return end
    seen[text] = true
    result[#result + 1] = { key = key, name = name, text = text }
end

-- NSRT keeps the active runtime strings on its private namespace, while the
-- public NSRT table contains the persistent copies and selected note names.
-- The reminder-changed callback supplies the private strings when they change;
-- the saved variables and MRT note are used to populate the page on login.
function Addon:GetLoadedNoteSources()
    local result, seen = {}, {}
    local nsrt = _G.NSRT

    local cache = self.loadedNoteCache or {}
    AddUniqueNoteSource(result, seen, "shared-callback", "NSRT shared note", cache.shared)
    AddUniqueNoteSource(result, seen, "personal-callback", "NSRT personal note", cache.personal)

    if nsrt then
        local activeSharedName = type(nsrt.ActiveReminder) == "string" and nsrt.ActiveReminder or nil
        local activeShared = activeSharedName and type(nsrt.Reminders) == "table" and nsrt.Reminders[activeSharedName] or nil
        AddUniqueNoteSource(result, seen, "shared-active", activeSharedName and ("Shared note: " .. activeSharedName) or "NSRT shared note", activeShared)
        AddUniqueNoteSource(result, seen, "shared-stored", "NSRT shared note", nsrt.StoredSharedReminder)

        local profileKey = self:GetNSRTProfileKey()
        local personalName = profileKey and type(nsrt.StoredPersonalReminder) == "table" and nsrt.StoredPersonalReminder[profileKey] or nil
        local personalText = personalName and type(nsrt.PersonalReminders) == "table" and nsrt.PersonalReminders[personalName] or nil
        AddUniqueNoteSource(result, seen, "personal-active", personalName and ("Personal note: " .. personalName) or "NSRT personal note", personalText)

        -- Compatibility fallbacks for older or modified NSRT builds that expose
        -- the active strings directly on the saved-variable table.
        AddUniqueNoteSource(result, seen, "shared-runtime", "NSRT shared note", nsrt.Reminder)
        AddUniqueNoteSource(result, seen, "personal-runtime", "NSRT personal note", nsrt.PersonalReminder)

        local settings = nsrt.ReminderSettings or {}
        local timelineUsesMRT = _G.LiquidRemindersSaved
            and _G.LiquidRemindersSaved.settings
            and _G.LiquidRemindersSaved.settings.timeline
            and _G.LiquidRemindersSaved.settings.timeline.mrtNote
        if settings.MRTNote or timelineUsesMRT then
            local mrtNote = _G.VMRT and _G.VMRT.Note
            AddUniqueNoteSource(result, seen, "mrt-shared", "MRT shared note", mrtNote and mrtNote.Text1)
            AddUniqueNoteSource(result, seen, "mrt-personal", "MRT personal note", mrtNote and mrtNote.SelfText)
        end
    end

    return result
end

local NOTE_SYMBOLS = { star=1, circle=2, diamond=3, triangle=4, moon=5, square=6, cross=7, skull=8 }

function Addon:NormalizeNoteReminderText(value)
    local text = TrimText(value)
    if text == "" then return "" end
    text = text:gsub("||c(%x%x%x%x%x%x%x%x)", "|c%1")
        :gsub("||r", "|r")
        :gsub("||T", "|T")
        :gsub("||t", "|t")
    text = text:gsub("{(%a*%d*)}", function(token)
        local id = NOTE_SYMBOLS[token] or (token:match("^rt(%d)$") and tonumber(token:match("^rt(%d)$")))
        if id then return "|TInterface\\TargetingFrame\\UI-RaidTargetingIcon_" .. id .. ":0|t" end
    end)
    return text
end

function Addon:BuildNoteReminderKey(encID, phase, timeValue, spellID, text)
    encID = tonumber(encID)
    if not encID then return nil end
    local normalizedText = self:NormalizeNoteReminderText(text)
    local numericSpellID = tonumber(spellID)
    local identity
    if normalizedText ~= "" then
        identity = "text:" .. normalizedText
        if numericSpellID then identity = identity .. "|spell:" .. tostring(numericSpellID) end
    elseif numericSpellID then
        identity = "spell:" .. tostring(numericSpellID)
    else
        return nil
    end
    return table.concat({
        tostring(encID),
        CanonicalNumber(phase, 1),
        CanonicalNumber(timeValue, 0),
        identity,
    }, "|")
end

function Addon:GetNoteLineCountdown(spellID, explicitCountdown, timeValue)
    local countdown
    local source
    if explicitCountdown ~= nil then
        countdown = tonumber(explicitCountdown)
        source = "note"
    else
        local settings = _G.NSRT and _G.NSRT.ReminderSettings
        local settingName = tonumber(spellID) and "SpellCountdown" or "TextCountdown"
        countdown = settings and tonumber(settings[settingName])
        source = "NSRT " .. settingName
    end
    countdown = countdown and floor(countdown + 0.5)
    if not countdown or countdown < 1 then return nil, source .. " disabled" end
    local reminderTime = tonumber(timeValue)
    if reminderTime and countdown > reminderTime then countdown = floor(reminderTime + 0.5) end
    if countdown < 1 then return nil, source .. " disabled" end
    return countdown, source
end

function Addon:GetCurrentNoteReminders()
    local result = {}
    local seen = {}
    for _, source in ipairs(self:GetLoadedNoteSources()) do
        local encID
        local encounterLabel
        local lineNumber = 0
        local text = source.text
        if text:sub(-1) ~= "\n" then text = text .. "\n" end
        for line in text:gmatch("([^\n]*)\n") do
            lineNumber = lineNumber + 1
            local headerID = line:match("EncounterID:(%d+)")
            if headerID then
                local nextEncID = tonumber(headerID)
                local nextLabel = TrimText(line:match("Name:([^;]+)"))
                if nextLabel ~= "" then
                    encounterLabel = nextLabel
                elseif nextEncID ~= encID or not encounterLabel or encounterLabel == "" then
                    encounterLabel = self:GetEncounterName(nextEncID)
                end
                encID = nextEncID
            else
                local timeValue = line:match("time:(%d*%.?%d+)")
                local tag = line:match("tag:([^;]+)")
                local spellID = tonumber(line:match("spellid:(%d+)"))
                local reminderText = line:match("text:([^;]+)")
                if encID and timeValue and tag and (spellID or reminderText) and self:TagMatchesPlayer(tag) then
                    local phase = tonumber(line:match("ph:(%d*%.?%d+)")) or 1
                    local runtimeKey = self:BuildNoteReminderKey(encID, phase, timeValue, spellID, reminderText)
                    if runtimeKey and not seen[runtimeKey] then
                        seen[runtimeKey] = true
                        local spell = spellID and self:GetSpellData(spellID)
                        local label = TrimText(reminderText)
                        if label == "" then label = spell and spell.name or ("Spell " .. tostring(spellID)) end
                        local explicit = line:match("countdown:(%d+)")
                        local countdown, countdownSource = self:GetNoteLineCountdown(spellID, explicit, timeValue)
                        result[#result + 1] = {
                            key = runtimeKey,
                            encID = encID,
                            encounterName = encounterLabel or self:GetEncounterName(encID),
                            source = source.name,
                            sourceKey = source.key,
                            lineNumber = lineNumber,
                            phase = phase,
                            time = tonumber(timeValue),
                            tag = TrimText(tag),
                            spellID = spellID,
                            text = reminderText,
                            normalizedText = self:NormalizeNoteReminderText(reminderText),
                            label = label,
                            icon = spell and spell.icon or self:GetEncounterIcon(encID),
                            countdown = countdown,
                            countdownSource = countdownSource,
                            rawLine = line,
                        }
                    end
                end
            end
        end
    end

    table.sort(result, function(a, b)
        if a.encID ~= b.encID then return a.encID < b.encID end
        if a.phase ~= b.phase then return a.phase < b.phase end
        if a.time ~= b.time then return a.time < b.time end
        return a.label < b.label
    end)
    return result
end

function Addon:GetNoteAssignment(noteKey)
    if noteKey == nil then return nil end
    return self.db.noteAssignments and self.db.noteAssignments[tostring(noteKey)]
end

local function CopyNoteReminderMetadata(target, reminder)
    target.encID = tonumber(reminder.encID)
    target.phase = tonumber(reminder.phase) or 1
    target.time = tonumber(reminder.time)
    target.spellID = tonumber(reminder.spellID)
    target.text = reminder.text
    target.normalizedText = reminder.normalizedText or Addon:NormalizeNoteReminderText(reminder.text)
    target.label = reminder.label
    target.tag = reminder.tag
    target.encounterName = reminder.encounterName
    target.source = reminder.source
end

local function GetStoredNoteTTSMode(assignment)
    if type(assignment) ~= "table" then return "default" end
    if assignment.ttsMode == "mute" or assignment.ttsMode == "custom" then
        return assignment.ttsMode
    end
    if assignment.muteTTS == true then return "mute" end
    if TrimText(assignment.customTTS) ~= "" then return "custom" end
    return "default"
end

function Addon:GetNoteTTSMode(noteKey)
    return GetStoredNoteTTSMode(self:GetNoteAssignment(noteKey))
end

function Addon:SetNoteOverrides(reminder, voiceReference, ttsMode, customTTS)
    if type(reminder) ~= "table" or not reminder.key then return false end

    -- Backwards compatibility for the 0.5.4 boolean mute argument.
    if type(ttsMode) == "boolean" then ttsMode = ttsMode and "mute" or "default" end
    if ttsMode ~= "mute" and ttsMode ~= "custom" then ttsMode = "default" end
    customTTS = TrimText(customTTS)
    if ttsMode == "custom" and customTTS == "" then return false end

    local assignment = self:GetNoteAssignment(reminder.key)
    if type(assignment) ~= "table" then assignment = {} end
    CopyNoteReminderMetadata(assignment, reminder)

    if voiceReference ~= nil then
        local provider, rawID = self:DecodeVoiceReference(voiceReference)
        if not provider or not rawID then return false end
        assignment.voice = rawID
        assignment.provider = provider
    else
        assignment.voice = nil
        assignment.provider = nil
    end

    assignment.muteTTS = nil
    assignment.ttsMode = ttsMode ~= "default" and ttsMode or nil
    assignment.customTTS = ttsMode == "custom" and customTTS or nil

    self.db.noteAssignments = self.db.noteAssignments or {}
    if not assignment.voice and not assignment.ttsMode then
        self.db.noteAssignments[tostring(reminder.key)] = nil
    else
        self.db.noteAssignments[tostring(reminder.key)] = assignment
    end
    return true
end

function Addon:SetNoteTTSMuted(reminder, muted)
    if type(reminder) ~= "table" or not reminder.key then return false end
    local assignment = self:GetNoteAssignment(reminder.key)
    local voiceReference = assignment and assignment.voice and self:GetVoiceKey(assignment) or nil
    return self:SetNoteOverrides(reminder, voiceReference, muted == true and "mute" or "default", nil)
end

function Addon:IsNoteTTSMuted(noteKey)
    return self:GetNoteTTSMode(noteKey) == "mute"
end

function Addon:SetNoteAssignment(reminder, voiceReference)
    local existing = type(reminder) == "table" and reminder.key and self:GetNoteAssignment(reminder.key)
    return self:SetNoteOverrides(
        reminder,
        voiceReference,
        GetStoredNoteTTSMode(existing),
        existing and existing.customTTS
    )
end

function Addon:RemoveNoteAssignment(noteKey)
    if self.db.noteAssignments then self.db.noteAssignments[tostring(noteKey)] = nil end
end

local function GetNoteOverrideSignature(assignment)
    if type(assignment) ~= "table" then return "" end
    local voiceKey = assignment.voice and Addon:GetVoiceKey(assignment) or ""
    local mode = GetStoredNoteTTSMode(assignment)
    local custom = mode == "custom" and TrimText(assignment.customTTS) or ""
    return tostring(mode) .. "|" .. custom .. "|" .. tostring(voiceKey or "")
end

function Addon:GetNoteAssignmentForInfo(info)
    if type(info) ~= "table" or info.IsAlert or info.IsAssignment then return nil end
    local key = self:BuildNoteReminderKey(info.encID, info.phase, info.time, info.spellID, info.text)
    if key then
        local assignment = self:GetNoteAssignment(key)
        if assignment then return assignment, key, "current note reminder" end
    end

    -- NSRT may generate spell-name text for a line that contained only spellid,
    -- and it expands raid-icon tokens before the callback. Match the stored line
    -- metadata as a compatibility fallback, but only when the resulting voice is
    -- unambiguous.
    local encID = tonumber(info.encID)
    local phase = tonumber(info.phase) or 1
    local timeValue = tonumber(info.time)
    local spellID = tonumber(info.spellID)
    local normalizedText = self:NormalizeNoteReminderText(info.text)
    local match, matchKey
    for storedKey, candidate in pairs(self.db.noteAssignments or {}) do
        if type(candidate) == "table"
            and tonumber(candidate.encID) == encID
            and math.abs((tonumber(candidate.phase) or 1) - phase) < 0.001
            and timeValue and tonumber(candidate.time) and math.abs(tonumber(candidate.time) - timeValue) < 0.001
            and tonumber(candidate.spellID) == spellID then
            local candidateText = candidate.normalizedText or self:NormalizeNoteReminderText(candidate.text)
            local textCompatible = spellID ~= nil or candidateText == normalizedText
            if textCompatible then
                if match and GetNoteOverrideSignature(match) ~= GetNoteOverrideSignature(candidate) then return nil end
                match, matchKey = candidate, storedKey
            end
        end
    end
    if match then return match, matchKey, "current note reminder metadata" end
end

function Addon:RememberSpell(spellID, specID)
    spellID = tonumber(spellID)
    specID = tonumber(specID)
    if not spellID or not specID or not self:GetSpellData(spellID) then return false end

    local specKey = tostring(specID)
    self.db.knownSpells[specKey] = self.db.knownSpells[specKey] or {}
    self.db.knownSpells[specKey][tostring(spellID)] = true
    return true
end

function Addon:AddCustomSpell(spellID, specID)
    spellID = tonumber(spellID)
    specID = tonumber(specID)
    if not spellID or not specID or not self:GetSpellData(spellID) then return false end

    local specKey = tostring(specID)
    self.db.manualSpells[specKey] = self.db.manualSpells[specKey] or {}
    self.db.manualSpells[specKey][tostring(spellID)] = true
    return true
end

-- Retained for saved-variable and external compatibility with earlier builds.
Addon.AddManualSpell = Addon.AddCustomSpell

function Addon:IsCustomSpell(spellID, specID)
    local specTable = self.db.manualSpells[tostring(specID)]
    return specTable and specTable[tostring(spellID)] and true or false
end

function Addon:ParseNoteForSpells(noteText, specID)
    if type(noteText) ~= "string" or noteText == "" or not specID then return end
    for spellID in noteText:gmatch("spellid:(%d+)") do
        self:RememberSpell(spellID, specID)
    end
end

function Addon:IsPassiveSpell(spellID)
    if C_Spell and C_Spell.IsSpellPassive then
        return C_Spell.IsSpellPassive(spellID)
    end
    if IsPassiveSpell then
        return IsPassiveSpell(spellID)
    end
    return false
end

function Addon:IsSpellBookItemPassive(slotIndex, bank, itemInfo, spellID)
    if type(itemInfo) == "table" and itemInfo.isPassive ~= nil then
        return itemInfo.isPassive and true or false
    end
    if C_SpellBook and C_SpellBook.IsSpellBookItemPassive then
        local ok, passive = pcall(C_SpellBook.IsSpellBookItemPassive, slotIndex, bank)
        if ok then return passive and true or false end
    end
    return self:IsPassiveSpell(spellID)
end

function Addon:ScanCurrentSpellbook()
    if not self.db then return end

    local specID = self:GetCurrentSpecID()
    if not specID then return end

    local className = select(1, UnitClass("player"))
    local specIndex = GetSpecialization and GetSpecialization()
    local specName = specIndex and select(2, GetSpecializationInfo(specIndex))

    -- Rebuild the active spec cache from only the class and active-specialisation
    -- spellbook lines. The General tab contains racials, guild perks, toys and
    -- other assorted clutter that is useless for NSRT player ability reminders.
    local specKey = tostring(specID)
    self.db.knownSpells[specKey] = {}

    local added = 0
    local seen = {}
    local function AddSpell(spellID, slotIndex, bank, itemInfo)
        spellID = tonumber(spellID)
        if not spellID or seen[spellID] then return end
        if type(itemInfo) == "table" and itemInfo.isOffSpec then return end
        if C_SpellBook and C_SpellBook.IsAutoAttackSpellBookItem then
            local ok, isAutoAttack = pcall(C_SpellBook.IsAutoAttackSpellBookItem, slotIndex, bank)
            if ok and isAutoAttack then return end
        end
        if C_SpellBook and C_SpellBook.IsRangedAutoAttackSpellBookItem then
            local ok, isRangedAutoAttack = pcall(C_SpellBook.IsRangedAutoAttackSpellBookItem, slotIndex, bank)
            if ok and isRangedAutoAttack then return end
        end
        if self:IsSpellBookItemPassive(slotIndex, bank, itemInfo, spellID) then return end
        seen[spellID] = true
        if self:RememberSpell(spellID, specID) then
            added = added + 1
        end
    end

    if C_SpellBook and C_SpellBook.GetNumSpellBookSkillLines and C_SpellBook.GetSpellBookSkillLineInfo then
        local bank = Enum and Enum.SpellBookSpellBank and Enum.SpellBookSpellBank.Player
        local lineCount = C_SpellBook.GetNumSpellBookSkillLines()
        for lineIndex = 1, lineCount do
            local lineInfo = C_SpellBook.GetSpellBookSkillLineInfo(lineIndex)
            if type(lineInfo) == "table" then
                local lineSpecID = tonumber(lineInfo.specID)
                local offSpecID = tonumber(lineInfo.offSpecID)
                local isClassLine = className and lineInfo.name == className
                local isActiveSpecLine = (lineSpecID and lineSpecID == specID)
                    or (not lineSpecID and specName and lineInfo.name == specName)
                local isCurrentLine = not lineInfo.isGuild
                    and not lineInfo.shouldHide
                    and (not offSpecID or offSpecID == 0)
                    and (isClassLine or isActiveSpecLine)

                if isCurrentLine then
                    local offset = tonumber(lineInfo.itemIndexOffset) or 0
                    local count = tonumber(lineInfo.numSpellBookItems) or 0
                    for slotIndex = offset + 1, offset + count do
                        local itemInfo = C_SpellBook.GetSpellBookItemInfo and C_SpellBook.GetSpellBookItemInfo(slotIndex, bank)
                        if type(itemInfo) == "table" then
                            -- Blizzard documents spellID as nil for non-spell entries,
                            -- making this safer than guessing enum values for flyouts.
                            if itemInfo.spellID then
                                AddSpell(itemInfo.spellID, slotIndex, bank, itemInfo)
                            end
                        elseif GetSpellBookItemInfo then
                            local itemType, actionID, spellID = GetSpellBookItemInfo(slotIndex, BOOKTYPE_SPELL)
                            if itemType == "SPELL" then
                                AddSpell(spellID or actionID, slotIndex, bank)
                            end
                        end
                    end
                end
            end
        end
    elseif GetNumSpellTabs and GetSpellTabInfo and GetSpellBookItemInfo then
        for tabIndex = 1, GetNumSpellTabs() do
            local tabName, _, offset, count, isGuild, tabSpecID = GetSpellTabInfo(tabIndex)
            local isClassLine = className and tabName == className
            local isActiveSpecLine = tonumber(tabSpecID) == specID or (specName and tabName == specName)
            if not isGuild and (isClassLine or isActiveSpecLine) then
                for slotIndex = offset + 1, offset + count do
                    local itemType, actionID, spellID = GetSpellBookItemInfo(slotIndex, BOOKTYPE_SPELL)
                    if itemType == "SPELL" then AddSpell(spellID or actionID, slotIndex) end
                end
            end
        end
    end

    self:Debug(("Spellbook scan for %s [%s] found %d active class/spec abilities."):format(
        tostring(specName or "Unknown spec"), tostring(specID), added))
    if self.RefreshOptions then self:RefreshOptions() end
    return added
end

function Addon:GetKnownAbilities(specID)
    specID = tonumber(specID)
    if not specID then return {} end

    local ids = {}
    local specKey = tostring(specID)
    local customSpells = self.db.manualSpells[specKey] or {}
    for spellKey in pairs(self.db.knownSpells[specKey] or {}) do
        if not customSpells[spellKey] then ids[tonumber(spellKey)] = true end
    end
    for spellKey in pairs(self.db.assignments[specKey] or {}) do
        if not customSpells[spellKey] then ids[tonumber(spellKey)] = true end
    end

    local abilities = {}
    for spellID in pairs(ids) do
        local spell = self:GetSpellData(spellID)
        if spell then abilities[#abilities + 1] = spell end
    end
    table.sort(abilities, function(a, b)
        if a.name == b.name then return a.id < b.id end
        return a.name < b.name
    end)
    return abilities
end

local VOICE_KEY_SEPARATOR = "\031"

Addon.VOICE_PROVIDER_BIGWIGS = "BIGWIGS"
Addon.VOICE_PROVIDER_DBM = "DBM"
Addon.VOICE_PROVIDER_MUTE = "MUTE"
Addon.VOICE_MUTE_ID = "COUNTDOWN"

function Addon:NormalizeVoiceProvider(provider)
    provider = tostring(provider or ""):upper()
    if provider == self.VOICE_PROVIDER_MUTE then return self.VOICE_PROVIDER_MUTE end
    if provider == self.VOICE_PROVIDER_DBM then return self.VOICE_PROVIDER_DBM end
    return self.VOICE_PROVIDER_BIGWIGS
end

function Addon:MakeVoiceKey(provider, voiceID)
    if voiceID == nil then return nil end
    return self:NormalizeVoiceProvider(provider) .. VOICE_KEY_SEPARATOR .. tostring(voiceID)
end

function Addon:DecodeVoiceReference(voice, providerHint)
    if type(voice) == "table" then
        if voice.muted == true then
            return self.VOICE_PROVIDER_MUTE, self.VOICE_MUTE_ID
        end
        providerHint = voice.provider or providerHint
        voice = voice.voice
    end
    if voice == nil then return nil, nil end

    local value = tostring(voice)
    if value == "MUTE" or value == "MUTE_COUNTDOWN" then
        return self.VOICE_PROVIDER_MUTE, self.VOICE_MUTE_ID
    end
    local separatorAt = value:find(VOICE_KEY_SEPARATOR, 1, true)
    if separatorAt then
        local provider = value:sub(1, separatorAt - 1)
        local rawID = value:sub(separatorAt + 1)
        return self:NormalizeVoiceProvider(provider), rawID
    end

    if value:sub(1, 9) == "BIGWIGS:" then
        return self.VOICE_PROVIDER_BIGWIGS, value:sub(10)
    elseif value:sub(1, 4) == "DBM:" then
        return self.VOICE_PROVIDER_DBM, value:sub(5)
    end

    -- Assignments created before DBM support contain only a BigWigs voice ID.
    return self:NormalizeVoiceProvider(providerHint), value
end

function Addon:GetVoiceKey(voice, providerHint)
    local provider, rawID = self:DecodeVoiceReference(voice, providerHint)
    if not provider or not rawID then return nil end
    return self:MakeVoiceKey(provider, rawID)
end

function Addon:IsMuteVoice(voice, providerHint)
    local provider, rawID = self:DecodeVoiceReference(voice, providerHint)
    return provider == self.VOICE_PROVIDER_MUTE and rawID == self.VOICE_MUTE_ID
end

function Addon:GetBigWigsVoiceDefinitions()
    local voices = {}
    if not BigWigsAPI or type(BigWigsAPI.GetCountdownList) ~= "function" then return voices end

    local ok, voiceMap = pcall(BigWigsAPI.GetCountdownList, BigWigsAPI)
    if not ok or type(voiceMap) ~= "table" then return voices end

    for rawID, name in pairs(voiceMap) do
        local voiceID = tostring(rawID)
        voices[#voices + 1] = {
            id = self:MakeVoiceKey(self.VOICE_PROVIDER_BIGWIGS, voiceID),
            rawID = voiceID,
            provider = self.VOICE_PROVIDER_BIGWIGS,
            providerName = "BigWigs",
            voiceName = tostring(name or voiceID),
            name = "BigWigs: " .. tostring(name or voiceID),
        }
    end
    return voices
end

function Addon:GetDBMVoiceDefinitions()
    local voices = {}
    if not DBM or type(DBM.GetCountSounds) ~= "function" then return voices end

    local ok, countSounds = pcall(DBM.GetCountSounds, DBM)
    if not ok or type(countSounds) ~= "table" then return voices end

    local seen = {}
    for _, count in pairs(countSounds) do
        if type(count) == "table" and count.value and count.path then
            local rawID = tostring(count.value)
            if not seen[rawID] then
                seen[rawID] = true
                local maximum = tonumber(count.max) or 5
                maximum = min(max(floor(maximum + 0.5), 1), 10)
                voices[#voices + 1] = {
                    id = self:MakeVoiceKey(self.VOICE_PROVIDER_DBM, rawID),
                    rawID = rawID,
                    provider = self.VOICE_PROVIDER_DBM,
                    providerName = "DBM",
                    voiceName = tostring(count.text or rawID),
                    name = "DBM: " .. tostring(count.text or rawID),
                    path = tostring(count.path),
                    max = maximum,
                }
            end
        end
    end
    return voices
end

function Addon:GetVoiceList()
    local voices = {}
    local function Append(source)
        for _, voice in ipairs(source) do voices[#voices + 1] = voice end
    end
    Append(self:GetBigWigsVoiceDefinitions())
    Append(self:GetDBMVoiceDefinitions())

    table.sort(voices, function(a, b)
        if a.provider ~= b.provider then
            return a.provider == self.VOICE_PROVIDER_BIGWIGS
        end
        if a.voiceName == b.voiceName then return a.rawID < b.rawID end
        return a.voiceName < b.voiceName
    end)

    table.insert(voices, 1, {
        id = self:MakeVoiceKey(self.VOICE_PROVIDER_MUTE, self.VOICE_MUTE_ID),
        rawID = self.VOICE_MUTE_ID,
        provider = self.VOICE_PROVIDER_MUTE,
        providerName = "Companion",
        voiceName = "Mute countdown",
        name = "Mute countdown",
        muted = true,
    })
    return voices
end

function Addon:GetVoiceDefinition(voice, providerHint)
    local key = self:GetVoiceKey(voice, providerHint)
    if not key then return nil end
    for _, definition in ipairs(self:GetVoiceList()) do
        if definition.id == key then return definition end
    end
end

function Addon:GetVoiceMap()
    local map = {}
    for _, voice in ipairs(self:GetVoiceList()) do
        map[voice.id] = voice.name
    end
    return map
end

function Addon:GetVoiceName(voice, providerHint)
    local definition = self:GetVoiceDefinition(voice, providerHint)
    if definition then return definition.name end

    local provider, rawID = self:DecodeVoiceReference(voice, providerHint)
    if not rawID then return "Unknown voice" end
    local providerName = provider == self.VOICE_PROVIDER_DBM and "DBM" or "BigWigs"
    return providerName .. ": " .. rawID
end

function Addon:GetVoiceProviderCounts()
    local counts = { BIGWIGS = 0, DBM = 0, total = 0 }
    for _, voice in ipairs(self:GetVoiceList()) do
        if voice.provider ~= self.VOICE_PROVIDER_MUTE then
            counts[voice.provider] = (counts[voice.provider] or 0) + 1
            counts.total = counts.total + 1
        end
    end
    return counts
end

function Addon:GetVoiceSound(voice, number, providerHint)
    number = tonumber(number)
    if not number then return nil end

    local provider, rawID = self:DecodeVoiceReference(voice, providerHint)
    if provider == self.VOICE_PROVIDER_MUTE then return nil end
    if provider == self.VOICE_PROVIDER_DBM then
        local definition = self:GetVoiceDefinition(voice, providerHint)
        if not definition or number > (definition.max or 0) then return nil end
        local path = definition.path
        if path:sub(-1) ~= "\\" and path:sub(-1) ~= "/" then path = path .. "\\" end
        return path .. number .. ".ogg"
    end

    if not BigWigsAPI or type(BigWigsAPI.GetCountdownSound) ~= "function" then return nil end
    local sound = BigWigsAPI:GetCountdownSound(rawID, number)
    if not sound then
        local numericID = tonumber(rawID)
        if numericID then sound = BigWigsAPI:GetCountdownSound(numericID, number) end
    end
    return sound
end

function Addon:GetMaximumVoiceNumber(voice, providerHint)
    local provider = self:DecodeVoiceReference(voice, providerHint)
    if provider == self.VOICE_PROVIDER_MUTE then return 10 end
    if provider == self.VOICE_PROVIDER_DBM then
        local definition = self:GetVoiceDefinition(voice, providerHint)
        return definition and definition.max or 0
    end

    for number = 10, 1, -1 do
        if self:GetVoiceSound(voice, number, providerHint) then return number end
    end
    return 0
end

function Addon:GetAssignment(specID, spellID)
    local specTable = self.db.assignments[tostring(specID)]
    return specTable and specTable[tostring(spellID)]
end

-- Prefer the current spec, but allow a shared class ability to use an assignment
-- made under another spec. This matters for abilities such as Divine Toll that
-- appear in more than one Paladin spellbook.
function Addon:GetAssignmentForReminder(specID, spellID)
    specID = tonumber(specID)
    spellID = tonumber(spellID)
    if not spellID then return nil end

    local exact = specID and self:GetAssignment(specID, spellID)
    if exact then
        return exact, specID, "exact spec"
    end

    local currentClass = self:GetCurrentClass()
    local classMatches = {}
    local allMatches = {}
    local spellKey = tostring(spellID)

    for specKey, spellTable in pairs(self.db.assignments) do
        local assignment = spellTable[spellKey]
        if assignment then
            local assignedSpecID = tonumber(specKey)
            local spec = self.SPEC_DATA[assignedSpecID]
            local assignedClass = assignment.class or (spec and spec.class)
            local match = { assignment = assignment, specID = assignedSpecID }
            allMatches[#allMatches + 1] = match
            if currentClass and assignedClass == currentClass then
                classMatches[#classMatches + 1] = match
            end
        end
    end

    local function PickCompatible(matches, reason)
        if #matches == 0 then return nil end
        local first = matches[1]
        for index = 2, #matches do
            if self:GetVoiceKey(matches[index].assignment) ~= self:GetVoiceKey(first.assignment) then
                return nil
            end
        end
        return first.assignment, first.specID, reason
    end

    local assignment, assignedSpecID, reason = PickCompatible(classMatches, "shared class ability")
    if assignment then return assignment, assignedSpecID, reason end

    return PickCompatible(allMatches, "unique spell assignment")
end

function Addon:SetAssignment(classFile, specID, spellID, voiceReference)
    specID = tonumber(specID)
    spellID = tonumber(spellID)
    local provider, rawID = self:DecodeVoiceReference(voiceReference)
    if not specID or not spellID or not provider or not rawID then return false end

    local specKey = tostring(specID)
    self.db.assignments[specKey] = self.db.assignments[specKey] or {}
    self.db.assignments[specKey][tostring(spellID)] = {
        voice = rawID,
        provider = provider,
        class = classFile,
    }
    self:RememberSpell(spellID, specID)
    return true
end

function Addon:RemoveAssignment(specID, spellID)
    local specKey = tostring(specID)
    local spellKey = tostring(spellID)
    if self.db.assignments[specKey] then
        self.db.assignments[specKey][spellKey] = nil
        if not next(self.db.assignments[specKey]) then
            self.db.assignments[specKey] = nil
        end
    end
end

function Addon:GetAssignments()
    local result = {}
    for specKey, spellTable in pairs(self.db.assignments) do
        local specID = tonumber(specKey)
        for spellKey, assignment in pairs(spellTable) do
            local spellID = tonumber(spellKey)
            local spell = self:GetSpellData(spellID)
            local spec = self.SPEC_DATA[specID]
            result[#result + 1] = {
                specID = specID,
                spellID = spellID,
                spellName = spell and spell.name or ("Spell " .. spellKey),
                spellIcon = spell and spell.icon or 134400,
                specName = spec and spec.name or ("Spec " .. specKey),
                classFile = assignment.class or (spec and spec.class),
                voiceID = assignment.voice,
                voiceName = self:GetVoiceName(assignment),
                voiceProvider = self:NormalizeVoiceProvider(assignment.provider),
            }
        end
    end
    table.sort(result, function(a, b)
        if a.classFile ~= b.classFile then return tostring(a.classFile) < tostring(b.classFile) end
        if a.specName ~= b.specName then return a.specName < b.specName end
        return a.spellName < b.spellName
    end)
    return result
end


function Addon:GetAbilityRename(specID, spellID)
    local specTable = self.db.abilityRenames[tostring(specID)]
    return specTable and specTable[tostring(spellID)]
end

-- Ability names can be shared across specialisations. Prefer the current spec,
-- then reuse a rename from another spec only when every compatible saved value
-- agrees. This mirrors the safe cross-spec behaviour used by voice assignments.
function Addon:GetAbilityRenameForReminder(specID, spellID)
    specID = tonumber(specID)
    spellID = tonumber(spellID)
    if not spellID then return nil end

    local exact = specID and self:GetAbilityRename(specID, spellID)
    if exact then return exact, specID, "exact spec" end

    local currentClass = self:GetCurrentClass()
    local classMatches = {}
    local allMatches = {}
    local spellKey = tostring(spellID)

    for specKey, spellTable in pairs(self.db.abilityRenames) do
        local rename = spellTable[spellKey]
        if rename then
            local assignedSpecID = tonumber(specKey)
            local spec = self.SPEC_DATA[assignedSpecID]
            local assignedClass = type(rename) == "table" and rename.class or (spec and spec.class)
            local text = type(rename) == "table" and rename.text or rename
            local match = { rename = rename, text = TrimText(text), specID = assignedSpecID }
            allMatches[#allMatches + 1] = match
            if currentClass and assignedClass == currentClass then
                classMatches[#classMatches + 1] = match
            end
        end
    end

    local function PickCompatible(matches, reason)
        if #matches == 0 then return nil end
        local first = matches[1]
        for index = 2, #matches do
            if matches[index].text ~= first.text then return nil end
        end
        return first.rename, first.specID, reason
    end

    local rename, assignedSpecID, reason = PickCompatible(classMatches, "shared class ability")
    if rename then return rename, assignedSpecID, reason end
    return PickCompatible(allMatches, "unique spell rename")
end

function Addon:SetAbilityRename(classFile, specID, spellID, replacement)
    specID = tonumber(specID)
    spellID = tonumber(spellID)
    replacement = TrimText(replacement):gsub("[%c]+", " "):gsub("%s+", " ")
    if not specID or not spellID or replacement == "" or #replacement > 80 then return false end

    local specKey = tostring(specID)
    self.db.abilityRenames[specKey] = self.db.abilityRenames[specKey] or {}
    self.db.abilityRenames[specKey][tostring(spellID)] = {
        text = replacement,
        class = classFile,
    }
    self:RememberSpell(spellID, specID)
    return true
end

function Addon:RemoveAbilityRename(specID, spellID)
    local specKey = tostring(specID)
    local spellKey = tostring(spellID)
    if self.db.abilityRenames[specKey] then
        self.db.abilityRenames[specKey][spellKey] = nil
        if not next(self.db.abilityRenames[specKey]) then
            self.db.abilityRenames[specKey] = nil
        end
    end
end

function Addon:GetAbilityRenames()
    local result = {}
    for specKey, spellTable in pairs(self.db.abilityRenames) do
        local specID = tonumber(specKey)
        for spellKey, saved in pairs(spellTable) do
            local spellID = tonumber(spellKey)
            local spell = self:GetSpellData(spellID)
            local spec = self.SPEC_DATA[specID]
            local replacement = type(saved) == "table" and saved.text or saved
            result[#result + 1] = {
                specID = specID,
                spellID = spellID,
                spellName = spell and spell.name or ("Spell " .. spellKey),
                spellIcon = spell and spell.icon or 134400,
                specName = spec and spec.name or ("Spec " .. specKey),
                classFile = type(saved) == "table" and saved.class or (spec and spec.class),
                replacement = TrimText(replacement),
            }
        end
    end
    table.sort(result, function(a, b)
        if a.classFile ~= b.classFile then return tostring(a.classFile) < tostring(b.classFile) end
        if a.specName ~= b.specName then return a.specName < b.specName end
        return a.spellName < b.spellName
    end)
    return result
end

local function EscapeLuaPattern(value)
    return tostring(value or ""):gsub("([^%w])", "%%%1")
end

function Addon:RestoreNoteTTS(info)
    if type(info) ~= "table" or not info.__NSRTCountdownCompanionTTSOverrideApplied then return end
    info.TTS = info.__NSRTCountdownCompanionOriginalTTS
    info.__NSRTCountdownCompanionOriginalTTS = nil
    info.__NSRTCountdownCompanionTTSOverrideApplied = nil
end

local function GetExpectedReminderTTS(info)
    if type(info) ~= "table" then return nil end
    if type(info.TTS) == "string" then return TrimText(info.TTS) end
    if info.TTS ~= true then return nil end

    local text = TrimText(info.text)
    if text == "" and info.spellID then
        local spell = Addon:GetSpellData(info.spellID)
        text = spell and TrimText(spell.name) or ""
    end
    if text == "" then return nil end

    local settings = _G.NSRT and _G.NSRT.ReminderSettings
    local announce = settings and ((info.spellID and settings.AnnounceSpellDuration) or (not info.spellID and settings.AnnounceTextDuration))
    if announce and not (info.IsAlert or info.IsAssignment) then
        text = text .. " in " .. tostring(info.TTSTimer or "")
    end
    return TrimText(text)
end

local function BuildCustomReminderTTS(info, customTTS, expected)
    customTTS = TrimText(customTTS)
    if customTTS == "" then return nil end
    expected = TrimText(expected or GetExpectedReminderTTS(info))
    local suffix = expected:match("(%s+[Ii][Nn]%s+[%d%.]+%s*)$") or ""
    return customTTS .. suffix
end

function Addon:ApplyNoteTTSOverride(info, frame)
    if type(info) ~= "table" or info.IsAlert or info.IsAssignment or info.__NSRTCountdownCompanionTTSOverrideApplied then return false end
    local assignment, _, reason = self:GetNoteAssignmentForInfo(info)
    local mode = GetStoredNoteTTSMode(assignment)
    if mode == "default" then return false end
    if not info.TTS then return false end
    if type(issecretvalue) == "function" and issecretvalue(info.TTS) then return false end

    local original = info.TTS
    local replacement
    if mode == "mute" then
        replacement = false
    elseif mode == "custom" then
        replacement = BuildCustomReminderTTS(info, assignment.customTTS, GetExpectedReminderTTS(info))
        if not replacement then return false end
    else
        return false
    end

    info.__NSRTCountdownCompanionOriginalTTS = original
    info.__NSRTCountdownCompanionTTSOverrideApplied = mode
    info.TTS = replacement

    if frame and frame.HookScript and not frame.__NSRTCountdownCompanionTTSRestoreHook then
        frame.__NSRTCountdownCompanionTTSRestoreHook = true
        frame:HookScript("OnHide", function(selfFrame)
            local frameInfo = selfFrame and selfFrame.info
            if frameInfo then Addon:RestoreNoteTTS(frameInfo) end
        end)
    end

    if mode == "mute" then
        self:Debug(("Muted opening TTS for %s via %s."):format(tostring(info.text or info.spellID or "note reminder"), tostring(reason)))
    else
        self:Debug(("Changed opening TTS for %s to '%s' via %s."):format(
            tostring(info.text or info.spellID or "note reminder"), tostring(replacement), tostring(reason)))
    end
    return true
end

-- Compatibility name retained for older internal calls and test helpers.
function Addon:ApplyNoteTTSMute(info, frame)
    return self:ApplyNoteTTSOverride(info, frame)
end

function Addon:GetOutgoingNoteTTSOverride(sound)
    if type(sound) ~= "string" or not EnumerateFrames then return false, sound end
    if type(issecretvalue) == "function" and issecretvalue(sound) then return false, sound end
    local spoken = TrimText(sound)
    if spoken == "" then return false, sound end

    local frame = EnumerateFrames()
    while frame do
        local shown = frame.IsShown and frame:IsShown()
        if type(issecretvalue) == "function" and issecretvalue(shown) then shown = false end
        local info = shown and frame.info
        if type(issecretvalue) == "function" and issecretvalue(info) then info = nil end
        if type(info) == "table" and not info.IsAlert and not info.IsAssignment then
            local assignment, _, reason = self:GetNoteAssignmentForInfo(info)
            local mode = GetStoredNoteTTSMode(assignment)
            if mode ~= "default" then
                local expected = GetExpectedReminderTTS(info)
                local remaining = self.GetReminderRemaining and self:GetReminderRemaining(info)
                local timer = tonumber(info.TTSTimer)
                local due = not remaining or not timer or abs(remaining - timer) <= 1.0
                if due and expected and spoken == expected then
                    if mode == "mute" then
                        self:Debug(("Suppressed outgoing NSRT TTS '%s' via %s."):format(spoken, tostring(reason)))
                        return true, nil
                    end
                    local replacement = BuildCustomReminderTTS(info, assignment.customTTS, expected)
                    if replacement then
                        self:Debug(("Changed outgoing NSRT TTS '%s' to '%s' via %s."):format(spoken, replacement, tostring(reason)))
                        return true, replacement
                    end
                end
            end
        end
        frame = EnumerateFrames(frame)
    end
    return false, sound
end

function Addon:ShouldMuteOutgoingNoteTTS(sound)
    local handled, replacement = self:GetOutgoingNoteTTSOverride(sound)
    return handled and replacement == nil
end

function Addon:ApplyAbilityRename(info)
    if type(info) ~= "table" or info.IsAlert or info.__NSRTCountdownCompanionRenameApplied then return false end
    local spellID = tonumber(info.spellID)
    if not spellID or not info.TTS then return false end
    if type(issecretvalue) == "function" and issecretvalue(info.TTS) then return false end

    local saved, _, reason = self:GetAbilityRenameForReminder(self:GetCurrentSpecID(), spellID)
    local replacement = type(saved) == "table" and saved.text or saved
    replacement = TrimText(replacement)
    if replacement == "" then return false end

    local original = info.TTS
    local renamedText
    if type(original) == "string" then
        local spoken = TrimText(original)
        if spoken == "" then return false end

        local suffix
        local spell = self:GetSpellData(spellID)
        local candidates = {
            spell and spell.name,
            TrimText(info.text),
        }
        for _, candidate in ipairs(candidates) do
            candidate = TrimText(candidate)
            if candidate ~= "" then
                local rest = spoken:match("^" .. EscapeLuaPattern(candidate) .. "(.*)$")
                if rest ~= nil then
                    suffix = rest
                    break
                end
            end
        end
        if suffix == nil then
            suffix = spoken:match("(%s+[Ii][Nn]%s+[%d%.]+%s*)$") or ""
        end
        renamedText = replacement .. suffix
    elseif original == true then
        renamedText = replacement
        if NSRT and NSRT.ReminderSettings and NSRT.ReminderSettings.AnnounceSpellDuration
            and not (info.IsAlert or info.IsAssignment) then
            renamedText = renamedText .. " in " .. tostring(info.TTSTimer or "")
        end
    else
        return false
    end

    info.__NSRTCountdownCompanionOriginalTTS = original
    info.__NSRTCountdownCompanionRenameApplied = true
    info.TTS = renamedText
    self:Debug(("Renamed TTS for spell %d to '%s' via %s."):format(spellID, renamedText, tostring(reason)))
    return true
end


function Addon:GetRenamedTTSString(sound)
    if type(sound) ~= "string" then return sound end
    if type(issecretvalue) == "function" and issecretvalue(sound) then return sound end

    local spoken = TrimText(sound)
    if spoken == "" then return sound end

    local currentSpecID = self:GetCurrentSpecID()
    local seenSpellIDs = {}
    for _, row in ipairs(self:GetAbilityRenames()) do
        local spellID = tonumber(row.spellID)
        if spellID and not seenSpellIDs[spellID] then
            seenSpellIDs[spellID] = true
            local saved, _, reason = self:GetAbilityRenameForReminder(currentSpecID, spellID)
            local replacement = type(saved) == "table" and saved.text or saved
            replacement = TrimText(replacement)
            local spell = self:GetSpellData(spellID)
            local originalName = spell and TrimText(spell.name) or ""

            if replacement ~= "" and originalName ~= "" then
                local suffix = spoken:match("^" .. EscapeLuaPattern(originalName) .. "(.*)$")
                if suffix ~= nil and (suffix == "" or suffix:match("^%s+[Ii][Nn]%s+[%d%.]+%s*$")) then
                    local renamed = replacement .. suffix
                    self:Debug(("Renamed outgoing NSRT TTS for spell %d from '%s' to '%s' via %s."):format(
                        spellID, spoken, renamed, tostring(reason)))
                    return renamed
                end
            end
        end
    end

    return sound
end

function Addon:GetNSRTConfiguredTTSVoice()
    local settings = _G.NSRT and _G.NSRT.Settings
    local voice = settings and settings.TTSVoice
    if voice == nil then return nil end
    return tonumber(voice) or voice
end

function Addon:InstallNSRTTTSRenameHook()
    if self.nsrtTTSRenameHookInstalled then return true end
    if not NSAPI or type(NSAPI.TTS) ~= "function" then return false end

    local original = NSAPI.TTS
    self.originalNSRTTTS = original
    local addon = self

    local function GetReplacementVoice(requestedVoice)
        local configuredVoice = addon:GetNSRTConfiguredTTSVoice()
        if configuredVoice ~= nil then return configuredVoice end
        return requestedVoice
    end

    NSAPI.TTS = function(apiOrSound, maybeSound, maybeVoice)
        if apiOrSound == NSAPI then
            local handled, noteOverride = addon:GetOutgoingNoteTTSOverride(maybeSound)
            if handled then
                if noteOverride == nil then return end
                return original(NSAPI, noteOverride, GetReplacementVoice(maybeVoice))
            end
            local renamed = addon:GetRenamedTTSString(maybeSound)
            if renamed ~= maybeSound then
                return original(NSAPI, renamed, GetReplacementVoice(maybeVoice))
            end
            return original(NSAPI, renamed, maybeVoice)
        end

        -- Support the uncommon dot-call form as well as NSRT's normal colon call.
        local handled, noteOverride = addon:GetOutgoingNoteTTSOverride(apiOrSound)
        if handled then
            if noteOverride == nil then return end
            return original(NSAPI, noteOverride, GetReplacementVoice(maybeSound))
        end
        local renamed = addon:GetRenamedTTSString(apiOrSound)
        if renamed ~= apiOrSound then
            return original(NSAPI, renamed, GetReplacementVoice(maybeSound))
        end
        return original(NSAPI, renamed, maybeSound)
    end

    self.nsrtTTSRenameHookInstalled = true
    self:Debug("Installed NSRT main TTS rename hook.")
    return true
end


function Addon:GetEncounterName(encID)
    encID = tonumber(encID)
    local data = encID and self.ENCOUNTER_DATA and self.ENCOUNTER_DATA[encID]
    return (data and data.name) or (encID and ("Encounter " .. encID)) or "Unknown encounter"
end

function Addon:GetEncounterIcon(encID)
    encID = tonumber(encID)
    local data = encID and self.ENCOUNTER_DATA and self.ENCOUNTER_DATA[encID]
    return (data and data.icon) or 134400
end

function Addon:IsConfigurableEncounterAlert(alert)
    -- NSRT's bundled alerts have stable internal IDs. User-created/imported alerts
    -- may use generated table keys instead, so keep this page focused on the
    -- built-in boss assignments requested by the user. Special-display entries
    -- do not run through the normal reminder countdown system.
    return type(alert) == "table"
        and alert.internalID ~= nil
        and tostring(alert.internalID) ~= ""
        and not alert.isSpecialDisplay
end

function Addon:GetEncounterAlertIdentity(info)
    if type(info) ~= "table" or not info.IsAlert then return nil end
    local encID = tonumber(info.encID)
    if not encID then return nil end

    local alertKey = info.internalID or info.alertKey
    if alertKey ~= nil and tostring(alertKey) ~= "" then
        return encID, tostring(alertKey), "internal ID"
    end

    -- Built-in NSRT alerts have stable internal IDs. This fallback keeps imported
    -- or older custom alerts usable when they only expose a name or display text.
    local fallback = info.name or info.text
    if fallback ~= nil and tostring(fallback) ~= "" then
        return encID, "name:" .. tostring(fallback), "alert name"
    end
end

function Addon:GetEncounterAssignment(encID, alertKey)
    encID = tonumber(encID)
    if not encID or alertKey == nil then return nil end
    local encounterTable = self.db.encounterAssignments[tostring(encID)]
    return encounterTable and encounterTable[tostring(alertKey)]
end

function Addon:GetEncounterAssignmentForInfo(info)
    local encID, alertKey, reason = self:GetEncounterAlertIdentity(info)
    if not encID then return nil end

    local exact = self:GetEncounterAssignment(encID, alertKey)
    if exact then return exact, encID, alertKey, reason end

    -- An alert imported from another NSRT version can occasionally have a new
    -- table key while retaining its name. Match a unique stored name as a safe
    -- compatibility fallback rather than silently losing the assignment.
    local encounterTable = self.db.encounterAssignments[tostring(encID)] or {}
    local alertName = tostring(info.name or info.text or "")
    if alertName ~= "" then
        local match, matchKey
        for storedKey, assignment in pairs(encounterTable) do
            if type(assignment) == "table" and (assignment.alertName == alertName or assignment.alertText == alertName) then
                if match and self:GetVoiceKey(match) ~= self:GetVoiceKey(assignment) then
                    return nil
                end
                match = assignment
                matchKey = storedKey
            end
        end
        if match then return match, encID, matchKey, "unique alert name" end
    end
end

function Addon:SetEncounterAssignment(encID, alertKey, voiceReference, alertData)
    encID = tonumber(encID)
    if not encID or alertKey == nil then return false end
    local provider, rawID = self:DecodeVoiceReference(voiceReference)
    if not provider or not rawID then return false end

    local encKey = tostring(encID)
    local key = tostring(alertKey)
    self.db.encounterAssignments[encKey] = self.db.encounterAssignments[encKey] or {}
    self.db.encounterAssignments[encKey][key] = {
        voice = rawID,
        provider = provider,
        alertName = alertData and (alertData.name or alertData.text) or key,
        alertText = alertData and alertData.text or nil,
        spellID = alertData and tonumber(alertData.spellID) or nil,
    }
    return true
end

function Addon:RemoveEncounterAssignment(encID, alertKey)
    local encKey = tostring(encID)
    local key = tostring(alertKey)
    local encounterTable = self.db.encounterAssignments[encKey]
    if not encounterTable then return end
    encounterTable[key] = nil
    if not next(encounterTable) then self.db.encounterAssignments[encKey] = nil end
end

function Addon:GetEncounterAssignments()
    local result = {}
    for encKey, alertTable in pairs(self.db.encounterAssignments or {}) do
        local encID = tonumber(encKey)
        for alertKey, assignment in pairs(alertTable) do
            local spell = assignment.spellID and self:GetSpellData(assignment.spellID)
            result[#result + 1] = {
                encID = encID,
                encounterName = self:GetEncounterName(encID),
                encounterIcon = self:GetEncounterIcon(encID),
                alertKey = alertKey,
                alertName = assignment.alertName or assignment.alertText or tostring(alertKey),
                alertIcon = spell and spell.icon or self:GetEncounterIcon(encID),
                voiceName = self:GetVoiceName(assignment),
                voiceID = assignment.voice,
                voiceProvider = self:NormalizeVoiceProvider(assignment.provider),
            }
        end
    end
    table.sort(result, function(a, b)
        if a.encounterName ~= b.encounterName then return a.encounterName < b.encounterName end
        return a.alertName < b.alertName
    end)
    return result
end

function Addon:GetEncounterList(diffID)
    diffID = tonumber(diffID) or 16
    local result = {}
    for encID, encounterTable in pairs((_G.NSRT and _G.NSRT.EncounterAlerts) or {}) do
        local diffTable = type(encounterTable) == "table" and encounterTable[diffID]
        if type(diffTable) == "table" then
            local hasSupportedAlert = false
            for _, alert in pairs(diffTable) do
                if self:IsConfigurableEncounterAlert(alert) then
                    hasSupportedAlert = true
                    break
                end
            end
            if hasSupportedAlert then
                result[#result + 1] = {
                    id = tonumber(encID),
                    name = self:GetEncounterName(encID),
                    icon = self:GetEncounterIcon(encID),
                }
            end
        end
    end
    table.sort(result, function(a, b) return a.name < b.name end)
    return result
end

function Addon:GetEncounterAlerts(encID, diffID)
    encID = tonumber(encID)
    diffID = tonumber(diffID) or 16
    local result = {}
    local diffTable = _G.NSRT and _G.NSRT.EncounterAlerts and encID
        and _G.NSRT.EncounterAlerts[encID] and _G.NSRT.EncounterAlerts[encID][diffID]
    if type(diffTable) ~= "table" then return result end

    for alertKey, alert in pairs(diffTable) do
        if self:IsConfigurableEncounterAlert(alert) then
            local key = tostring(alert.internalID or alertKey)
            local spell = alert.spellID and self:GetSpellData(alert.spellID)
            local alertName = tostring(alert.name or alert.text or alert.internalID or alertKey)
            local groupName = alert.group and tostring(alert.group) or nil
            result[#result + 1] = {
                key = key,
                tableKey = tostring(alertKey),
                name = alertName,
                label = groupName and groupName ~= "" and (groupName .. " - " .. alertName) or alertName,
                text = alert.text,
                group = alert.group,
                icon = (alert.customIcon and self:GetSpellData(alert.customIcon) and self:GetSpellData(alert.customIcon).icon)
                    or (spell and spell.icon) or self:GetEncounterIcon(encID),
                data = alert,
            }
        end
    end
    table.sort(result, function(a, b)
        local ag, bg = tostring(a.group or ""), tostring(b.group or "")
        if ag ~= bg then return ag < bg end
        return a.name < b.name
    end)
    return result
end

function Addon:CancelCountdown(token)
    local countdown = self.activeCountdowns[token]
    if not countdown then return end
    countdown.active = false
    for _, timer in ipairs(countdown.timers) do
        if timer and timer.Cancel then timer:Cancel() end
    end

    if countdown.entries then
        for _, entry in ipairs(countdown.entries) do
            if entry.info and entry.info.__NSRTCountdownCompanionToken == token then
                entry.info.countdown = entry.originalCountdown
                entry.info.__NSRTCountdownCompanionToken = nil
            end
        end
    elseif countdown.info and countdown.info.__NSRTCountdownCompanionToken == token then
        countdown.info.countdown = countdown.originalCountdown
        countdown.info.__NSRTCountdownCompanionToken = nil
    end
    self.activeCountdowns[token] = nil
end

function Addon:CancelAllCountdowns()
    local tokens = {}
    for token in pairs(self.activeCountdowns) do tokens[#tokens + 1] = token end
    for _, token in ipairs(tokens) do self:CancelCountdown(token) end
end

function Addon:PlayVoiceNumber(voiceReference, number)
    if self:IsMuteVoice(voiceReference) then return true end
    local soundPath = self:GetVoiceSound(voiceReference, number)
    if not soundPath then
        self:Debug(("No sound file for voice %s, number %s."):format(self:GetVoiceName(voiceReference), tostring(number)))
        return false
    end
    local played = PlaySoundFile(soundPath, self.db.soundChannel or "Master")
    if not played then
        self:Debug(("PlaySoundFile failed for %s (%s)."):format(self:GetVoiceName(voiceReference), tostring(soundPath)))
    end
    return played and true or false
end

function Addon:ScheduleCountdown(info, frame, voiceReference, seconds, originalCountdown)
    local expires = tonumber(info.expires) or (GetTime() + (tonumber(info.dur) or seconds))
    local token = {}
    local countdown = {
        active = true,
        timers = {},
        info = info,
        originalCountdown = originalCountdown,
    }
    self.activeCountdowns[token] = countdown
    info.__NSRTCountdownCompanionToken = token

    for number = seconds, 1, -1 do
        local countdownNumber = number
        local soundPath = self:GetVoiceSound(voiceReference, countdownNumber)
        if soundPath then
            local delay = expires - countdownNumber - GetTime()
            if delay >= -0.15 then
                local timer = C_Timer.NewTimer(max(0, delay), function()
                    local state = self.activeCountdowns[token]
                    if state and state.active then
                        self:PlayVoiceNumber(voiceReference, countdownNumber)
                    end
                end)
                countdown.timers[#countdown.timers + 1] = timer
            end
        end
    end

    countdown.timers[#countdown.timers + 1] = C_Timer.NewTimer(max(0.1, expires - GetTime() + 0.5), function()
        self:CancelCountdown(token)
    end)

    if frame and frame.HookScript then
        frame:HookScript("OnHide", function()
            if info.__NSRTCountdownCompanionToken == token then
                self:CancelCountdown(token)
                info.__NSRTCountdownCompanionToken = nil
            end
        end)
    end
end

function Addon:OnNSRTReminderShow(_, info, frame)
    if type(info) ~= "table" then return end
    local openingTTSOverridden = self:ApplyNoteTTSOverride(info, frame)
    if not openingTTSOverridden then self:ApplyAbilityRename(info) end
    local existingToken = info.__NSRTCountdownCompanionToken
    if existingToken and self.activeCountdowns[existingToken] then return end

    local requested, countdownSource = self:GetReminderCountdown(info)
    local assignment, identityName, identityID, matchReason

    if info.IsAlert then
        local encID, alertKey
        assignment, encID, alertKey, matchReason = self:GetEncounterAssignmentForInfo(info)
        identityName = tostring(info.name or info.text or alertKey or "Encounter alert")
        identityID = encID and (tostring(encID) .. "/" .. tostring(alertKey)) or "unknown alert"
    else
        local spellID = tonumber(info.spellID)
        local specID = self:GetCurrentSpecID()
        local spell = spellID and self:GetSpellData(spellID)
        identityName = TrimText(info.text)
        if identityName == "" then
            identityName = spell and spell.name or (spellID and ("Spell " .. spellID) or "text reminder")
        end
        local noteAssignment, noteIdentityID, noteReason = self:GetNoteAssignmentForInfo(info)
        if noteAssignment and type(noteAssignment.voice) == "string" then
            assignment, identityID, matchReason = noteAssignment, noteIdentityID, noteReason
        else
            identityID = spellID or noteIdentityID
            assignment, _, matchReason = self:GetAssignmentForReminder(specID, spellID)
            if not assignment and noteAssignment then matchReason = noteReason end
        end
        if spellID and specID and assignment then self:RememberSpell(spellID, specID) end
    end

    self.lastReminder = {
        spellID = info.IsAlert and nil or tonumber(info.spellID),
        spellName = identityName,
        alertID = info.IsAlert and identityID or nil,
        specID = self:GetCurrentSpecID(),
        countdown = requested,
        receivedAt = GetTime(),
        source = "NSRT callback",
    }

    self:Debug(("NSRT reminder received: %s [%s], countdown %s via %s."):format(
        identityName, tostring(identityID), tostring(requested), tostring(countdownSource)))

    if not assignment or type(assignment.voice) ~= "string" then
        self:Debug(("No compatible voice assignment found for %s [%s]."):format(identityName, tostring(identityID)))
        return
    end

    if not requested or requested < 1 then
        self:Debug("The reminder has no active numeric countdown, so NSRT CC left it alone.")
        return
    end

    local maximum = self:GetMaximumVoiceNumber(assignment)
    if maximum < 1 then
        self:Print("The assigned countdown voice is not currently available: " .. self:GetVoiceName(assignment))
        return
    end

    local seconds = min(requested, maximum)
    local originalCountdown = info.countdown
    info.countdown = false

    self:Debug(("Using %s via %s; scheduling %d to 1."):format(
        self:GetVoiceName(assignment), tostring(matchReason), seconds))

    self:ScheduleCountdown(info, frame, assignment, seconds, originalCountdown)
end


-- Older NSRT builds do not reliably emit NSRT_REMINDER_SHOW during the built-in
-- reminder test. The numeric countdown still passes through the public
-- NSAPI:TTSCountdown function, so this is a compatibility fallback. At the exact
-- moment NSRT asks for its 5-4-3-2-1, we find the visible reminder frame whose
-- expiry matches that countdown and replace only those numbers.
function Addon:GetReminderRemaining(info)
    if type(info) ~= "table" then return nil end
    local now = GetTime()
    local expires = tonumber(info.expires)
    if expires then return expires - now end
    local startTime = tonumber(info.startTime)
    local duration = tonumber(info.dur)
    if startTime and duration then
        return duration - (now - startTime)
    end
end

function Addon:CollectDueReminderAssignments(seconds)
    local timed = {}
    local untimed = {}
    local seenInfo = {}
    if not EnumerateFrames then return timed end

    local currentSpecID = self:GetCurrentSpecID()
    local frame = EnumerateFrames()
    while frame do
        local shown = frame.IsShown and frame:IsShown()
        -- WoW 12.x can return a secret boolean for the visibility of protected
        -- Blizzard frames. Skip those frames without evaluating the value.
        if type(issecretvalue) == "function" and issecretvalue(shown) then shown = false end

        local info = shown and frame.info
        if type(issecretvalue) == "function" and issecretvalue(info) then info = nil end

        if type(info) == "table" and not seenInfo[info] and not info.__NSRTCountdownCompanionToken then
            seenInfo[info] = true
            local requested = self:GetReminderCountdown(info)
            if requested == seconds then
                local assignment, identityName, identityID, reason, spellID, assignedSpecID
                if info.IsAlert then
                    local encID, alertKey
                    assignment, encID, alertKey, reason = self:GetEncounterAssignmentForInfo(info)
                    identityName = tostring(info.name or info.text or alertKey or "Encounter alert")
                    identityID = encID and (tostring(encID) .. "/" .. tostring(alertKey)) or "unknown alert"
                else
                    spellID = tonumber(info.spellID)
                    local noteAssignment, noteIdentityID, noteReason = self:GetNoteAssignmentForInfo(info)
                    local spell = spellID and self:GetSpellData(spellID)
                    identityName = TrimText(info.text)
                    if identityName == "" then
                        identityName = spell and spell.name or (spellID and ("Spell " .. spellID) or "text reminder")
                    end
                    if noteAssignment and type(noteAssignment.voice) == "string" then
                        assignment, identityID, reason = noteAssignment, noteIdentityID, noteReason
                    elseif spellID then
                        assignment, assignedSpecID, reason = self:GetAssignmentForReminder(currentSpecID, spellID)
                        identityID = spellID
                        if not assignment and noteAssignment then reason = noteReason end
                    else
                        identityID, reason = noteIdentityID, noteReason
                    end
                end

                if assignment and type(assignment.voice) == "string" then
                    local candidate = {
                        frame = frame,
                        info = info,
                        spellID = spellID,
                        identityName = identityName,
                        identityID = identityID,
                        assignment = assignment,
                        assignedSpecID = assignedSpecID,
                        reason = reason,
                        remaining = self:GetReminderRemaining(info),
                    }
                    if candidate.remaining then
                        candidate.distance = abs(candidate.remaining - seconds)
                        if candidate.remaining <= seconds + 0.6 and candidate.remaining >= seconds - 1.5 then
                            timed[#timed + 1] = candidate
                        end
                    else
                        untimed[#untimed + 1] = candidate
                    end
                end
            end
        end
        frame = EnumerateFrames(frame)
    end

    table.sort(timed, function(a, b) return (a.distance or 99) < (b.distance or 99) end)
    if #timed > 0 then return timed end
    if #untimed == 1 then return untimed end
    return {}
end


function Addon:ScheduleFallbackCountdown(candidates, voiceReference, seconds)
    if #candidates == 0 then return end

    local token = {}
    local entries = {}
    local expires = GetTime() + seconds
    for _, candidate in ipairs(candidates) do
        local info = candidate.info
        entries[#entries + 1] = {
            info = info,
            originalCountdown = info.countdown,
        }
        info.__NSRTCountdownCompanionToken = token
        info.countdown = false
        local candidateExpires = tonumber(info.expires)
        if candidateExpires and abs(candidateExpires - expires) < 1.5 then
            expires = candidateExpires
        end
    end

    local countdown = {
        active = true,
        timers = {},
        entries = entries,
    }
    self.activeCountdowns[token] = countdown

    for number = seconds, 1, -1 do
        local countdownNumber = number
        local delay = expires - countdownNumber - GetTime()
        if delay >= -0.2 then
            countdown.timers[#countdown.timers + 1] = C_Timer.NewTimer(max(0, delay), function()
                local state = self.activeCountdowns[token]
                if state and state.active then
                    self:PlayVoiceNumber(voiceReference, countdownNumber)
                end
            end)
        end
    end

    countdown.timers[#countdown.timers + 1] = C_Timer.NewTimer(max(0.1, expires - GetTime() + 0.5), function()
        self:CancelCountdown(token)
    end)
end

function Addon:HandleNSRTTTSCountdown(seconds)
    seconds = tonumber(seconds)
    seconds = seconds and floor(seconds + 0.5)
    if not seconds or seconds < 1 then return false end

    local candidates = self:CollectDueReminderAssignments(seconds)
    if #candidates == 0 then
        self:Debug(("NSRT requested a %d-second numeric countdown, but no due assigned reminder or Encounter Alert was found; leaving NSRT's voice alone."):format(seconds))
        return false
    end

    local groups = {}
    for _, candidate in ipairs(candidates) do
        local voiceKey = self:GetVoiceKey(candidate.assignment)
        local maximum = self:GetMaximumVoiceNumber(candidate.assignment)
        if maximum > 0 then
            local group = groups[voiceKey]
            if not group then
                group = { voiceReference = candidate.assignment, seconds = min(seconds, maximum), candidates = {} }
                groups[voiceKey] = group
            end
            group.candidates[#group.candidates + 1] = candidate
        end
    end

    local intercepted = false
    for _, group in pairs(groups) do
        local first = group.candidates[1]
        local identityName = first.identityName or (first.spellID and ("Spell " .. first.spellID)) or "Encounter alert"
        self.lastReminder = {
            spellID = first.spellID,
            spellName = identityName,
            alertID = first.spellID and nil or first.identityID,
            specID = self:GetCurrentSpecID(),
            countdown = group.seconds,
            receivedAt = GetTime(),
            source = "TTS fallback hook",
        }
        if first.spellID then self:RememberSpell(first.spellID, self:GetCurrentSpecID()) end
        self:Debug(("Intercepted NSRT countdown for %s [%s]; using %s via %s."):format(
            identityName, tostring(first.identityID), self:GetVoiceName(group.voiceReference), tostring(first.reason)))
        self:ScheduleFallbackCountdown(group.candidates, group.voiceReference, group.seconds)
        intercepted = true
    end

    return intercepted
end

function Addon:InstallNSRTCountdownHook()
    if self.nsrtHookInstalled then return true end
    if not NSAPI or type(NSAPI.TTSCountdown) ~= "function" then return false end

    local original = NSAPI.TTSCountdown
    self.originalNSRTTTSCountdown = original
    local addon = self
    NSAPI.TTSCountdown = function(apiOrNumber, maybeNumber)
        local seconds = tonumber(maybeNumber)
        if not seconds and type(apiOrNumber) == "number" then
            seconds = tonumber(apiOrNumber)
        end
        if seconds and addon:HandleNSRTTTSCountdown(seconds) then
            return
        end
        return original(apiOrNumber, maybeNumber)
    end
    self.nsrtHookInstalled = true
    self:Debug("Installed NSRT numeric countdown compatibility hook.")
    return true
end

function Addon:TestAssignedSpell(spellID, seconds)
    spellID = tonumber(spellID)
    seconds = min(max(floor((tonumber(seconds) or 5) + 0.5), 1), 10)
    local specID = self:GetCurrentSpecID()
    local assignment, assignedSpecID, reason = self:GetAssignmentForReminder(specID, spellID)
    if not assignment then
        self:Print(("No compatible assignment found for spell ID %s on the current character."):format(tostring(spellID)))
        return false
    end
    if self:IsMuteVoice(assignment) then
        self:Print(("Spell %s is assigned to Mute countdown; no numbered audio will play."):format(tostring(spellID)))
        return true
    end
    local maximum = self:GetMaximumVoiceNumber(assignment)
    if maximum < 1 then
        self:Print("The assigned voice is unavailable: " .. self:GetVoiceName(assignment))
        return false
    end
    seconds = min(seconds, maximum)
    local voiceReference = assignment
    self:Print(("Testing %s for spell %s using %s (%s, assignment spec %s)."):format(
        seconds .. "-to-1", tostring(spellID), self:GetVoiceName(voiceReference), tostring(reason), tostring(assignedSpecID)))
    for number = seconds, 1, -1 do
        local countdownNumber = number
        C_Timer.After(seconds - countdownNumber, function()
            self:PlayVoiceNumber(voiceReference, countdownNumber)
        end)
    end
    return true
end

function Addon:PrintStatus()
    local counts = self:GetVoiceProviderCounts()
    self:Print(("Debug: %s | Current spec: %s | Theme: %s | Voices: %d BigWigs + %d DBM | Countdown hook: %s | TTS hook: %s"):format(
        tostring(self.debugEnabled == true), tostring(self:GetCurrentSpecID()), tostring(self.db and self.db.theme or "arcane"),
        counts.BIGWIGS or 0, counts.DBM or 0, self.nsrtHookInstalled and "installed" or "missing",
        self.nsrtTTSRenameHookInstalled and "installed" or "missing"))
    if self.lastReminder then
        self:Print(("Last intercepted reminder: %s [%s], countdown %s, via %s."):format(
            tostring(self.lastReminder.spellName), tostring(self.lastReminder.alertID or self.lastReminder.spellID),
            tostring(self.lastReminder.countdown), tostring(self.lastReminder.source or "NSRT callback")))
    else
        self:Print("No assigned NSRT countdown has been intercepted since login/reload.")
    end
end

function Addon:OnNSRTReminderChanged(event, personalReminder, sharedReminder)
    -- CallbackHandler passes the event name before the note strings. Accept the
    -- older direct-call shape as well, since addon interoperability apparently
    -- needs diplomatic immunity from consistent function signatures.
    if event ~= "NSRT_REMINDER_CHANGED" then
        if type(event) == "string" and event:match("^NSRT_ALERT") then
            if self.RefreshOptions then self:RefreshOptions() end
            return
        end
        sharedReminder = personalReminder
        personalReminder = event
    end

    self.loadedNoteCache = self.loadedNoteCache or { personal = "", shared = "" }
    if type(personalReminder) == "string" then self.loadedNoteCache.personal = personalReminder end
    if type(sharedReminder) == "string" then self.loadedNoteCache.shared = sharedReminder end

    -- Do not import every spell ID from a raid note into the current spec. A
    -- shared note naturally contains abilities for many classes, which was the
    -- source of the enormous contaminated dropdown in earlier builds.
    if self.RefreshOptions then self:RefreshOptions() end
end

function Addon:RegisterNSRTCallbacks()
    if not NSAPI or not NSAPI.RegisterCallback then
        self:Debug("NSRT callback API was not found; the TTS compatibility hook will be used instead.")
        return false
    end

    local showOK, showError = pcall(NSAPI.RegisterCallback, self, "NSRT_REMINDER_SHOW", "OnNSRTReminderShow")
    local changedOK, changedError = pcall(NSAPI.RegisterCallback, self, "NSRT_REMINDER_CHANGED", "OnNSRTReminderChanged")
    local alertOK, alertError = pcall(NSAPI.RegisterCallback, self, "NSRT_ALERT_CHANGED", "OnNSRTReminderChanged")
    if not showOK then self:Debug("Could not register NSRT_REMINDER_SHOW: " .. tostring(showError)) end
    if not changedOK then self:Debug("Could not register NSRT_REMINDER_CHANGED: " .. tostring(changedError)) end
    if not alertOK then self:Debug("Could not register NSRT_ALERT_CHANGED: " .. tostring(alertError)) end
    return showOK or changedOK or alertOK
end

function Addon:Initialize()
    if self.initialized then return end
    self.initialized = true

    NSRTCountdownCompanionDB = NSRTCountdownCompanionDB or {}
    local storedSchemaVersion = tonumber(NSRTCountdownCompanionDB.schemaVersion) or 0
    ApplyDefaults(NSRTCountdownCompanionDB, defaults)
    self.db = NSRTCountdownCompanionDB

    if storedSchemaVersion < 3 then
        -- Earlier builds imported every spell ID from the active NSRT raid note
        -- into the current spec. Keep assignments, but discard that polluted
        -- discovery cache so it can be rebuilt from the actual spellbook.
        self.db.knownSpells = {}
    end
    if storedSchemaVersion < 4 then
        -- Versions before 0.2.0 only supported BigWigs, so unlabelled saved
        -- voices are safely migrated to the BigWigs provider.
        for _, spellTable in pairs(self.db.assignments) do
            for _, assignment in pairs(spellTable) do
                if type(assignment) == "table" and not assignment.provider then
                    assignment.provider = self.VOICE_PROVIDER_BIGWIGS
                end
            end
        end
    end
    if storedSchemaVersion < 5 then
        -- Debug diagnostics are intentionally session-only from 0.2.4 onward.
        self.db.debug = nil
    end
    if storedSchemaVersion < 6 then
        self.db.encounterAssignments = self.db.encounterAssignments or {}
    end
    if storedSchemaVersion < 7 then
        self.db.noteAssignments = self.db.noteAssignments or {}
    end
    if storedSchemaVersion < 8 then
        -- 0.4.2 adds an explicit per-assignment mute provider. Existing saved
        -- voice assignments require no conversion.
    end
    if storedSchemaVersion < 9 then
        -- 0.4.3 removes the global enable toggle. Installing the addon now
        -- means its configured assignments are always active.
        self.db.enabled = nil
    end
    if storedSchemaVersion < 10 then
        -- 0.4.5 introduces selectable interface themes. The approved muted
        -- arcane palette is the default for both existing and new installs.
        self.db.theme = "arcane"
    end
    if storedSchemaVersion < 11 then
        -- 0.5.2 adds independent per-ability TTS rename mappings.
        self.db.abilityRenames = self.db.abilityRenames or {}
    end
    if storedSchemaVersion < 12 then
        -- 0.5.4 extends Current Note overrides with an independent opening-TTS mute flag.
        self.db.noteAssignments = self.db.noteAssignments or {}
    end
    if storedSchemaVersion < 13 then
        -- 0.5.5 replaces the boolean opening-TTS mute with a three-state mode
        -- and adds optional per-reminder custom spoken text.
        for _, assignment in pairs(self.db.noteAssignments or {}) do
            if type(assignment) == "table" and assignment.muteTTS == true and not assignment.ttsMode then
                assignment.ttsMode = "mute"
            end
            if type(assignment) == "table" then assignment.muteTTS = nil end
        end
    end
    self.db.schemaVersion = 13
    self.debugEnabled = false

    self:RegisterNSRTCallbacks()
    if not self:InstallNSRTCountdownHook() then
        C_Timer.After(1, function() self:InstallNSRTCountdownHook() end)
    end
    if not self:InstallNSRTTTSRenameHook() then
        C_Timer.After(1, function() self:InstallNSRTTTSRenameHook() end)
    end
    C_Timer.After(1, function() self:ScanCurrentSpellbook() end)

    SLASH_NSRTCOUNTDOWNCOMPANION1 = "/nsrtcc"
    SLASH_NSRTCOUNTDOWNCOMPANION2 = "/ncc"
    SlashCmdList.NSRTCOUNTDOWNCOMPANION = function(message)
        local command, rest = tostring(message or ""):match("^%s*(%S*)%s*(.-)%s*$")
        command = command and command:lower() or ""
        if command == "debug" then
            self.debugEnabled = not self.debugEnabled
            self:Print("Debug output " .. (self.debugEnabled and "enabled for this session." or "disabled."))
        elseif command == "status" then
            self:PrintStatus()
        elseif command == "test" then
            local spellID, seconds = rest:match("^(%d+)%s*(%d*)$")
            self:TestAssignedSpell(spellID, seconds ~= "" and seconds or 5)
        elseif command == "help" then
            self:Print("Commands: /ncc, /ncc debug, /ncc status, /ncc test <spellID> [seconds]")
        else
            self:ToggleOptions()
        end
    end
end

local eventFrame = CreateFrame("Frame")
eventFrame:RegisterEvent("ADDON_LOADED")
eventFrame:SetScript("OnEvent", function(_, event, ...)
    if event == "ADDON_LOADED" then
        local loadedAddon = ...
        if loadedAddon ~= addonName then return end
        Addon:Initialize()
        eventFrame:RegisterEvent("PLAYER_LOGIN")
        eventFrame:RegisterEvent("PLAYER_SPECIALIZATION_CHANGED")
        eventFrame:RegisterEvent("SPELLS_CHANGED")
        eventFrame:RegisterEvent("ENCOUNTER_END")
        eventFrame:RegisterEvent("PLAYER_ENTERING_WORLD")
    elseif event == "PLAYER_LOGIN" or event == "SPELLS_CHANGED" then
        C_Timer.After(0.5, function()
            Addon:InstallNSRTCountdownHook()
            Addon:InstallNSRTTTSRenameHook()
            Addon:ScanCurrentSpellbook()
        end)
    elseif event == "PLAYER_SPECIALIZATION_CHANGED" then
        local unit = ...
        if unit == "player" then
            C_Timer.After(0.5, function() Addon:ScanCurrentSpellbook() end)
        end
    elseif event == "ENCOUNTER_END" or event == "PLAYER_ENTERING_WORLD" then
        Addon:CancelAllCountdowns()
    end
end)