Bootstrap.lua

local ADDON_NAME, ns = ...

ns.ADDON_NAME = ADDON_NAME
-- One shared texture keeps the addon's header, minimap button, compartment
-- entry, and packaged metadata visually aligned.
ns.ICON_TEXTURE = "Interface\\AddOns\\Resonance\\Assets\\ResonanceIcon"
ns.GENERIC_ICON_TEXTURE = "Interface\\Icons\\INV_Misc_Rune_01"
local getMetadata = C_AddOns and C_AddOns.GetAddOnMetadata or GetAddOnMetadata
ns.VERSION = (type(getMetadata) == "function" and getMetadata("Resonance", "Version")) or "1.1.0"
ns.COLOR = "|cff9d7cff"
ns.GENERIC_SPEC_ID = 0
ns.SPEC_ORDER = {
    ns.GENERIC_SPEC_ID,
    71, 72, 73,       -- Warrior
    65, 66, 70,       -- Paladin
    253, 254, 255,    -- Hunter
    259, 260, 261,    -- Rogue
    256, 257, 258,    -- Priest
    250, 251, 252,    -- Death Knight
    262, 263, 264,    -- Shaman
    62, 63, 64,       -- Mage
    265, 266, 267,    -- Warlock
    268, 269, 270,    -- Monk
    102, 103, 104, 105, -- Druid
    577, 581, 1480,   -- Demon Hunter
    1467, 1468, 1473, -- Evoker
}
ns.SUPPORTED_SPECS = {
    [ns.GENERIC_SPEC_ID] = "Generic",
    [71] = "Arms Warrior",
    [72] = "Fury Warrior",
    [73] = "Protection Warrior",
    [65] = "Holy Paladin",
    [66] = "Protection Paladin",
    [70] = "Retribution Paladin",
    [253] = "Beast Mastery Hunter",
    [254] = "Marksmanship Hunter",
    [255] = "Survival Hunter",
    [259] = "Assassination Rogue",
    [260] = "Outlaw Rogue",
    [261] = "Subtlety Rogue",
    [256] = "Discipline Priest",
    [257] = "Holy Priest",
    [258] = "Shadow Priest",
    [250] = "Blood Death Knight",
    [251] = "Frost Death Knight",
    [252] = "Unholy Death Knight",
    [262] = "Elemental Shaman",
    [263] = "Enhancement Shaman",
    [264] = "Restoration Shaman",
    [62] = "Arcane Mage",
    [63] = "Fire Mage",
    [64] = "Frost Mage",
    [265] = "Affliction Warlock",
    [266] = "Demonology Warlock",
    [267] = "Destruction Warlock",
    [268] = "Brewmaster Monk",
    [269] = "Windwalker Monk",
    [270] = "Mistweaver Monk",
    [102] = "Balance Druid",
    [103] = "Feral Druid",
    [104] = "Guardian Druid",
    [105] = "Restoration Druid",
    [577] = "Havoc Demon Hunter",
    [581] = "Vengeance Demon Hunter",
    [1480] = "Devourer Demon Hunter",
    [1467] = "Devastation Evoker",
    [1468] = "Preservation Evoker",
    [1473] = "Augmentation Evoker",
}
-- Increment whenever curated built-in layers change. Existing untouched
-- built-ins then refresh on reload; personal and saved sets remain intact.
ns.BUILTIN_SET_VERSION = 10
ns.PROFILE_SCHEMA_VERSION = 1
ns.RULE_CATALOG_VERSION = 6
ns.SOUND_CATALOG_VERSION = 4
ns.CURATED_PRESETS = {
    { key = "subtle", name = "Resonance Subtle" },
    { key = "medium", name = "Resonance Medium" },
    { key = "expressive", name = "Resonance Expressive" },
}

local DEFAULTS = {
    version = 8,
    enabled = true,
    palette = "subtle",
    channel = "SFX",
    specEnabled = {},
    ruleOverrides = {},
    ruleSettings = {},
    specProfiles = {},
    favorites = {},
    soundSortDebug = false,
    categoryDraft = {},
    deleteDraft = {},
    categoryExport = nil,
    minimap = {
        hide = false,
        angle = 225,
    },
    debug = false,
    soloMode = false,
    tutorial = {
        completedVersion = 0,
        lastStep = 1,
    },
}

for specID in pairs(ns.SUPPORTED_SPECS) do
    DEFAULTS.specEnabled[specID] = true
end

local CHARACTER_DEFAULTS = {
    version = 9,
    specs = {},
}

ns.DEFAULTS = DEFAULTS
ns.Runtime = {
    capabilities = { hasSpellID = {}, rankBySpellID = {} },
    activeRules = {},
    eventSpellRules = {},
    lastRulePlay = {},
    refreshQueued = false,
    castingSoundGeneration = 0,
    castingSoundHandles = {},
    castingSoundTimers = {},
    delayedSoundGeneration = 0,
    delayedSoundTimers = {},
    previewGeneration = 0,
    previewTimers = {},
    resolvedSoundCache = {},
}

-- Rule layers are edited in place, but profile loads/resets can replace the
-- whole working tree. Keep the derived sound descriptors and any queued
-- delayed playback in sync at the mutation boundary instead of waiting for
-- the next zero-delay refresh callback.
function ns:InvalidateRuntimeAudio(cancelDelayed)
    self.Runtime.resolvedSoundCache = {}
    if cancelDelayed and self.CancelDelayedSoundTimers then
        self:CancelDelayedSoundTimers()
    end
end

local function CopyDefaults(source)
    local result = {}
    for key, value in pairs(source) do
        if type(value) == "table" then
            result[key] = CopyDefaults(value)
        else
            result[key] = value
        end
    end
    return result
end

local function FillDefaults(target, source)
    for key, value in pairs(source) do
        if target[key] == nil then
            target[key] = type(value) == "table" and CopyDefaults(value) or value
        elseif type(value) == "table" and type(target[key]) == "table" then
            FillDefaults(target[key], value)
        end
    end
end

-- Compatibility registries are intentionally permanent. Never reuse a retired
-- rule ID for another spell; point it at its successor here instead. Removed
-- sounds should be remapped here or retained as hidden catalog tombstones.
local SOUND_ID_REMAP = {
    [1884443] = 568175, -- encrypted Avenging Wrath revamp take -> verified legacy impact
}
local RULE_ID_ALIASES = {}
local CATEGORY_ID_ALIASES = {}
ns.SoundIDRemap = SOUND_ID_REMAP
ns.RuleIDAliases = RULE_ID_ALIASES
ns.CategoryIDAliases = CATEGORY_ID_ALIASES

local function ResolveAlias(mapping, value)
    local seen = {}
    while mapping[value] ~= nil and not seen[value] do
        seen[value] = true
        value = mapping[value]
    end
    return value
end

local function ValidateAliasMap(name, mapping)
    for start in pairs(mapping) do
        local seen, value = {}, start
        while mapping[value] ~= nil do
            if seen[value] then
                error("Resonance " .. name .. " alias cycle at " .. tostring(value))
            end
            seen[value] = true
            value = mapping[value]
        end
    end
end

local function ValidateCompatibilityRegistries(owner)
    ValidateAliasMap("sound", SOUND_ID_REMAP)
    ValidateAliasMap("rule", RULE_ID_ALIASES)
    ValidateAliasMap("category", CATEGORY_ID_ALIASES)

    local validCategories = {}
    for _, category in ipairs(owner.SoundCategories or {}) do validCategories[category.id] = true end
    for oldID in pairs(SOUND_ID_REMAP) do
        local target = ResolveAlias(SOUND_ID_REMAP, oldID)
        if not (owner.SoundByID and owner.SoundByID[target]) then
            owner:Print("Compatibility warning: sound " .. oldID .. " maps to missing " .. tostring(target))
        end
    end
    for oldID in pairs(RULE_ID_ALIASES) do
        local target = ResolveAlias(RULE_ID_ALIASES, oldID)
        if not (owner.RuleByID and owner.RuleByID[target]) then
            owner:Print("Compatibility warning: rule " .. oldID .. " maps to missing " .. tostring(target))
        end
    end
    for oldID in pairs(CATEGORY_ID_ALIASES) do
        local target = ResolveAlias(CATEGORY_ID_ALIASES, oldID)
        if not validCategories[target] then
            owner:Print("Compatibility warning: category " .. oldID .. " maps to missing " .. tostring(target))
        end
    end
end

local function RemapNumericKeyedTable(source)
    if type(source) ~= "table" then return {} end
    local migrated = {}
    -- Canonical keys win if an old and a new identifier coexist.
    for key, value in pairs(source) do
        local soundID = tonumber(key)
        if not soundID or ResolveAlias(SOUND_ID_REMAP, soundID) == soundID then
            migrated[soundID or key] = value
        end
    end
    for key, value in pairs(source) do
        local soundID = tonumber(key)
        if soundID then
            local resolved = ResolveAlias(SOUND_ID_REMAP, soundID)
            if migrated[resolved] == nil then migrated[resolved] = value end
        end
    end
    return migrated
end

local function NormalizeAccountSoundReferences(database)
    database.favorites = RemapNumericKeyedTable(database.favorites)
    database.categoryDraft = RemapNumericKeyedTable(database.categoryDraft)
    database.deleteDraft = RemapNumericKeyedTable(database.deleteDraft)
    if type(database.categoryExport) == "table" then
        local export = database.categoryExport
        local hadCompactMaps = type(export.moves) == "table" or type(export.deletions) == "table"
        if not hadCompactMaps and type(export.sounds) == "table" then
            export.moves, export.deletions = {}, {}
            for _, entry in ipairs(export.sounds) do
                if type(entry) == "table" and tonumber(entry.id) then
                    local soundID = ResolveAlias(SOUND_ID_REMAP, tonumber(entry.id))
                    local categoryID = ResolveAlias(CATEGORY_ID_ALIASES, entry.category)
                    local canonical = ns.SoundByID and ns.SoundByID[soundID]
                    if canonical and categoryID and categoryID ~= canonical.category then
                        export.moves[soundID] = categoryID
                    end
                    if entry.deleted then export.deletions[soundID] = true end
                end
            end
        else
            export.moves = RemapNumericKeyedTable(export.moves)
            export.deletions = RemapNumericKeyedTable(export.deletions)
        end
        for soundID, categoryID in pairs(export.moves) do
            export.moves[soundID] = ResolveAlias(CATEGORY_ID_ALIASES, categoryID)
        end
        if type(export.sounds) == "table" then
            for _, sound in ipairs(export.sounds) do
                if type(sound) == "table" and tonumber(sound.id) then
                    sound.id = ResolveAlias(SOUND_ID_REMAP, tonumber(sound.id))
                    sound.category = ResolveAlias(CATEGORY_ID_ALIASES, sound.category)
                end
            end
        end
    end

    local validCategories = {}
    for _, category in ipairs(ns.SoundCategories or {}) do validCategories[category.id] = true end
    database.legacyCategoryDraft = type(database.legacyCategoryDraft) == "table"
        and database.legacyCategoryDraft or {}
    for soundID, categoryID in pairs(database.categoryDraft) do
        local migratedCategory = ResolveAlias(CATEGORY_ID_ALIASES, categoryID)
        if validCategories[migratedCategory] then
            database.categoryDraft[soundID] = migratedCategory
        else
            -- Preserve the old value for a future alias while returning the
            -- sound to its canonical category instead of hiding it.
            database.legacyCategoryDraft[soundID] = categoryID
            database.categoryDraft[soundID] = nil
        end
    end

    -- Once a user draft has been canonized in the shipped catalog, retire its
    -- staging records automatically. Removed sounds likewise leave no stale
    -- red/deletion state behind after the next reload.
    for soundID, categoryID in pairs(database.categoryDraft) do
        local sound = ns.SoundByID and ns.SoundByID[tonumber(soundID)]
        if not sound or categoryID == sound.category then database.categoryDraft[soundID] = nil end
    end
    for soundID in pairs(database.deleteDraft) do
        if not (ns.SoundByID and ns.SoundByID[tonumber(soundID)]) then database.deleteDraft[soundID] = nil end
    end
    local export = database.categoryExport
    if type(export) == "table" then
        for soundID, categoryID in pairs(export.moves or {}) do
            local sound = ns.SoundByID and ns.SoundByID[tonumber(soundID)]
            if not sound or categoryID == sound.category then export.moves[soundID] = nil end
        end
        for soundID in pairs(export.deletions or {}) do
            if not (ns.SoundByID and ns.SoundByID[tonumber(soundID)]) then export.deletions[soundID] = nil end
        end
    end
end

local ACCOUNT_MIGRATIONS = {
    [6] = function() end, -- Introduced ordered migrations and compatibility metadata.
    [7] = function(database) -- Interactive tutorial progress; no profile data changes.
        if type(database.tutorial) ~= "table" then database.tutorial = {} end
    end,
    [8] = function(database) -- Debug sorting is always opt-in after this update.
        database.soundSortDebug = false
    end,
    [9] = function() end, -- Individual hearthstone settings migrate per sound set.
}

local function RunOrderedMigrations(database, previousVersion, currentVersion, migrations)
    previousVersion = math.max(0, math.floor(tonumber(previousVersion) or 0))
    for version = previousVersion + 1, currentVersion do
        local migrate = migrations[version]
        if migrate then migrate(database) end
        -- Advance one step at a time. If a later migration errors, WoW will not
        -- falsely claim the database reached a schema it never completed.
        database.version = version
    end
end

local function MigrateAccountDatabase(database, previousVersion)
    if previousVersion > DEFAULTS.version then return end
    RunOrderedMigrations(database, previousVersion, DEFAULTS.version, ACCOUNT_MIGRATIONS)
    -- Identifier aliases may grow without changing the surrounding table shape.
    NormalizeAccountSoundReferences(database)
    database.version = DEFAULTS.version
end

function ns:InitializeDatabase()
    ValidateCompatibilityRegistries(self)
    local previousAccountVersion
    if type(ResonanceDB) ~= "table" then
        ResonanceDB = CopyDefaults(DEFAULTS)
        previousAccountVersion = DEFAULTS.version
    else
        previousAccountVersion = tonumber(ResonanceDB.version) or 0
        MigrateAccountDatabase(ResonanceDB, previousAccountVersion)
        if type(ResonanceDB.specEnabled) ~= "table" then ResonanceDB.specEnabled = {} end
        if type(ResonanceDB.ruleOverrides) ~= "table" then ResonanceDB.ruleOverrides = {} end
        if type(ResonanceDB.ruleSettings) ~= "table" then ResonanceDB.ruleSettings = {} end
        if type(ResonanceDB.specProfiles) ~= "table" then ResonanceDB.specProfiles = {} end
        if type(ResonanceDB.favorites) ~= "table" then ResonanceDB.favorites = {} end
        if type(ResonanceDB.categoryDraft) ~= "table" then ResonanceDB.categoryDraft = {} end
        if type(ResonanceDB.deleteDraft) ~= "table" then ResonanceDB.deleteDraft = {} end
        if type(ResonanceDB.minimap) ~= "table" then ResonanceDB.minimap = {} end
        FillDefaults(ResonanceDB, DEFAULTS)
    end

    if not self.SoundPalettes[ResonanceDB.palette] then ResonanceDB.palette = DEFAULTS.palette end
    -- Density was a runtime filter before 1.1. Presets now own actual rule toggles.
    ResonanceDB.density = nil
    if ResonanceDB.channel ~= "SFX" and ResonanceDB.channel ~= "Dialog" and ResonanceDB.channel ~= "Master" then
        ResonanceDB.channel = DEFAULTS.channel
    end
    if type(ResonanceDB.enabled) ~= "boolean" then ResonanceDB.enabled = DEFAULTS.enabled end
    -- Debug controls are intentionally unavailable in this release. Always
    -- fail closed here so an old saved toggle cannot continue spamming chat
    -- after the UI that controlled it has been tucked away.
    ResonanceDB.debug = false
    if type(ResonanceDB.soloMode) ~= "boolean" then ResonanceDB.soloMode = false end
    -- Keep category drafts themselves, but clear the dormant editor mode.
    ResonanceDB.soundSortDebug = false
    for specID, defaultValue in pairs(DEFAULTS.specEnabled) do
        if type(ResonanceDB.specEnabled[specID]) ~= "boolean" then
            ResonanceDB.specEnabled[specID] = defaultValue
        end
    end
    for ruleID, enabled in pairs(ResonanceDB.ruleOverrides) do
        if type(ruleID) ~= "string" or type(enabled) ~= "boolean" then
            ResonanceDB.ruleOverrides[ruleID] = nil
        end
    end
    self:InitializeProfiles(previousAccountVersion)
    self:InitializeCharacterProfiles()
    if type(ResonanceDB.minimap.hide) ~= "boolean" then ResonanceDB.minimap.hide = DEFAULTS.minimap.hide end
    if type(ResonanceDB.minimap.angle) ~= "number" then ResonanceDB.minimap.angle = DEFAULTS.minimap.angle end

    if (tonumber(ResonanceDB.version) or 0) < DEFAULTS.version then
        ResonanceDB.version = DEFAULTS.version
    end

    self.DB = ResonanceDB
    self.CharDB = ResonanceCharDB
end

function ns:InitializeProfiles(previousVersion)
    local hadLegacy = next(ResonanceDB.ruleOverrides or {}) ~= nil or next(ResonanceDB.ruleSettings or {}) ~= nil
    for specID in pairs(self.SUPPORTED_SPECS) do
        local store = ResonanceDB.specProfiles[specID]
        if type(store) ~= "table" then
            store = { active = hadLegacy and "Migrated" or "Default", profiles = {} }
            ResonanceDB.specProfiles[specID] = store
        end
        if type(store.profiles) ~= "table" then store.profiles = {} end
        if type(store.active) ~= "string" or store.active == "" then store.active = "Default" end
        if type(store.profiles[store.active]) ~= "table" then
            store.profiles[store.active] = { rules = {} }
        end
        for name, profile in pairs(store.profiles) do
            if type(name) ~= "string" or type(profile) ~= "table" then
                store.profiles[name] = nil
            elseif type(profile.rules) ~= "table" then
                profile.rules = {}
            end
        end
    end

    if (tonumber(previousVersion) or 0) < 3 and hadLegacy then
        for ruleID, rule in pairs(self.RuleByID or {}) do
            local legacyEnabled = ResonanceDB.ruleOverrides[ruleID]
            local legacy = ResonanceDB.ruleSettings[ruleID]
            if legacyEnabled ~= nil or type(legacy) == "table" then
                local profile = ResonanceDB.specProfiles[rule.spec].profiles.Migrated
                profile.rules[ruleID] = profile.rules[ruleID] or {}
                profile.rules[ruleID].enabled = legacyEnabled
                if legacy and legacy.layers == 2 then profile.rules[ruleID].layerCount = 2 end
            end
        end
    end
end

local function DeepCopy(source)
    if type(source) ~= "table" then return source end
    local copy = {}
    for key, value in pairs(source) do copy[key] = DeepCopy(value) end
    return copy
end

-- Grouped hearthstone cards became one stable card per toy/item. This is a
-- one-to-many profile migration, so it cannot use the normal ID alias map.
local function ExpandHearthstoneGroupRules(set)
    if type(set) ~= "table" or type(set.rules) ~= "table" then return end
    for legacyID, targetIDs in pairs(ns.HearthstoneGroupRuleExpansions or {}) do
        local oldCast = set.rules[legacyID]
        local oldCasting = set.rules[legacyID .. "_casting"]
        if type(targetIDs) == "table" then
            for _, targetID in ipairs(targetIDs) do
                if type(oldCast) == "table" and set.rules[targetID] == nil then
                    set.rules[targetID] = DeepCopy(oldCast)
                end
                if type(oldCasting) == "table" and set.rules[targetID .. "_casting"] == nil then
                    set.rules[targetID .. "_casting"] = DeepCopy(oldCasting)
                end
            end
        end
        set.rules[legacyID] = nil
        set.rules[legacyID .. "_casting"] = nil
    end
end

-- Individual Hearthstone cards use the normal two editable slots unless the
-- player actually added another sound. Older family cards could carry an
-- unused third placeholder into every expanded card; remove only genuinely
-- empty optional slots, never a selected (even disabled) layer.
local function TrimEmptyHearthstoneLayers(set)
    if type(set) ~= "table" or type(set.rules) ~= "table" then return end
    for ruleID, config in pairs(set.rules) do
        local rule = ns.RuleByID and ns.RuleByID[ruleID]
        if rule and rule.hearthstoneItemID and type(config) == "table" and type(config.layers) == "table" then
            local layerCount = math.max(2, math.floor(tonumber(config.layerCount) or 2))
            while layerCount > 2 do
                local layer = config.layers[layerCount]
                if type(layer) == "table" and tonumber(layer.soundID) and tonumber(layer.soundID) > 0 then
                    break
                end
                config.layers[layerCount] = nil
                layerCount = layerCount - 1
            end
            config.layerCount = layerCount
        end
    end
end

-- Crystal lift is a short pickup chime, not an Arcantina teleport texture.
-- Replace the bundled Casting accent with a longer power-source resonance and
-- its old completion accent with a compact spark impact. This preserves each
-- layer's enabled state and timing.
local function RefreshArcantinaCastingAccent(set)
    local rules = type(set) == "table" and set.rules
    if type(rules) ~= "table" then return end
    local replacements = {
        generic_arcantina = 2428623,
        generic_arcantina_casting = 566646,
    }
    for ruleID, replacementID in pairs(replacements) do
        local config = rules[ruleID]
        if type(config) == "table" and type(config.layers) == "table" then
            for _, layer in pairs(config.layers) do
                if type(layer) == "table" and tonumber(layer.soundID) == 4580313 then
                    layer.soundID = replacementID
                    layer.soundKind = "file"
                    layer.soundLabel = nil
                    layer.missingSound = nil
                end
            end
        end
    end
end

local function RemapSetSounds(set)
    if type(set) ~= "table" or type(set.rules) ~= "table" then return end
    for _, config in pairs(set.rules) do
        if type(config) == "table" and type(config.layers) == "table" then
            for _, layer in pairs(config.layers) do
                if type(layer) == "table" and tonumber(layer.soundID) then
                    layer.soundID = ResolveAlias(SOUND_ID_REMAP, tonumber(layer.soundID))
                end
            end
        end
    end
end

local function NormalizeProfileSet(set, allowNewRuleDefaults)
    if type(set) ~= "table" then return end
    if type(set.rules) ~= "table" then set.rules = {} end
    ExpandHearthstoneGroupRules(set)
    TrimEmptyHearthstoneLayers(set)
    RefreshArcantinaCastingAccent(set)

    local migratedRules = {}
    -- Keep an already-current configuration if both old and new IDs exist.
    for ruleID, config in pairs(set.rules) do
        if ResolveAlias(RULE_ID_ALIASES, ruleID) == ruleID then
            migratedRules[ruleID] = config
        end
    end
    for ruleID, config in pairs(set.rules) do
        local resolved = ResolveAlias(RULE_ID_ALIASES, ruleID)
        if migratedRules[resolved] == nil then
            migratedRules[resolved] = config
        end
    end
    set.rules = migratedRules

    for _, config in pairs(set.rules) do
        if type(config) == "table" and type(config.layers) == "table" then
            for _, layer in pairs(config.layers) do
                if type(layer) == "table" and tonumber(layer.soundID) then
                    local soundID = tonumber(layer.soundID)
                    layer.soundID = ResolveAlias(SOUND_ID_REMAP, soundID)
                    local sound = ns.SoundByID and ns.SoundByID[layer.soundID]
                    if sound then
                        layer.soundKind = sound.kind or "file"
                        layer.soundLabel = sound.label
                        layer.missingSound = nil
                    else
                        -- Keep the original choice recoverable, but mark it so
                        -- runtime playback can fail closed until it is restored
                        -- or explicitly remapped in a future migration.
                        layer.soundKind = layer.soundKind or "file"
                        layer.soundLabel = layer.soundLabel or ("Sound " .. layer.soundID)
                        layer.missingSound = true
                    end
                end
            end
        end
    end

    set.schemaVersion = math.max(tonumber(set.schemaVersion) or 0, ns.PROFILE_SCHEMA_VERSION)
    set.ruleCatalogVersion = math.max(tonumber(set.ruleCatalogVersion) or 0, ns.RULE_CATALOG_VERSION)
    set.soundCatalogVersion = math.max(tonumber(set.soundCatalogVersion) or 0, ns.SOUND_CATALOG_VERSION)
    if set.ruleFallback == nil then
        set.ruleFallback = allowNewRuleDefaults and "current-defaults" or "disabled"
    end
end

local function FreezeProfileSet(set, specID, includeMissingRules)
    if type(set) ~= "table" then return end
    if type(set.rules) ~= "table" then set.rules = {} end
    ExpandHearthstoneGroupRules(set)
    for _, rule in ipairs(ns.RulesBySpec[specID] or {}) do
        local existing = set.rules[rule.id]
        if existing ~= nil or includeMissingRules then
            local config = type(existing) == "table" and existing or {}
            set.rules[rule.id] = config
            if type(config.enabled) ~= "boolean" then
                config.enabled = set.ruleFallback == "disabled" and false or rule.defaultOn == true
            end
            if type(config.layers) ~= "table" then config.layers = {} end

            local layerCount = tonumber(config.layerCount)
            if not layerCount then
                layerCount = math.max(2, #(rule.defaultSounds or {}))
                for index in pairs(config.layers) do
                    if type(index) == "number" and index > layerCount then layerCount = index end
                end
            end
            layerCount = math.max(2, math.min(ns.MAX_RULE_LAYERS or 8, math.floor(layerCount)))
            config.layerCount = layerCount
            for index = 1, layerCount do
                local layer = config.layers[index]
                local defaultSound = rule.defaultSounds and rule.defaultSounds[index]
                local defaultDelay = rule.defaultDelays and tonumber(rule.defaultDelays[index])
                    or (index == 1 and math.floor((rule.delay or 0) * 1000 + 0.5) or 0)
                if type(layer) ~= "table" then
                    layer = {
                        enabled = defaultSound ~= nil,
                        soundID = defaultSound or false,
                        delayMs = defaultDelay,
                    }
                    config.layers[index] = layer
                else
                    if type(layer.enabled) ~= "boolean" then layer.enabled = defaultSound ~= nil end
                    if layer.soundID == nil then layer.soundID = defaultSound or false end
                    if tonumber(layer.delayMs) == nil then layer.delayMs = defaultDelay end
                end
            end
            for index in pairs(config.layers) do
                if type(index) == "number" and index > layerCount then config.layers[index] = nil end
            end
        end
    end
    set.ruleFallback = "disabled"
end

local CHARACTER_STORE_MIGRATIONS = {
    [4] = function(store, specID)
        for _, set in pairs(store.savedSets or {}) do
            if type(set) == "table" and set.builtin ~= true then
                -- Generated sets already stored explicit toggles. Ambiguous
                -- sparse legacy entries fail closed instead of inheriting a
                -- possibly changed default from the new addon release.
                set.ruleFallback = "disabled"
                FreezeProfileSet(set, specID, false)
                NormalizeProfileSet(set, false)
            end
        end
        local loadedSet = store.loadedName and store.savedSets and store.savedSets[store.loadedName]
        if type(store.working) == "table" and not (loadedSet and loadedSet.builtin == true) then
            store.working.ruleFallback = "disabled"
            FreezeProfileSet(store.working, specID, false)
            NormalizeProfileSet(store.working, false)
        end
    end,
    [5] = function(store)
        -- Before v5, loadedName doubled as the dirty flag: every edit cleared
        -- it. Preserve that meaning once, then keep the source set name and a
        -- separate dirty bit from this version onward.
        if type(store.dirty) ~= "boolean" then
            store.dirty = store.loadedName == nil
        end
    end,
    [6] = function(store)
        -- The personal set name is created lazily on the first edit.
        -- Keep older character/spec stores untouched until then.
        if store.autoSaveName ~= nil and type(store.autoSaveName) ~= "string" then
            store.autoSaveName = nil
        end
    end,
    [7] = function(store)
        -- v7 replaces rolling auto-saves with one first-edit personal set.
        -- Existing automatic rows are reused and refreshed on that first edit.
        store.personalSetInitialized = false
    end,
    [8] = function(store, specID)
        -- The Generic tab is a normal per-character store shared by every
        -- specialization. Its profile is created by the standard initializer.
        if specID == ns.GENERIC_SPEC_ID and type(store.personalSetInitialized) ~= "boolean" then
            store.personalSetInitialized = false
        end
    end,
}

local function RunCharacterStoreMigrations(store, specID, previousVersion)
    previousVersion = math.max(0, math.floor(tonumber(previousVersion) or 0))
    for version = previousVersion + 1, CHARACTER_DEFAULTS.version do
        local migrate = CHARACTER_STORE_MIGRATIONS[version]
        if migrate then migrate(store, specID) end
    end
end

local PRESET_RANK = { subtle = 1, medium = 2, expressive = 3 }

local function BuildCuratedPreset(specID, presetKey)
    local targetRank = PRESET_RANK[presetKey] or 2
    local preset = {
        rules = {}, builtin = true, builtinVersion = ns.BUILTIN_SET_VERSION, preset = presetKey,
        schemaVersion = ns.PROFILE_SCHEMA_VERSION,
        ruleCatalogVersion = ns.RULE_CATALOG_VERSION,
        soundCatalogVersion = ns.SOUND_CATALOG_VERSION,
        ruleFallback = "current-defaults",
    }
    for _, rule in ipairs(ns.RulesBySpec[specID] or {}) do
        local curated = ns.CuratedRulePresets and ns.CuratedRulePresets[rule.id]
        local curatedPreset = curated and curated[presetKey]
        if type(curatedPreset) == "table" then
            local config = { enabled = curatedPreset.enabled == true, layers = {} }
            local layerCount = math.max(2, #(rule.defaultSounds or {}), #(curatedPreset.layers or {}))
            for index = 1, math.min(ns.MAX_RULE_LAYERS or 8, layerCount) do
                local source = curatedPreset.layers and curatedPreset.layers[index]
                if type(source) == "table" and tonumber(source.soundID) and ns.SoundByID[tonumber(source.soundID)] then
                    config.layers[index] = {
                        enabled = source.enabled ~= false,
                        soundID = tonumber(source.soundID),
                        delayMs = math.max(0, math.min(5000, math.floor(tonumber(source.delayMs) or 0))),
                    }
                else
                    config.layers[index] = { enabled = false, soundID = false, delayMs = 0 }
                end
            end
            preset.rules[rule.id] = config
        else
            -- Compatibility fallback for rules awaiting a dedicated curation.
            local ruleRank = PRESET_RANK[rule.preset]
            local enabled = false
            if rule.defaultOn and ruleRank and ruleRank <= targetRank then
                enabled = true
            elseif presetKey == "expressive" and rule.preset ~= "custom" then
                enabled = true
            end
            preset.rules[rule.id] = { enabled = enabled }
        end
    end
    return preset
end

function ns:InitializeCharacterProfiles()
    local previousCharacterVersion
    if type(ResonanceCharDB) ~= "table" then
        ResonanceCharDB = CopyDefaults(CHARACTER_DEFAULTS)
        previousCharacterVersion = CHARACTER_DEFAULTS.version
    else
        previousCharacterVersion = tonumber(ResonanceCharDB.version) or 0
    end
    if type(ResonanceCharDB.specs) ~= "table" then ResonanceCharDB.specs = {} end
    for specID in pairs(self.SUPPORTED_SPECS) do
        local store = ResonanceCharDB.specs[specID]
        local createdStore = type(store) ~= "table"
        local legacyStore = ResonanceDB.specProfiles and ResonanceDB.specProfiles[specID]
        local legacyProfile = legacyStore and legacyStore.profiles and legacyStore.profiles[legacyStore.active]
        local hasLegacyProfile = type(legacyProfile) == "table" and type(legacyProfile.rules) == "table"
            and next(legacyProfile.rules) ~= nil
        if type(store) ~= "table" then
            store = { working = nil, savedSets = {}, loadedName = nil, dirty = false }
            ResonanceCharDB.specs[specID] = store
        end
        if type(store.savedSets) ~= "table" then store.savedSets = {} end
        if createdStore and type(store.dirty) ~= "boolean" then store.dirty = false end
        if type(store.working) ~= "table" then
            store.working = hasLegacyProfile and DeepCopy(legacyProfile) or { rules = {} }
        end
        if type(store.working.rules) ~= "table" then store.working.rules = {} end
        RemapSetSounds(store.working)
        for name, set in pairs(store.savedSets) do
            if type(name) ~= "string" or type(set) ~= "table" then
                store.savedSets[name] = nil
            elseif type(set.rules) ~= "table" then
                set.rules = {}
            end
            RemapSetSounds(set)
            NormalizeProfileSet(set, set.builtin == true)
        end
        local oldBase = store.savedSets["Resonance Base"]
        if type(oldBase) == "table" and oldBase.builtin == true then
            store.savedSets["Resonance Base"] = nil
            if store.loadedName == "Resonance Base" then store.loadedName = nil end
        end
        local refreshLoadedBuiltin
        for _, definition in ipairs(self.CURATED_PRESETS) do
            local existing = store.savedSets[definition.name]
            if existing == nil or (type(existing) == "table" and existing.builtin == true
                and (tonumber(existing.builtinVersion) or 0) < self.BUILTIN_SET_VERSION) then
                store.savedSets[definition.name] = BuildCuratedPreset(specID, definition.key)
                if store.loadedName == definition.name then refreshLoadedBuiltin = definition.name end
            end
        end
        if createdStore then
            if hasLegacyProfile then
                store.savedSets.Migrated = DeepCopy(store.working)
                store.loadedName = "Migrated"
            else
                store.working = DeepCopy(store.savedSets["Resonance Medium"])
                store.loadedName = "Resonance Medium"
            end
        elseif refreshLoadedBuiltin and store.dirty ~= true then
            -- Only refresh an untouched built-in preset. A working set with
            -- edits keeps its current layers even when the bundled preset is
            -- upgraded by a newer addon release.
            store.working = DeepCopy(store.savedSets[refreshLoadedBuiltin])
            store.loadedName = refreshLoadedBuiltin
        end
        local loadedSet = store.loadedName and store.savedSets[store.loadedName]
        NormalizeProfileSet(store.working, loadedSet and loadedSet.builtin == true)
        RunCharacterStoreMigrations(store, specID, previousCharacterVersion)
    end
    ResonanceCharDB.version = math.max(previousCharacterVersion, CHARACTER_DEFAULTS.version)
end

function ns:GetSpecProfileStore(specID)
    specID = specID or self.Runtime.specID
    return specID and self.CharDB and self.CharDB.specs[specID]
end

function ns:GetActiveProfile(specID)
    local store = self:GetSpecProfileStore(specID)
    return store and store.working, store and store.loadedName
end

local function GetPersonalSetBaseName()
    local character, realm
    if UnitFullName then character, realm = UnitFullName("player") end
    character = type(character) == "string" and character ~= "" and character
        or (UnitName and UnitName("player"))
    realm = type(realm) == "string" and realm ~= "" and realm
        or (GetRealmName and GetRealmName())
    if type(character) == "string" and character ~= "" and type(realm) == "string" and realm ~= "" then
        return character .. " — " .. realm
    end
    return type(character) == "string" and character ~= "" and character or "My Resonance Set"
end

local function PrepareSavedSnapshot(owner, source, specID, automatic)
    local snapshot = DeepCopy(source)
    NormalizeProfileSet(snapshot, false)
    FreezeProfileSet(snapshot, specID, true)
    NormalizeProfileSet(snapshot, false)
    snapshot.builtin = nil
    snapshot.builtinVersion = nil
    snapshot.baseVersion = nil
    snapshot.preset = nil
    snapshot.ruleFallback = "disabled"
    snapshot.schemaVersion = owner.PROFILE_SCHEMA_VERSION
    snapshot.ruleCatalogVersion = owner.RULE_CATALOG_VERSION
    snapshot.soundCatalogVersion = owner.SOUND_CATALOG_VERSION
    snapshot.savedAt = GetServerTime and GetServerTime() or 0
    snapshot.automatic = automatic == true or nil
    return snapshot
end

local function GetAutomaticSetName(store)
    local preferred = GetPersonalSetBaseName()
    local name = type(store.autoSaveName) == "string" and store.autoSaveName or preferred
    local existing = store.savedSets and store.savedSets[name]
    if existing and existing.automatic ~= true then
        name = preferred .. " (Auto)"
        local suffix = 2
        while store.savedSets[name] and store.savedSets[name].automatic ~= true do
            name = preferred .. " (Auto " .. suffix .. ")"
            suffix = suffix + 1
        end
    end
    store.autoSaveName = name
    return name
end

local function CreatePersonalSet(owner, store, specID, replaceSnapshot)
    local name = GetAutomaticSetName(store)
    if replaceSnapshot == true or type(store.savedSets[name]) ~= "table" then
        store.savedSets[name] = PrepareSavedSnapshot(owner, store.working, specID, true)
    end
    store.personalSetInitialized = true
    return name
end

function ns:MarkSpecProfileDirty(specID)
    local store = self:GetSpecProfileStore(specID)
    if not store or type(store.working) ~= "table" then return end

    -- Sound descriptors are derived from the working profile. Invalidate the
    -- small runtime cache and cancel delayed playback immediately so a
    -- preview or gameplay timer fired before the queued refresh cannot use a
    -- stale layer or delay.
    self:InvalidateRuntimeAudio(true)

    local loaded = store.loadedName and store.savedSets[store.loadedName]
    -- Presets are sources, never editable destinations. The first change to a
    -- bundled preset immediately moves the edited working copy under the
    -- character's personal set, without overwriting that saved personal set.
    if store.personalSetInitialized ~= true or not store.loadedName or (loaded and loaded.builtin == true) then
        local personalName = CreatePersonalSet(self, store, specID, store.personalSetInitialized ~= true)
        store.loadedName = personalName
    end
    -- Later edits are deliberately not written into the active set until the
    -- player chooses Save changes.
    store.dirty = true

    local window = self.SoundSetWindow
    if window and window:IsShown() and window.specID == specID and type(window.Refresh) == "function" then
        window:Refresh()
    end
end

function ns:HasUnsavedProfileChanges(specID)
    local store = self:GetSpecProfileStore(specID)
    return store and store.dirty == true or false
end

function ns:GetRuleConfig(ruleID, create)
    local rule = self.RuleByID[ruleID]
    if not rule then return nil end
    local profile = self:GetActiveProfile(rule.spec)
    if not profile then return nil end
    local config = profile.rules[ruleID]
    if not config and create then
        config = {}
        profile.rules[ruleID] = config
    end
    return config
end

local function CountProfileCompatibility(owner, profile, specID)
    local report = { missingSounds = 0, retiredRules = 0, newRules = 0 }
    if not profile or type(profile.rules) ~= "table" then return report end
    for ruleID, config in pairs(profile.rules) do
        if not owner.RuleByID[ruleID] then report.retiredRules = report.retiredRules + 1 end
        if type(config) == "table" and type(config.layers) == "table" then
            for _, layer in pairs(config.layers) do
                if type(layer) == "table" and tonumber(layer.soundID)
                    and not owner.SoundByID[tonumber(layer.soundID)] then
                    report.missingSounds = report.missingSounds + 1
                end
            end
        end
    end
    for _, rule in ipairs(owner.RulesBySpec[specID] or {}) do
        if profile.rules[rule.id] == nil then report.newRules = report.newRules + 1 end
    end
    return report
end

function ns:GetProfileCompatibility(specID)
    return CountProfileCompatibility(self, self:GetActiveProfile(specID), specID)
end

function ns:GetSavedSetsCompatibility(specID)
    local store = self:GetSpecProfileStore(specID)
    local total = { missingSounds = 0, retiredRules = 0, newRules = 0, affectedSets = 0 }
    for _, set in pairs((store and store.savedSets) or {}) do
        local report = CountProfileCompatibility(self, set, specID)
        if report.missingSounds > 0 or report.retiredRules > 0 or report.newRules > 0 then
            total.affectedSets = total.affectedSets + 1
            total.missingSounds = total.missingSounds + report.missingSounds
            total.retiredRules = total.retiredRules + report.retiredRules
            total.newRules = total.newRules + report.newRules
        end
    end
    return total
end

ns.MAX_RULE_LAYERS = 8

function ns:GetRuleLayerCount(rule)
    local config = self:GetRuleConfig(rule.id, false)
    if config and tonumber(config.layerCount) then
        return math.max(2, math.min(self.MAX_RULE_LAYERS, math.floor(tonumber(config.layerCount))))
    end
    local count = math.max(2, #(rule.defaultSounds or {}))
    if config and type(config.layers) == "table" then
        for index in pairs(config.layers) do
            if type(index) == "number" and index > count then count = index end
        end
    end
    return math.min(self.MAX_RULE_LAYERS, count)
end

function ns:GetLayerConfig(rule, index)
    local config = self:GetRuleConfig(rule.id, false)
    local layer = config and config.layers and config.layers[index]
    local default = rule.defaultSounds and rule.defaultSounds[index]
    local soundID = default
    if layer ~= nil then soundID = layer.soundID end
    return {
        enabled = layer ~= nil and layer.enabled ~= false or (layer == nil and default ~= nil),
        soundID = soundID,
        soundLabel = layer and layer.soundLabel,
        missingSound = layer and layer.missingSound == true,
        delayMs = layer and tonumber(layer.delayMs)
            or (rule.defaultDelays and tonumber(rule.defaultDelays[index]))
            or (index == 1 and math.floor((rule.delay or 0) * 1000 + 0.5) or 0),
    }
end

function ns:AddRuleLayer(rule)
    local count = self:GetRuleLayerCount(rule)
    if count >= self.MAX_RULE_LAYERS then return false end
    local config = self:GetRuleConfig(rule.id, true)
    config.layers = config.layers or {}
    config.layers[count + 1] = { enabled = false, soundID = false, delayMs = 0 }
    config.layerCount = count + 1
    self:MarkSpecProfileDirty(rule.spec)
    return true
end

function ns:RemoveRuleLayer(rule, index)
    local count = self:GetRuleLayerCount(rule)
    if index < 3 or index > count then return false end
    local config = self:GetRuleConfig(rule.id, true)
    config.layers = config.layers or {}
    for fill = 1, count do
        if config.layers[fill] == nil then
            local current = self:GetLayerConfig(rule, fill)
            config.layers[fill] = { enabled = current.enabled, soundID = current.soundID or false, delayMs = current.delayMs or 0 }
        end
    end
    table.remove(config.layers, index)
    config.layerCount = count - 1
    self:MarkSpecProfileDirty(rule.spec)
    return true
end

function ns:SetLayerConfig(rule, index, values)
    local config = self:GetRuleConfig(rule.id, true)
    config.layers = config.layers or {}
    local layer = config.layers[index] or {}
    config.layers[index] = layer
    config.layerCount = math.max(tonumber(config.layerCount) or self:GetRuleLayerCount(rule), index)
    if values.enabled ~= nil then layer.enabled = values.enabled and true or false end
    if values.soundID ~= nil then layer.soundID = tonumber(values.soundID) end
    if values.clearSound then layer.soundID = false end
    if values.delayMs ~= nil then layer.delayMs = math.max(0, math.min(5000, math.floor(tonumber(values.delayMs) or 0))) end
    self:MarkSpecProfileDirty(rule.spec)
    self:QueueRefresh("layer")
end

function ns:SaveSoundSet(specID, name)
    local store = self:GetSpecProfileStore(specID)
    name = type(name) == "string" and name:match("^%s*(.-)%s*$") or ""
    if not store or name == "" then return false end
    if store.savedSets[name] and store.savedSets[name].builtin == true then
        return false, "builtin"
    end
    store.savedSets[name] = PrepareSavedSnapshot(self, store.working, specID, name == store.autoSaveName)
    store.working = DeepCopy(store.savedSets[name])
    store.loadedName = name
    store.dirty = false
    self:InvalidateRuntimeAudio(true)
    self:QueueRefresh("sound set saved")
    return true
end

-- Commits the visible working copy without ever trying to overwrite a
-- protected bundled preset. The first edit has already created an active
-- personal set, so this normally writes directly into that set.
function ns:SaveActiveSoundSet(specID)
    local store = self:GetSpecProfileStore(specID)
    if not store then return false end
    local loaded = store.loadedName and store.savedSets[store.loadedName]
    if loaded and loaded.builtin ~= true then
        return self:SaveSoundSet(specID, store.loadedName)
    end
    local personalName = CreatePersonalSet(self, store, specID, true)
    return self:SaveSoundSet(specID, personalName)
end

function ns:LoadSoundSet(specID, name)
    local store = self:GetSpecProfileStore(specID)
    if not store or type(store.savedSets[name]) ~= "table" then return false end
    store.working = DeepCopy(store.savedSets[name])
    store.loadedName = name
    store.dirty = false
    self:InvalidateRuntimeAudio(true)
    self:QueueRefresh("sound set loaded")
    return true
end

function ns:RenameSoundSet(specID, oldName, newName)
    local store = self:GetSpecProfileStore(specID)
    oldName = type(oldName) == "string" and oldName or ""
    newName = type(newName) == "string" and newName:match("^%s*(.-)%s*$") or ""
    if not store or oldName == "" or newName == "" then return false, "empty" end
    local set = store.savedSets and store.savedSets[oldName]
    if type(set) ~= "table" then return false, "missing" end
    if set.builtin == true then return false, "builtin" end
    if oldName == newName then return true end
    if store.savedSets[newName] ~= nil then return false, "exists" end

    store.savedSets[newName] = set
    store.savedSets[oldName] = nil
    if store.loadedName == oldName then store.loadedName = newName end
    if store.autoSaveName == oldName then store.autoSaveName = newName end
    self:QueueRefresh("sound set renamed")
    return true
end

function ns:DeleteSoundSet(specID, name)
    local store = self:GetSpecProfileStore(specID)
    if not store or not store.savedSets[name] then return false end
    if store.savedSets[name].builtin == true then return false, "builtin" end
    if store.savedSets[name].automatic == true then return false, "automatic" end
    store.savedSets[name] = nil
    if store.loadedName == name then
        store.loadedName = nil
        store.dirty = true
    end
    return true
end

function ns:GetSoundSetNames(specID)
    local store = self:GetSpecProfileStore(specID)
    local names = {}
    if store then for name in pairs(store.savedSets) do names[#names + 1] = name end end
    local presetOrder = {
        ["Resonance Subtle"] = 1,
        ["Resonance Medium"] = 2,
        ["Resonance Expressive"] = 3,
    }
    table.sort(names, function(left, right)
        local leftSet = store and store.savedSets and store.savedSets[left]
        local rightSet = store and store.savedSets and store.savedSets[right]
        local leftOrder = presetOrder[left] or (leftSet and leftSet.automatic == true and 4)
        local rightOrder = presetOrder[right] or (rightSet and rightSet.automatic == true and 4)
        if leftOrder or rightOrder then
            return (leftOrder or 99) < (rightOrder or 99)
        end
        return left < right
    end)
    return names
end

local function TransferEncode(value)
    return (tostring(value or ""):gsub("([^%w%-%._])", function(character)
        return string.format("%%%02X", string.byte(character))
    end))
end

local function TransferDecode(value)
    if type(value) ~= "string" then return nil end
    local searchFrom = 1
    while true do
        local percent = value:find("%", searchFrom, true)
        if not percent then break end
        if not value:sub(percent + 1, percent + 2):match("^%x%x$") then return nil end
        searchFrom = percent + 3
    end
    return (value:gsub("%%(%x%x)", function(hex)
        return string.char(tonumber(hex, 16))
    end))
end

local function TransferSplit(value, delimiter, maximum)
    local parts, startAt = {}, 1
    while true do
        if maximum and #parts >= maximum then return nil end
        local found = value:find(delimiter, startAt, true)
        if not found then
            parts[#parts + 1] = value:sub(startAt)
            return parts
        end
        parts[#parts + 1] = value:sub(startAt, found - 1)
        startAt = found + #delimiter
    end
end

local function TransferChecksum(value)
    local first, second = 1, 0
    for index = 1, #value do
        first = (first + string.byte(value, index)) % 65521
        second = (second + first) % 65521
    end
    return string.format("%04X%04X", second, first)
end

local function TransferBoolean(value)
    if value == "1" then return true end
    if value == "0" then return false end
    return nil
end

-- RES3F is a compact, self-contained share format.  It deliberately carries
-- stable rule IDs and FileDataIDs rather than catalog indexes: an import can
-- still be read after a later catalog reorder, a renamed rule, or a Blizzard
-- spell prune.  Human labels are only included as a fallback for sounds that
-- are already absent from this client catalog.
local TRANSFER64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
local TRANSFER64_DECODE = {}
for index = 1, #TRANSFER64_ALPHABET do
    TRANSFER64_DECODE[TRANSFER64_ALPHABET:sub(index, index)] = index - 1
end

local function TransferWriteVarUInt(parts, value)
    value = math.floor(tonumber(value) or 0)
    if value < 0 or value > 2147483647 then return false end
    repeat
        local byte = value % 128
        value = math.floor(value / 128)
        if value > 0 then byte = byte + 128 end
        parts[#parts + 1] = string.char(byte)
    until value == 0
    return true
end

local function TransferReadVarUInt(value, position)
    local result, multiplier = 0, 1
    for _ = 1, 5 do
        local byte = string.byte(value, position)
        if not byte then return nil end
        position = position + 1
        result = result + (byte % 128) * multiplier
        if byte < 128 then
            if result > 2147483647 then return nil end
            return result, position
        end
        multiplier = multiplier * 128
    end
    return nil
end

local function TransferWriteString(parts, value, maximum)
    value = tostring(value or "")
    if maximum and #value > maximum then return false end
    if not TransferWriteVarUInt(parts, #value) then return false end
    parts[#parts + 1] = value
    return true
end

local function TransferReadString(value, position, maximum)
    local length
    length, position = TransferReadVarUInt(value, position)
    if not length or (maximum and length > maximum) or position + length - 1 > #value then return nil end
    return value:sub(position, position + length - 1), position + length
end

local function TransferEncode64(value)
    local encoded, length = {}, #value
    for position = 1, length, 3 do
        local first = string.byte(value, position) or 0
        local second = string.byte(value, position + 1) or 0
        local third = string.byte(value, position + 2) or 0
        encoded[#encoded + 1] = TRANSFER64_ALPHABET:sub(math.floor(first / 4) + 1, math.floor(first / 4) + 1)
        encoded[#encoded + 1] = TRANSFER64_ALPHABET:sub((first % 4) * 16 + math.floor(second / 16) + 1, (first % 4) * 16 + math.floor(second / 16) + 1)
        if position + 1 <= length then
            encoded[#encoded + 1] = TRANSFER64_ALPHABET:sub((second % 16) * 4 + math.floor(third / 64) + 1, (second % 16) * 4 + math.floor(third / 64) + 1)
        end
        if position + 2 <= length then
            encoded[#encoded + 1] = TRANSFER64_ALPHABET:sub(third % 64 + 1, third % 64 + 1)
        end
    end
    return table.concat(encoded)
end

local function TransferDecode64(value)
    if type(value) ~= "string" or #value == 0 or #value % 4 == 1 then return nil end
    local decoded, position = {}, 1
    while position <= #value do
        local first = TRANSFER64_DECODE[value:sub(position, position)]
        local second = TRANSFER64_DECODE[value:sub(position + 1, position + 1)]
        local third = position + 2 <= #value and TRANSFER64_DECODE[value:sub(position + 2, position + 2)] or nil
        local fourth = position + 3 <= #value and TRANSFER64_DECODE[value:sub(position + 3, position + 3)] or nil
        if first == nil or second == nil or (position + 2 <= #value and third == nil) or (position + 3 <= #value and fourth == nil) then
            return nil
        end
        decoded[#decoded + 1] = string.char(first * 4 + math.floor(second / 16))
        if third ~= nil then
            decoded[#decoded + 1] = string.char((second % 16) * 16 + math.floor(third / 4))
        end
        if fourth ~= nil then
            decoded[#decoded + 1] = string.char((third % 4) * 64 + fourth)
        end
        position = position + 4
    end
    return table.concat(decoded)
end

local function TransferCommonPrefix(left, right)
    local maximum = math.min(#left, #right)
    local index = 0
    while index < maximum and left:byte(index + 1) == right:byte(index + 1) do
        index = index + 1
    end
    return index
end

local function TransferSetName(store, name)
    local importedName = name
    if store.savedSets[importedName] == nil then return importedName end
    local suffixText = " (Imported)"
    importedName = name:sub(1, 32 - #suffixText) .. suffixText
    local suffix = 2
    while store.savedSets[importedName] ~= nil and suffix < 100 do
        suffixText = " (Imported " .. suffix .. ")"
        importedName = name:sub(1, 32 - #suffixText) .. suffixText
        suffix = suffix + 1
    end
    return store.savedSets[importedName] == nil and importedName or nil
end

function ns:ExportSoundSet(specID, name)
    local store = self:GetSpecProfileStore(specID)
    local source = store and store.savedSets and store.savedSets[name]
    if type(source) ~= "table" then return nil, "missing-set" end

    local snapshot = DeepCopy(source)
    NormalizeProfileSet(snapshot, source.builtin == true)
    FreezeProfileSet(snapshot, specID, true)
    NormalizeProfileSet(snapshot, source.builtin == true)

    local ruleIDs = {}
    for ruleID, config in pairs(snapshot.rules or {}) do
        if type(ruleID) == "string" and type(config) == "table" then
            ruleIDs[#ruleIDs + 1] = ruleID
        end
    end
    table.sort(ruleIDs)

    local encoded = {}
    if not TransferWriteVarUInt(encoded, 1) -- RES3F payload revision
        or not TransferWriteVarUInt(encoded, math.floor(tonumber(specID) or 0))
        or not TransferWriteVarUInt(encoded, math.floor(tonumber(snapshot.schemaVersion) or self.PROFILE_SCHEMA_VERSION))
        or not TransferWriteVarUInt(encoded, math.floor(tonumber(snapshot.ruleCatalogVersion) or self.RULE_CATALOG_VERSION))
        or not TransferWriteVarUInt(encoded, math.floor(tonumber(snapshot.soundCatalogVersion) or self.SOUND_CATALOG_VERSION))
        or not TransferWriteString(encoded, name, 96)
        or not TransferWriteVarUInt(encoded, #ruleIDs) then
        return nil, "invalid"
    end

    local previousRuleID = ""
    for _, ruleID in ipairs(ruleIDs) do
        local config = snapshot.rules[ruleID]
        local count = math.max(2, math.min(self.MAX_RULE_LAYERS or 8, math.floor(tonumber(config.layerCount) or 2)))
        local prefixLength = TransferCommonPrefix(previousRuleID, ruleID)
        local suffix = ruleID:sub(prefixLength + 1)
        if not TransferWriteVarUInt(encoded, prefixLength) or not TransferWriteString(encoded, suffix, 128)
            or not TransferWriteVarUInt(encoded, (count - 2) * 2 + (config.enabled == true and 1 or 0)) then
            return nil, "invalid"
        end
        for index = 1, count do
            local layer = type(config.layers) == "table" and config.layers[index] or nil
            local soundID = layer and tonumber(layer.soundID) or nil
            local sound = soundID and self.SoundByID and self.SoundByID[soundID]
            local kind = (layer and layer.soundKind) or (sound and sound.kind) or "file"
            local label = (layer and layer.soundLabel) or (sound and sound.label) or ""
            soundID = soundID and math.floor(soundID) or 0
            local delayMs = math.max(0, math.min(5000, math.floor(layer and tonumber(layer.delayMs) or 0)))
            local includeFallbackLabel = soundID > 0 and not sound and label ~= ""
            local hasSoundState = soundID > 0 or delayMs > 0 or includeFallbackLabel
            local flags = (layer and layer.enabled == true and 1 or 0)
                + (kind == "kit" and 2 or 0)
                + (includeFallbackLabel and 4 or 0)
                + (hasSoundState and 8 or 0)
            if not TransferWriteVarUInt(encoded, flags) then return nil, "invalid" end
            if hasSoundState then
                if not TransferWriteVarUInt(encoded, soundID) or not TransferWriteVarUInt(encoded, delayMs) then return nil, "invalid" end
            end
            if includeFallbackLabel and not TransferWriteString(encoded, label, 128) then return nil, "invalid" end
        end
        previousRuleID = ruleID
    end
    local body = table.concat(encoded)
    return "RES3F:" .. TransferChecksum(body) .. ":" .. TransferEncode64(body)
end

local function CommitImportedSoundSet(self, targetSpecID, name, imported)
    NormalizeProfileSet(imported, false)
    FreezeProfileSet(imported, targetSpecID, true)
    NormalizeProfileSet(imported, false)
    imported.builtin = nil
    imported.builtinVersion = nil
    imported.preset = nil
    imported.savedAt = GetServerTime and GetServerTime() or 0

    local store = self:GetSpecProfileStore(targetSpecID)
    if not store then return nil, "invalid" end
    local importedName = TransferSetName(store, name)
    if not importedName then return nil, "name-conflict" end
    store.savedSets[importedName] = imported
    self:InvalidateRuntimeAudio(false)
    self:QueueRefresh("sound set imported")
    return importedName
end

local function ImportRes1SoundSet(self, targetSpecID, exportText)
    if type(exportText) ~= "string" then return nil, "invalid" end
    exportText = exportText:match("^%s*(.-)%s*$") or ""
    if #exportText == 0 or #exportText > 100000 then return nil, "invalid" end

    local checksum, body = exportText:match("^RES1:([%x]+):(.*)$")
    if not checksum or not body or string.upper(checksum) ~= TransferChecksum(body) then
        return nil, "checksum"
    end

    local encodedSpec, schemaVersion, ruleCatalogVersion, soundCatalogVersion, encodedName, payload =
        body:match("^(%d+)|(%d+)|(%d+)|(%d+)|([^|]*)|(.*)$")
    if not encodedSpec or not schemaVersion or not ruleCatalogVersion or not soundCatalogVersion
        or encodedName == nil or payload == nil then return nil, "invalid" end
    local sourceSpecID = tonumber(encodedSpec)
    targetSpecID = tonumber(targetSpecID)
    if not sourceSpecID or sourceSpecID ~= targetSpecID then
        return nil, "wrong-spec", sourceSpecID
    end
    local schemaNumber = tonumber(schemaVersion)
    local ruleCatalogNumber = tonumber(ruleCatalogVersion)
    local soundCatalogNumber = tonumber(soundCatalogVersion)
    if not schemaNumber or schemaNumber < 0 or schemaNumber > 1000000
        or not ruleCatalogNumber or ruleCatalogNumber < 0 or ruleCatalogNumber > 1000000
        or not soundCatalogNumber or soundCatalogNumber < 0 or soundCatalogNumber > 1000000 then
        return nil, "invalid"
    end

    local name = TransferDecode(encodedName)
    if not name then return nil, "invalid" end
    name = name:match("^%s*(.-)%s*$") or ""
    if name == "" then name = "Imported set" end
    name = name:sub(1, 32)

    local imported = {
        rules = {},
        schemaVersion = math.floor(schemaNumber),
        ruleCatalogVersion = math.floor(ruleCatalogNumber),
        soundCatalogVersion = math.floor(soundCatalogNumber),
        ruleFallback = "disabled",
    }

    local ruleCount = 0
    for encodedRule in payload:gmatch("([^;]+)") do
        ruleCount = ruleCount + 1
        if ruleCount > 500 then return nil, "invalid" end
        local parts = TransferSplit(encodedRule, "~", (self.MAX_RULE_LAYERS or 8) + 4)
        if not parts then return nil, "invalid" end
        local ruleID = TransferDecode(parts[1])
        local enabled = TransferBoolean(parts[2])
        local layerCount = tonumber(parts[3])
        if not ruleID or ruleID == "" or #ruleID > 128 or enabled == nil or not layerCount then
            return nil, "invalid"
        end
        layerCount = math.floor(layerCount)
        if layerCount < 2 or layerCount > (self.MAX_RULE_LAYERS or 8) or #parts ~= layerCount + 3 then
            return nil, "invalid"
        end

        local config = { enabled = enabled, layerCount = layerCount, layers = {} }
        for index = 1, layerCount do
            local layerEnabled, soundIDText, delayText, kindText, encodedLabel =
                parts[index + 3]:match("^([01]),(%d+),(%d+),([fk]),(.*)$")
            local layerState = TransferBoolean(layerEnabled)
            local soundID = tonumber(soundIDText)
            local delayMs = tonumber(delayText)
            local label = TransferDecode(encodedLabel)
            if layerState == nil or not soundID or soundID < 0 or soundID > 2147483647
                or not delayMs or delayMs < 0 or delayMs > 5000 or label == nil then
                return nil, "invalid"
            end
            config.layers[index] = {
                enabled = layerState,
                soundID = soundID > 0 and math.floor(soundID) or false,
                delayMs = math.floor(delayMs),
                soundKind = kindText == "k" and "kit" or "file",
                soundLabel = label ~= "" and label or nil,
            }
        end
        imported.rules[ruleID] = config
    end
    if ruleCount == 0 then return nil, "invalid" end

    return CommitImportedSoundSet(self, targetSpecID, name, imported)
end

local function ImportRes3FullSoundSet(self, targetSpecID, exportText)
    local checksum, encodedBody = exportText:match("^RES3F:([%x]+):([A-Za-z0-9%-%_]+)$")
    if not checksum or not encodedBody then return nil, "invalid" end
    local body = TransferDecode64(encodedBody)
    if not body or string.upper(checksum) ~= TransferChecksum(body) then return nil, "checksum" end

    local position = 1
    local revision, sourceSpecID, schemaNumber, ruleCatalogNumber, soundCatalogNumber
    revision, position = TransferReadVarUInt(body, position)
    sourceSpecID, position = TransferReadVarUInt(body, position)
    schemaNumber, position = TransferReadVarUInt(body, position)
    ruleCatalogNumber, position = TransferReadVarUInt(body, position)
    soundCatalogNumber, position = TransferReadVarUInt(body, position)
    if revision ~= 1 or not sourceSpecID or not schemaNumber or not ruleCatalogNumber or not soundCatalogNumber then
        return nil, "invalid"
    end
    targetSpecID = tonumber(targetSpecID)
    if sourceSpecID ~= targetSpecID then return nil, "wrong-spec", sourceSpecID end
    if schemaNumber > 1000000 or ruleCatalogNumber > 1000000 or soundCatalogNumber > 1000000 then
        return nil, "invalid"
    end

    local name, ruleCount
    name, position = TransferReadString(body, position, 96)
    ruleCount, position = TransferReadVarUInt(body, position)
    if not name or not ruleCount or ruleCount < 1 or ruleCount > 500 then return nil, "invalid" end
    name = name:match("^%s*(.-)%s*$") or ""
    if name == "" then name = "Imported set" end
    name = name:sub(1, 32)

    local imported = {
        rules = {},
        schemaVersion = schemaNumber,
        ruleCatalogVersion = ruleCatalogNumber,
        soundCatalogVersion = soundCatalogNumber,
        ruleFallback = "disabled",
    }
    local previousRuleID = ""
    for _ = 1, ruleCount do
        local prefixLength, suffix, packedConfig
        prefixLength, position = TransferReadVarUInt(body, position)
        suffix, position = TransferReadString(body, position, 128)
        packedConfig, position = TransferReadVarUInt(body, position)
        if prefixLength == nil or not suffix or packedConfig == nil or prefixLength > #previousRuleID or packedConfig > 13 then
            return nil, "invalid"
        end
        local ruleID = previousRuleID:sub(1, prefixLength) .. suffix
        if ruleID == "" or #ruleID > 128 or imported.rules[ruleID] then return nil, "invalid" end
        local enabled = packedConfig % 2 == 1
        local layerCount = math.floor(packedConfig / 2) + 2
        if layerCount > (self.MAX_RULE_LAYERS or 8) then return nil, "invalid" end

        local config = { enabled = enabled, layerCount = layerCount, layers = {} }
        for index = 1, layerCount do
            local flags
            flags, position = TransferReadVarUInt(body, position)
            if flags == nil or flags > 15 then return nil, "invalid" end
            local layerEnabled = flags % 2 == 1
            local soundKind = math.floor(flags / 2) % 2 == 1 and "kit" or "file"
            local hasFallbackLabel = math.floor(flags / 4) % 2 == 1
            local hasSoundState = math.floor(flags / 8) % 2 == 1
            if hasFallbackLabel and not hasSoundState then return nil, "invalid" end
            local soundID, delayMs, label = 0, 0, nil
            if hasSoundState then
                soundID, position = TransferReadVarUInt(body, position)
                delayMs, position = TransferReadVarUInt(body, position)
                if soundID == nil or delayMs == nil or delayMs > 5000 then return nil, "invalid" end
            end
            if hasFallbackLabel then
                label, position = TransferReadString(body, position, 128)
                if not label or label == "" then return nil, "invalid" end
            end
            config.layers[index] = {
                enabled = layerEnabled,
                soundID = soundID > 0 and soundID or false,
                delayMs = delayMs,
                soundKind = soundKind,
                soundLabel = label,
            }
        end
        imported.rules[ruleID] = config
        previousRuleID = ruleID
    end
    if position <= #body then return nil, "invalid" end
    return CommitImportedSoundSet(self, targetSpecID, name, imported)
end

function ns:ImportSoundSet(targetSpecID, exportText)
    if type(exportText) ~= "string" then return nil, "invalid" end
    exportText = exportText:match("^%s*(.-)%s*$") or ""
    if #exportText == 0 or #exportText > 100000 then return nil, "invalid" end
    if exportText:match("^RES3F:") then
        return ImportRes3FullSoundSet(self, targetSpecID, exportText)
    end
    if exportText:match("^RES1:") then
        return ImportRes1SoundSet(self, targetSpecID, exportText)
    end
    return nil, "invalid"
end

function ns:ResetDatabase()
    if self.DB and self.DB.soloMode and self.DisableSoloMode then
        self:DisableSoloMode(true)
    end
    ResonanceDB = CopyDefaults(DEFAULTS)
    self:InitializeProfiles()
    ResonanceCharDB = CopyDefaults(CHARACTER_DEFAULTS)
    self:InitializeCharacterProfiles()
    self.DB = ResonanceDB
    self.CharDB = ResonanceCharDB
    self:InvalidateRuntimeAudio(true)
    self:QueueRefresh("reset")
    if self.RefreshOptions then
        self:RefreshOptions()
    end
    if self.UpdateMinimapButton then
        self:UpdateMinimapButton()
    end
end

function ns:GetRuleTone(ruleID)
    local settings = self.DB.ruleSettings[ruleID]
    return settings and settings.tone or "default"
end

function ns:SetRuleTone(ruleID, tone)
    local valid = tone == "soft" or tone == "bright" or tone == "impact" or tone == "apex"
    local settings = self.DB.ruleSettings[ruleID]
    if not valid then
        if settings then settings.tone = nil end
        return
    end
    if type(settings) ~= "table" then
        settings = {}
        self.DB.ruleSettings[ruleID] = settings
    end
    settings.tone = tone
end

function ns:GetRuleLayers(ruleID)
    local settings = self.DB.ruleSettings[ruleID]
    return settings and settings.layers == 2 and 2 or 1
end

function ns:SetRuleLayers(ruleID, layers)
    local settings = self.DB.ruleSettings[ruleID]
    if layers ~= 2 then
        if settings then settings.layers = nil end
        return
    end
    if type(settings) ~= "table" then
        settings = {}
        self.DB.ruleSettings[ruleID] = settings
    end
    settings.layers = 2
end

function ns:IsSecret(value)
    return issecretvalue and issecretvalue(value)
end

function ns:IsSafeValue(value)
    if self:IsSecret(value) then
        return false
    end
    return value ~= nil
end

function ns:IsSafeTable(value)
    if self:IsSecret(value) then
        return false
    end
    return type(value) == "table"
end

function ns:Print(message)
    DEFAULT_CHAT_FRAME:AddMessage(self.COLOR .. "Resonance:|r " .. tostring(message))
end

function ns:GetRuleEnabled(rule)
    local config = self:GetRuleConfig(rule.id, false)
    local override = config and config.enabled
    if override ~= nil then
        return override
    end
    local profile = self:GetActiveProfile(rule.spec)
    if profile and profile.ruleFallback == "disabled" then
        return false
    end
    return rule.defaultOn
end

function ns:SetRuleEnabled(ruleID, enabled)
    local rule = self.RuleByID[ruleID]
    if not rule then
        return
    end
    local config = self:GetRuleConfig(ruleID, true)
    local profile = self:GetActiveProfile(rule.spec)
    if profile and profile.ruleFallback == "disabled" then
        config.enabled = enabled and true or false
    else
        config.enabled = enabled == rule.defaultOn and nil or (enabled and true or false)
    end
    self:MarkSpecProfileDirty(rule.spec)
    self:QueueRefresh("rule")
end

function ns:GetCharacterLabel()
    local name = UnitName("player")
    local realm = GetRealmName()
    if not self:IsSafeValue(name) or type(name) ~= "string" then name = "Unknown" end
    if not self:IsSafeValue(realm) or type(realm) ~= "string" then realm = "Unknown Realm" end
    return name .. " - " .. realm
end