UI.lua

-- PETAL UI
--
-- This file deliberately owns presentation only.  Runtime/evaluation code can
-- expose optional APS:GetRules/APS:SetRuleEnabled/APS:SetRulePets APIs; the
-- journal will use them when present and falls back to the original
-- PETALDB shape when it is not.  Nothing in this file writes secure
-- attributes or performs a protected action.

local APS = _G.PETAL
if not APS then
    return
end

local UI = {}
APS.UI = UI

local WHITE = "Interface\\Buttons\\WHITE8x8"
local QUESTION_ICON = "Interface\\Icons\\INV_Misc_QuestionMark"
local PAPER_WASH = "Interface\\AddOns\\PETAL\\Art\\paper-wash.tga"
local NAV_ICON_ROOT = "Interface\\AddOns\\PETAL\\Art\\ui-v2\\"
local WORDMARK = NAV_ICON_ROOT .. "petal-wordmark-clean.png"
local JOURNAL_SHELL = NAV_ICON_ROOT .. "journal-shell.png"
local NO_PET_ART = NAV_ICON_ROOT .. "pawprint-stamp.png"
local DEFAULT_CAT_SPECIES_ID = 40 -- Blizzard's Bombay Cat
local DEFAULT_MODEL_FACING = math.rad(45)
local PET_PREVIEW_ROTATION_SPEED = math.rad(15)
local TODAY_ROTATION_SPEED = math.rad(5)
-- Retail does not expose a battle-pet model bounding box. These conservative
-- distances keep the largest wide/tall meshes inside their visual stages.
local HERO_MODEL_FIT_DISTANCE = 1.65
local PREVIEW_MODEL_FIT_DISTANCE = 1.50
local CHANGE_PET_BINDING = "PETAL_CHANGE_PET"

local function rgba8(red, green, blue, alpha)
    return {red / 255, green / 255, blue / 255, alpha == nil and 1 or alpha}
end

-- Muted sand, clay, ochre, and wine from the supplied light references.
-- These avoid paper-white surfaces while keeping dark text readable.
local COLOR = {
    panel = rgba8(191, 168, 135),       -- warm parchment beige
    rail = rgba8(174, 139, 124),        -- dusty clay
    card = rgba8(201, 178, 146),        -- raised sand
    cardAlt = rgba8(184, 139, 120),     -- rose clay
    border = rgba8(97, 71, 59),         -- #61473B umber
    borderSoft = rgba8(145, 117, 76),   -- #91754C muted ochre
    text = rgba8(67, 0, 17),            -- #430011 wine-black
    muted = rgba8(92, 51, 61),          -- dusty wine
    faint = rgba8(119, 70, 82),         -- quiet rosewood
    sky = rgba8(141, 97, 34),           -- #8D6122 ochre
    skySoft = rgba8(194, 164, 119),     -- soft golden sand
    mint = rgba8(141, 68, 34),          -- #8D4422 burnt clay
    mintSoft = rgba8(188, 143, 125),    -- muted terracotta
    lilac = rgba8(128, 31, 55),         -- #801F37 berry
    lilacSoft = rgba8(166, 113, 130),   -- dusty mauve
    amber = rgba8(141, 97, 34),         -- #8D6122 ochre
    amberSoft = rgba8(194, 164, 119),   -- soft golden sand
    red = rgba8(128, 31, 55),           -- #801F37 berry
    redSoft = rgba8(166, 113, 130),     -- dusty mauve
    hoverSurface = rgba8(211, 157, 143), -- warm rose highlight
    hoverBorder = rgba8(128, 31, 55),   -- berry outline
    white = rgba8(244, 231, 216),
    tagAll = rgba8(78, 42, 64),          -- dark wine, deliberately neutral
    tagAllSoft = rgba8(101, 73, 91),
    tagCity = rgba8(78, 170, 194),       -- clear sky blue
    tagCitySoft = rgba8(173, 215, 225),
    tagDungeon = rgba8(138, 103, 194),   -- lavender
    tagDungeonSoft = rgba8(207, 190, 229),
    tagRaid = rgba8(218, 151, 52),       -- warm amber
    tagRaidSoft = rgba8(237, 206, 153),
    tagOpenWorld = rgba8(72, 163, 111),  -- meadow green
    tagOpenWorldSoft = rgba8(176, 215, 190),
    tagNeighborhood = rgba8(196, 91, 129), -- flower pink
    tagNeighborhoodSoft = rgba8(226, 177, 195),
    tagText = rgba8(37, 31, 35),
}

-- Cool ink surfaces with distinct elevation, selection, and accent states.
local DARK_COLOR = {
    panel = rgba8(18, 16, 25),          -- deepest page surface
    rail = rgba8(28, 27, 40),           -- raised navigation plane
    card = rgba8(35, 33, 46),           -- normal interactive surface
    cardAlt = rgba8(43, 39, 54),        -- secondary control surface
    border = rgba8(90, 83, 105),        -- focused outline
    borderSoft = rgba8(66, 62, 76),     -- quiet card separation
    text = rgba8(238, 233, 239),
    muted = rgba8(180, 172, 184),
    faint = rgba8(125, 117, 132),
    sky = rgba8(80, 173, 205),
    skySoft = rgba8(27, 54, 69),
    mint = rgba8(80, 199, 151),         -- selected pet outline
    mintSoft = rgba8(22, 69, 55),       -- selected pet surface
    lilac = rgba8(160, 124, 224),       -- selected navigation accent
    lilacSoft = rgba8(57, 43, 82),      -- selected navigation surface
    amber = rgba8(230, 171, 77),
    amberSoft = rgba8(76, 54, 24),
    red = rgba8(210, 92, 119),
    redSoft = rgba8(73, 33, 45),
    hoverSurface = rgba8(52, 48, 64),   -- neutral lift, distinct from selection
    hoverBorder = rgba8(110, 100, 124),
    white = rgba8(245, 241, 244),
    tagAll = rgba8(104, 72, 118),        -- brighter selected row action
    tagAllSoft = rgba8(42, 31, 49),
    tagCity = rgba8(81, 190, 215),       -- luminous without turning neon
    tagCitySoft = rgba8(21, 58, 70),
    tagDungeon = rgba8(160, 124, 224),
    tagDungeonSoft = rgba8(45, 34, 66),
    tagRaid = rgba8(231, 171, 75),
    tagRaidSoft = rgba8(70, 49, 20),
    tagOpenWorld = rgba8(83, 188, 129),
    tagOpenWorldSoft = rgba8(22, 61, 43),
    tagNeighborhood = rgba8(218, 104, 146),
    tagNeighborhoodSoft = rgba8(68, 32, 49),
    tagText = rgba8(18, 17, 22),
}
local LIGHT_SHELL_TINT = rgba8(191, 168, 135)
local DARK_SHELL_TINT = rgba8(31, 28, 42)
local LIGHT_COLOR = {}
for name, color in pairs(COLOR) do LIGHT_COLOR[name] = {color[1], color[2], color[3], color[4]} end
local THEME_BACKDROPS, THEME_FONTS, THEME_TEXTURES, THEME_EDITBOXES = {}, {}, {}, {}

-- The UI exposes the existing rule pools as five simple place tags.  Rule IDs
-- stay stable so old selections migrate without duplicating saved data.
local TAG_DEFINITIONS = {
    {key = "city", ruleID = "cities", label = "City", width = 64, color = COLOR.tagCity, soft = COLOR.tagCitySoft},
    {key = "dungeon", ruleID = "dungeons", label = "Dungeon", width = 82, color = COLOR.tagDungeon, soft = COLOR.tagDungeonSoft},
    {key = "raid", ruleID = "raids", label = "Raid", width = 58, color = COLOR.tagRaid, soft = COLOR.tagRaidSoft},
    {key = "openworld", ruleID = "solo", label = "Open world", width = 96, color = COLOR.tagOpenWorld, soft = COLOR.tagOpenWorldSoft},
    {key = "neighborhood", ruleID = "neighborhood", label = "Neighborhood", width = 108, color = COLOR.tagNeighborhood, soft = COLOR.tagNeighborhoodSoft},
}

-- ALL is a row action, not a sixth condition.  It is intentionally compact
-- so the five actual place toggles stay visible at every supported UI scale.
local ALL_TAG_DEFINITION = {key = "all", label = "ALL", width = 36, color = COLOR.tagAll, soft = COLOR.tagAllSoft}

local TAG_BY_KEY = {}
for _, definition in ipairs(TAG_DEFINITIONS) do
    TAG_BY_KEY[definition.key] = definition
end

local DEFAULT_RULES = {
    {id = "everywhere", label = "Everywhere", description = "Use selected pets anywhere.", accent = "lilac"},
    {id = "dungeons", label = "Dungeons", description = "Use selected pets in dungeons.", accent = "sky"},
    {id = "raids", label = "Raids", description = "Use selected pets in raids.", accent = "lilac"},
    {id = "solo", label = "Solo", description = "Use selected pets while solo.", accent = "mint"},
    {id = "cities", label = "Cities", description = "Use selected pets in cities.", accent = "sky"},
    {id = "neighborhood", label = "Home area", description = "Use selected pets near home.", accent = "mint"},
    {id = "outfit", label = "Outfit match", description = "Use a separate pet list for outfits.", accent = "lilac"},
}

local SIMPLE_RULE_COPY = {}
for _, rule in ipairs(DEFAULT_RULES) do
    SIMPLE_RULE_COPY[rule.id] = rule
end

local function copyColor(color, alpha)
    return color[1], color[2], color[3], alpha == nil and color[4] or alpha
end

local function setThemeTextureColor(texture, color, alpha)
    if not texture or not texture.SetColorTexture then return end
    texture._apsThemeColor = color
    texture._apsThemeAlpha = alpha
    if not texture._apsThemeTracked then
        texture._apsThemeTracked = true
        table.insert(THEME_TEXTURES, texture)
    end
    texture:SetColorTexture(copyColor(color, alpha))
end

local function applyShellPalette(shell, dark)
    if not shell then return end
    -- Both modes share the exact proven rounded alpha mask. Dark mode is a
    -- code tint, so it cannot reintroduce a baked opaque contour or halo.
    shell:SetTexture(JOURNAL_SHELL)
    if shell.SetDesaturated then pcall(shell.SetDesaturated, shell, true) end
    local tint = dark and DARK_SHELL_TINT or LIGHT_SHELL_TINT
    if shell.SetVertexColor then shell:SetVertexColor(copyColor(tint, 1)) end
    shell:SetAlpha(1)
end

local function safeCall(object, method, ...)
    if not object or type(object[method]) ~= "function" then
        return false, nil
    end
    local ok, a, b, c, d, e, f, g, h, i = pcall(object[method], object, ...)
    if not ok then
        return false, nil
    end
    return true, a, b, c, d, e, f, g, h, i
end

local function isSecret(value)
    if type(APS.IsSecret) == "function" then
        local ok, secret = pcall(APS.IsSecret, APS, value)
        if ok then return secret == true end
    end
    if type(_G.issecretvalue) == "function" then
        local ok, secret = pcall(_G.issecretvalue, value)
        if ok then return secret == true end
    end
    return false
end

local function readableString(value)
    return not isSecret(value) and type(value) == "string" and value or nil
end

local function readableValue(value)
    return not isSecret(value) and value or nil
end

local function safeGlobal(name, ...)
    local fn = _G[name]
    if type(fn) ~= "function" then
        return false, nil
    end
    local ok, a, b, c, d, e, f, g, h, i = pcall(fn, ...)
    if not ok then
        return false, nil
    end
    return true, a, b, c, d, e, f, g, h, i
end

local function setTextColor(fontString, color, alpha)
    if fontString and fontString.SetTextColor then
        fontString._apsThemeColor = color
        fontString._apsThemeAlpha = alpha
        if not fontString._apsThemeTracked then
            fontString._apsThemeTracked = true
            table.insert(THEME_FONTS, fontString)
        end
        fontString:SetTextColor(copyColor(color, alpha))
    end
end

local function setBackdrop(frame, background, border, alpha, edgeSize)
    if not frame then
        return
    end
    if frame.SetBackdrop then
        frame._apsThemeBackdrop = {background = background or COLOR.card, border = border or COLOR.border, alpha = alpha, edgeSize = edgeSize}
        if not frame._apsThemeTracked then
            frame._apsThemeTracked = true
            table.insert(THEME_BACKDROPS, frame)
        end
        frame:SetBackdrop({
            bgFile = WHITE,
            edgeFile = WHITE,
            tile = true,
            tileSize = 8,
            edgeSize = edgeSize or 1,
            insets = {left = 1, right = 1, top = 1, bottom = 1},
        })
        frame:SetBackdropColor(copyColor(background or COLOR.card, alpha))
        frame:SetBackdropBorderColor(copyColor(border or COLOR.border, alpha or 1))
        return
    end
    if not frame._apsBackground then
        frame._apsBackground = frame:CreateTexture(nil, "BACKGROUND")
        frame._apsBackground:SetAllPoints(frame)
    end
    setThemeTextureColor(frame._apsBackground, background or COLOR.card, alpha)
end

function UI:ApplyTheme()
    local dark = type(APS.GetSetting) == "function" and APS:GetSetting("darkMode", false) == true
    local palette = dark and DARK_COLOR or LIGHT_COLOR
    for name, source in pairs(palette) do
        local target = COLOR[name]
        if target then
            target[1], target[2], target[3], target[4] = source[1], source[2], source[3], source[4]
        end
    end
    for _, frame in ipairs(THEME_BACKDROPS) do
        local style = frame and frame._apsThemeBackdrop
        if style and frame.SetBackdropColor then
            frame:SetBackdropColor(copyColor(style.background, style.alpha))
            if frame.SetBackdropBorderColor then frame:SetBackdropBorderColor(copyColor(style.border, style.alpha or 1)) end
        end
    end
    for _, fontString in ipairs(THEME_FONTS) do
        if fontString and fontString.SetTextColor and fontString._apsThemeColor then
            fontString:SetTextColor(copyColor(fontString._apsThemeColor, fontString._apsThemeAlpha))
        end
    end
    for _, editBox in ipairs(THEME_EDITBOXES) do
        if editBox and editBox.SetTextColor and editBox._apsThemeTextColor then
            editBox:SetTextColor(copyColor(editBox._apsThemeTextColor, 1))
        end
    end
    for _, texture in ipairs(THEME_TEXTURES) do
        if texture and texture.SetColorTexture and texture._apsThemeColor then
            texture:SetColorTexture(copyColor(texture._apsThemeColor, texture._apsThemeAlpha))
        end
    end
    if not self.frame then return end
    if self.frame.SetBackdrop then self.frame:SetBackdrop(nil) end
    if self.frame.shell then
        applyShellPalette(self.frame.shell, dark)
    end
    if self.frame.paper then self.frame.paper:SetAlpha(dark and 0.055 or 0.11) end
    if self.help and self.help.paper then self.help.paper:SetAlpha(dark and 0.04 or 0.08) end
    if self.pages then
        self:RefreshAll(true)
        for pageID, button in pairs(self.nav or {}) do self:StyleRailButton(button, pageID == self.currentPage) end
    end
    if self.help and self.help:IsShown() then self:ShowHelpTopic(self.helpTopic or "start") end
end

local function font(parent, template, size, color)
    local fs = parent:CreateFontString(nil, "OVERLAY", template or "GameFontNormal")
    if fs.SetFont then
        local path = _G.STANDARD_TEXT_FONT
        if not path and fs.GetFont then path = fs:GetFont() end
        if path then fs:SetFont(path, size or 12, "") end
    end
    setTextColor(fs, color or COLOR.text)
    if fs.SetShadowColor then fs:SetShadowColor(0, 0, 0, 0) end
    if fs.SetShadowOffset then fs:SetShadowOffset(0, 0) end
    return fs
end

local function makeLabel(parent, text, size, color)
    local fs = font(parent, "GameFontNormal", size, color)
    fs:SetText(text or "")
    return fs
end

local function setModelFacing(model, facing)
    if not model or type(facing) ~= "number" then return end
    model._apsRotation = facing
    if model.SetFacing then
        pcall(model.SetFacing, model, facing)
    elseif model.SetRotation then
        pcall(model.SetRotation, model, facing)
    end
end

local function setModelSilhouette(model, enabled)
    if not model or type(model.SetLight) ~= "function" then return false end
    if type(_G.CreateVector3D) ~= "function" or type(_G.CreateColor) ~= "function" then
        return false
    end
    if not enabled then
        local nativeLight = {
            omnidirectional = false,
            point = _G.CreateVector3D(-1, 0, -1),
            ambientIntensity = 0.7,
            ambientColor = _G.CreateColor(0.7, 0.7, 0.7),
            diffuseIntensity = 1,
            diffuseColor = _G.CreateColor(0.8, 0.8, 0.8),
        }
        -- SetLight(false) does not reliably clear the previous custom light
        -- on Retail PlayerModel widgets. Install the neutral light explicitly
        -- so a real summoned pet can never inherit the empty-state silhouette.
        return pcall(model.SetLight, model, true, nativeLight)
    end
    local dark = type(APS.GetSetting) == "function" and APS:GetSetting("darkMode", false) == true
    -- Pure black is clear on parchment. Dark mode uses a single cool-ink tone
    -- so the same silhouette remains visible without restoring model color.
    local shade = dark and 0.19 or 0
    local light = {
        omnidirectional = true,
        point = _G.CreateVector3D(0, 0, 0),
        ambientIntensity = 1,
        ambientColor = _G.CreateColor(shade, shade, shade + (dark and 0.035 or 0)),
        diffuseIntensity = 0,
        diffuseColor = _G.CreateColor(0, 0, 0),
    }
    return pcall(model.SetLight, model, true, light)
end

local function resetModelRotation(model, automaticSpeed)
    if not model then return end
    model._apsAutoRotationSpeed = automaticSpeed
    setModelFacing(model, DEFAULT_MODEL_FACING)
end

local function enableModelRotation(model)
    if not model then return end
    model:EnableMouse(true)
    if model.EnableMouseMotion then pcall(model.EnableMouseMotion, model, true) end
    model:RegisterForDrag("LeftButton")
    model._apsRotation = 0
    local function stopRotation(self)
        self._apsRotating = nil
        self._apsLastCursorX = nil
    end
    local function updateRotation(self, elapsed)
        if not self._apsRotating then
            local speed = self._apsAutoRotationSpeed
            if type(speed) == "number" and speed ~= 0 then
                setModelFacing(self, (self._apsRotation or DEFAULT_MODEL_FACING) - speed * (elapsed or 0))
            end
            return
        end
        if type(_G.IsMouseButtonDown) == "function" then
            local downOK, isDown = pcall(_G.IsMouseButtonDown, "LeftButton")
            if downOK and not isSecret(isDown) and isDown == false then
                stopRotation(self)
                return
            end
        end
        local cursorOK, cursorX = safeGlobal("GetCursorPosition")
        if not cursorOK or isSecret(cursorX) or type(cursorX) ~= "number" then
            stopRotation(self)
            return
        end
        local previous = self._apsLastCursorX or cursorX
        local delta = cursorX - previous
        self._apsLastCursorX = cursorX
        if delta == 0 then return end
        local facing = self._apsRotation or 0
        if self.GetFacing then
            local facingOK, current = pcall(self.GetFacing, self)
            if facingOK and not isSecret(current) and type(current) == "number" then facing = current end
        end
        facing = facing + delta * 0.01
        setModelFacing(self, facing)
    end
    model:SetScript("OnUpdate", updateRotation)
    model:SetScript("OnModelLoaded", function(self)
        local callback = self._apsModelLoadedCallback
        if callback then callback(self) end
    end)
    model:SetScript("OnMouseDown", function(self, button)
        if button ~= "LeftButton" then return end
        stopRotation(self)
        local cursorOK, cursorX = safeGlobal("GetCursorPosition")
        if not cursorOK or isSecret(cursorX) or type(cursorX) ~= "number" then return end
        self._apsLastCursorX = cursorX
        self._apsRotating = true
    end)
    model:SetScript("OnMouseUp", stopRotation)
    model:SetScript("OnDragStop", stopRotation)
    model:SetScript("OnLeave", stopRotation)
    model:SetScript("OnHide", stopRotation)
end

local function setPetModel(model, info, fitDistance, automaticSpeed, onLoaded, onFailed)
    if not model or type(info) ~= "table" then return false end
    local displayID = not isSecret(info.displayID) and tonumber(info.displayID) or nil
    local creatureID = not isSecret(info.creatureID) and tonumber(info.creatureID) or nil
    if not displayID and not creatureID then return false end

    model._apsModelRequestToken = (model._apsModelRequestToken or 0) + 1
    local token = model._apsModelRequestToken
    model._apsModelLoaded = false
    model._apsModelLoadedCallback = function(self)
        if self._apsModelRequestToken ~= token then return end
        self._apsModelLoaded = true
        if self.SetCamDistanceScale and fitDistance then
            pcall(self.SetCamDistanceScale, self, fitDistance)
        end
        resetModelRotation(self, automaticSpeed)
        if onLoaded then onLoaded(self) end
    end

    local function tryMethod(methodName, value)
        local method = model[methodName]
        if type(method) ~= "function" or type(value) ~= "number" then return false end
        local ok = pcall(method, model, value)
        return ok
    end

    if model.ClearModel then pcall(model.ClearModel, model) end
    model:Show()
    resetModelRotation(model, automaticSpeed)
    local attempted = tryMethod("SetDisplayInfo", displayID)
    if not attempted then attempted = tryMethod("SetCreature", creatureID) end
    if not attempted then
        model._apsModelLoadedCallback = nil
        if onFailed then onFailed(model) end
        return false
    end

    -- A successful Lua call only means the request was accepted. Some battle
    -- pet displays do not produce a model on the first request. Retry through
    -- their creature ID, then the exact display ID, for every pet rather than
    -- maintaining a list of exceptions.
    if C_Timer and C_Timer.After then
        C_Timer.After(0.35, function()
            if model._apsModelRequestToken ~= token or model._apsModelLoaded then return end
            if creatureID and model.SetCreature then
                if model.ClearModel then pcall(model.ClearModel, model) end
                tryMethod("SetCreature", creatureID)
            elseif displayID then
                tryMethod("SetDisplayInfo", displayID)
            end
        end)
        C_Timer.After(1.25, function()
            if model._apsModelRequestToken ~= token or model._apsModelLoaded then return end
            if displayID and model.SetDisplayInfo then
                if model.ClearModel then pcall(model.ClearModel, model) end
                tryMethod("SetDisplayInfo", displayID)
            end
        end)
        C_Timer.After(3, function()
            if model._apsModelRequestToken ~= token or model._apsModelLoaded then return end
            if onFailed then onFailed(model) end
        end)
    end
    return true
end

local function setButtonFont(button, size, color)
    local fs = button._apsText or (button.GetFontString and button:GetFontString())
    if fs then
        if size and fs.SetFont then
            local path = _G.STANDARD_TEXT_FONT
            if not path and fs.GetFont then path = fs:GetFont() end
            if path then fs:SetFont(path, size, "") end
        end
        setTextColor(fs, color or COLOR.text)
        if fs.SetShadowColor then fs:SetShadowColor(0, 0, 0, 0) end
        if fs.SetShadowOffset then fs:SetShadowOffset(0, 0) end
    end
end

local function makeButton(parent, text, width, height, tone)
    local button = CreateFrame("Button", nil, parent, "BackdropTemplate")
    button:SetSize(width or 100, height or 30)
    setBackdrop(button, (tone and tone[1]) or COLOR.card, (tone and tone[2]) or COLOR.borderSoft, 1, 1)
    local label = font(button, "GameFontNormal", 11, (tone and tone[3]) or COLOR.text)
    label:SetPoint("LEFT", 7, 0)
    label:SetPoint("RIGHT", -7, 0)
    label:SetJustifyH("CENTER")
    label:SetWordWrap(false)
    if label.SetMaxLines then label:SetMaxLines(1) end
    button._apsText = label
    if button.SetFontString then button:SetFontString(label) end
    button:SetText(text or "")
    setButtonFont(button, 11, (tone and tone[3]) or COLOR.text)
    button:SetScript("OnEnter", function(self)
        if self:IsEnabled() then
            self:SetBackdropColor(copyColor(COLOR.hoverSurface, 1))
            self:SetBackdropBorderColor(copyColor(COLOR.hoverBorder, 0.72))
        end
    end)
    button:SetScript("OnLeave", function(self)
        if self._apsSelected then
            self:SetBackdropColor(copyColor(COLOR.lilacSoft, 1))
            self:SetBackdropBorderColor(copyColor(COLOR.lilac, 1))
        else
            setBackdrop(self, (tone and tone[1]) or COLOR.card, (tone and tone[2]) or COLOR.borderSoft, 1, 1)
        end
    end)
    button:SetScript("OnDisable", function(self)
        self:SetAlpha(0.45)
    end)
    button:SetScript("OnEnable", function(self)
        self:SetAlpha(1)
    end)
    return button
end

local function addButtonIcon(button, texture, size)
    if not button then return end
    local icon = button:CreateTexture(nil, "ARTWORK", nil, 1)
    icon:SetSize(size or 16, size or 16)
    icon:SetPoint("LEFT", 9, 0)
    icon:SetTexture(texture)
    button._apsAdornmentIcon = icon
    if button._apsText then
        button._apsText:ClearAllPoints()
        button._apsText:SetPoint("LEFT", icon, "RIGHT", 6, 0)
        button._apsText:SetPoint("RIGHT", -8, 0)
    end
    return icon
end

local function addBottomAccent(button, color)
    if not button then return end
    local accent = button:CreateTexture(nil, "ARTWORK", nil, 2)
    accent:SetPoint("BOTTOMLEFT", 1, 1)
    accent:SetPoint("BOTTOMRIGHT", -1, 1)
    accent:SetHeight(3)
    setThemeTextureColor(accent, color or COLOR.lilac, 1)
    button._apsBottomAccent = accent
    button._apsAccentColor = color or COLOR.lilac
    return accent
end

function UI:StyleRailButton(button, selected)
    if not button then return end
    button._apsSelected = selected and true or false
    local accent = button._apsMarkerColor or COLOR.lilac
    if button._apsSelected then
        button:SetBackdropColor(copyColor(COLOR.lilacSoft, 1))
        button:SetBackdropBorderColor(copyColor(COLOR.lilacSoft, 1))
        if button._apsLabel then setTextColor(button._apsLabel, COLOR.text) end
        if button._apsMarker then setThemeTextureColor(button._apsMarker, accent, 1) end
        if button._apsIcon then button._apsIcon:SetAlpha(1) end
    else
        button:SetBackdropColor(copyColor(COLOR.rail, 1))
        button:SetBackdropBorderColor(copyColor(COLOR.rail, 1))
        if button._apsLabel then setTextColor(button._apsLabel, COLOR.muted) end
        if button._apsMarker then setThemeTextureColor(button._apsMarker, COLOR.faint, 0.55) end
        if button._apsIcon then button._apsIcon:SetAlpha(0.72) end
    end
end

function UI:StyleFilterButton(button, selected)
    if not button then return end
    button._apsSelected = selected and true or false
    local accent = button._apsAccentColor or COLOR.lilac
    if selected then
        button:SetBackdropColor(copyColor(COLOR.lilacSoft, 1))
        button:SetBackdropBorderColor(copyColor(COLOR.lilac, 1))
        setButtonFont(button, nil, COLOR.text)
        if button._apsAdornmentIcon then button._apsAdornmentIcon:SetAlpha(1) end
        if button._apsBottomAccent then setThemeTextureColor(button._apsBottomAccent, accent, 1) end
    else
        button:SetBackdropColor(copyColor(COLOR.cardAlt, 0.55))
        button:SetBackdropBorderColor(copyColor(COLOR.borderSoft, 0.85))
        setButtonFont(button, nil, COLOR.muted)
        if button._apsAdornmentIcon then button._apsAdornmentIcon:SetAlpha(0.68) end
        if button._apsBottomAccent then setThemeTextureColor(button._apsBottomAccent, accent, 0.45) end
    end
end

local function styleEditBox(editBox)
    if not editBox then return end
    local fontObject = _G.GameFontHighlight or _G.GameFontNormal
    if fontObject and editBox.SetFontObject then editBox:SetFontObject(fontObject) end
    if editBox.SetFont then
        local path = _G.STANDARD_TEXT_FONT
        if not path and fontObject and fontObject.GetFont then path = fontObject:GetFont() end
        if path then editBox:SetFont(path, 12, "") end
    end
    editBox._apsThemeTextColor = COLOR.text
    if not editBox._apsThemeTextTracked then
        editBox._apsThemeTextTracked = true
        table.insert(THEME_EDITBOXES, editBox)
    end
    if editBox.SetTextColor then editBox:SetTextColor(copyColor(editBox._apsThemeTextColor, 1)) end
    if editBox.SetShadowColor then editBox:SetShadowColor(0, 0, 0, 0) end
end

local function setButtonSelected(button, selected, accent)
    button._apsSelected = selected and true or false
    accent = accent or COLOR.lilac
    if selected then
        button:SetBackdropColor(copyColor(COLOR.lilacSoft, 1))
        button:SetBackdropBorderColor(copyColor(accent, 1))
        setButtonFont(button, nil, COLOR.text)
    else
        button:SetBackdropColor(copyColor(COLOR.card, 1))
        button:SetBackdropBorderColor(copyColor(COLOR.borderSoft, 1))
        setButtonFont(button, nil, COLOR.muted)
    end
end

local function makeDivider(parent, x, y, width, color)
    local divider = parent:CreateTexture(nil, "ARTWORK")
    setThemeTextureColor(divider, color or COLOR.borderSoft, 1)
    divider:SetPoint("TOPLEFT", x, y)
    divider:SetSize(width, 1)
    return divider
end

local function trim(value)
    value = tostring(value or "")
    return (value:gsub("^%s+", ""):gsub("%s+$", ""))
end

local function lower(value)
    return string.lower(tostring(value or ""))
end

local function tableContains(list, value)
    if type(list) ~= "table" then
        return false
    end
    for _, item in ipairs(list) do
        if tostring(item) == tostring(value) then
            return true
        end
    end
    return false
end

local function tableCopy(list)
    local result = {}
    if type(list) == "table" then
        for index, value in ipairs(list) do
            result[index] = value
        end
    end
    return result
end

local function petSelectionList(selection)
    if type(selection) ~= "table" then return {} end
    if #selection > 0 then return tableCopy(selection) end
    local result = {}
    for petID, selected in pairs(selection) do
        if selected == true and (type(petID) == "string" or type(petID) == "number") then
            result[#result + 1] = petID
        end
    end
    table.sort(result, function(a, b) return tostring(a) < tostring(b) end)
    return result
end

function UI:EnsureDB()
    if type(APS.GetDB) == "function" then
        local ok, runtimeDB = pcall(APS.GetDB, APS)
        if ok and type(runtimeDB) == "table" then
            if type(runtimeDB.ui) ~= "table" then runtimeDB.ui = {} end
            return runtimeDB
        end
    end
    if type(_G.PETALDB) ~= "table" then
        _G.PETALDB = {}
    end
    local db = _G.PETALDB
    if db.enabled == nil then db.enabled = true end
    if db.intervalMinutes == nil then db.intervalMinutes = 5 end
    if db.dismissGraceMinutes == nil then db.dismissGraceMinutes = 10 end
    if type(db.selectedPets) ~= "table" then db.selectedPets = {} end
    if type(db.rules) ~= "table" then db.rules = {} end
    if type(db.ui) ~= "table" then db.ui = {} end
    return db
end

function UI:ReadRules()
    local ok, rules = safeCall(APS, "GetRules")
    if ok and type(rules) == "table" and #rules > 0 then
        return rules
    end
    if ok and type(rules) == "table" then
        local mapped = {}
        for key, value in pairs(rules) do
            if type(value) == "table" then
                local copy = {}
                for field, fieldValue in pairs(value) do copy[field] = fieldValue end
                if not copy.id and not copy.key then copy.id = key end
                table.insert(mapped, copy)
            end
        end
        if #mapped > 0 then return mapped end
    end

    local db = self:EnsureDB()
    local source = db.rules
    local result = {}
    local legacyPets = self:SelectedPetIDs(nil)
    for index, fallback in ipairs(DEFAULT_RULES) do
        local stored = source[fallback.id]
        if type(stored) ~= "table" and type(source[index]) == "table" then
            stored = source[index]
        end
        local rule = {
            id = fallback.id,
            key = fallback.id,
            label = fallback.label,
            title = fallback.label,
            description = fallback.description,
            accent = fallback.accent,
            enabled = stored and stored.enabled ~= false or (not stored and fallback.id == "everywhere"),
            petIDs = stored and (stored.petIDs or stored.pets or stored.selectedPets) or tableCopy(legacyPets),
            mode = stored and (stored.mode or stored.selectionMode) or "selected",
        }
        result[index] = rule
    end
    return result
end

function UI:RuleID(rule)
    if type(rule) ~= "table" then return nil end
    return rule.id or rule.key or rule.context or rule.name
end

function UI:RuleTitle(rule)
    if type(rule) ~= "table" then return "Rule" end
    local preset = SIMPLE_RULE_COPY[self:RuleID(rule)]
    if preset then return preset.label end
    return rule.title or rule.label or rule.name or self:RuleID(rule) or "Rule"
end

function UI:RuleDescription(rule)
    if type(rule) ~= "table" then return "" end
    local preset = SIMPLE_RULE_COPY[self:RuleID(rule)]
    if preset then return preset.description end
    return rule.description or rule.subtitle or rule.summary or "Uses your selected pets."
end

function UI:RuleAccent(rule)
    local accent = type(rule) == "table" and rule.accent
    if type(accent) == "table" then return accent end
    return COLOR[accent] or COLOR.sky
end

function UI:RulePetIDs(rule)
    if type(rule) ~= "table" then return {} end
    local ids = rule.petIDs or rule.pets or rule.selectedPets or rule.petPool or rule.pool
    if type(ids) == "table" then
        ids = ids.petIDs or ids.petIds or ids.pets or ids.selectedPets or ids
    end
    if type(ids) == "table" and #ids == 0 and type(rule.pool) == "table" then
        local poolIDs = rule.pool.petIDs or rule.pool.petIds or rule.pool.pets or rule.pool.selectedPets
        if type(poolIDs) == "table" then ids = poolIDs end
    end
    if type(ids) ~= "table" then return {} end
    if #ids > 0 then return tableCopy(ids) end
    local result = {}
    for petID, enabled in pairs(ids) do
        if enabled then table.insert(result, petID) end
    end
    return result
end

function UI:RuleMode(rule)
    if type(rule) ~= "table" then return "selected" end
    local mode = rule.mode or rule.selectionMode
    if not mode and type(rule.pool) == "table" then
        mode = rule.pool.mode or rule.pool.randomMode
        if rule.pool.random == true and mode == "selected" then mode = "shuffle" end
    end
    mode = type(mode) == "string" and string.lower(mode) or "selected"
    if mode == "random" or mode == "selectedrandom" then mode = "shuffle" end
    if mode == "fullrandom" or mode == "full_random" or mode == "all" then mode = "full" end
    if mode == "favorites" then mode = "favorite" end
    return mode
end

function UI:RulesSignature(rules)
    local parts = {}
    for _, rule in ipairs(rules or {}) do
        local ids = self:RulePetIDs(rule)
        table.sort(ids, function(a, b) return tostring(a) < tostring(b) end)
        local switches = rule.switchOnMomentChange == true
        if type(rule.behavior) == "table" then switches = switches or rule.behavior.switchOnMomentChange == true end
        table.insert(parts, tostring(self:RuleID(rule)) .. ":" .. (self:IsRuleEnabled(rule) and "1" or "0") .. ":" .. self:RuleMode(rule) .. ":" .. (switches and "1" or "0") .. ":" .. table.concat(ids, ","))
    end
    return table.concat(parts, "|")
end

function UI:IsRuleEnabled(rule)
    return type(rule) == "table" and rule.enabled ~= false
end

function UI:PersistRuleField(rule, field, value)
    local id = self:RuleID(rule)
    if not id then return end
    local method
    if field == "enabled" then
        method = "SetRuleEnabled"
    elseif field == "petIDs" or field == "pets" then
        method = "SetRulePets"
    elseif field == "mode" then
        method = "SetRuleMode"
    elseif field == "switchOnMomentChange" then
        method = "SetRuleSwitchOnMomentChange"
    end
    local handled = false
    if method and type(APS[method]) == "function" then
        local ok = pcall(APS[method], APS, id, value)
        handled = ok
        if not ok then
            handled = pcall(APS[method], id, value)
        end
    end

    if not handled then
        local db = self:EnsureDB()
        local target
        for _, candidate in ipairs(db.rules or {}) do
            if self:RuleID(candidate) == id then target = candidate break end
        end
        if not target and type(id) == "number" then target = db.rules[id] end
        if not target then
            db.rules = db.rules or {}
            target = {id = id, name = id, enabled = false, order = #db.rules + 1}
            db.rules[#db.rules + 1] = target
        end
        target[field] = type(value) == "table" and tableCopy(value) or value
    end

    if field == "enabled" then rule.enabled = value
    elseif field == "petIDs" then rule.petIDs = tableCopy(value)
    elseif field == "mode" then rule.mode = value
    elseif field == "switchOnMomentChange" then
        rule.switchOnMomentChange = value == true
        rule.behavior = type(rule.behavior) == "table" and rule.behavior or {}
        rule.behavior.switchOnMomentChange = value == true
    end

    if type(APS.RefreshRules) == "function" then
        pcall(APS.RefreshRules, APS)
    end
end

function UI:SelectedPetIDs(rule)
    if rule then
        return self:RulePetIDs(rule)
    end
    local rosterOK, roster = safeCall(APS, "GetSelectedRoster")
    if rosterOK and type(roster) == "table" then
        return petSelectionList(roster)
    end
    local apiOK, apiIDs = safeCall(APS, "GetSelectedPetIDs")
    if apiOK and type(apiIDs) == "table" then
        return tableCopy(apiIDs)
    end
    local db = self:EnsureDB()
    local result = {}
    for petID, enabled in pairs(db.selectedPets) do
        if enabled then table.insert(result, petID) end
    end
    return result
end

function UI:IsPetSelected(petID, rule)
    return tableContains(self:SelectedPetIDs(rule), petID)
end

function UI:SetPetSelected(petID, selected, rule)
    if not petID then return end
    local current = self:SelectedPetIDs(rule)
    local nextList = {}
    for _, id in ipairs(current) do
        if tostring(id) ~= tostring(petID) then table.insert(nextList, id) end
    end
    if selected then table.insert(nextList, petID) end

    if rule then
        self:PersistRuleField(rule, "petIDs", nextList)
        return
    end

    if type(APS.SetPetSelected) == "function" then
        local ok = pcall(APS.SetPetSelected, APS, petID, selected and true or false)
        if ok then return end
    end

    local db = self:EnsureDB()
    db.selectedPets[petID] = selected and true or nil
    if type(APS.SetSelectedPets) == "function" then
        pcall(APS.SetSelectedPets, APS, db.selectedPets)
    end
end

function UI:PetIDsForInfo(info)
    if not info then return {} end
    if type(info.petIDs) == "table" and #info.petIDs > 0 then return info.petIDs end
    return info.petID and {info.petID} or {}
end

function UI:IsPetInfoSelected(info)
    for _, petID in ipairs(self:PetIDsForInfo(info)) do
        if self:IsPetSelected(petID, nil) then return true end
    end
    return false
end

function UI:SetPetInfoSelected(info, selected)
    if not info then return end
    if selected then
        self:SetPetSelected(info.petID, true, nil)
        return
    end
    -- A species may still have several GUIDs selected from an older build.
    -- One click on its single visible card removes every copy and its tags.
    for _, petID in ipairs(self:PetIDsForInfo(info)) do
        if self:IsPetSelected(petID, nil) then self:SetPetSelected(petID, false, nil) end
    end
end

function UI:SelectedPetSpeciesCount()
    local count = 0
    for _, info in ipairs(self.petCache or {}) do
        if self:IsPetInfoSelected(info) then count = count + 1 end
    end
    return count
end

function UI:GetPetInfoTags(info)
    local result = {}
    for _, petID in ipairs(self:PetIDsForInfo(info)) do
        local tags = self:GetPetTags(petID)
        for _, definition in ipairs(TAG_DEFINITIONS) do
            if tags[definition.key] == true then result[definition.key] = true end
        end
    end
    return result
end

function UI:SetPetInfoTag(info, tagKey, enabled)
    if not info then return false end
    if enabled then return self:SetPetTag(info.petID, tagKey, true) end
    local handled = false
    for _, petID in ipairs(self:PetIDsForInfo(info)) do
        if self:PetHasTag(petID, tagKey) then
            handled = self:SetPetTag(petID, tagKey, false) or handled
        end
    end
    if not handled then handled = self:SetPetTag(info.petID, tagKey, false) end
    return handled
end

function UI:SetPetInfoAllTags(info, enabled)
    if not info or type(APS.SetPetTags) ~= "function" then return false end
    local states = {}
    for _, definition in ipairs(TAG_DEFINITIONS) do
        states[definition.key] = enabled and true or false
    end
    -- Match the species-card behavior of an individual tag: enabling writes
    -- the current representative, while clearing also removes legacy copies.
    local targets = enabled and {info.petID} or self:PetIDsForInfo(info)
    local ok, result = pcall(APS.SetPetTags, APS, targets, states)
    if not ok or result == false then return false end
    self:RefreshTaggedPetRowByID(info.petID)
    self:RefreshOverview()
    self:Toast((enabled and "All situations enabled: " or "All situations cleared: ") .. (info.name or "Pet"), enabled and COLOR.lilac or COLOR.muted)
    return true
end

function UI:IsPetDead(petID)
    if petID == nil or isSecret(petID) then return false end
    local journal = _G.C_PetJournal
    if not journal or type(journal.GetPetStats) ~= "function" then return false end
    local ok, health, maximumHealth = pcall(journal.GetPetStats, petID)
    if not ok or isSecret(health) or isSecret(maximumHealth) then return false end
    health, maximumHealth = tonumber(health), tonumber(maximumHealth)
    return health ~= nil and maximumHealth ~= nil and maximumHealth > 0 and health <= 0
end

function UI:GetDeadPoolMessage(rule)
    local ids = self:RulePetIDs(rule)
    if #ids == 0 then return nil end
    local deadCount, firstName = 0, nil
    for _, petID in ipairs(ids) do
        if not self:IsPetDead(petID) then return nil end
        deadCount = deadCount + 1
        if not firstName then
            local info = self:GetPetInfo(petID)
            firstName = info and info.name or nil
        end
    end
    if deadCount == 1 then return (firstName or "This pet") .. " needs revival" end
    return tostring(deadCount) .. " matching pets need revival"
end

function UI:HandleChangePetResult(changed, reason, rule)
    if changed ~= false or reason ~= "empty pet pool" then return end
    local message = self:GetDeadPoolMessage(rule)
    if not message then return end
    if self.frame and self.frame:IsShown() then
        self:Toast(message .. ".", COLOR.red)
    elseif type(_G.print) == "function" then
        _G.print("|cffc45b81PETAL:|r " .. message .. ".")
    end
end

function UI:GetPetTags(petID)
    if not petID then return {} end
    local ok, tags = safeCall(APS, "GetPetTags", petID)
    if ok and type(tags) == "table" then
        return tags
    end
    local result = {}
    for _, definition in ipairs(TAG_DEFINITIONS) do
        for _, rule in ipairs(self:ReadRules()) do
            if self:RuleID(rule) == definition.ruleID and tableContains(self:RulePetIDs(rule), petID) then
                result[definition.key] = true
                break
            end
        end
    end
    return result
end

function UI:PetHasTag(petID, tagKey)
    local tags = self:GetPetTags(petID)
    return tags[tagKey] == true
end

function UI:SetPetTag(petID, tagKey, enabled)
    local definition = TAG_BY_KEY[tagKey]
    if not petID or not definition then return false end
    local handled = false
    if type(APS.SetPetTag) == "function" then
        local ok, result = pcall(APS.SetPetTag, APS, petID, tagKey, enabled and true or false)
        handled = ok and result ~= false
    end
    if not handled then
        local rule
        for _, candidate in ipairs(self:ReadRules()) do
            if self:RuleID(candidate) == definition.ruleID then rule = candidate break end
        end
        if rule then
            local pets = self:RulePetIDs(rule)
            local nextPets = {}
            for _, id in ipairs(pets) do
                if tostring(id) ~= tostring(petID) then nextPets[#nextPets + 1] = id end
            end
            if enabled then nextPets[#nextPets + 1] = petID end
            self:PersistRuleField(rule, "petIDs", nextPets)
            self:PersistRuleField(rule, "enabled", #nextPets > 0)
            self:PersistRuleField(rule, "mode", "shuffle")
            self:PersistRuleField(rule, "switchOnMomentChange", true)
            handled = true
        end
    end
    if handled then
        local info = self:GetPetInfo(petID)
        self:RefreshTaggedPetRowByID(petID)
        self:RefreshOverview()
    self:Toast((enabled and definition.label .. " enabled" or definition.label .. " cleared") .. (info and (": " .. info.name) or ""), enabled and definition.color or COLOR.muted)
    end
    return handled
end

function UI:GetPets()
    local result = {}
    local journal = _G.C_PetJournal
    if not journal then
        return result
    end

    local selected = {}
    for _, petID in ipairs(self:SelectedPetIDs(nil)) do selected[tostring(petID)] = true end
    local seen = {}
    local groups = {}
    local groupsByKey = {}
    local function addPet(petID, speciesID, customName, level, favorite, revoked, speciesName, icon, displayID, creatureID)
        if isSecret(petID) or not petID then return end
        local petKey = tostring(petID)
        if seen[petKey] then return end
        seen[petKey] = true
        local currentlySummonable
        if type(journal.PetIsSummonable) == "function" then
            local summonOK, value = pcall(journal.PetIsSummonable, petID)
            if summonOK and not isSecret(value) then currentlySummonable = value ~= false end
        end
        customName = trim(readableString(customName) or "")
        speciesName = trim(readableString(speciesName) or "")
        local displayName = customName ~= "" and customName or (speciesName ~= "" and speciesName or "Pet")
        local safeSpeciesID = readableValue(speciesID)
        local speciesKey = safeSpeciesID and ("id:" .. tostring(safeSpeciesID)) or ("name:" .. lower(speciesName ~= "" and speciesName or displayName))
        local group = groupsByKey[speciesKey]
        if not group then
            group = {instances = {}}
            groupsByKey[speciesKey] = group
            groups[#groups + 1] = group
        end
        group.instances[#group.instances + 1] = {
            petID = petID,
            speciesID = safeSpeciesID,
            name = displayName,
            speciesName = speciesName ~= "" and speciesName or displayName,
            icon = readableValue(icon) or QUESTION_ICON,
            favorite = not isSecret(favorite) and favorite == true,
            level = readableValue(level),
            displayID = readableValue(displayID),
            creatureID = readableValue(creatureID),
            revoked = not isSecret(revoked) and revoked == true,
            currentlySummonable = currentlySummonable,
            dead = self:IsPetDead(petID),
        }
    end

    -- GetOwnedPetIDs is independent of the Blizzard Pet Journal's current
    -- search, source, type, and collected filters. Indexed enumeration is not.
    if type(journal.GetOwnedPetIDs) == "function" and type(journal.GetPetInfoTableByPetID) == "function" then
        local ownedOK, ownedPetIDs = pcall(journal.GetOwnedPetIDs)
        if ownedOK and not isSecret(ownedPetIDs) and type(ownedPetIDs) == "table" then
            for index = 1, math.min(#ownedPetIDs, 50000) do
                local petID = ownedPetIDs[index]
                local infoOK, info = pcall(journal.GetPetInfoTableByPetID, petID)
                if infoOK and not isSecret(info) and type(info) == "table" then
                    addPet(petID, info.speciesID, info.customName, info.petLevel, info.isFavorite,
                        info.isRevoked, info.name, info.icon, info.displayID, info.creatureID)
                end
            end
        end
    end

    -- Compatibility fallback for clients without the filter-independent API.
    if #groups == 0 and type(journal.GetNumPets) == "function" and type(journal.GetPetInfoByIndex) == "function" then
        local ok, count = pcall(journal.GetNumPets)
        count = ok and tonumber(count) or 0
        for index = 1, math.min(count or 0, 50000) do
            local infoOK, petID, speciesID, owned, customName, level, favorite, revoked, speciesName, icon = pcall(journal.GetPetInfoByIndex, index)
            if infoOK and not isSecret(owned) and owned == true then
                addPet(petID, speciesID, customName, level, favorite, revoked, speciesName, icon, nil)
            end
        end
    end

    for _, group in ipairs(groups) do
        local representative = group.instances[1]
        for _, candidate in ipairs(group.instances) do
            if selected[tostring(candidate.petID)] then
                representative = candidate
                break
            elseif not selected[tostring(representative.petID)] and candidate.currentlySummonable and not representative.currentlySummonable then
                representative = candidate
            end
        end
        representative.petIDs = {}
        representative.instanceCount = #group.instances
        representative.searchNames = ""
        for _, candidate in ipairs(group.instances) do
            representative.petIDs[#representative.petIDs + 1] = candidate.petID
            representative.favorite = representative.favorite or candidate.favorite
            representative.currentlySummonable = representative.currentlySummonable or candidate.currentlySummonable
            representative.displayID = representative.displayID or candidate.displayID
            representative.creatureID = representative.creatureID or candidate.creatureID
            representative.searchNames = representative.searchNames .. " " .. lower(candidate.name) .. " " .. lower(candidate.speciesName)
        end
        local anySelected, allRelevantDead = false, true
        for _, candidate in ipairs(group.instances) do
            if selected[tostring(candidate.petID)] then
                anySelected = true
                if not candidate.dead then allRelevantDead = false end
            end
        end
        if not anySelected then
            for _, candidate in ipairs(group.instances) do
                if not candidate.dead then allRelevantDead = false break end
            end
        end
        representative.dead = allRelevantDead
        result[#result + 1] = representative
    end
    table.sort(result, function(a, b)
        local left, right = lower(a.name), lower(b.name)
        if left ~= right then return left < right end
        return tostring(a.petID) < tostring(b.petID)
    end)
    return result
end

function UI:GetPetInfo(petID)
    if not petID then return nil end
    local journal = _G.C_PetJournal
    if journal and type(journal.GetPetInfoTableByPetID) == "function" then
        local ok, info = pcall(journal.GetPetInfoTableByPetID, petID)
        if ok and not isSecret(info) and type(info) == "table" then
            local speciesName = trim(readableString(info.name) or "")
            local customName = trim(readableString(info.customName) or "")
            local result = {
                petID = petID,
                speciesID = readableValue(info.speciesID),
                name = customName ~= "" and customName or (speciesName ~= "" and speciesName or "Pet"),
                speciesName = speciesName ~= "" and speciesName or nil,
                icon = readableValue(info.icon) or QUESTION_ICON,
                level = readableValue(info.petLevel),
                displayID = readableValue(info.displayID),
                creatureID = readableValue(info.creatureID),
                favorite = not isSecret(info.isFavorite) and info.isFavorite == true,
            }
            -- Retail's table API does not populate creatureID for every pet.
            -- Keep the exact display ID, but retain the legacy creature ID as
            -- a model-loading fallback for displays that fail to instantiate.
            if type(journal.GetPetInfoByPetID) == "function" and not result.creatureID then
                local legacyOK, legacySpeciesID, _, _, _, _, legacyDisplayID, _, _, _, _, legacyCreatureID =
                    pcall(journal.GetPetInfoByPetID, petID)
                if legacyOK then
                    result.speciesID = result.speciesID or readableValue(legacySpeciesID)
                    result.displayID = result.displayID or readableValue(legacyDisplayID)
                    result.creatureID = readableValue(legacyCreatureID)
                end
            end
            return result
        end
    end
    if journal and type(journal.GetPetInfoByPetID) == "function" then
        local ok, speciesID, customName, level, xp, maxXP, displayID, favorite,
            speciesName, icon, petType, creatureID = pcall(journal.GetPetInfoByPetID, petID)
        if ok and not isSecret(speciesID) and speciesID then
            customName = trim(readableString(customName) or "")
            speciesName = trim(readableString(speciesName) or "")
            return {
                petID = petID,
                speciesID = readableValue(speciesID),
                name = customName ~= "" and customName or (speciesName ~= "" and speciesName or "Pet"),
                speciesName = speciesName ~= "" and speciesName or nil,
                icon = readableValue(icon) or QUESTION_ICON,
                level = readableValue(level),
                petType = readableValue(petType),
                displayID = readableValue(displayID),
                creatureID = readableValue(creatureID),
                favorite = not isSecret(favorite) and favorite == true,
            }
        end
    end
    for _, info in ipairs(self.petCache or self:GetPets()) do
        if tostring(info.petID) == tostring(petID) then return info end
    end
    return nil
end

function UI:GetNoPetModelInfo(forceNew)
    if not forceNew and type(self._noPetModelInfo) == "table" then
        return self._noPetModelInfo
    end

    local candidates = {}
    for _, petID in ipairs(self:SelectedPetIDs()) do
        local info = self:GetPetInfo(petID)
        if info and (type(info.displayID) == "number" or type(info.creatureID) == "number") then
            candidates[#candidates + 1] = info
        end
    end
    if #candidates > 0 then
        self._noPetModelInfo = candidates[math.random(#candidates)]
        return self._noPetModelInfo
    end

    local journal = _G.C_PetJournal
    if journal and type(journal.GetPetInfoBySpeciesID) == "function" then
        local ok, name, icon, _, creatureID, _, _, _, _, _, _, _, displayID =
            pcall(journal.GetPetInfoBySpeciesID, DEFAULT_CAT_SPECIES_ID)
        if ok and (type(displayID) == "number" or type(creatureID) == "number") then
            self._noPetModelInfo = {
                speciesID = DEFAULT_CAT_SPECIES_ID,
                name = readableString(name) or "Cat",
                icon = readableValue(icon) or NO_PET_ART,
                displayID = readableValue(displayID),
                creatureID = readableValue(creatureID),
            }
            return self._noPetModelInfo
        end
    end

    self._noPetModelInfo = nil
    return nil
end

function UI:GetCurrentPet()
    local apiOK, apiInfo = safeCall(APS, "GetCurrentPet")
    if apiOK and type(apiInfo) == "table" then
        return apiInfo
    end
    local journal = _G.C_PetJournal
    if not journal or type(journal.GetSummonedPetGUID) ~= "function" then return nil end
    local ok, petID = pcall(journal.GetSummonedPetGUID)
    if not ok then return nil end
    if isSecret(petID) then
        local recordOK, record = safeCall(APS, "GetLastPetalSummonRecord")
        if not recordOK or type(record) ~= "table" then return nil end
        local info = record.petID and self:GetPetInfo(record.petID) or nil
        info = info or {petID = record.petID, name = "Last Petal pet", icon = QUESTION_ICON}
        info.speciesID = info.speciesID or record.speciesID
        info._petalLastSummon = true
        return info
    end
    if petID == nil then return nil end
    local info = self:GetPetInfo(petID) or {petID = petID, name = "Current pet", icon = QUESTION_ICON}
    info.petID = petID
    return info
end

function UI:IsCombatLocked()
    local locked = false
    if type(_G.InCombatLockdown) == "function" then
        local ok, value = pcall(InCombatLockdown)
        locked = ok and value or false
    end
    if not locked and type(_G.UnitAffectingCombat) == "function" then
        local ok, value = pcall(UnitAffectingCombat, "player")
        locked = ok and value or false
    end
    return locked
end

function UI:IsSummonSafe()
    if self:IsCombatLocked() then return false, "Combat is still active." end
    if type(APS.IsInvalidSummonState) == "function" then
        local ok, invalid, why = pcall(APS.IsInvalidSummonState, APS)
        if ok and invalid then return false, why or "Summoning is currently unavailable." end
    end
    return true, nil
end

function UI:Build()
    if self.frame then return self.frame end
    self:ApplyTheme()

    local frame = CreateFrame("Frame", "PETALJournal", UIParent, "BackdropTemplate")
    self.frame = frame
    frame:SetSize(1040, 700)
    -- This is a normal journal, not a modal dialog. Other addon and Blizzard
    -- windows may be raised above it when the player clicks them.
    frame:SetFrameStrata("MEDIUM")
    frame:SetToplevel(false)
    frame:SetClampedToScreen(true)
    frame:EnableMouse(true)
    frame:SetMovable(true)
    frame:RegisterForDrag("LeftButton")
    if frame.SetBackdrop then frame:SetBackdrop(nil) end

    local shell = frame:CreateTexture(nil, "BACKGROUND", nil, -8)
    shell:SetSize(1088, 748)
    shell:SetPoint("TOPLEFT", frame, "TOPLEFT", -24, 16)
    local dark = type(APS.GetSetting) == "function" and APS:GetSetting("darkMode", false) == true
    applyShellPalette(shell, dark)
    frame.shell = shell

    local paper = frame:CreateTexture(nil, "ARTWORK", nil, -8)
    paper:SetPoint("TOPLEFT", frame, "TOPLEFT", 12, -12)
    paper:SetPoint("BOTTOMRIGHT", frame, "BOTTOMRIGHT", -12, 12)
    paper:SetTexture(PAPER_WASH)
    paper:SetAlpha(dark and 0.055 or 0.11)
    frame.paper = paper

    local top = CreateFrame("Frame", nil, frame)
    top:SetPoint("TOPLEFT", 1, -1)
    top:SetPoint("TOPRIGHT", -1, -1)
    top:SetHeight(72)
    frame.top = top

    local wordmark = top:CreateTexture(nil, "ARTWORK")
    wordmark:SetSize(150, 65)
    wordmark:SetPoint("LEFT", 20, 0)
    wordmark:SetTexture(WORDMARK)
    frame.wordmark = wordmark

    local closeButton = makeButton(top, "Close", 72, 28, {COLOR.cardAlt, COLOR.borderSoft, COLOR.text})
    closeButton:SetPoint("RIGHT", -18, 0)
    addButtonIcon(closeButton, NAV_ICON_ROOT .. "close-coral.png", 15)
    addBottomAccent(closeButton, COLOR.red)
    closeButton:SetScript("OnClick", function() self:Hide() end)
    local helpButton = makeButton(top, "Help", 76, 28, {COLOR.cardAlt, COLOR.borderSoft, COLOR.text})
    helpButton:SetPoint("RIGHT", closeButton, "LEFT", -9, 0)
    addButtonIcon(helpButton, NAV_ICON_ROOT .. "icon-compass.png", 15)
    addBottomAccent(helpButton, COLOR.sky)
    helpButton:SetScript("OnClick", function() self:ToggleHelp() end)
    frame.helpButton = helpButton
    frame.closeButton = closeButton

    local rail = CreateFrame("Frame", nil, frame)
    rail:SetPoint("TOPLEFT", 1, -73)
    rail:SetPoint("BOTTOMLEFT", 1, 1)
    rail:SetWidth(184)
    frame.rail = rail

    local railHint = makeLabel(rail, "SETUP", 9, COLOR.faint)
    railHint:SetPoint("TOPLEFT", 22, -23)

    local nav = {
        {id = "overview", label = "Today", color = COLOR.amber, icon = NAV_ICON_ROOT .. "icon-today.png"},
        {id = "library", label = "Pets", color = COLOR.mint, icon = NAV_ICON_ROOT .. "icon-friends.png"},
        {id = "tags", label = "Situations", color = COLOR.sky, icon = NAV_ICON_ROOT .. "icon-moments.png"},
        {id = "sets", label = "Save / Load", color = COLOR.amber, icon = NAV_ICON_ROOT .. "icon-ready.png"},
        {id = "settings", label = "Settings", color = COLOR.lilac, icon = NAV_ICON_ROOT .. "icon-settings.png"},
    }
    self.nav = {}
    for index, item in ipairs(nav) do
        local button = makeButton(rail, "", 150, 38, {COLOR.rail, COLOR.rail, COLOR.muted})
        button:SetPoint("TOPLEFT", 16, -46 - (index - 1) * 44)
        button:SetBackdropColor(copyColor(COLOR.rail, 1))
        button:SetBackdropBorderColor(copyColor(COLOR.rail, 1))
        local marker = button:CreateTexture(nil, "ARTWORK")
        marker:SetSize(4, 18)
        marker:SetPoint("LEFT", 10, 0)
        setThemeTextureColor(marker, item.color, 1)
        local icon = button:CreateTexture(nil, "ARTWORK", nil, 1)
        icon:SetSize(20, 20)
        icon:SetPoint("LEFT", 18, 0)
        icon:SetTexture(item.icon)
        local label = makeLabel(button, item.label, 11, COLOR.text)
        label:SetPoint("LEFT", icon, "RIGHT", 10, 0)
        button._apsLabel = label
        button._apsMarker = marker
        button._apsMarkerColor = item.color
        button._apsIcon = icon
        local pageID = item.id
        button:SetScript("OnClick", function()
            self:ShowPage(pageID)
        end)
        button:SetScript("OnEnter", function(selfButton)
            if not selfButton._apsSelected then
                selfButton:SetBackdropColor(copyColor(COLOR.hoverSurface, 1))
            end
        end)
        button:SetScript("OnLeave", function(selfButton) self:StyleRailButton(selfButton, selfButton._apsSelected) end)
        self.nav[item.id] = button
    end

    local railFooter = makeLabel(rail, "1. Choose pets\n2. Set situations", 10, COLOR.muted)
    railFooter:SetPoint("BOTTOMLEFT", 22, 24)
    railFooter:SetWidth(138)
    railFooter:SetJustifyH("LEFT")

    local content = CreateFrame("Frame", nil, frame)
    content:SetPoint("TOPLEFT", 185, -74)
    -- Keep a dedicated footer band so page notes and scroll regions never
    -- collide with the journal's global travel note.
    content:SetPoint("BOTTOMRIGHT", -1, 32)
    frame.content = content

    self:CreatePages(content)

    frame:SetScript("OnDragStart", function(selfFrame)
        selfFrame:StartMoving()
    end)
    frame:SetScript("OnDragStop", function(selfFrame)
        selfFrame:StopMovingOrSizing()
        selfFrame:SetClampedToScreen(true)
        self:SavePosition()
    end)
    frame:SetScript("OnShow", function() self:OnShown() end)
    frame:SetScript("OnHide", function() self:OnHidden() end)

    return frame
end

function UI:CreatePages(content)
    self.pages = {}
    for _, id in ipairs({"overview", "library", "tags", "sets", "settings"}) do
        local page = CreateFrame("Frame", nil, content)
        page:SetAllPoints(content)
        page:Hide()
        self.pages[id] = page
    end
    self:CreateOverview(self.pages.overview)
    self:CreateLibraryPage(self.pages.library)
    self:CreateTagsPage(self.pages.tags)
    self:CreateSetsPage(self.pages.sets)
    self:CreateSettingsPage(self.pages.settings)
end

function UI:CreatePageHeader(page, eyebrow, titleText, description)
    local eyebrowText = makeLabel(page, eyebrow:upper(), 9, COLOR.lilac)
    eyebrowText:SetPoint("TOPLEFT", 28, -22)
    local title = makeLabel(page, titleText, 21, COLOR.text)
    title:SetPoint("TOPLEFT", eyebrowText, "BOTTOMLEFT", 0, -5)
    title:SetWidth(570)
    title:SetJustifyH("LEFT")
    title:SetWordWrap(false)
    if title.SetMaxLines then title:SetMaxLines(1) end
    local desc = makeLabel(page, description, 11, COLOR.muted)
    desc:SetPoint("TOPLEFT", title, "BOTTOMLEFT", 0, -5)
    desc:SetWidth(570)
    desc:SetJustifyH("LEFT")
    return eyebrowText, title, desc
end

function UI:CreateOverview(page)
    self:CreatePageHeader(page, "Today", "Current pet", "")

    local hero = CreateFrame("Frame", nil, page)
    hero:SetPoint("TOPLEFT", 28, -91)
    hero:SetSize(748, 430)
    page.hero = hero

    local heroModel = CreateFrame("PlayerModel", nil, hero)
    heroModel:SetPoint("TOPLEFT", 0, 0)
    heroModel:SetPoint("TOPRIGHT", 0, 0)
    heroModel:SetHeight(330)
    heroModel:SetFrameLevel(hero:GetFrameLevel() + 1)
    enableModelRotation(heroModel)
    hero.heroModel = heroModel

    local heroIcon = hero:CreateTexture(nil, "ARTWORK", nil, 1)
    heroIcon:SetSize(138, 138)
    heroIcon:SetPoint("CENTER", heroModel, "CENTER", 0, 0)
    heroIcon:SetTexture(NO_PET_ART)
    if heroIcon.SetDesaturated then pcall(heroIcon.SetDesaturated, heroIcon, true) end
    heroIcon:SetVertexColor(copyColor(COLOR.faint, 0.62))
    hero.heroIcon = heroIcon

    local heroKicker = makeLabel(hero, "CURRENT PET", 9, COLOR.faint)
    heroKicker:SetPoint("TOP", heroModel, "BOTTOM", 0, -5)
    heroKicker:SetWidth(620)
    heroKicker:SetJustifyH("CENTER")
    hero.heroKicker = heroKicker
    local heroName = makeLabel(hero, "No pet out", 24, COLOR.text)
    heroName:SetPoint("TOP", heroKicker, "BOTTOM", 0, -7)
    heroName:SetWidth(620)
    heroName:SetJustifyH("CENTER")
    heroName:SetWordWrap(false)
    if heroName.SetMaxLines then heroName:SetMaxLines(1) end
    hero.heroName = heroName

    local heroMeta = makeLabel(hero, "Ready  •  Open world", 11, COLOR.mint)
    heroMeta:SetPoint("TOP", heroName, "BOTTOM", 0, -8)
    heroMeta:SetWidth(620)
    heroMeta:SetJustifyH("CENTER")
    hero.heroMeta = heroMeta

    local heroStat = makeLabel(hero, "", 10, COLOR.muted)
    heroStat:SetPoint("TOP", heroMeta, "BOTTOM", 0, -8)
    heroStat:SetWidth(620)
    heroStat:SetJustifyH("CENTER")
    hero.heroStat = heroStat

end

function UI:CreateRulesPage(page)
    self:CreatePageHeader(page, "Situations", "Situations", "Use a different pet set for each situation.")
    local scroll, list = self:CreateScrollArea(page, 28, -105, 748, 430)
    self.rulesScroll = scroll
    self.rulesList = list
    self.rulesPage = page
    local note = makeLabel(page, "When situations overlap, the highest priority match is used.", 10, COLOR.faint)
    note:SetPoint("BOTTOMLEFT", 28, 17)
    note:SetWidth(650)
    note:SetJustifyH("LEFT")
end

function UI:CreateLibraryPage(page)
    self:CreatePageHeader(page, "Pets", "Select pets", "Click a pet to select it.")

    local search = CreateFrame("EditBox", nil, page, "BackdropTemplate")
    search:SetSize(250, 30)
    search:SetPoint("TOPRIGHT", -28, -23)
    search:SetAutoFocus(false)
    search:SetTextInsets(35, 10, 0, 0)
    setBackdrop(search, COLOR.card, COLOR.borderSoft, 1, 1)
    styleEditBox(search)
    local searchIcon = search:CreateTexture(nil, "ARTWORK")
    searchIcon:SetSize(16, 16)
    searchIcon:SetPoint("LEFT", 10, 0)
    searchIcon:SetTexture(NAV_ICON_ROOT .. "icon-search.png")
    local searchPlaceholder = makeLabel(search, "Search pets...", 11, COLOR.faint)
    searchPlaceholder:SetPoint("LEFT", 35, 0)
    search:SetScript("OnTextChanged", function(edit)
        searchPlaceholder:SetShown(trim(edit:GetText()) == "")
        self:RefreshPetPicker(false)
    end)
    search:SetScript("OnEscapePressed", function(edit) edit:ClearFocus() end)
    self.petSearch = search

    local filterBar = CreateFrame("Frame", nil, page)
    filterBar:SetPoint("TOPLEFT", 28, -103)
    filterBar:SetSize(560, 35)
    self.petFilters = {}
    for index, filter in ipairs({
        {id = "all", label = "All pets", icon = NAV_ICON_ROOT .. "icon-friends.png", accent = COLOR.sky},
        {id = "favorites", label = "Favorites", icon = NAV_ICON_ROOT .. "icon-favorite.png", accent = COLOR.amber},
        {id = "selected", label = "Selected", icon = NAV_ICON_ROOT .. "check-selected.png", accent = COLOR.mint},
    }) do
        local button = makeButton(filterBar, filter.label, 108, 30, {COLOR.cardAlt, COLOR.borderSoft, COLOR.muted})
        button:SetPoint("LEFT", (index - 1) * 116, 0)
        addButtonIcon(button, filter.icon, 15)
        addBottomAccent(button, filter.accent)
        button:SetScript("OnClick", function()
            self.petFilter = filter.id
            self:RefreshPetPicker(false)
        end)
        self.petFilters[filter.id] = button
    end

    local scope = makeLabel(filterBar, "", 10, COLOR.faint)
    scope:SetPoint("RIGHT", 0, 0)
    self.petScope = scope

    local preview = CreateFrame("Frame", nil, page)
    preview:SetPoint("TOPRIGHT", -28, -91)
    preview:SetSize(200, 300)
    local previewFallback = preview:CreateTexture(nil, "ARTWORK")
    previewFallback:SetSize(88, 88)
    previewFallback:SetPoint("CENTER", 0, 20)
    previewFallback:SetTexture(QUESTION_ICON)
    previewFallback:Hide()
    local model = CreateFrame("PlayerModel", nil, preview)
    model:SetPoint("TOPLEFT", -10, 0)
    model:SetPoint("BOTTOMRIGHT", 10, 61)
    model:SetFrameLevel(preview:GetFrameLevel() + 1)
    enableModelRotation(model)
    local previewName = makeLabel(preview, "Preview", 12, COLOR.text)
    previewName:SetPoint("BOTTOM", 0, 37)
    previewName:SetWidth(200)
    previewName:SetJustifyH("CENTER")
    previewName:SetWordWrap(false)
    if previewName.SetMaxLines then previewName:SetMaxLines(1) end
    self.petPreview = model
    self.petPreviewFallback = previewFallback
    self.petPreviewName = previewName

    local selectedCount = makeLabel(preview, "0 selected", 9, COLOR.muted)
    selectedCount:SetPoint("BOTTOM", 0, 18)
    self.petPreviewSelectedCount = selectedCount

    local assignTags = makeButton(page, "Set situations", 200, 36, {COLOR.lilacSoft, COLOR.lilac, COLOR.text})
    assignTags:SetPoint("TOPRIGHT", -28, -403)
    addButtonIcon(assignTags, NAV_ICON_ROOT .. "icon-moments.png", 17)
    addBottomAccent(assignTags, COLOR.lilac)
    assignTags:SetScript("OnClick", function() self:ShowPage("tags") end)
    self.assignTagsButton = assignTags

    local scroll, content = self:CreateScrollArea(page, 28, -141, 560, 416)
    self.petScroll = scroll
    -- Keep the library's scroll content distinct from runtime pet caches.
    self.libraryContent = content
    local count = makeLabel(page, "", 10, COLOR.muted)
    count:SetPoint("BOTTOMLEFT", 28, 17)
    self.petCount = count
end

function UI:CreateTagsPage(page)
    self:CreatePageHeader(page, "Situations", "Set situations", "Choose situations for each pet.")

    local scroll, content = self:CreateScrollArea(page, 28, -101, 748, 452)
    self.tagsScroll = scroll
    self.tagsContent = content

    local status = makeLabel(page, "Click a situation to toggle it.", 10, COLOR.faint)
    status:SetPoint("BOTTOMLEFT", 28, 17)
    status:SetWidth(620)
    status:SetJustifyH("LEFT")
    self.tagStatus = status

    local count = makeLabel(page, "", 10, COLOR.muted)
    count:SetPoint("BOTTOMRIGHT", -28, 17)
    self.tagCount = count

    local empty = CreateFrame("Frame", nil, page, "BackdropTemplate")
    empty:SetPoint("TOPLEFT", 28, -101)
    empty:SetSize(748, 250)
    setBackdrop(empty, COLOR.card, COLOR.borderSoft, 1, 1)
    local emptyTitle = makeLabel(empty, "No pets selected", 16, COLOR.text)
    emptyTitle:SetPoint("CENTER", 0, 25)
    local emptyText = makeLabel(empty, "Select pets first.", 10, COLOR.muted)
    emptyText:SetPoint("TOP", emptyTitle, "BOTTOM", 0, -8)
    local choose = makeButton(empty, "Select pets", 112, 30, {COLOR.lilacSoft, COLOR.lilac, COLOR.text})
    choose:SetPoint("TOP", emptyText, "BOTTOM", 0, -15)
    choose:SetScript("OnClick", function() self:ShowPage("library") end)
    empty:Hide()
    self.tagsEmpty = empty
end

function UI:CreateSetsPage(page)
    self:CreatePageHeader(page, "", "Save / Load", "Save different pet and situation setups.")

    local scroll, content = self:CreateScrollArea(page, 28, -104, 748, 338)
    self.setsScroll = scroll
    self.setsContent = content
    self.setRows = {}

    local empty = makeLabel(page, "No saved sets.", 11, COLOR.muted)
    empty:SetPoint("TOPLEFT", 44, -132)
    self.setsEmpty = empty

    local nameBox = CreateFrame("EditBox", nil, page, "BackdropTemplate")
    nameBox:SetSize(250, 30)
    nameBox:SetPoint("BOTTOMLEFT", 28, 55)
    nameBox:SetAutoFocus(false)
    nameBox:SetMaxLetters(32)
    nameBox:SetTextInsets(10, 10, 0, 0)
    setBackdrop(nameBox, COLOR.card, COLOR.borderSoft, 1, 1)
    styleEditBox(nameBox)
    nameBox:SetScript("OnEscapePressed", function(box) box:ClearFocus() end)
    self.setNameBox = nameBox

    local saveNew = makeButton(page, "Save new set", 114, 30, {COLOR.cardAlt, COLOR.borderSoft, COLOR.text})
    saveNew:SetPoint("LEFT", nameBox, "RIGHT", 8, 0)
    addButtonIcon(saveNew, NAV_ICON_ROOT .. "icon-ready.png", 15)
    addBottomAccent(saveNew, COLOR.mint)
    saveNew:SetScript("OnClick", function()
        local ok, saved, reason = safeCall(APS, "SavePetSet", trim(nameBox:GetText()))
        if not ok or saved == false then
            local message = reason == "name required" and "Enter a set name."
                or reason == "exists" and "A set with this name already exists."
                or "Could not save this set."
            self:Toast(message, COLOR.red)
            return
        end
        nameBox:SetText("")
        nameBox:ClearFocus()
        self:RefreshSetsPage(false)
        self:Toast("Set saved.", COLOR.mint)
    end)

    local importButton = makeButton(page, "Import set", 100, 30, {COLOR.cardAlt, COLOR.borderSoft, COLOR.text})
    importButton:SetPoint("LEFT", saveNew, "RIGHT", 8, 0)
    addButtonIcon(importButton, NAV_ICON_ROOT .. "travel-ticket.png", 15)
    addBottomAccent(importButton, COLOR.sky)
    importButton:SetScript("OnClick", function() self:ShowSetTransfer("import") end)

    local note = makeLabel(page, "Exports include selected pet species and their situations.", 9, COLOR.faint)
    note:SetPoint("BOTTOMLEFT", 28, 24)
    note:SetWidth(620)
    note:SetJustifyH("LEFT")
end

function UI:CreateSetRow(parent)
    local row = CreateFrame("Frame", nil, parent, "BackdropTemplate")
    row:SetSize(718, 62)
    setBackdrop(row, COLOR.card, COLOR.borderSoft, 1, 1)
    row.nameText = makeLabel(row, "Saved set", 12, COLOR.text)
    row.nameText:SetPoint("TOPLEFT", 16, -13)
    row.nameText:SetWidth(250)
    row.nameText:SetJustifyH("LEFT")
    row.statusText = makeLabel(row, "", 9, COLOR.muted)
    row.statusText:SetPoint("TOPLEFT", row.nameText, "BOTTOMLEFT", 0, -5)
    row.statusText:SetWidth(250)
    row.statusText:SetJustifyH("LEFT")

    row.delete = makeButton(row, "Delete", 58, 26, {COLOR.cardAlt, COLOR.borderSoft, COLOR.muted})
    row.delete:SetPoint("RIGHT", -12, 0)
    row.export = makeButton(row, "Export", 62, 26, {COLOR.cardAlt, COLOR.borderSoft, COLOR.text})
    row.export:SetPoint("RIGHT", row.delete, "LEFT", -6, 0)
    row.save = makeButton(row, "Save", 54, 26, {COLOR.cardAlt, COLOR.borderSoft, COLOR.text})
    row.save:SetPoint("RIGHT", row.export, "LEFT", -6, 0)
    row.use = makeButton(row, "Use", 50, 26, {COLOR.lilacSoft, COLOR.lilac, COLOR.text})
    row.use:SetPoint("RIGHT", row.save, "LEFT", -6, 0)

    row.use:SetScript("OnClick", function() self:RequestLoadPetSet(row.setName) end)
    row.save:SetScript("OnClick", function()
        local ok, saved = safeCall(APS, "SavePetSet", row.setName)
        if ok and saved then
            self:RefreshSetsPage(true)
            self:Toast("Changes saved.", COLOR.mint)
        else
            self:Toast("Could not save changes.", COLOR.red)
        end
    end)
    row.export:SetScript("OnClick", function()
        local ok, code, reason = safeCall(APS, "ExportPetSet", row.setName)
        if ok and code then self:ShowSetTransfer("export", row.setName, code)
        else self:Toast(reason or "Could not export this set.", COLOR.red) end
    end)
    row.delete:SetScript("OnClick", function()
        self:ShowSetConfirm("Delete set?", "Delete “" .. tostring(row.setName or "") .. "”?", "Delete", function()
            local ok, deleted, reason = safeCall(APS, "DeletePetSet", row.setName)
            if ok and deleted then
                self:RefreshSetsPage(true)
                self:Toast("Set deleted.", COLOR.muted)
            else
                self:Toast(reason == "active set" and "Load another set before deleting this one." or "Could not delete this set.", COLOR.red)
            end
        end)
    end)
    return row
end

function UI:RefreshSetsPage(preserveScroll)
    if not self.setsContent then return end
    local ok, names = safeCall(APS, "GetPetSetNames")
    names = ok and type(names) == "table" and names or {}
    local storeOK, _, activeName = safeCall(APS, "GetPetSetStore")
    activeName = storeOK and activeName or nil
    local dirtyOK, dirty = safeCall(APS, "HasUnsavedPetSetChanges")
    dirty = dirtyOK and dirty == true

    for _, row in ipairs(self.setRows or {}) do row:Hide() end
    for index, name in ipairs(names) do
        local row = self.setRows[index]
        if not row then
            row = self:CreateSetRow(self.setsContent)
            self.setRows[index] = row
        end
        row.setName = name
        row:ClearAllPoints()
        row:SetPoint("TOPLEFT", 0, -((index - 1) * 70))
        row.nameText:SetText(name)
        local active = name == activeName
        row.statusText:SetText(active and (dirty and "In use  •  Unsaved changes" or "In use") or "Saved")
        setTextColor(row.statusText, active and (dirty and COLOR.amber or COLOR.mint) or COLOR.muted)
        row.use:SetEnabled(not active)
        row.save:SetEnabled(active and dirty)
        row.delete:SetEnabled(not active)
        row:SetBackdropColor(copyColor(active and COLOR.mintSoft or COLOR.card, 1))
        row:SetBackdropBorderColor(copyColor(active and COLOR.mint or COLOR.borderSoft, 1))
        row:Show()
    end
    local height = math.max(338, #names * 70 + 2)
    self.setsContent:SetHeight(height)
    self.setsScroll:UpdateLayout(height, not preserveScroll)
    self.setsEmpty:SetShown(#names == 0)
end

function UI:ApplyPetSet(name)
    local ok, loaded, _, missing = safeCall(APS, "LoadPetSet", name)
    if not ok or loaded == false then
        self:Toast("Could not load this set.", COLOR.red)
        return
    end
    self.petCache = self:GetPets()
    self:RefreshSetsPage(true)
    if tonumber(missing) and missing > 0 then
        self:Toast(tostring(missing) .. " unowned pet" .. (missing == 1 and " was" or "s were") .. " skipped.", COLOR.amber)
    else
        self:Toast("Set loaded.", COLOR.mint)
    end
end

function UI:RequestLoadPetSet(name)
    local ok, dirty = safeCall(APS, "HasUnsavedPetSetChanges")
    if ok and dirty then
        self:ShowSetConfirm("Unsaved changes", "Loading another set will replace the current unsaved changes.", "Load set", function()
            self:ApplyPetSet(name)
        end)
        return
    end
    self:ApplyPetSet(name)
end

function UI:ShowSetConfirm(title, message, actionLabel, callback)
    local modal = self.setConfirm
    if not modal then
        modal = self:CreateModal("setConfirm", title, 430, 190)
        self.setConfirm = modal
        modal.body = makeLabel(modal, "", 11, COLOR.muted)
        modal.body:SetPoint("TOPLEFT", 24, -68)
        modal.body:SetWidth(382)
        modal.body:SetJustifyH("LEFT")
        modal.cancel = makeButton(modal, "Cancel", 76, 28, {COLOR.cardAlt, COLOR.borderSoft, COLOR.text})
        modal.cancel:SetPoint("BOTTOMRIGHT", -20, 18)
        modal.cancel:SetScript("OnClick", function() modal:Hide() end)
        modal.action = makeButton(modal, "Continue", 90, 28, {COLOR.lilacSoft, COLOR.lilac, COLOR.text})
        modal.action:SetPoint("RIGHT", modal.cancel, "LEFT", -8, 0)
        modal.action:SetScript("OnClick", function()
            local action = modal.callback
            modal:Hide()
            if action then action() end
        end)
    end
    modal.title:SetText(title or "Confirm")
    modal.body:SetText(message or "")
    modal.action:SetText(actionLabel or "Continue")
    modal.callback = callback
    modal:Show()
    modal:Raise()
end

function UI:ShowSetTransfer(mode, setName, exportText)
    local modal = self.setTransfer
    if not modal then
        modal = self:CreateModal("setTransfer", "Import set", 590, 370)
        self.setTransfer = modal
        modal.help = makeLabel(modal, "", 10, COLOR.muted)
        modal.help:SetPoint("TOPLEFT", 24, -58)
        modal.help:SetWidth(535)
        modal.help:SetJustifyH("LEFT")
        local boxFrame = CreateFrame("Frame", nil, modal, "BackdropTemplate")
        boxFrame:SetPoint("TOPLEFT", 24, -88)
        boxFrame:SetSize(542, 210)
        setBackdrop(boxFrame, COLOR.panel, COLOR.borderSoft, 1, 1)
        local scroll = CreateFrame("ScrollFrame", nil, boxFrame)
        scroll:SetPoint("TOPLEFT", 10, -10)
        scroll:SetPoint("BOTTOMRIGHT", -10, 10)
        local edit = CreateFrame("EditBox", nil, scroll)
        edit:SetMultiLine(true)
        edit:SetAutoFocus(false)
        edit:SetWidth(510)
        edit:SetFontObject(GameFontHighlight)
        styleEditBox(edit)
        edit:SetTextInsets(2, 2, 2, 2)
        edit:SetScript("OnEscapePressed", function(box) box:ClearFocus(); modal:Hide() end)
        edit:SetScript("OnTextChanged", function(box)
            local textHeight = 178
            if type(box.GetStringHeight) == "function" then
                local ok, measured = pcall(box.GetStringHeight, box)
                if ok and type(measured) == "number" then textHeight = measured end
            end
            box:SetHeight(math.max(190, textHeight + 12))
        end)
        scroll:SetScrollChild(edit)
        modal.edit = edit
        modal:SetScript("OnHide", function() edit:ClearFocus() end)
        modal.status = makeLabel(modal, "", 9, COLOR.red)
        modal.status:SetPoint("BOTTOMLEFT", 24, 24)
        modal.status:SetWidth(300)
        modal.status:SetJustifyH("LEFT")
        modal.action = makeButton(modal, "Import", 88, 28, {COLOR.lilacSoft, COLOR.lilac, COLOR.text})
        modal.action:SetPoint("BOTTOMRIGHT", -20, 18)
        modal.action:SetScript("OnClick", function()
            if modal.mode == "export" then modal:Hide(); return end
            local ok, imported, reason = safeCall(APS, "ImportPetSet", modal.edit:GetText())
            if ok and imported then
                modal:Hide()
                self:RefreshSetsPage(false)
                self:Toast("Imported “" .. imported .. "”.", COLOR.mint)
            else
                local messages = {
                    ["wrong format"] = "This is not a PETAL set code.",
                    ["checksum failed"] = "The code is incomplete or damaged.",
                    ["invalid pets"] = "The pet list is invalid.",
                    ["invalid situations"] = "The situation list is invalid.",
                }
                modal.status:SetText(messages[reason] or "Paste a complete PETAL set code.")
            end
        end)
    end
    modal.mode = mode
    modal.status:SetText("")
    if mode == "export" then
        modal.title:SetText("Export “" .. tostring(setName or "set") .. "”")
        modal.help:SetText("Copy this code.")
        modal.edit:SetText(exportText or "")
        modal.action:SetText("Done")
    else
        modal.title:SetText("Import set")
        modal.help:SetText("Paste a PETAL set code. Importing creates a saved set; it does not replace the current setup.")
        modal.edit:SetText("")
        modal.action:SetText("Import")
    end
    modal:Show()
    modal:Raise()
    modal.edit:SetFocus()
    if mode == "export" then modal.edit:HighlightText() end
end

function UI:CreateSettingsPage(page)
    self:CreatePageHeader(page, "", "Settings", "")

    local card = CreateFrame("Frame", nil, page, "BackdropTemplate")
    card:SetPoint("TOPLEFT", 28, -105)
    card:SetSize(748, 292)
    self.settingsCard = card

    self.settingsEnabled = self:CreateToggle(card, "Enable Petal", "Keep a matching pet out.", "enabled")
    self.settingsEnabled:SetPoint("TOPLEFT", 24, -22)

    local keybindTitle = makeLabel(card, "Change pet", 12, COLOR.text)
    keybindTitle:SetPoint("TOPLEFT", 24, -82)
    local keybindHint = makeLabel(card, "Choose another pet for this situation.", 10, COLOR.muted)
    keybindHint:SetPoint("TOPLEFT", keybindTitle, "BOTTOMLEFT", 0, -4)
    keybindHint:SetWidth(450)

    local keybind = makeButton(card, "Not bound", 180, 30, {COLOR.cardAlt, COLOR.borderSoft, COLOR.text})
    keybind:SetPoint("TOPRIGHT", -24, -78)
    addButtonIcon(keybind, NAV_ICON_ROOT .. "icon-shuffle.png", 16)
    addBottomAccent(keybind, COLOR.lilac)
    keybind:EnableKeyboard(true)
    if keybind.SetPropagateKeyboardInput then keybind:SetPropagateKeyboardInput(true) end
    keybind:SetScript("OnClick", function() self:BeginKeybindCapture() end)
    keybind:SetScript("OnKeyDown", function(_, key) self:HandleKeybindInput(key) end)
    self.settingsKeybindButton = keybind

    self.settingsRandomShuffle = self:CreateToggle(card, "Random shuffle", "Choose another matching pet at a random interval.", "randomShuffleEnabled")
    self.settingsRandomShuffle:SetPoint("TOPLEFT", 24, -140)

    local rangeLabel = makeLabel(card, "Shuffle after", 11, COLOR.text)
    rangeLabel:SetPoint("TOPLEFT", 24, -194)
    local minBox = CreateFrame("EditBox", nil, card, "BackdropTemplate")
    minBox:SetSize(64, 28)
    minBox:SetPoint("LEFT", rangeLabel, "RIGHT", 10, 0)
    styleEditBox(minBox)
    minBox:SetAutoFocus(false)
    minBox:SetJustifyH("CENTER")
    local minLabel = makeLabel(card, "minimum", 10, COLOR.muted)
    minLabel:SetPoint("LEFT", minBox, "RIGHT", 6, 0)
    local dash = makeLabel(card, "to", 10, COLOR.muted)
    dash:SetPoint("LEFT", minLabel, "RIGHT", 12, 0)
    local maxBox = CreateFrame("EditBox", nil, card, "BackdropTemplate")
    maxBox:SetSize(64, 28)
    maxBox:SetPoint("LEFT", dash, "RIGHT", 12, 0)
    styleEditBox(maxBox)
    maxBox:SetAutoFocus(false)
    maxBox:SetJustifyH("CENTER")
    local maxLabel = makeLabel(card, "maximum minutes", 10, COLOR.muted)
    maxLabel:SetPoint("LEFT", maxBox, "RIGHT", 6, 0)
    local function saveShuffleRange()
        self:SaveNumber("randomShuffleMinMinutes", minBox:GetText(), 1, 1440, 15)
        self:SaveNumber("randomShuffleMaxMinutes", maxBox:GetText(), 1, 1440, 30)
        self:RefreshSettings()
    end
    minBox:SetScript("OnEnterPressed", function(box) saveShuffleRange(); box:ClearFocus() end)
    maxBox:SetScript("OnEnterPressed", function(box) saveShuffleRange(); box:ClearFocus() end)
    minBox:SetScript("OnEditFocusLost", saveShuffleRange)
    maxBox:SetScript("OnEditFocusLost", saveShuffleRange)
    self.settingsShuffleMin = minBox
    self.settingsShuffleMax = maxBox

    self.settingsDarkMode = self:CreateToggle(card, "Dark mode", "Use the night palette.", "darkMode")
    self.settingsDarkMode:SetPoint("TOPLEFT", 24, -242)

    page:SetScript("OnHide", function() self:StopKeybindCapture() end)
end

function UI:CreateToggle(parent, title, description, key)
    local row = CreateFrame("Frame", nil, parent)
    row:SetSize(700, 44)
    row.key = key
    local titleText = makeLabel(row, title, 12, COLOR.text)
    titleText:SetPoint("TOPLEFT", 0, 0)
    local descText = makeLabel(row, description, 10, COLOR.muted)
    descText:SetPoint("TOPLEFT", titleText, "BOTTOMLEFT", 0, -4)
    descText:SetWidth(450)
    row.yes = makeButton(row, "Yes", 45, 25, {COLOR.mintSoft, COLOR.mint, COLOR.mint})
    row.no = makeButton(row, "No", 45, 25, {COLOR.cardAlt, COLOR.borderSoft, COLOR.muted})
    row.no:SetPoint("RIGHT", 0, 2)
    row.yes:SetPoint("RIGHT", row.no, "LEFT", -5, 0)
    row.yes:SetScript("OnClick", function() self:SetSetting(key, true) end)
    row.no:SetScript("OnClick", function() self:SetSetting(key, false) end)
    row.SetValue = function(toggleRow, value)
        toggleRow.value = value and true or false
        setButtonSelected(toggleRow.yes, toggleRow.value, COLOR.mint)
        setButtonSelected(toggleRow.no, not toggleRow.value, COLOR.sky)
    end
    return row
end

function UI:CreateScrollArea(parent, x, y, width, height)
    local scroll = CreateFrame("ScrollFrame", nil, parent)
    scroll:SetPoint("TOPLEFT", x, y)
    scroll:SetSize(width, height)
    scroll:EnableMouseWheel(true)
    local content = CreateFrame("Frame", nil, scroll)
    content:SetSize(width - 18, height)
    scroll:SetScrollChild(content)

    local slider = CreateFrame("Slider", nil, parent, "BackdropTemplate")
    slider:SetPoint("TOPLEFT", scroll, "TOPRIGHT", 6, 0)
    slider:SetSize(10, height)
    slider:SetOrientation("VERTICAL")
    slider:SetMinMaxValues(0, 1)
    slider:SetValueStep(1)
    slider:SetValue(0)
    slider:SetObeyStepOnDrag(false)
    slider:SetThumbTexture(WHITE)
    local thumb = slider:GetThumbTexture()
    if thumb then
        thumb:SetSize(10, 40)
        setThemeTextureColor(thumb, COLOR.lilac, 1)
    end
    setBackdrop(slider, COLOR.cardAlt, COLOR.borderSoft, 1, 1)
    slider:SetScript("OnValueChanged", function(_, value)
        scroll:SetVerticalScroll(value or 0)
    end)
    scroll:SetScript("OnMouseWheel", function(_, delta)
        local minValue, maxValue = slider:GetMinMaxValues()
        local current = slider:GetValue() or 0
        slider:SetValue(math.max(minValue, math.min(maxValue, current - delta * 56)))
    end)
    slider:SetScript("OnEnter", function()
        if thumb then setThemeTextureColor(thumb, COLOR.mint, 1) end
    end)
    slider:SetScript("OnLeave", function()
        if thumb then setThemeTextureColor(thumb, COLOR.lilac, 1) end
    end)
    scroll.slider = slider
    scroll.content = content
    scroll.UpdateLayout = function(scrollFrame, contentHeight, reset)
        local previous = scrollFrame:GetVerticalScroll() or slider:GetValue() or 0
        contentHeight = math.max(height, tonumber(contentHeight) or height)
        content:SetHeight(contentHeight)
        local maxScroll = math.max(0, contentHeight - height)
        if maxScroll <= 0 then
            slider:SetMinMaxValues(0, 0)
            slider:SetValue(0)
            slider:Hide()
            return
        end
        local visibleRatio = math.min(1, height / contentHeight)
        if thumb then thumb:SetSize(10, math.max(36, math.floor(height * visibleRatio))) end
        slider:Show()
        slider:SetMinMaxValues(0, maxScroll)
        local target = reset and 0 or math.min(previous, maxScroll)
        slider:SetValue(target)
        scrollFrame:SetVerticalScroll(target)
    end
    slider:Hide()
    return scroll, content
end

function UI:StylePetConditionToggle(button, active, hovered)
    if not button or not button.tagDefinition then return end
    local definition = button.tagDefinition
    button._apsActive = active and true or false
    if button._apsActive then
        button:SetBackdropColor(copyColor(definition.color, 1))
        button:SetBackdropBorderColor(copyColor(definition.color, 1))
        local activeText = definition.key == "all" and COLOR.white or COLOR.tagText
        setButtonFont(button, nil, activeText)
    elseif hovered then
        button:SetBackdropColor(copyColor(definition.soft, 0.7))
        button:SetBackdropBorderColor(copyColor(definition.color, definition.key == "all" and 0.9 or 0.75))
        setButtonFont(button, nil, definition.key == "all" and COLOR.white or COLOR.text)
    else
        -- Only the control surface is faded; labels remain fully opaque.
        button:SetBackdropColor(copyColor(definition.soft, 0.5))
        button:SetBackdropBorderColor(copyColor(definition.color, definition.key == "all" and 0.78 or 0.5))
        setButtonFont(button, nil, definition.key == "all" and COLOR.white or COLOR.text)
    end
end

function UI:CreateTaggedPetRow(parent)
    local row = CreateFrame("Frame", nil, parent, "BackdropTemplate")
    row:SetSize(718, 82)
    setBackdrop(row, COLOR.card, COLOR.borderSoft, 1, 1)
    row:EnableMouse(true)
    row:SetScript("OnEnter", function(selfRow)
        selfRow:SetBackdropColor(copyColor(COLOR.hoverSurface, 1))
        selfRow:SetBackdropBorderColor(copyColor(COLOR.hoverBorder, 1))
        if selfRow.info and selfRow.info.dead and GameTooltip then
            GameTooltip:SetOwner(selfRow, "ANCHOR_RIGHT")
            GameTooltip:ClearLines()
            GameTooltip:AddLine(selfRow.info.name or "Pet", 1, 1, 1)
            GameTooltip:AddLine("Needs revival", 0.9, 0.28, 0.38)
            GameTooltip:Show()
        end
    end)
    row:SetScript("OnLeave", function(selfRow)
        selfRow:SetBackdropColor(copyColor(COLOR.card, 1))
        selfRow:SetBackdropBorderColor(copyColor(COLOR.borderSoft, 1))
        if GameTooltip then GameTooltip:Hide() end
    end)

    local portrait = row:CreateTexture(nil, "ARTWORK")
    portrait:SetSize(54, 54)
    portrait:SetPoint("LEFT", 14, 0)
    portrait:SetTexture(QUESTION_ICON)
    row.portrait = portrait
    local deadIcon = row:CreateTexture(nil, "OVERLAY")
    deadIcon:SetSize(18, 18)
    deadIcon:SetPoint("TOPRIGHT", portrait, "TOPRIGHT", 5, 5)
    deadIcon:SetTexture("Interface\\PetBattles\\DeadPetIcon")
    deadIcon:Hide()
    row.deadIcon = deadIcon

    local name = makeLabel(row, "Pet", 12, COLOR.text)
    name:SetPoint("TOPLEFT", portrait, "TOPRIGHT", 12, -8)
    name:SetWidth(150)
    name:SetJustifyH("LEFT")
    name:SetWordWrap(false)
    if name.SetMaxLines then name:SetMaxLines(1) end
    row.nameText = name
    local species = makeLabel(row, "Selected pet", 9, COLOR.muted)
    species:SetPoint("TOPLEFT", name, "BOTTOMLEFT", 0, -5)
    species:SetWidth(150)
    species:SetJustifyH("LEFT")
    species:SetWordWrap(false)
    if species.SetMaxLines then species:SetMaxLines(1) end
    row.speciesText = species

    local tags = CreateFrame("Frame", nil, row)
    tags:SetPoint("LEFT", 234, 0)
    tags:SetSize(482, 52)
    row.tags = tags
    row.tagButtons = {}

    local all = makeButton(tags, ALL_TAG_DEFINITION.label, ALL_TAG_DEFINITION.width, 25, {COLOR.cardAlt, COLOR.borderSoft, COLOR.faint})
    all:SetPoint("LEFT", 0, 0)
    all.tagDefinition = ALL_TAG_DEFINITION
    all:SetScript("OnClick", function(toggle)
        if row.info then
            self:SetPetInfoAllTags(row.info, not toggle._apsActive)
        end
    end)
    all:SetScript("OnEnter", function(toggle)
        self:StylePetConditionToggle(toggle, toggle._apsActive, true)
    end)
    all:SetScript("OnLeave", function(toggle)
        self:StylePetConditionToggle(toggle, toggle._apsActive, false)
    end)
    row.allTagButton = all

    local x = ALL_TAG_DEFINITION.width + 6
    for _, definition in ipairs(TAG_DEFINITIONS) do
        local button = makeButton(tags, definition.label, definition.width, 25, {COLOR.cardAlt, COLOR.borderSoft, COLOR.faint})
        button:SetPoint("LEFT", x, 0)
        button.tagDefinition = definition
        button.tagKey = definition.key
        button:SetScript("OnClick", function(toggle)
            if row.info then
                self:SetPetInfoTag(row.info, toggle.tagKey, not toggle._apsActive)
            end
        end)
        button:SetScript("OnEnter", function(toggle)
            self:StylePetConditionToggle(toggle, toggle._apsActive, true)
        end)
        button:SetScript("OnLeave", function(toggle)
            self:StylePetConditionToggle(toggle, toggle._apsActive, false)
        end)
        row.tagButtons[definition.key] = button
        x = x + definition.width + 6
    end
    return row
end

function UI:RefreshTaggedPetRow(row, info)
    if not row or not info then return end
    row.info = info
    row.petID = info.petID
    row.portrait:SetTexture(info.icon or QUESTION_ICON)
    row.deadIcon:SetShown(info.dead == true)
    row.nameText:SetText(info.name or "Pet")
    local speciesName = trim(info.speciesName or "")
    local showSpecies = speciesName ~= "" and lower(speciesName) ~= lower(info.name or "")
    row.speciesText:SetText(showSpecies and speciesName or "")
    row.speciesText:SetShown(showSpecies)
    local tags = self:GetPetInfoTags(info)
    local allActive = true
    for _, definition in ipairs(TAG_DEFINITIONS) do
        local active = tags[definition.key] == true
        self:StylePetConditionToggle(row.tagButtons[definition.key], active, false)
        if not active then allActive = false end
    end
    self:StylePetConditionToggle(row.allTagButton, allActive, false)
    row:SetBackdropColor(copyColor(COLOR.card, 1))
    row:SetBackdropBorderColor(copyColor(COLOR.borderSoft, 1))
end

function UI:RefreshTaggedPetRowByID(petID)
    for _, row in ipairs(self.tagRows or {}) do
        if row:IsShown() then
            for _, candidate in ipairs(self:PetIDsForInfo(row.info)) do
                if tostring(candidate) == tostring(petID) then
                    self:RefreshTaggedPetRow(row, row.info)
                    return
                end
            end
        end
    end
end

function UI:RefreshTagsPage(preserveScroll)
    if not self.tagsContent then return end
    self.petCache = self.petCache or self:GetPets()
    local pets = {}
    for _, info in ipairs(self.petCache) do
        if self:IsPetInfoSelected(info) then pets[#pets + 1] = info end
    end
    table.sort(pets, function(a, b) return lower(a.name) < lower(b.name) end)

    self.tagRows = self.tagRows or {}
    for _, row in ipairs(self.tagRows) do row:Hide() end
    for index, info in ipairs(pets) do
        local row = self.tagRows[index]
        if not row then
            row = self:CreateTaggedPetRow(self.tagsContent)
            self.tagRows[index] = row
        end
        row:ClearAllPoints()
        row:SetPoint("TOPLEFT", 0, -((index - 1) * 92))
        row:Show()
        self:RefreshTaggedPetRow(row, info)
    end
    self.tagsContent:SetHeight(math.max(452, #pets * 92 + 6))
    self.tagsScroll:UpdateLayout(self.tagsContent:GetHeight(), not preserveScroll)
    self.tagsScroll:SetShown(#pets > 0)
    self.tagsScroll.slider:SetShown(#pets > 0 and self.tagsContent:GetHeight() > 452)
    self.tagsEmpty:SetShown(#pets == 0)
    self.tagCount:SetText(tostring(#pets) .. " selected")
    if self.tagStatus then self.tagStatus:SetText("Click a situation to toggle it.") end
end

function UI:ShowPage(id)
    if not self.frame then self:Build() end
    id = self.pages[id] and id or "overview"
    for pageID, page in pairs(self.pages) do
        if pageID == id then page:Show() else page:Hide() end
    end
    self.currentPage = id
    for navID, button in pairs(self.nav or {}) do
        self:StyleRailButton(button, navID == id)
    end
    if id == "overview" then
        self._resetOverviewModelFacing = true
        self._resetNoPetModelChoice = true
        self:RefreshOverview()
    end
    if id == "library" then self:RefreshPetPicker(true) end
    if id == "tags" then self:RefreshTagsPage(true) end
    if id == "sets" then self:RefreshSetsPage(true) end
    if id == "settings" then self:RefreshSettings() end
end

function UI:ScaleToScreen()
    if not self.frame or not UIParent then return end
    local width, height = UIParent:GetWidth(), UIParent:GetHeight()
    if not width or not height or width <= 0 or height <= 0 then return end
    local scale = math.min(1, (width - 24) / 1040, (height - 24) / 700)
    if scale <= 0 then scale = 0.01 end
    self.frame:SetScale(scale)
end

function UI:RestorePosition()
    local db = self:EnsureDB()
    local point = db.ui.point or "CENTER"
    local relative = db.ui.relative or "CENTER"
    local x = tonumber(db.ui.x) or 0
    local y = tonumber(db.ui.y) or 0
    self.frame:ClearAllPoints()
    self.frame:SetPoint(point, UIParent, relative, x, y)
    self.frame:SetClampedToScreen(true)
end

function UI:SavePosition()
    if not self.frame then return end
    local db = self:EnsureDB()
    local point, _, relative, x, y = self.frame:GetPoint(1)
    db.ui.point = point or "CENTER"
    db.ui.relative = relative or "CENTER"
    db.ui.x = math.floor((x or 0) + 0.5)
    db.ui.y = math.floor((y or 0) + 0.5)
end

function UI:Show()
    self:EnsureDB()
    self:Build()
    self:ScaleToScreen()
    self:RestorePosition()
    self.frame:Show()
    self:ShowPage(self.currentPage or "overview")
    self.frame:Raise()
end

function UI:Hide()
    if self.help then self.help:Hide() end
    if self.preview then self.preview:Hide() end
    if self.audit then self.audit:Hide() end
    if self.setTransfer then self.setTransfer:Hide() end
    if self.setConfirm then self.setConfirm:Hide() end
    if self.frame then
        self:SavePosition()
        self.frame:Hide()
    end
end

function UI:OnShown()
    self:ScaleToScreen()
    self:RestorePosition()
    self:RefreshAll(true)
end

function UI:OnHidden()
    self:StopKeybindCapture()
    if self.help then self.help:Hide() end
    if self.preview then self.preview:Hide() end
    if self.audit then self.audit:Hide() end
    if self.setTransfer then self.setTransfer:Hide() end
    if self.setConfirm then self.setConfirm:Hide() end
end

function UI:RefreshAll(preserveLibraryScroll)
    self.petCache = self:GetPets()
    if self.currentPage == "overview" then self:RefreshOverview() end
    if self.currentPage == "library" then self:RefreshPetPicker(preserveLibraryScroll) end
    if self.currentPage == "tags" then self:RefreshTagsPage(preserveLibraryScroll) end
    if self.currentPage == "sets" then self:RefreshSetsPage(preserveLibraryScroll) end
    if self.currentPage == "settings" then self:RefreshSettings() end
end

function UI:RefreshOverview()
    if not self.pages or not self.pages.overview or not self.pages.overview.hero then return end
    local current = self:GetCurrentPet()
    local hero = self.pages.overview.hero
    local petInfo = current and current.petID and self:GetPetInfo(current.petID) or current
    if petInfo and current then
        current.displayID = petInfo.displayID
        current.creatureID = petInfo.creatureID
        current.icon = current.icon or petInfo.icon
    end
    if current then
        hero.heroIcon:SetSize(104, 104)
        hero.heroIcon:SetTexture(current.icon or QUESTION_ICON)
        if hero.heroIcon.SetDesaturated then pcall(hero.heroIcon.SetDesaturated, hero.heroIcon, false) end
        hero.heroIcon:SetVertexColor(1, 1, 1, 1)
    else
        hero.heroIcon:SetSize(138, 138)
        hero.heroIcon:SetTexture(NO_PET_ART)
        if hero.heroIcon.SetDesaturated then pcall(hero.heroIcon.SetDesaturated, hero.heroIcon, true) end
        hero.heroIcon:SetVertexColor(copyColor(COLOR.faint, 0.62))
    end
    hero.heroKicker:SetText(current and (current._petalLastSummon and "LAST PETAL SUMMON" or "CURRENT PET") or "CURRENT PET")
    hero.heroName:SetText(current and current.name or "No pet out")
    local recordOK, record = safeCall(APS, "GetLastPetalSummonRecord")
    record = recordOK and type(record) == "table" and record or nil
    local sameSpecies = current and record and not isSecret(current.speciesID) and current.speciesID ~= nil
        and not isSecret(record.speciesID) and record.speciesID ~= nil
        and tonumber(current.speciesID) == tonumber(record.speciesID)
    local showPetalCount = record and current and (current._petalLastSummon or sameSpecies)
    local count = showPetalCount and not isSecret(record.count) and type(record.count) == "number"
        and math.max(0, math.floor(record.count)) or 0
    hero.heroStat:SetText(showPetalCount and ("Summoned " .. tostring(count) .. (count == 1 and " time" or " times")) or "")
    hero.heroStat:SetShown(showPetalCount == true)
    local wasShowingPet = self._overviewHadCurrentPet == true
    local silhouette = current == nil
    local modelInfo = current
    if silhouette then
        modelInfo = self:GetNoPetModelInfo(self._resetNoPetModelChoice or wasShowingPet)
    else
        self._noPetModelInfo = nil
    end
    self._resetNoPetModelChoice = nil
    self._overviewHadCurrentPet = current ~= nil

    local hasModel = modelInfo and hero.heroModel and
        ((type(modelInfo.displayID) == "number" and hero.heroModel.SetDisplayInfo)
            or (type(modelInfo.creatureID) == "number" and hero.heroModel.SetCreature))
    if hasModel then
        local modelKey = table.concat({
            silhouette and "silhouette" or "pet",
            tostring(readableValue(modelInfo.speciesID) or ""),
            tostring(readableValue(modelInfo.displayID) or ""),
            tostring(readableValue(modelInfo.creatureID) or ""),
            readableString(modelInfo.name) or "",
        }, ":")
        local shouldReload = self._overviewModelKey ~= modelKey or self._resetOverviewModelFacing
            or not hero.heroModel._apsModelLoaded
        if shouldReload then
            self._overviewModelKey = modelKey
            hero.heroIcon:Show()
            setModelSilhouette(hero.heroModel, false)
            setPetModel(hero.heroModel, modelInfo, HERO_MODEL_FIT_DISTANCE, TODAY_ROTATION_SPEED,
                function(model)
                    setModelSilhouette(model, silhouette)
                    model:Show()
                    hero.heroIcon:Hide()
                end,
                function(model)
                    setModelSilhouette(model, false)
                    model:Hide()
                    hero.heroIcon:Show()
                end)
        else
            setModelSilhouette(hero.heroModel, silhouette)
            hero.heroModel:Show()
            hero.heroIcon:Hide()
        end
    else
        self._overviewModelKey = nil
        if hero.heroModel then
            hero.heroModel._apsModelRequestToken = (hero.heroModel._apsModelRequestToken or 0) + 1
            hero.heroModel._apsAutoRotationSpeed = nil
            setModelSilhouette(hero.heroModel, false)
            hero.heroModel:Hide()
        end
        hero.heroIcon:Show()
    end
    self._resetOverviewModelFacing = nil
    local active = type(APS.IsEnabled) == "function" and APS:IsEnabled()
        or (_G.PETALDB and _G.PETALDB.enabled ~= false)
    local tagOK, tagKey = safeCall(APS, "GetActiveContextTag")
    local tag = tagOK and TAG_BY_KEY[tagKey] or nil
    local safe = self:IsSummonSafe()
    local ruleOK, activeRule = safeCall(APS, "GetActiveRule")
    local deadPoolMessage = not current and ruleOK and self:GetDeadPoolMessage(activeRule) or nil
    local statusLabel, statusColor
    if not active then
        statusLabel, statusColor = "Paused", COLOR.amber
    elseif current then
        statusLabel, statusColor = "Active", COLOR.mint
    elseif deadPoolMessage then
        statusLabel, statusColor = deadPoolMessage, COLOR.red
    elseif not safe then
        statusLabel, statusColor = "Waiting", COLOR.amber
    else
        statusLabel, statusColor = "Ready", COLOR.sky
    end
    hero.heroMeta:SetText(statusLabel .. "  •  " .. (tag and tag.label or "Other"))
    setTextColor(hero.heroMeta, statusColor)
end

function UI:CreateRuleCard(parent, rule, compact)
    local card = CreateFrame("Frame", nil, parent, "BackdropTemplate")
    card:SetSize(compact and 356 or 700, 78)
    setBackdrop(card, COLOR.card, COLOR.borderSoft, 1, 1)
    card:EnableMouse(true)
    card:SetScript("OnEnter", function(selfCard)
        selfCard:SetBackdropColor(copyColor(COLOR.hoverSurface, 1))
        selfCard:SetBackdropBorderColor(copyColor(COLOR.hoverBorder, 1))
    end)
    card:SetScript("OnLeave", function(selfCard)
        selfCard:SetBackdropColor(copyColor(COLOR.card, 1))
        selfCard:SetBackdropBorderColor(copyColor(COLOR.borderSoft, 1))
    end)
    card.rule = rule
    local accent = card:CreateTexture(nil, "ARTWORK")
    accent:SetPoint("TOPLEFT", 1, -1)
    accent:SetPoint("BOTTOMLEFT", 1, 1)
    accent:SetWidth(4)
    setThemeTextureColor(accent, self:RuleAccent(rule), 1)

    local title = makeLabel(card, self:RuleTitle(rule), compact and 12 or 14, COLOR.text)
    title:SetPoint("TOPLEFT", 18, -15)
    title:SetWidth(compact and 160 or 330)
    title:SetJustifyH("LEFT")
    title:SetWordWrap(false)
    if title.SetMaxLines then title:SetMaxLines(1) end
    card.title = title
    local petCount = #self:RulePetIDs(rule)
    local summary = makeLabel(card, petCount == 0 and "No pets selected" or (tostring(petCount) .. " pet" .. (petCount == 1 and "" or "s") .. " selected"), 10, COLOR.muted)
    summary:SetPoint("TOPLEFT", title, "BOTTOMLEFT", 0, -5)
    summary:SetJustifyH("LEFT")
    card.summary = summary

    local petsButton = makeButton(card, "Pets", compact and 60 or 82, 28, {COLOR.cardAlt, COLOR.borderSoft, COLOR.text})
    petsButton:SetPoint("RIGHT", compact and -142 or -176, 0)
    petsButton:SetScript("OnClick", function()
        self.selectedRule = rule
        self:ShowPage("library")
    end)
    card.petsButton = petsButton

    local activeLabel = makeLabel(card, "ACTIVE", 9, COLOR.faint)
    activeLabel:SetPoint("TOPRIGHT", compact and -12 or -20, -13)
    local toggle = self:CreateToggle(card, "", "", "enabled")
    toggle:SetSize(compact and 115 or 125, 25)
    toggle.yes:SetSize(44, 24)
    toggle.no:SetSize(44, 24)
    toggle.yes:ClearAllPoints()
    toggle.no:ClearAllPoints()
    toggle.yes:SetPoint("RIGHT", toggle.no, "LEFT", -4, 0)
    toggle.no:SetPoint("RIGHT", 0, 0)
    toggle:SetPoint("BOTTOMRIGHT", compact and -12 or -20, 11)
    toggle:SetFrameLevel(card:GetFrameLevel() + 3)
    toggle:SetValue(self:IsRuleEnabled(rule))
    toggle.yes:SetScript("OnClick", function() self:PersistRuleField(rule, "enabled", true); self:RefreshAll() end)
    toggle.no:SetScript("OnClick", function() self:PersistRuleField(rule, "enabled", false); self:RefreshAll() end)
    card.toggle = toggle

    return card
end

function UI:FillPetChips(parent, rule, compact)
    for _, child in ipairs({parent:GetChildren()}) do child:Hide() end
    local ids = self:RulePetIDs(rule)
    local shown = 0
    for _, petID in ipairs(ids) do
        if shown >= (compact and 3 or 5) then break end
        local info = self:GetPetInfo(petID)
        if info then
            shown = shown + 1
            local chip = CreateFrame("Frame", nil, parent, "BackdropTemplate")
            chip:SetSize(compact and 80 or 92, 24)
            chip:SetPoint("LEFT", (shown - 1) * (compact and 84 or 96), 0)
            setBackdrop(chip, COLOR.cardAlt, COLOR.borderSoft, 1, 1)
            local icon = chip:CreateTexture(nil, "ARTWORK")
            icon:SetSize(18, 18)
            icon:SetPoint("LEFT", 4, 0)
            icon:SetTexture(info.icon or QUESTION_ICON)
            local text = makeLabel(chip, info.name, 9, COLOR.muted)
            text:SetPoint("LEFT", icon, "RIGHT", 4, 0)
            text:SetWidth(compact and 51 or 62)
            text:SetWordWrap(false)
            text:SetMaxLines(1)
        end
    end
    if #ids > shown then
        local more = makeLabel(parent, "+" .. tostring(#ids - shown), 10, COLOR.lilac)
        more:SetPoint("LEFT", shown * (compact and 84 or 96) + 2, 0)
    elseif shown == 0 then
        local empty = makeLabel(parent, "No pets selected yet", 9, COLOR.faint)
        empty:SetPoint("LEFT", 0, 0)
    end
end

function UI:RefreshRulesPage()
    if not self.rulesList then return end
    local rules = {}
    for _, rule in ipairs(self:ReadRules()) do
        -- Outfit matching is intentionally kept out of the simple setup flow.
        -- Existing saved data is preserved and can still be migrated safely.
        if self:RuleID(rule) ~= "outfit" then rules[#rules + 1] = rule end
    end
    local signature = self:RulesSignature(rules)
    if self._rulesPageSignature ~= signature then
        self._rulesPageSignature = signature
        for _, child in ipairs({self.rulesList:GetChildren()}) do child:Hide() end
        for index, rule in ipairs(rules) do
            local card = self:CreateRuleCard(self.rulesList, rule, false)
            card:SetPoint("TOPLEFT", 0, -((index - 1) * 88))
            card:Show()
        end
    end
    self.rulesList:SetHeight(math.max(1, #rules * 88))
    if self.rulesScroll and self.rulesScroll.UpdateLayout then
        self.rulesScroll:UpdateLayout(self.rulesList:GetHeight(), true)
    end
end

function UI:RefreshPetPicker(preserveScroll)
    if not self.libraryContent then return end
    self.petCache = self:GetPets()
    local searchText = lower(self.petSearch and self.petSearch:GetText() or "")
    local filter = self.petFilter or "all"
    self.petScope:SetText("")
    for filterID, button in pairs(self.petFilters) do
        self:StyleFilterButton(button, filterID == filter)
    end
    for _, child in ipairs({self.libraryContent:GetChildren()}) do child:Hide() end

    local shown = 0
    self.petTiles = self.petTiles or {}
    for _, info in ipairs(self.petCache) do
        local matchesSearch = searchText == "" or string.find(lower(info.searchNames or info.name), searchText, 1, true)
        local matchesFilter = filter == "all" or (filter == "favorites" and info.favorite) or (filter == "selected" and self:IsPetInfoSelected(info))
        if matchesSearch and matchesFilter then
            local column = shown % 3
            local row = math.floor(shown / 3)
            local tileIndex = shown + 1
            local tile = self.petTiles[tileIndex]
            if not tile then
                tile = self:CreatePetTile(self.libraryContent)
                self.petTiles[tileIndex] = tile
            end
            self:UpdatePetTile(tile, info)
            tile:ClearAllPoints()
            tile:SetPoint("TOPLEFT", column * 180, -row * 62)
            tile:Show()
            shown = shown + 1
        end
    end
    local rows = math.ceil(shown / 3)
    self._petShownCount = shown
    self.libraryContent:SetHeight(math.max(402, rows * 62 + 8))
    if self.petScroll and self.petScroll.UpdateLayout then
        self.petScroll:UpdateLayout(self.libraryContent:GetHeight(), not preserveScroll)
    end
    local selectedCount = self:SelectedPetSpeciesCount()
    self.petCount:SetText(tostring(shown) .. " shown  •  " .. tostring(selectedCount) .. " selected")
    if self.petPreviewSelectedCount then self.petPreviewSelectedCount:SetText(tostring(selectedCount) .. " selected") end
    if self.assignTagsButton then
        if selectedCount > 0 then self.assignTagsButton:Enable() else self.assignTagsButton:Disable() end
    end
end

function UI:SetPetPreview(info)
    if not self.petPreview or not self.petPreviewName then return end
    if not info then
        self._petPreviewPetID = nil
        self._petPreviewDisplayID = nil
        self.petPreviewName:SetText("Preview")
        self.petPreview._apsAutoRotationSpeed = nil
        if self.petPreviewFallback then self.petPreviewFallback:Hide() end
        if self.petPreview.ClearModel then self.petPreview:ClearModel() end
        return
    end
    local detailed = self:GetPetInfo(info.petID) or info
    detailed.displayID = detailed.displayID or info.displayID
    detailed.creatureID = detailed.creatureID or info.creatureID
    self.petPreviewName:SetText(detailed.name or info.name or "Pet")
    if self._petPreviewPetID == detailed.petID and self._petPreviewDisplayID == detailed.displayID
        and self.petPreview._apsModelLoaded then
        return
    end
    self._petPreviewPetID = detailed.petID
    self._petPreviewDisplayID = detailed.displayID
    if self.petPreviewFallback then
        self.petPreviewFallback:SetTexture(detailed.icon or info.icon or QUESTION_ICON)
        self.petPreviewFallback:Hide()
    end
    local requested = setPetModel(self.petPreview, detailed, PREVIEW_MODEL_FIT_DISTANCE, PET_PREVIEW_ROTATION_SPEED,
        function(model)
            model:Show()
            if self.petPreviewFallback then self.petPreviewFallback:Hide() end
        end,
        function(model)
            model:Hide()
            if self.petPreviewFallback then self.petPreviewFallback:Show() end
        end)
    if requested then
        return
    end
    self._petPreviewPetID = nil
    self._petPreviewDisplayID = nil
    if self.petPreview.ClearModel then self.petPreview:ClearModel() end
    self.petPreview:Hide()
    if self.petPreviewFallback then self.petPreviewFallback:Show() end
end

function UI:CreatePetTile(parent)
    local tile = CreateFrame("Button", nil, parent, "BackdropTemplate")
    tile:SetSize(170, 54)
    setBackdrop(tile, COLOR.card, COLOR.borderSoft, 1, 1)
    local icon = tile:CreateTexture(nil, "ARTWORK")
    icon:SetSize(38, 38)
    icon:SetPoint("LEFT", 8, 0)
    icon:SetTexture(QUESTION_ICON)
    tile.icon = icon
    local name = makeLabel(tile, "Pet", 10, COLOR.text)
    name:SetPoint("LEFT", icon, "RIGHT", 8, 0)
    name:SetWidth(94)
    name:SetJustifyH("LEFT")
    name:SetWordWrap(false)
    name:SetMaxLines(1)
    local species = makeLabel(tile, "Pet", 9, COLOR.muted)
    species:SetPoint("TOPLEFT", name, "BOTTOMLEFT", 0, -3)
    species:SetWidth(94)
    species:SetJustifyH("LEFT")
    species:SetWordWrap(false)
    species:SetMaxLines(1)
    local favorite = tile:CreateTexture(nil, "ARTWORK")
    favorite:SetSize(14, 14)
    favorite:SetPoint("TOPRIGHT", -5, -5)
    favorite:SetTexture(NAV_ICON_ROOT .. "icon-favorite.png")
    local check = tile:CreateTexture(nil, "ARTWORK")
    check:SetSize(16, 16)
    check:SetPoint("BOTTOMRIGHT", -5, 5)
    check:SetTexture(NAV_ICON_ROOT .. "check-selected.png")
    tile.check = check
    local deadIcon = tile:CreateTexture(nil, "OVERLAY")
    deadIcon:SetSize(15, 15)
    deadIcon:SetPoint("TOPRIGHT", icon, "TOPRIGHT", 4, 4)
    deadIcon:SetTexture("Interface\\PetBattles\\DeadPetIcon")
    deadIcon:Hide()
    tile.deadIcon = deadIcon
    tile:SetScript("OnClick", function(selfTile)
        local info = selfTile and selfTile.info
        if not info then return end
        self:SetPetPreview(info)
        self:SetPetInfoSelected(info, not self:IsPetInfoSelected(info))
        local selected = self:IsPetInfoSelected(info)
        -- In the Selected tab a deselected card no longer belongs in this
        -- result set. Rebuild only for that deliberate membership change.
        if self.petFilter == "selected" and not selected then
            self:RefreshPetPicker(true)
            return
        end
        self:UpdatePetTile(selfTile, info)
        local selectedCount = self:SelectedPetSpeciesCount()
        self.petCount:SetText(tostring(self._petShownCount or 0) .. " shown  •  " .. tostring(selectedCount) .. " selected")
        if self.petPreviewSelectedCount then self.petPreviewSelectedCount:SetText(tostring(selectedCount) .. " selected") end
        if self.assignTagsButton then
            if selectedCount > 0 then self.assignTagsButton:Enable() else self.assignTagsButton:Disable() end
        end
    end)
    tile:SetScript("OnEnter", function(selfTile)
        selfTile:SetBackdropColor(copyColor(COLOR.hoverSurface, 1))
        selfTile:SetBackdropBorderColor(copyColor(COLOR.hoverBorder, 1))
        -- Browsing must be separate from roster selection: hovering a pet
        -- immediately turns the right-hand model into its live inspector.
        if selfTile.info then self:SetPetPreview(selfTile.info) end
        self:ShowPetTooltip(selfTile, selfTile.info)
    end)
    tile:SetScript("OnLeave", function(selfTile)
        local selected = self:IsPetInfoSelected(selfTile.info)
        selfTile:SetBackdropColor(copyColor(selected and COLOR.mintSoft or COLOR.card, 1))
        selfTile:SetBackdropBorderColor(copyColor(selected and COLOR.mint or COLOR.borderSoft, 1))
        if GameTooltip then GameTooltip:Hide() end
    end)
    tile.nameText = name
    tile.speciesText = species
    tile.favoriteIcon = favorite
    return tile
end

function UI:UpdatePetTile(tile, info, rule)
    if not tile or not info then return end
    tile.info = info
    tile.rule = nil
    tile.icon:SetTexture(info.icon or QUESTION_ICON)
    tile.deadIcon:SetShown(info.dead == true)
    tile.nameText:SetText(info.name or "Pet")
    local speciesName = trim(info.speciesName or "")
    local showSpecies = speciesName ~= "" and lower(speciesName) ~= lower(info.name or "")
    tile.speciesText:SetText(showSpecies and speciesName or "")
    tile.speciesText:SetShown(showSpecies)
    tile.nameText:ClearAllPoints()
    if showSpecies then
        tile.nameText:SetPoint("TOPLEFT", tile.icon, "TOPRIGHT", 8, -2)
    else
        tile.nameText:SetPoint("LEFT", tile.icon, "RIGHT", 8, 0)
    end
    tile.favoriteIcon:SetAlpha(info.favorite and 0.9 or 0)
    local selected = self:IsPetInfoSelected(info)
    if selected then
        tile:SetBackdropColor(copyColor(COLOR.mintSoft, 1))
        tile:SetBackdropBorderColor(copyColor(COLOR.mint, 1))
        tile.check:SetAlpha(1)
    else
        tile:SetBackdropColor(copyColor(COLOR.card, 1))
        tile:SetBackdropBorderColor(copyColor(COLOR.borderSoft, 1))
        tile.check:SetAlpha(0)
    end
end

function UI:ShowPetTooltip(tile, info)
    if not GameTooltip or not tile then return end
    GameTooltip:SetOwner(tile, "ANCHOR_RIGHT")
    GameTooltip:ClearLines()
    if C_PetJournal and type(C_PetJournal.GetPetInfoByPetID) == "function" then
        local ok = pcall(C_PetJournal.GetPetInfoByPetID, info.petID)
        if ok and GameTooltip.SetHyperlink and type(info.speciesID) == "number" then
            -- Pet journal tooltips are not stable across Retail builds; the
            -- plain tooltip below is the safe cross-build fallback.
        end
    end
    GameTooltip:AddLine(info.name or "Pet", 1, 1, 1)
    if info.speciesName and info.speciesName ~= info.name then GameTooltip:AddLine(info.speciesName, 0.65, 0.70, 0.78) end
    if info.level then GameTooltip:AddLine("Level " .. tostring(info.level), 0.65, 0.70, 0.78) end
    if info.dead then GameTooltip:AddLine("Needs revival", 0.9, 0.28, 0.38) end
    GameTooltip:Show()
end

function UI:SetSetting(key, value)
    local db = self:EnsureDB()
    local nextValue = value and true or false
    if type(APS.SetSetting) == "function" then
        local ok = pcall(APS.SetSetting, APS, key, nextValue)
        if not ok then db[key] = nextValue end
    elseif key == "enabled" and type(APS.SetEnabled) == "function" then
        pcall(APS.SetEnabled, APS, nextValue)
    elseif key == "disableInInstances" and type(APS.SetDisableInInstances) == "function" then
        pcall(APS.SetDisableInInstances, APS, nextValue)
    else
        db[key] = nextValue
    end
    db[key] = nextValue
    if key == "darkMode" then self:ApplyTheme() end
    self:RefreshSettings()
    self:RefreshOverview()
end

function UI:SaveNumber(key, value, minimum, maximum, fallback)
    local number = tonumber(value)
    if not number then number = fallback end
    if number < minimum then number = minimum end
    if number > maximum then number = maximum end
    local db = self:EnsureDB()
    if type(APS.SetSetting) == "function" then
        local ok = pcall(APS.SetSetting, APS, key, number)
        if not ok then db[key] = number end
    else
        db[key] = number
    end
    db[key] = number
    if key == "intervalMinutes" then
        if type(APS.ResetScheduler) == "function" then pcall(APS.ResetScheduler, APS)
        elseif type(APS.ResetTicker) == "function" then pcall(APS.ResetTicker, APS) end
    end
    if self.settingsInterval and key == "intervalMinutes" then self.settingsInterval:SetText(tostring(number)) end
    if self.settingsGrace and key == "dismissGraceMinutes" then self.settingsGrace:SetText(tostring(number)) end
    if self.settingsShuffleMin and key == "randomShuffleMinMinutes" then self.settingsShuffleMin:SetText(tostring(number)) end
    if self.settingsShuffleMax and key == "randomShuffleMaxMinutes" then self.settingsShuffleMax:SetText(tostring(number)) end
end

function UI:StopKeybindCapture()
    local button = self.settingsKeybindButton
    if not button then return end
    button._apsCapturing = nil
    if button.SetPropagateKeyboardInput then
        pcall(button.SetPropagateKeyboardInput, button, true)
    end
    self:RefreshSettings()
end

function UI:BeginKeybindCapture()
    local button = self.settingsKeybindButton
    if not button then return end
    local combatOK, inCombat = safeGlobal("InCombatLockdown")
    if not combatOK or isSecret(inCombat) or inCombat == true then
        self:Toast("Keybindings cannot be changed in combat.", COLOR.amber)
        return
    end
    button._apsCapturing = true
    if button.SetPropagateKeyboardInput then
        pcall(button.SetPropagateKeyboardInput, button, false)
    end
    button:SetText("Press a key...")
    button:SetBackdropColor(copyColor(COLOR.lilacSoft, 1))
    button:SetBackdropBorderColor(copyColor(COLOR.lilac, 1))
    setButtonFont(button, nil, COLOR.text)
end

function UI:SetChangePetBinding(bindingKey)
    local combatOK, inCombat = safeGlobal("InCombatLockdown")
    if not combatOK or isSecret(inCombat) or inCombat == true then
        self:Toast("Keybindings cannot be changed in combat.", COLOR.amber)
        self:StopKeybindCapture()
        return false
    end
    if type(_G.SetBinding) ~= "function" or type(_G.SaveBindings) ~= "function" then
        self:Toast("Keybinding controls are unavailable.", COLOR.red)
        self:StopKeybindCapture()
        return false
    end

    local _, primary, secondary = safeGlobal("GetBindingKey", CHANGE_PET_BINDING)
    local oldKeys = {}
    primary = readableString(primary)
    secondary = readableString(secondary)
    if primary then oldKeys[#oldKeys + 1] = primary end
    if secondary and secondary ~= primary then oldKeys[#oldKeys + 1] = secondary end
    local function restoreOldBinding()
        for _, oldKey in ipairs(oldKeys) do pcall(_G.SetBinding, oldKey, CHANGE_PET_BINDING) end
    end
    for _, oldKey in ipairs(oldKeys) do pcall(_G.SetBinding, oldKey) end

    if bindingKey then
        local setOK, result = pcall(_G.SetBinding, bindingKey, CHANGE_PET_BINDING)
        if not setOK or result == false then
            restoreOldBinding()
            self:Toast("That key could not be assigned.", COLOR.red)
            self:StopKeybindCapture()
            return false
        end
    end

    local setOK, bindingSet = safeGlobal("GetCurrentBindingSet")
    if not setOK or isSecret(bindingSet) or type(bindingSet) ~= "number" then bindingSet = 1 end
    local saveOK, saveResult = pcall(_G.SaveBindings, bindingSet)
    if not saveOK or saveResult == false then
        if bindingKey then pcall(_G.SetBinding, bindingKey) end
        restoreOldBinding()
        pcall(_G.SaveBindings, bindingSet)
    end
    self:StopKeybindCapture()
    if not saveOK or saveResult == false then
        self:Toast("The keybinding could not be saved.", COLOR.red)
        return false
    end
    self:Toast(bindingKey and ("Change pet: " .. bindingKey) or "Change pet key cleared.", COLOR.mint)
    return true
end

function UI:HandleKeybindInput(key)
    local button = self.settingsKeybindButton
    if not button or not button._apsCapturing or isSecret(key) or type(key) ~= "string" then return end
    key = key:upper()
    if key == "ESCAPE" then
        self:StopKeybindCapture()
        return
    end
    if key == "BACKSPACE" or key == "DELETE" then
        self:SetChangePetBinding(nil)
        return
    end
    if key == "LSHIFT" or key == "RSHIFT" or key == "LCTRL" or key == "RCTRL"
        or key == "LALT" or key == "RALT" or key == "UNKNOWN" then
        return
    end

    local parts = {}
    local ctrlOK, ctrl = safeGlobal("IsControlKeyDown")
    local altOK, alt = safeGlobal("IsAltKeyDown")
    local shiftOK, shift = safeGlobal("IsShiftKeyDown")
    if ctrlOK and not isSecret(ctrl) and ctrl == true then parts[#parts + 1] = "CTRL" end
    if altOK and not isSecret(alt) and alt == true then parts[#parts + 1] = "ALT" end
    if shiftOK and not isSecret(shift) and shift == true then parts[#parts + 1] = "SHIFT" end
    parts[#parts + 1] = key
    self:SetChangePetBinding(table.concat(parts, "-"))
end

function UI:RefreshSettings()
    if not self.settingsCard then return end
    local db = self:EnsureDB()
    self.settingsEnabled:SetValue(db.enabled ~= false)
    if self.settingsRandomShuffle then self.settingsRandomShuffle:SetValue(db.randomShuffleEnabled == true) end
    if self.settingsDarkMode then self.settingsDarkMode:SetValue(db.darkMode == true) end
    if self.settingsInstances then self.settingsInstances:SetValue(db.disableInInstances == true) end
    if self.settingsKeybindButton and not self.settingsKeybindButton._apsCapturing then
        local ok, primary, secondary = safeGlobal("GetBindingKey", CHANGE_PET_BINDING)
        local binding = ok and (primary or secondary) or nil
        self.settingsKeybindButton:SetText(tostring(readableString(binding) or "Not bound"))
        self.settingsKeybindButton:SetBackdropColor(copyColor(COLOR.cardAlt, 1))
        self.settingsKeybindButton:SetBackdropBorderColor(copyColor(COLOR.borderSoft, 1))
        setButtonFont(self.settingsKeybindButton, nil, COLOR.text)
    end
    if self.settingsInterval then self.settingsInterval:SetText(tostring(db.intervalMinutes or 5)) end
    if self.settingsGrace then self.settingsGrace:SetText(tostring(db.dismissGraceMinutes or 10)) end
    if self.settingsShuffleMin and not self.settingsShuffleMin:HasFocus() then self.settingsShuffleMin:SetText(tostring(db.randomShuffleMinMinutes or 15)) end
    if self.settingsShuffleMax and not self.settingsShuffleMax:HasFocus() then self.settingsShuffleMax:SetText(tostring(db.randomShuffleMaxMinutes or 30)) end
end

function UI:SummonNow()
    local safe, reason = self:IsSummonSafe()
    if not safe then
        self:Toast(reason or "A summon is not safe right now.", COLOR.amber)
        return
    end
    if type(APS.SummonNow) ~= "function" then
        self:Toast("The summon service is unavailable on this client.", COLOR.red)
        return
    end
    local ok, result, reason = pcall(APS.SummonNow, APS)
    if ok and result == false and reason == "already active" then
        self:Toast("This pet is already active.", COLOR.mint)
        return
    end
    if not ok or result == false then
        self:Toast("Choose at least one summonable pet first.", COLOR.amber)
        return
    end
    self:Toast("Pet summoned.", COLOR.mint)
    self:RefreshOverview()
end

function UI:Toast(message, color)
    if not self.frame then return end
    if not self.toast then
        local toast = CreateFrame("Frame", nil, self.frame, "BackdropTemplate")
        toast:SetSize(330, 42)
        toast:SetPoint("BOTTOM", self.frame, "BOTTOM", 0, 18)
        toast:SetFrameLevel(self.frame:GetFrameLevel() + 20)
        setBackdrop(toast, COLOR.card, COLOR.borderSoft, 1, 1)
        toast.text = makeLabel(toast, "", 10, COLOR.text)
        toast.text:SetPoint("CENTER", 0, 0)
        toast.text:SetWidth(290)
        toast.text:SetJustifyH("CENTER")
        self.toast = toast
    end
    self.toast.text:SetText(message or "")
    setTextColor(self.toast.text, color or COLOR.text)
    self.toast:Show()
    if self.toastTimer then self.toastTimer:Cancel() end
    self.toastTimer = C_Timer and C_Timer.After and C_Timer.After(3.2, function()
        if self.toast then self.toast:Hide() end
    end)
end

function UI:CreateModal(kind, titleText, width, height)
    local modal = CreateFrame("Frame", nil, self.frame, "BackdropTemplate")
    modal:SetSize(width, height)
    modal:SetPoint("CENTER", self.frame, "CENTER", 0, 0)
    modal:SetFrameLevel(self.frame:GetFrameLevel() + 10)
    modal:EnableMouse(true)
    setBackdrop(modal, COLOR.card, COLOR.border, 1, 1)
    local title = makeLabel(modal, titleText, 17, COLOR.text)
    title:SetPoint("TOPLEFT", 24, -23)
    local close = makeButton(modal, "Close", 58, 26, {COLOR.cardAlt, COLOR.borderSoft, COLOR.text})
    close:SetPoint("TOPRIGHT", -18, -18)
    close:SetScript("OnClick", function() modal:Hide() end)
    modal.title = title
    modal.kind = kind
    return modal
end

function UI:ShowPreview()
    if not self.frame then self:Build() end
    local modal = self.preview
    if not modal then
        modal = self:CreateModal("preview", "Preview", 510, 335)
        self.preview = modal
        local intro = makeLabel(modal, "This preview does not summon a pet.", 10, COLOR.muted)
        intro:SetPoint("TOPLEFT", 24, -58)
        intro:SetWidth(445)
        intro:SetJustifyH("LEFT")
        modal.intro = intro
        local body = makeLabel(modal, "", 12, COLOR.text)
        body:SetPoint("TOPLEFT", 24, -103)
        body:SetWidth(445)
        body:SetJustifyH("LEFT")
        modal.body = body
        local close = makeButton(modal, "Close", 82, 30, {COLOR.cardAlt, COLOR.borderSoft, COLOR.muted})
        close:SetPoint("BOTTOMRIGHT", -22, 20)
        close:SetScript("OnClick", function() modal:Hide() end)
    end
    local rules = self:ReadRules()
    local lines = {}
    local current = self:GetCurrentPet()
    table.insert(lines, current and ("Current pet:  " .. current.name) or "Current pet:  None")
    table.insert(lines, "")
    local activeCount = 0
    for _, rule in ipairs(rules) do
        if self:IsRuleEnabled(rule) then activeCount = activeCount + 1 end
    end
    table.insert(lines, "Enabled situations:  " .. tostring(activeCount) .. " of " .. tostring(#rules))
    table.insert(lines, "")
    local selectedRule = self.selectedRule or rules[1]
    local previewOK, runtimePreview = safeCall(APS, "Preview")
    if previewOK and type(runtimePreview) == "table" then
        local activeRule = runtimePreview.rule or selectedRule
        if activeRule then
            table.insert(lines, "Current situation:  " .. self:RuleTitle(activeRule))
        end
        table.insert(lines, "Eligible choices:  " .. tostring(#(runtimePreview.pool or {})))
        if runtimePreview.satisfied then
            table.insert(lines, "Already satisfied: current pet stays out")
        elseif runtimePreview.blocked then
            table.insert(lines, "Waiting:  " .. tostring(runtimePreview.blockReason or "world state"))
        elseif runtimePreview.nextPetGUID then
            local nextInfo = self:GetPetInfo(runtimePreview.nextPetGUID)
            table.insert(lines, "Next pet:  " .. (nextInfo and nextInfo.name or "an eligible pet"))
        end
    elseif selectedRule then
        table.insert(lines, "First situation:  " .. self:RuleTitle(selectedRule))
        local ids = self:RulePetIDs(selectedRule)
        local choiceCount = #ids
        if choiceCount == 0 then choiceCount = #self:SelectedPetIDs(nil) end
        table.insert(lines, "Available pets:  " .. tostring(choiceCount))
    end
    modal.body:SetText(table.concat(lines, "\n"))
    modal:Show()
    modal:Raise()
end

function UI:ShowAudit()
    if not self.frame then self:Build() end
    local modal = self.audit
    if not modal then
        modal = self:CreateModal("audit", "Setup check", 570, 410)
        self.audit = modal
        local intro = makeLabel(modal, "This check does not change settings.", 10, COLOR.muted)
        intro:SetPoint("TOPLEFT", 24, -58)
        intro:SetWidth(505)
        intro:SetJustifyH("LEFT")
        modal.intro = intro
        local body = makeLabel(modal, "", 11, COLOR.text)
        body:SetPoint("TOPLEFT", 24, -102)
        body:SetWidth(505)
        body:SetJustifyH("LEFT")
        modal.body = body
        local close = makeButton(modal, "Close", 82, 30, {COLOR.cardAlt, COLOR.borderSoft, COLOR.muted})
        close:SetPoint("BOTTOMRIGHT", -22, 20)
        close:SetScript("OnClick", function() modal:Hide() end)
    end
    local db = self:EnsureDB()
    local rules = self:ReadRules()
    local enabled = 0
    local configured = 0
    for _, rule in ipairs(rules) do
        if self:IsRuleEnabled(rule) then enabled = enabled + 1 end
        if #self:RulePetIDs(rule) > 0 then configured = configured + 1 end
    end
    local current = self:GetCurrentPet()
    local safe, reason = self:IsSummonSafe()
    local lines = {
        (db.enabled ~= false and "OK  Automation is on" or "--  Automation is paused"),
        (current and ("OK  Current pet: " .. current.name) or "--  No pet is out"),
        "OK  " .. tostring(enabled) .. " enabled situation" .. (enabled == 1 and "" or "s"),
        "OK  " .. tostring(configured) .. " situation" .. (configured == 1 and "" or "s") .. " with selected pets",
        (safe and "OK  A summon would be safe now" or "--  Waiting: " .. tostring(reason or "world state")),
        "",
        "Nothing was changed by this audit.",
    }
    modal.body:SetText(table.concat(lines, "\n\n"))
    modal:Show()
    modal:Raise()
end

function UI:CreateHelp()
    if self.help then return self.help end
    local help = CreateFrame("Frame", "PETALHelp", UIParent, "BackdropTemplate")
    self.help = help
    help:SetSize(760, 555)
    help:SetFrameStrata("FULLSCREEN_DIALOG")
    help:SetToplevel(true)
    help:SetClampedToScreen(true)
    help:SetMovable(true)
    help:EnableMouse(true)
    help:RegisterForDrag("LeftButton")
    if help.EnableKeyboard then help:EnableKeyboard(true) end
    if help.SetPropagateKeyboardInput then help:SetPropagateKeyboardInput(false) end
    help:SetScript("OnKeyDown", function(selfFrame, key)
        if key == "ESCAPE" then
            selfFrame:Hide()
        end
    end)
    setBackdrop(help, COLOR.panel, COLOR.border, 1, 1)
    local helpPaper = help:CreateTexture(nil, "ARTWORK", nil, -8)
    helpPaper:SetAllPoints(help)
    helpPaper:SetTexture(PAPER_WASH)
    helpPaper:SetAlpha(type(APS.GetSetting) == "function" and APS:GetSetting("darkMode", false) == true and 0.04 or 0.08)
    help.paper = helpPaper

    local top = CreateFrame("Frame", nil, help, "BackdropTemplate")
    top:SetPoint("TOPLEFT", 1, -1)
    top:SetPoint("TOPRIGHT", -1, -1)
    top:SetHeight(66)
    setBackdrop(top, COLOR.card, COLOR.borderSoft, 1, 1)
    local title = makeLabel(top, "Help", 18, COLOR.text)
    title:SetPoint("LEFT", 26, 5)
    local close = makeButton(top, "Close", 72, 28, {COLOR.cardAlt, COLOR.borderSoft, COLOR.muted})
    close:SetPoint("RIGHT", -18, 0)
    addButtonIcon(close, NAV_ICON_ROOT .. "close-coral.png", 15)
    addBottomAccent(close, COLOR.red)
    close:SetScript("OnClick", function() help:Hide() end)

    local rail = CreateFrame("Frame", nil, help, "BackdropTemplate")
    rail:SetPoint("TOPLEFT", 1, -67)
    rail:SetPoint("BOTTOMLEFT", 1, 1)
    rail:SetWidth(184)
    setBackdrop(rail, COLOR.rail, COLOR.borderSoft, 1, 1)
    local topicTitle = makeLabel(rail, "HELP", 9, COLOR.faint)
    topicTitle:SetPoint("TOPLEFT", 22, -23)

    local body = CreateFrame("Frame", nil, help)
    body:SetPoint("TOPLEFT", 185, -67)
    body:SetPoint("BOTTOMRIGHT", -1, 1)
    help.body = body
    local topics = {
        {id = "start", label = "Setup", title = "Setup", text = "1. Select pets.\n2. Set situations for each pet.\n\nPetal keeps a matching pet out.", accent = COLOR.sky, icon = NAV_ICON_ROOT .. "icon-ready.png"},
        {id = "tags", label = "Situations", title = "Situations", text = "Use the situation toggles on each pet. A colored situation is enabled.", accent = COLOR.mint, icon = NAV_ICON_ROOT .. "icon-moments.png"},
        {id = "library", label = "Pets", title = "Pets", text = "Click a pet to select it. Use search and filters to narrow the list.", accent = COLOR.lilac, icon = NAV_ICON_ROOT .. "icon-friends.png"},
        {id = "sets", label = "Save / Load", title = "Save / Load", text = "Save named setups, load them later, or move them with an export code. Imported sets are not loaded automatically.", accent = COLOR.amber, icon = NAV_ICON_ROOT .. "icon-ready.png"},
    }
    self.helpTopics = {}
    for index, topic in ipairs(topics) do
        local button = makeButton(rail, "", 150, 38, {COLOR.rail, COLOR.rail, COLOR.muted})
        button:SetPoint("TOPLEFT", 16, -46 - (index - 1) * 44)
        button:SetBackdropColor(copyColor(COLOR.rail, 1))
        button:SetBackdropBorderColor(copyColor(COLOR.rail, 1))
        local marker = button:CreateTexture(nil, "ARTWORK")
        marker:SetSize(4, 18)
        marker:SetPoint("LEFT", 10, 0)
        setThemeTextureColor(marker, topic.accent, 1)
        local icon = button:CreateTexture(nil, "ARTWORK", nil, 1)
        icon:SetSize(20, 20)
        icon:SetPoint("LEFT", 18, 0)
        icon:SetTexture(topic.icon)
        local label = makeLabel(button, topic.label, 11, COLOR.text)
        label:SetPoint("LEFT", icon, "RIGHT", 10, 0)
        button._apsLabel = label
        button._apsMarker = marker
        button._apsMarkerColor = topic.accent
        button._apsIcon = icon
        local topicID = topic.id
        button:SetScript("OnClick", function() self:ShowHelpTopic(topicID) end)
        button:SetScript("OnEnter", function(selfButton)
            if not selfButton._apsSelected then selfButton:SetBackdropColor(copyColor(COLOR.hoverSurface, 1)) end
        end)
        button:SetScript("OnLeave", function(selfButton) self:StyleRailButton(selfButton, selfButton._apsSelected) end)
        self.helpTopics[topic.id] = button
    end
    local summary = makeLabel(body, "", 12, COLOR.text)
    summary:SetPoint("TOPLEFT", 34, -31)
    summary:SetWidth(510)
    summary:SetJustifyH("LEFT")
    summary:SetSpacing(5)
    body.summary = summary
    local footer = makeLabel(body, "Press Escape to close", 10, COLOR.faint)
    footer:SetPoint("BOTTOMLEFT", 34, 25)
    body.footer = footer

    help:SetScript("OnDragStart", function(frame) frame:StartMoving() end)
    help:SetScript("OnDragStop", function(frame) frame:StopMovingOrSizing(); frame:SetClampedToScreen(true) end)
    help:SetScript("OnShow", function() self:ScaleHelp(); self:ShowHelpTopic(self.helpTopic or "start") end)
    help:SetScript("OnHide", function() end)
    -- CreateFrame starts visible. Hide the new window before returning so the
    -- first click on Help opens it rather than merely hiding it.
    help:Hide()
    return help
end

function UI:ScaleHelp()
    if not self.help or not UIParent then return end
    local width, height = UIParent:GetWidth(), UIParent:GetHeight()
    if not width or not height or width <= 0 or height <= 0 then return end
    local scale = math.min(1, (width - 24) / 760, (height - 24) / 555)
    if scale <= 0 then scale = 0.01 end
    self.help:SetScale(scale)
    if not self.help:GetPoint(1) then self.help:SetPoint("CENTER", UIParent, "CENTER", 0, 0) end
end

function UI:ShowHelpTopic(id)
    self:CreateHelp()
    local topics = {
        start = {title = "Setup", text = "1. Select pets.\n2. Set situations for each pet.\n\nPetal keeps a matching pet out.", accent = COLOR.sky},
        tags = {title = "Situations", text = "Use the situation toggles on each pet. A colored situation is enabled.", accent = COLOR.mint},
        library = {title = "Pets", text = "Click a pet to select it. Use search and filters to narrow the list.", accent = COLOR.lilac},
        sets = {title = "Save / Load", text = "Save named setups, load them later, or move them with an export code. Imported sets are not loaded automatically.", accent = COLOR.amber},
    }
    local topic = topics[id] or topics.start
    self.helpTopic = id
    self.help.body.summary:SetText(topic.title .. "\n\n" .. topic.text)
    setTextColor(self.help.body.summary, COLOR.text)
    for topicID, button in pairs(self.helpTopics or {}) do
        self:StyleRailButton(button, topicID == id)
    end
end

function UI:ToggleHelp()
    self:CreateHelp()
    if self.help:IsShown() then
        self.help:Hide()
    else
        if type(APS.CloseTutorial) == "function" then pcall(APS.CloseTutorial, APS) end
        self:ScaleHelp()
        self.help:Show()
        self.help:Raise()
    end
end

function UI:ShowTutorial(topic)
    if self.help then self.help:Hide() end
    if type(APS.StartTutorial) == "function" then
        pcall(APS.StartTutorial, APS, topic)
    end
end

-- If another options entry point was registered by an external integration,
-- retain it as a fallback while making Petal the normal destination.
if type(APS.OpenOptions) == "function" and not APS.OpenOptionsLegacy then
    APS.OpenOptionsLegacy = APS.OpenOptions
end
function APS:OpenOptions()
    if APS.UI and type(APS.UI.Show) == "function" then
        APS.UI:Show()
        return
    end
    if APS.OpenOptionsLegacy then
        return APS.OpenOptionsLegacy(self)
    end
end

local events = CreateFrame("Frame")
events:SetScript("OnEvent", function(_, event)
    if not UI.frame or not UI.frame:IsShown() then return end
    if event == "UI_SCALE_CHANGED" or event == "DISPLAY_SIZE_CHANGED" then
        UI:ScaleToScreen()
        UI:RestorePosition()
        if UI.help and UI.help:IsShown() then UI:ScaleHelp() end
        UI:RefreshAll(true)
        return
    end
    if event == "PLAYER_REGEN_DISABLED" then
        UI:RefreshOverview()
        return
    end
    UI:RefreshAll(true)
end)
for _, event in ipairs({"COMPANION_UPDATE", "PET_JOURNAL_LIST_UPDATE", "PLAYER_ENTERING_WORLD", "ZONE_CHANGED_NEW_AREA", "ZONE_CHANGED", "ZONE_CHANGED_INDOORS", "GROUP_ROSTER_UPDATE", "PLAYER_UPDATE_RESTING", "UI_SCALE_CHANGED", "DISPLAY_SIZE_CHANGED", "PLAYER_REGEN_DISABLED", "PLAYER_REGEN_ENABLED"}) do
    events:RegisterEvent(event)
end

return UI