Build.lua

local ADDON, ns = ...

-- Buttons and bar frames: creation, appearance, layout.
--
-- === Division of labour with the engine ===
--
-- A button is a SecureActionButtonTemplate and gets its action slot as the
-- "action" attribute. The engine then does the pressing: casting, cooldown,
-- usability and range are its business. Ours is to create the button, tell it
-- the slot and draw what is visible on it.
--
-- This is not a convenience. Casting from insecure code is impossible; an
-- addon that "presses the button itself" is asking the engine to do it by a
-- longer route.
--
-- === Forbidden in combat ===
--
-- Creating a button, assigning its slot, binding a key to it, showing or
-- hiding a bar. All of it is protected and all of it happens out of combat.
-- In combat the buttons run on what the engine was told in advance: which
-- page to show in a stance, when to hide the bar.

local Build = {}
ns.Build = Build

-- Bar frames we created: key -> frame.
local frames = {}

-- Buttons: bar key -> array of buttons.
local buttons = {}

Build.frames = frames
Build.buttons = buttons

--- Whether combat is in progress.
-- @return boolean
local function inCombat()
    if type(InCombatLockdown) ~= "function" then return false end
    local ok, locked = pcall(InCombatLockdown)
    return ok and locked and true or false
end
Build.InCombat = inCombat

--============================================================================
-- Bar frame
--============================================================================

--- Create the bar frame, or return the existing one.
--
-- SecureHandlerStateTemplate is required for two things at once: page paging
-- and the visibility condition. The engine evaluates both, so both work in
-- combat.
--
-- For moving purposes the frame is ordinary: it is ours, so Core/Mover.lua
-- drags it like any other. That was the point of the whole design.
--
-- @param key string bar key
-- @return table|nil
function Build.Frame(key)
    if type(key) ~= "string" or key == "" then return nil end
    if frames[key] then return frames[key] end
    if type(CreateFrame) ~= "function" then return nil end
    if inCombat() then return nil end

    local name = "RackBar_" .. key
    local ok, frame = pcall(CreateFrame, "Frame", name, _G.UIParent,
        "SecureHandlerStateTemplate")
    if not ok or type(frame) ~= "table" then return nil end

    pcall(frame.SetSize, frame, 1, 1)
    pcall(frame.SetPoint, frame, "CENTER", _G.UIParent, "CENTER", 0, 0)

    frames[key] = frame
    buttons[key] = buttons[key] or {}

    return frame
end

--============================================================================
-- Button
--============================================================================

-- Layers of the button's artwork and what sits on them.
--
-- Field names here are ours: we created the button and nobody else reads it.
-- The game-owned aliases are set at the end of dressButton.
--- A piece the game's template already made, if it made one.
--
-- Two ways of asking, because the client has had two. Modern builds hang the
-- piece on the button by a key - button.icon, button.cooldown - and older
-- ones name it after the button: RackButton1Icon. A build that answers
-- neither gets nothing back, and the caller makes its own.
--
-- Using the template's piece rather than our own is the whole point. A piece
-- the game created is driven by the game, and Show and Hide on it work in
-- combat. One we create is a child of a protected frame, where both are
-- blocked - silently, taking the rest of the repaint down with them.
--
-- @param button table the button
-- @param key string the modern field name
-- @param suffix string what the old name adds to the button's name
-- @return table|nil
local function piece(button, key, suffix)
    if type(button) ~= "table" then return nil end
    if type(button[key]) == "table" then return button[key] end

    if type(button.GetName) == "function" then
        local ok, name = pcall(button.GetName, button)
        if ok and type(name) == "string" and name ~= "" then
            local said = _G[name .. suffix]
            if type(said) == "table" then return said end
        end
    end

    return nil
end

local function dressButton(button)
    -- Whether the game's template actually handed its pieces over.
    --
    -- Bartender4 gets its icon, cooldown, flash and labels from
    -- ActionButtonTemplate. If that template is absent here, or names its
    -- pieces differently, we build our own - and ours are addon-made
    -- children of a protected button, which behave differently in combat.
    -- Which of the two we are on decides what else has to be defended
    -- against, so it is recorded rather than assumed.
    button.rackTemplated = piece(button, "cooldown", "Cooldown") ~= nil

    local icon = piece(button, "icon", "Icon")
        or button:CreateTexture(nil, "BACKGROUND")

    -- Above the frame fill, below everything drawn over it: cooldown, equipped
    -- border, activation glow. The sublevel is given as a number rather than
    -- left to creation order - order is what once hid the icon under the fill.
    pcall(icon.SetDrawLayer, icon, "BACKGROUND", 0)

    icon:SetPoint("TOPLEFT", button, "TOPLEFT", 1, -1)
    icon:SetPoint("BOTTOMRIGHT", button, "BOTTOMRIGHT", -1, 1)
    -- The crop removes the icon file's own border, which on a button with a
    -- frame of its own reads as a second frame.
    icon:SetTexCoord(0.08, 0.92, 0.08, 0.92)
    button.rackIcon = icon

    -- Cooldown. A CooldownFrameTemplate of its own: the engine drives it, so
    -- the seconds are not ours to count.
    -- Named, and anchored TO THE BUTTON.
    --
    -- === Both of those were wrong, and the second is why nothing was drawn ===
    --
    -- A Cooldown is a FRAME. Frame:SetAllPoints expects a frame, and it was
    -- being handed the icon TEXTURE. Neither the game's own buttons nor
    -- LibActionButton-1.0 ever anchor a cooldown to a texture - they anchor
    -- it to the button, with SetAllPoints() or with two SetPoints. Anchored
    -- to a texture the frame has no size it can draw into, so the numbers
    -- arrived, the frame took them, and the sweep had nowhere to appear.
    --
    -- The player saw it as: long cooldowns and the global cooldown alike
    -- simply never showed.
    --
    -- The name matters for a different reason: a template's own pieces are
    -- reached by name on older builds, and we support more than one build.
    local cooldownName
    if type(button.GetName) == "function" then
        local okName, said = pcall(button.GetName, button)
        if okName and type(said) == "string" and said ~= "" then
            cooldownName = said .. "Cooldown"
        end
    end

    local cooldown = piece(button, "cooldown", "Cooldown")

    if cooldown == nil then
        -- Ours, so ours to place. Anchored to the BUTTON and never to the
        -- icon texture: Frame:SetAllPoints wants a frame, and anchored to a
        -- texture the frame has no size to draw into.
        cooldown = CreateFrame("Cooldown", cooldownName, button,
            "CooldownFrameTemplate")
        cooldown:ClearAllPoints()
        cooldown:SetAllPoints(button)
    end

    -- A cooldown that came from the template keeps the template's own
    -- anchors. LibActionButton-1.0 re-anchors one only when it is hiding the
    -- button's border, and otherwise leaves it exactly as the game set it -
    -- which is how the game's own buttons draw it.

    -- The level is LEFT ALONE.
    --
    -- LibActionButton-1.0 sets a level only on its charge cooldown, never on
    -- this one, and that is right: two frames on the same level draw in no
    -- defined order, so a cooldown lowered to the button's own level can end
    -- up under the button's artwork instead of over the icon.
    --
    -- Whatever the template gave it is what the game's own buttons use.

    -- Dressed, not left bare.
    --
    -- A Cooldown frame straight out of the template carries no swipe colour
    -- and no edge texture of its own, and a sweep drawn in no colour is a
    -- sweep nobody sees. The game's own buttons are dressed before use and so
    -- is every button LibActionButton-1.0 makes; these are its values.
    --
    -- Regression this fixes: the global cooldown was invisible. The numbers
    -- reached the frame and the frame drew them in nothing.
    pcall(cooldown.SetSwipeColor, cooldown, 0, 0, 0)
    pcall(cooldown.SetEdgeTexture, cooldown,
        "Interface\\Cooldown\\edge")
    pcall(cooldown.SetDrawSwipe, cooldown, true)

    -- The edge is the bright line that runs round the sweep, and the bling is
    -- the flash when it ends. Both are the game's defaults on its own
    -- buttons; the flash is off because a hundred and twenty of them going
    -- off together is a light show, not information.
    pcall(cooldown.SetDrawEdge, cooldown, false)
    pcall(cooldown.SetDrawBling, cooldown, false)


    button.rackCooldown = cooldown

    -- Labels. The font object is named at creation: a FontString with no font
    -- assigned drops on SetText, and drops the first time text arrives before
    -- a font does.
    local hotkey = piece(button, "HotKey", "HotKey")
        or button:CreateFontString(nil, "OVERLAY",
            "NumberFontNormalSmallGray")
    hotkey:SetPoint("TOPRIGHT", button, "TOPRIGHT", -2, -2)
    button.rackHotkey = hotkey

    local macro = piece(button, "Name", "Name")
        or button:CreateFontString(nil, "OVERLAY",
            "GameFontHighlightSmallOutline")
    macro:SetPoint("BOTTOM", button, "BOTTOM", 0, 2)
    button.rackMacro = macro

    local count = piece(button, "Count", "Count")
        or button:CreateFontString(nil, "OVERLAY", "NumberFontNormal")
    count:SetPoint("BOTTOMRIGHT", button, "BOTTOMRIGHT", -2, 2)
    button.rackCount = count

    -- Charge cooldown: one charge coming back while the others are usable.
    --
    -- A separate frame rather than the same one: the ordinary cooldown is not
    -- running at this point - the spell is castable - and reusing its sweep
    -- would show "unavailable" for something available.
    --
    -- Drawn as a STRIP along the bottom, not as a sweep over the icon: a dark
    -- sweep over a castable spell reads as a cooldown, a strip reads as
    -- "coming back". The game draws it the same way.
    -- Anchored to the BUTTON, for the reason written at the cooldown above:
    -- a frame anchored to a texture has no size to draw into.
    local charge = CreateFrame("Cooldown",
        cooldownName and (cooldownName .. "Charge") or nil,
        button, "CooldownFrameTemplate")
    charge:SetPoint("BOTTOMLEFT", button, "BOTTOMLEFT", 0, 0)
    charge:SetPoint("BOTTOMRIGHT", button, "BOTTOMRIGHT", 0, 0)
    charge:SetHeight(4)
    pcall(charge.SetDrawEdge, charge, false)
    pcall(charge.SetDrawSwipe, charge, true)
    pcall(charge.SetHideCountdownNumbers, charge, true)

    -- Shown and transparent, not hidden: this frame is ours and sits under a
    -- protected button, so it is revealed with alpha (ns.Paint.Reveal). A
    -- hidden frame has nothing for alpha to reveal.
    charge:Show()
    charge:SetAlpha(0)
    button.rackCharge = charge

    -- The flash: auto-attack and auto-repeat blink while they are running.
    --
    -- It is how the game says "this is what you are doing right now", and
    -- without it a melee player cannot tell auto-attack is on except by
    -- watching the character. The game's own texture and its own blend, so
    -- that it reads the same as on every other bar on screen.
    --
    -- Hidden at birth and shown by the ticker (ns.Paint.Flashes): a texture
    -- that blinks is a texture somebody has to toggle, and the addon already
    -- has one frame doing that kind of work.
    local flash = piece(button, "Flash", "Flash")
        or button:CreateTexture(nil, "OVERLAY")
    flash:SetTexture("Interface\\Buttons\\UI-QuickslotRed")
    flash:SetBlendMode("ADD")
    flash:SetAllPoints(button)
    flash:Hide()
    button.rackFlash = flash

    -- The name the game uses for this piece, for the same reason the icon and
    -- the cooldown carry theirs: a neighbour looking for it finds it.
    button.Flash = flash

    -- Activation glow: the game says this spell is the one to cast now.
    --
    -- === Why not the game's artwork ===
    --
    -- The native glow is an animated gold flare built from a texture set and
    -- driven by a 250-line library. In a dark flat theme it is the only gold
    -- object on screen and argues with everything else; the textures are also
    -- named differently across builds.
    --
    -- === Why a pulse rather than a static border ===
    --
    -- The glow has to be distinguishable from the equipped border and from
    -- mouse hover, and the palette has no third colour to spare for it. So it
    -- differs by MOTION, not colour: the glowing button is the only one on the
    -- bar that breathes. Motion is caught at the edge of vision, which is how
    -- a rotation hint is read.
    do
        local glow = CreateFrame("Frame", nil, button)
        glow:SetPoint("TOPLEFT", icon, "TOPLEFT", -2, 2)
        glow:SetPoint("BOTTOMRIGHT", icon, "BOTTOMRIGHT", 2, -2)

        local okLevel, level = pcall(button.GetFrameLevel, button)
        if okLevel and type(level) == "number" then
            pcall(glow.SetFrameLevel, glow, level + 3)
        end

        local r, g, b = ns.Skin.Color("accent")
        local sides = {
            { "TOPLEFT", "TOPRIGHT", nil, 2 },
            { "BOTTOMLEFT", "BOTTOMRIGHT", nil, 2 },
            { "TOPLEFT", "BOTTOMLEFT", 2, nil },
            { "TOPRIGHT", "BOTTOMRIGHT", 2, nil },
        }
        for i = 1, #sides do
            local side = sides[i]
            local line = glow:CreateTexture(nil, "OVERLAY")
            line:SetPoint(side[1])
            line:SetPoint(side[2])
            if side[3] then line:SetWidth(side[3]) end
            if side[4] then line:SetHeight(side[4]) end
            if r then line:SetColorTexture(r, g, b, 1) end
        end

        glow:Show()
        glow:SetAlpha(0)
        button.rackGlow = glow

    -- The pulse uses an engine animation group rather than a per-frame count
    -- of our own: counting on OnUpdate for 120 buttons would cost a frame of
    -- combat and look identical.
    --
    -- A missing animation group is a normal answer, not an error: the glow
    -- then shines steadily instead of breathing, and it is still a glow.
        if type(glow.CreateAnimationGroup) == "function" then
            local okGroup, pulse = pcall(glow.CreateAnimationGroup, glow)
            if okGroup and type(pulse) == "table" then
                pcall(pulse.SetLooping, pulse, "BOUNCE")

                local okFade, fade = pcall(pulse.CreateAnimation, pulse, "Alpha")
                if okFade and type(fade) == "table" then
                    pcall(fade.SetFromAlpha, fade, 1)
                    pcall(fade.SetToAlpha, fade, 0.35)
                    pcall(fade.SetDuration, fade, 0.6)
                    button.rackGlowPulse = pulse
                end
            end
        end
    end

    -- Pet autocast: a strip under the icon.
    --
    -- A pet ability with autocast on is cast by the pet without an order. The
    -- game says so with spinning sparkles around the button - artwork a dark
    -- flat theme has no source for, and named differently across builds.
    --
    -- It must be distinguishable from the three things the button already
    -- says: equipped (border), cast this now (pulse), newly learned (corner
    -- dot). The palette has no fourth colour, so this one differs by shape
    -- again: a strip along the bottom edge of the icon means "runs itself".
    do
        local auto = button:CreateTexture(nil, "OVERLAY")
        auto:SetHeight(2)
        auto:SetPoint("BOTTOMLEFT", icon, "BOTTOMLEFT", 0, 0)
        auto:SetPoint("BOTTOMRIGHT", icon, "BOTTOMRIGHT", 0, 0)

        local r, g, b = ns.Skin.Color("accent")
        if r then pcall(auto.SetColorTexture, auto, r, g, b, 1) end

        auto:Hide()
        button.rackAuto = auto
    end

    -- New-action mark: a dot in the corner of the icon.
    --
    -- The game drops newly learned spells onto the bars itself and marks
    -- them, so the player notices what appeared. The mark is cleared by the
    -- first use or by mouse hover (ns.Paint.Touch).
    --
    -- === Why a dot, and not a border or a warm colour ===
    --
    -- A border already says "equipped" and the pulse says "cast this now"; a
    -- third border is more than the button can carry. A warm colour is
    -- forbidden by the palette rule: this theme has exactly one warm role, and
    -- it belongs to a reading that demands action, not to a mark that can
    -- light up on ten buttons at once (Core/Skin.lua).
    --
    -- So the mark differs by SHAPE rather than colour, which is enough: a new
    -- spell is looked for once.
    do
        local fresh = button:CreateTexture(nil, "OVERLAY")
        fresh:SetSize(5, 5)
        fresh:SetPoint("TOPLEFT", icon, "TOPLEFT", 1, -1)

        local r, g, b = ns.Skin.Color("accent")
        if r then pcall(fresh.SetColorTexture, fresh, r, g, b, 1) end

        fresh:Hide()
        button.rackFresh = fresh
    end

    -- Equipped-item border. Wanted where a weapon or shield lies on the bar:
    -- the player sees what is worn without opening a bag.
    --
    -- Palette accent rather than the game's green gem: there is no green in
    -- this theme at all, and a single green object would outshine everything
    -- else on screen.
    --
    -- Built from four strips for the same reason the button frame is: not
    -- every frame has SetBackdrop on this client, while textures always work
    -- (Core/Skin.lua).
    do
        local worn = CreateFrame("Frame", nil, button)
        worn:SetAllPoints(icon)

        -- The border goes ABOVE the icon and the cooldown: otherwise the
        -- cooldown sweep paints over it and worn gear looks unworn on cooldown.
        local okLevel, level = pcall(button.GetFrameLevel, button)
        if okLevel and type(level) == "number" then
            pcall(worn.SetFrameLevel, worn, level + 2)
        end

        local r, g, b = ns.Skin.Color("accent")
        local sides = {
            { "TOPLEFT", "TOPRIGHT", nil, 1 },
            { "BOTTOMLEFT", "BOTTOMRIGHT", nil, 1 },
            { "TOPLEFT", "BOTTOMLEFT", 1, nil },
            { "TOPRIGHT", "BOTTOMRIGHT", 1, nil },
        }
        for i = 1, #sides do
            local side = sides[i]
            local line = worn:CreateTexture(nil, "OVERLAY")
            line:SetPoint(side[1])
            line:SetPoint(side[2])
            if side[3] then line:SetWidth(side[3]) end
            if side[4] then line:SetHeight(side[4]) end
            if r then line:SetColorTexture(r, g, b, 1) end
        end

        worn:Show()
        worn:SetAlpha(0)
        button.rackEquipped = worn
    end

    -- Frame, hover response and pressed state.
    --
    -- The regions are created HERE; Skinning.lua decides how they look. The
    -- split is not cosmetic: the player picks the button look - our flat one,
    -- the game's art or a Masque skin - and changes it at will. A texture,
    -- once created, cannot be given back to the engine, so creating one per
    -- look would accumulate three textures per button, 300 per bar.
    --
    -- Hence one texture per state, re-dressed by Skinning.
    ns.Skin.Backdrop(button, "panel", "line")

    -- State textures: pushed, highlight, checked.
    --
    -- === The engine must create them, not us ===
    --
    -- Creating them ourselves and handing them over ("here is a texture, be
    -- the pushed one") does not work: the button accepts the texture but does
    -- not drive it, so the texture stays visible ALWAYS.
    --
    -- The pushed texture is a dark inset square drawn over the icon, which is
    -- why every icon on the bar looked black from the start.
    --
    -- Passing a FILE PATH instead makes the engine create the texture, show
    -- and hide it itself. The object can then be fetched back with
    -- Get*Texture() and recoloured, which is what Skinning.lua needs.
    --
    -- The white pixel here is a canvas, not a picture: the palette gives it
    -- its colour, the flat look paints it, and the game look replaces it with
    -- the game's own art.
    local FLAT = ns.Media.FLAT

    if type(button.SetCheckedTexture) == "function" then
        pcall(button.SetCheckedTexture, button, FLAT)
        if type(button.GetCheckedTexture) == "function" then
            local ok, said = pcall(button.GetCheckedTexture, button)
            if ok then button.rackChecked = said end
        end
    end

    if type(button.SetPushedTexture) == "function" then
        pcall(button.SetPushedTexture, button, FLAT)
        if type(button.GetPushedTexture) == "function" then
            local ok, said = pcall(button.GetPushedTexture, button)
            if ok then button.rackPushed = said end
        end
    end

    if type(button.SetHighlightTexture) == "function" then
        pcall(button.SetHighlightTexture, button, FLAT)
        if type(button.GetHighlightTexture) == "function" then
            local ok, said = pcall(button.GetHighlightTexture, button)
            if ok then button.rackHover = said end
        end
    end

    -- Game-owned ALIASES for the button's parts.
    --
    -- === Why a second name for things already named ===
    --
    -- Neighbouring addons find the parts of someone else's button by the
    -- game's field names: the icon in "icon", the cooldown in "cooldown", the
    -- key label in "HotKey". That is how the game's own button is built, and
    -- skinning addons, Masque and darkening addons all read those names.
    --
    -- Our prefixed names stay internal - they make it obvious the field is
    -- ours - but the button has to look like a button from outside.
    --
    -- Regression this fixed: a darkening addon looks for the icon in order NOT
    -- to touch it (the icon is content, it identifies the spell). Not finding
    -- the usual field, it treated the icon as chrome and darkened it with the
    -- frame. Buttons lit up in colour and went black a moment later.
    --
    -- One line per part, and it settles a dozen such conversations in advance.
    button.icon = icon
    button.cooldown = button.rackCooldown
    button.HotKey = button.rackHotkey
    button.Name = button.rackMacro
    button.Count = button.rackCount

    ns.Skinning.Dress(button.rackBar, button)
end

--- Create a bar button, or return the existing one.
--
-- The button's name comes from ns.Bind.ButtonName: it is needed here and when
-- binding a key, and two spellings drifting apart would break the key
-- silently.
--
-- @param key string bar key
-- @param index number button number
-- @return table|nil
function Build.Button(key, index)
    local parent = Build.Frame(key)
    if not parent then return nil end
    if inCombat() then return nil end

    local list = buttons[key]
    if list[index] then return list[index] end

    local name = ns.Bind.ButtonName(key, index)
    if not name then return nil end

    -- The game's own action button template, plus the secure one.
    --
    -- === Why the game's template and not a bare button ===
    --
    -- A bare SecureActionButtonTemplate gives a button with nothing on it,
    -- and every piece then has to be created by us: icon, cooldown, flash,
    -- labels. Those pieces are CHILDREN OF A PROTECTED FRAME, and in combat
    -- Show and Hide on such a frame are blocked - silently, aborting the
    -- whole call stack. The repaint then died part way through, and
    -- everything painted after the first hidden frame stopped updating in a
    -- fight: no cooldown, no range colour, nothing. Out of combat it all
    -- worked, which is what the symptom looked like.
    --
    -- ActionButtonTemplate is how the game makes its own buttons and how
    -- LibActionButton-1.0 makes Bartender4's. Its pieces come from the
    -- client rather than from us, and they behave in combat because the game
    -- drives them.
    --
    -- The bare template stays as a fallback: this addon declares every live
    -- client and must not fail to build a button on one that lacks it.
    local ok, button = pcall(CreateFrame, "CheckButton", name, parent,
        "ActionButtonTemplate, SecureActionButtonTemplate")

    if not ok or type(button) ~= "table" then
        ok, button = pcall(CreateFrame, "CheckButton", name, parent,
            "SecureActionButtonTemplate")
    end
    if not ok or type(button) ~= "table" then return nil end

    -- The template's own handlers are taken off.
    --
    -- === This is the bug, and it is their comment that names it ===
    --
    -- LibActionButton-1.0 writes, at this exact point:
    --
    --     button:SetScript("OnAttributeChanged", nil)
    --     -- inherited templates bring in a handler here which we
    --     -- don't want, so get rid of it
    --
    -- ActionButtonTemplate carries the game's own action button code with
    -- it. On the game's buttons that code knows the slot it is looking at;
    -- on ours it does not, so it runs, finds nothing, and HIDES the pieces -
    -- the cooldown among them.
    --
    -- OnAttributeChanged is the worst of them, and it is what made this look
    -- like a combat bug. It fires on every attribute change, and the secure
    -- state driver changes attributes constantly in a fight - paging,
    -- stances, vehicles. Out of combat the attributes sit still and the
    -- handler rarely runs, so everything looked right; in a fight it ran
    -- over and over and hid the cooldown as fast as the repaint set it.
    --
    -- The pieces are kept, the behaviour is dropped. Ours is set afterwards.
    for _, script in ipairs({ "OnAttributeChanged", "OnEvent", "OnUpdate",
        "OnShow", "OnHide", "OnLoad" }) do
        pcall(button.SetScript, button, script, nil)
    end

    if type(button.UnregisterAllEvents) == "function" then
        pcall(button.UnregisterAllEvents, button)
    end

    -- Which bar this button belongs to. Needed where the button repaints
    -- itself - after a drag: the settings are fetched by key, and finding the
    -- button by walking every bar backwards would be a second way to answer a
    -- question it can already answer.
    button.rackBar = key

    -- Its own index, held for the same reason as the bar key: the key-binding
    -- mode asks the button what it does. The field is the button's PLACE on
    -- the bar, which the slot offset does not change.
    button.rackIndex = index

    -- The slot is also an attribute, but that attribute is a DIFFERENT number.
    --
    -- * button.rackIndex - the button's PLACE on the bar. The key-binding mode
    --   says "third button of the main bar" by it, and Slots.Shift does not
    --   change it: the player presses the third from the left regardless of
    --   what lies on it.
    -- * attribute "rackSlot" - which slot OF THE PAGE the button shows. The
    --   offset rotates this one (Build.Assign) and the paging snippet reads
    --   it: the secure handler lives in a separate environment and sees only
    --   attributes. Without it the snippet cannot compute the slot and the bar
    --   stays on page one forever.
    --
    -- The unrotated slot is set here; how large the offset is belongs to the
    -- settings, which this function knows nothing about.
    pcall(button.SetAttribute, button, "rackSlot", index)

    -- What the button does. For an action bar it is "use this slot"; for the
    -- pet bar "use this pet action", and the numbering differs: slot ten of a
    -- bar and pet action ten are different things with the same number.
    if key == "pet" then
        button.rackPetIndex = index
        pcall(button.SetAttribute, button, "type", "pet")
        pcall(button.SetAttribute, button, "action", index)
    elseif key == "stance" then
        -- A stance button gets no number: it has a spell rather than a slot,
        -- and the repaint names it where it learns the name (Stance.Assign).
        button.rackStanceIndex = index
    else
        pcall(button.SetAttribute, button, "type", "action")
    end

    -- Snippets the button runs ITSELF when the bar says so.
    --
    -- The alternative would be the bar walking its children - and a list of
    -- children cannot be obtained in the secure handler environment (see the
    -- paging snippet below). The bar calls ChildUpdate and each button does
    -- its own part.
    --
    -- The value arrives as "message": that is the engine's own name for it.
    pcall(button.SetAttribute, button, "_childupdate-page", [[
        local slot = self:GetAttribute("rackSlot")
        if not slot then return end

        local page = tonumber(message) or 1
        self:SetAttribute("actionpage", page)
        self:SetAttribute("action", (page - 1) * 12 + slot)

        local header = self:GetParent()
        local pick = header and header:GetAttribute("rackPickTarget")
        if pick then header:RunFor(self, pick) end
    ]])

    pcall(button.SetAttribute, button, "_childupdate-pick", [[
        local header = self:GetParent()
        local pick = header and header:GetAttribute("rackPickTarget")
        if pick then header:RunFor(self, pick) end
    ]])

    -- Click registration follows the game's own ActionButtonUseKeyDown CVar.
    -- Build.Clicks picks one of AnyUp/AnyDown; we do not add a second setting
    -- about the same thing.
    Build.Clicks(button)

    if type(button.RegisterForDrag) == "function" then
        pcall(button.RegisterForDrag, button, "LeftButton", "RightButton")
    end

    Build.Draggable(button)

    -- Flyout opening. Action bars only: a pet slot or a stance list has no
    -- source for a flyout.
    if key ~= "pet" and key ~= "stance" then
        Build.Hatch(button, parent)
    end

    -- Right-click autocast toggling - pet bar only.
    if key == "pet" then ns.Pet.Autocast(button) end

    -- Tooltip. The mode is asked of the bar at the moment the mouse arrives
    -- rather than remembered at creation: the player changes it in the
    -- settings, and a remembered value would hold until the next login.
    if ns.Tip then
        ns.Tip.Hook(button, function()
            return ns.Bars.TipMode(button.rackBar)
        end)
    end

    dressButton(button)

    list[index] = button
    return button
end

--- Create a flyout button.
--
-- === How it differs from a bar button ===
--
-- Not at all in appearance and entirely in substance. It is dressed by the
-- same dressButton on purpose: buttons dropping out of a flyout have to look
-- like bar buttons, or the flyout reads as a foreign window.
--
-- In substance it carries a SPELL, not a slot: no index, no page, no paging.
-- So it gets no "rackSlot" attribute, no snippets and no drag handlers - the
-- game owns the flyout's contents and there is nothing to rearrange.
--
-- These buttons are shown and placed by the secure snippet in Flyout.lua; our
-- part is to create and dress them.
--
-- @param index number position in the pool
-- @param parent table the flyout handler
-- @return table|nil
function Build.Spare(index, parent)
    if inCombat() then return nil end
    if type(CreateFrame) ~= "function" then return nil end
    if type(parent) ~= "table" then return nil end

    local name = "RackFlyoutButton" .. tostring(index)

    -- The same template as a bar button, for the same reason (Build.Button).
    local ok, button = pcall(CreateFrame, "CheckButton", name, parent,
        "ActionButtonTemplate, SecureActionButtonTemplate")

    if not ok or type(button) ~= "table" then
        ok, button = pcall(CreateFrame, "CheckButton", name, parent,
            "SecureActionButtonTemplate")
    end
    if not ok or type(button) ~= "table" then return nil end

    -- The template's own handlers are taken off.
    --
    -- === This is the bug, and it is their comment that names it ===
    --
    -- LibActionButton-1.0 writes, at this exact point:
    --
    --     button:SetScript("OnAttributeChanged", nil)
    --     -- inherited templates bring in a handler here which we
    --     -- don't want, so get rid of it
    --
    -- ActionButtonTemplate carries the game's own action button code with
    -- it. On the game's buttons that code knows the slot it is looking at;
    -- on ours it does not, so it runs, finds nothing, and HIDES the pieces -
    -- the cooldown among them.
    --
    -- OnAttributeChanged is the worst of them, and it is what made this look
    -- like a combat bug. It fires on every attribute change, and the secure
    -- state driver changes attributes constantly in a fight - paging,
    -- stances, vehicles. Out of combat the attributes sit still and the
    -- handler rarely runs, so everything looked right; in a fight it ran
    -- over and over and hid the cooldown as fast as the repaint set it.
    --
    -- The pieces are kept, the behaviour is dropped. Ours is set afterwards.
    for _, script in ipairs({ "OnAttributeChanged", "OnEvent", "OnUpdate",
        "OnShow", "OnHide", "OnLoad" }) do
        pcall(button.SetScript, button, script, nil)
    end

    if type(button.UnregisterAllEvents) == "function" then
        pcall(button.UnregisterAllEvents, button)
    end

    pcall(button.SetAttribute, button, "type", "spell")
    pcall(button.Hide, button)

    Build.Clicks(button)

    -- The method the snippet repaints the button through. The snippet sees
    -- none of our tables or functions - it can only call a METHOD by name,
    -- and this is that name (CallMethod("RackPaint")).
    button.RackPaint = function(self, spell)
        return ns.Flyout.Paint(self, spell)
    end

    if ns.Tip then
        ns.Tip.Hook(button, function() return ns.Bars.TipMode("main") end)
    end

    dressButton(button)
    return button
end

--- Give the engine the opening of flyouts on this button.
--
-- === Why a click wrapper and not an ordinary handler ===
--
-- A flyout is opened in combat, where insecure code may not show a secure
-- button. A wrapper is itself a snippet: the engine runs it, before the click,
-- and no such restriction applies.
--
-- Returning false from the pre-body means "there was no click": otherwise the
-- button would both open the flyout and use what lies in the slot - and what
-- lies there is the flyout itself, which has nothing to use.
--
-- The snippet asks what is in the slot by itself: GetActionInfo exists in the
-- restricted environment. So no attribute carries the flyout id, and there is
-- nothing for such an attribute to drift from.
--
-- @param button table
-- @param header table the bar frame, which is also the handler
-- @return boolean
--- Whether the game's bars are locked right now.
--
-- Locked is not a ban but a MODIFIER REQUIREMENT: with bars locked a spell
-- is picked up with a modifier held, and which one is the player's setting.
-- The caller decides what to do about it - the Lua path asks
-- IsModifiedClick itself, the drag snippet is handed this as an attribute
-- because the restricted environment cannot read a CVar.
--
-- A build with no such setting answers "not locked": refusing to let a
-- player move their spells because a question could not be asked is the
-- worse failure.
--
-- @return boolean
function Build.Locked()
    if type(_G.GetCVarBool) ~= "function" then return false end

    local ok, locked = pcall(_G.GetCVarBool, "lockActionBars")
    if not ok then return false end

    return locked and true or false
end

--- Let the button be dragged IN COMBAT, through the restricted environment.
--
-- === Why the Lua handler cannot do it ===
--
-- PickupAction and PlaceAction are protected: called from addon code in
-- combat they are blocked. So the Lua OnDragStart has to refuse in a fight,
-- and a player cannot rearrange their bars while one is on.
--
-- The restricted environment may do it. A wrapped OnDragStart runs there,
-- and what it RETURNS is the pickup: "action", slot. The engine performs
-- the move itself, so nothing protected is called by us at all.
--
-- LibActionButton-1.0 works this way - it sets its Lua OnDragStart to nil
-- and wraps the script on the header instead - and that is why Bartender4
-- can move spells mid-fight.
--
-- The lock is honoured in the snippet because it must be: with bars locked
-- the game wants a modifier held, and IsModifiedClick is one of the few
-- calls the restricted environment is given.
--
-- @param button any the button
-- @param header any the bar's secure header
-- @return boolean whether the secure drag was installed
function Build.Haul(button, header)
    if type(button) ~= "table" or type(header) ~= "table" then return false end
    if type(header.WrapScript) ~= "function" then return false end

    local ok = pcall(header.WrapScript, header, button, "OnDragStart", [[
        if self:GetAttribute("type") ~= "action" then return end

        if self:GetAttribute("rackLocked")
            and not IsModifiedClick("PICKUPACTION") then
            return false
        end

        return "action", self:GetAttribute("action")
    ]])
    if not ok then return false end

    pcall(header.WrapScript, header, button, "OnReceiveDrag", [[
        if self:GetAttribute("type") ~= "action" then return end
        return "action", self:GetAttribute("action")
    ]])

    -- The Lua handlers go, or both run and the spell is picked up twice.
    pcall(button.SetScript, button, "OnDragStart", nil)
    pcall(button.SetScript, button, "OnReceiveDrag", nil)

    button.rackHauled = true
    return true
end

function Build.Hatch(button, header)
    if type(button) ~= "table" or type(header) ~= "table" then return false end
    if type(header.WrapScript) ~= "function" then return false end
    if type(header.SetFrameRef) ~= "function" then return false end

    local host = ns.Flyout.Handler()
    if host == nil then return false end

    pcall(header.SetFrameRef, header, "rackFlyout", host)

    return pcall(header.WrapScript, header, button, "OnClick", [[
        if self:GetAttribute("type") ~= "action" then return end

        local host = owner:GetFrameRef("rackFlyout")
        if not host then return end

        local kind, id = GetActionInfo(self:GetAttribute("action"))

        if kind == "flyout" then
            host:SetAttribute("rackParent", self)
            host:RunAttribute("RackOpen", id)
            return false
        end

        -- Any other button closes an open flyout. Otherwise it would hang on
        -- screen until the player moved the mouse away.
        host:Hide()
    ]]) and true or false
end

--- Let the button pick up and accept spells with the mouse.
--
-- === Why this is separate and shaped this way ===
--
-- A bar you cannot drop a spell onto is not a bar. The player expects our
-- buttons to behave like the game's: pick up from one, drop on another, shake
-- the spare off onto the ground.
--
-- The work is done by PickupAction and PlaceAction, both protected. Out of
-- combat an addon may call them; in combat it may not, and that is not our
-- limitation - the game forbids rearranging bars mid-fight, and its own
-- buttons cannot be dragged there either.
--
-- The in-combat refusal is therefore silent. Saying "not in combat" here
-- would misattribute the rule and repeat what the player already sees on the
-- game's own buttons.
--
-- === The bar lock ===
--
-- The game can lock bars against accidental dragging (the lockActionBars
-- CVar). A locked button is not picked up - neither the game's nor ours. The
-- game is asked rather than a second setting of our own being kept: two
-- settings about one thing drift at the first edit of either.
--
-- @param button table
--- Whether the button fires on key down or on key up.
--
-- === Why not both at once ===
--
-- Both were registered, on the theory that the engine would sort it out. It
-- did: the button fired TWICE, on down and on up.
--
-- Worse, it broke dragging. Taking a spell off a button means pressing the
-- mouse on it and moving - and the spell was cast at the moment of the press,
-- before any movement. The player saw "the click fires first, and only then
-- do I drag".
--
-- The game has one setting for this (ActionButtonUseKeyDown) covering all its
-- buttons, and that is what is asked. A second one of ours would drift from
-- it at the first edit.
--
-- @param button any the button
-- @return boolean whether it was set
function Build.Clicks(button)
    if type(button) ~= "table" then return false end
    if type(button.RegisterForClicks) ~= "function" then return false end

    -- BOTH edges, exactly as LibActionButton-1.0 registers them:
    --
    --     button:RegisterForClicks("AnyDown", "AnyUp")
    --
    -- Choosing one from the ActionButtonUseKeyDown setting is what we did
    -- before, and it leaves the button deaf whenever the guess is wrong:
    -- the setting is missing on some builds, and a key arriving on the
    -- other edge then matches nothing at all. The player presses and
    -- nothing happens.
    --
    -- Registering both is safe because the secure template decides for
    -- itself which edge casts on - that is its business, not ours - and it
    -- is what every working bar addon does.
    local ok = pcall(button.RegisterForClicks, button, "AnyDown", "AnyUp")
    if ok then return true end

    -- A build that takes only one edge at a time still gets the one its
    -- own setting asks for.
    local down = false
    if type(_G.GetCVarBool) == "function" then
        local okSaid, said = pcall(_G.GetCVarBool, "ActionButtonUseKeyDown")
        if okSaid then down = said and true or false end
    end

    return pcall(button.RegisterForClicks, button,
        down and "AnyDown" or "AnyUp") or false
end

function Build.Draggable(button)
    if type(button) ~= "table" then return end
    if type(button.SetScript) ~= "function" then return end

    --- Whether what lies on the button may be picked up right now.
    --
    -- === Asking "are the bars locked" is not enough ===
    --
    -- Locked bars are not a ban but a MODIFIER REQUIREMENT. That is how the
    -- game works: with bars locked, a spell is picked up with a modifier held,
    -- and which one is the player's setting.
    --
    -- Regression: only "are they locked" was asked, so locked bars meant
    -- "never". They are locked BY DEFAULT on modern builds, so a player who
    -- had touched nothing simply could not take a spell off a bar at all.
    --
    -- Which modifier is wanted is asked of the game through the same call its
    -- own button uses (IsModifiedClick("PICKUPACTION")): the action has a name
    -- of its own, and keeping a second one beside it would drift from the
    -- player's settings.
    local function allowed()
        if not Build.Locked() then return true end

        if type(_G.IsModifiedClick) ~= "function" then return false end

        local okHeld, held = pcall(_G.IsModifiedClick, "PICKUPACTION")
        return okHeld and held and true or false
    end

    --- Pick up or put down what lies on this button.
    --
    -- The kind of button is ALWAYS asked, and not out of caution. A pet button
    -- holds the pet action number in its "action" attribute - one to ten - and
    -- the common path would take it for an action-bar slot: dragging a pet
    -- ability, the player would wipe their own third main-bar button with no
    -- idea why.
    --
    -- Stance buttons are not dragged at all: the game owns that list and there
    -- is nothing in it to rearrange.
    --
    -- @param self table the button
    -- @return boolean whether anything was done
    local function carry(self)
        local kind = ns.Bind.Kind(self)

        if kind == "pet" then
            -- The pet has one call for both picking up and putting down: it
            -- tells a loaded cursor from an empty one itself.
            if type(_G.PickupPetAction) ~= "function" then return false end
            return pcall(_G.PickupPetAction, self.rackPetIndex) and true
        end

        if kind ~= "action" then return false end

        local slot = ns.Paint.Slot(self)
        if slot == nil then return false end

        -- A loaded cursor means "put down", an empty one "pick up". The game
        -- is asked rather than this being inferred from which event arrived:
        -- a drag and a click with a loaded cursor arrive differently and mean
        -- the same thing.
        local holding = false
        if type(_G.GetCursorInfo) == "function" then
            local ok, what = pcall(_G.GetCursorInfo)
            holding = ok and what ~= nil
        end

        if holding then
            if type(_G.PlaceAction) ~= "function" then return false end
            return pcall(_G.PlaceAction, slot) and true
        end

        if type(_G.PickupAction) ~= "function" then return false end
        return pcall(_G.PickupAction, slot) and true
    end

    button:SetScript("OnDragStart", function(self)
        if inCombat() then return end
        if not allowed() then return end

        if carry(self) then
            -- Flag: "this spell was just taken off here".
            --
            -- Exactly one place needs it - the click that follows - and it
            -- lives until then (see the OnClick hook below).
            self.rackTook = true
            ns.Paint.Button(self, ns.Bars.BarSettings(self.rackBar) or {})
        end
    end)

    button:SetScript("OnReceiveDrag", function(self)
        if inCombat() then return end

        -- A drop onto the button is an intent to place, and an earlier pickup
        -- flag has nothing to do with it: taken off one button, dropped on
        -- another.
        self.rackTook = nil

        if carry(self) then
            ns.Paint.Button(self, ns.Bars.BarSettings(self.rackBar) or {})
        end
    end)

    -- A click with a loaded cursor is the same as a drop. The game behaves the
    -- same way: having picked a spell up, players click rather than aim a drop.
    --
    -- Hooked after the click rather than replacing it: the click itself
    -- belongs to the secure template, and replacing it would take casting away
    -- from the button.
    if type(button.HookScript) == "function" then
    -- HookScript on OUR OWN button is allowed: the hooked handler becomes
    -- ours, which it already is. The prohibition concerns other people's
    -- frames, where the reason is taint, and there is no source for it here.
        pcall(button.HookScript, button, "OnClick", function(self)
            -- The button is repainted FIRST, and in combat as well as out of
            -- it. Repainting is not protected work, and this is the moment
            -- the player is looking at the button hardest.
            --
            -- LibActionButton-1.0 does the same at the top of its PostClick,
            -- also without asking about combat. Waiting for the next event
            -- instead means the pressed and checked states arrive a beat
            -- after the press that caused them.
            pcall(ns.Paint.Button, self,
                ns.Bars.BarSettings(self.rackBar) or {})

            -- Everything below is about a spell on the cursor, and moving one
            -- is protected: in combat there is nothing further to do here.
            if inCombat() then return end

            -- The click that ends a drag must NOT put the spell back.
            --
            -- Regression - this is why a spell could not be taken off a bar.
            -- The sequence is: press, move, spell on the cursor; release over
            -- the same button and a click arrives with the cursor loaded. To
            -- this handler a loaded cursor means "place", so it dutifully put
            -- the spell back into the slot it had just come from.
            --
            -- From outside it looked as if the button kept trying to fire
            -- instead of giving the spell up.
            --
            -- The flag is set by the drag start and lives until the first
            -- click: a second click is an intent to place.
            if self.rackTook then
                self.rackTook = nil
                return
            end

            if type(_G.GetCursorInfo) ~= "function" then return end

            local ok, what = pcall(_G.GetCursorInfo)
            if not ok or what == nil then return end

            if carry(self) then
                ns.Paint.Button(self, ns.Bars.BarSettings(self.rackBar) or {})
            end
        end)
    end
end

--============================================================================
-- Layout
--============================================================================

--- Apply the label settings to a bar's buttons.
--
-- === Why the font is set here and not at button creation ===
--
-- A button has three labels: key, macro name, count. Created from the game's
-- font objects, they come with the game's font - visible immediately: a dark
-- flat bar with labels from the game's interface looks assembled from two
-- different addons.
--
-- Size is a setting: on a 24-pixel button a size-12 label takes half the
-- button, on a 50-pixel one it cannot be seen. So the font has to be set on
-- every apply rather than once at creation.
--
-- The outline is a separate tick because the answer depends on the screen: on
-- a dark bar the labels read without it, over a bright icon they do not.
--
-- The FACE, unlike the size, is one for every bar and arrives from the shared
-- settings: a player who reads labels in a given face reads them in that face
-- everywhere (Bars.lua, the "font" field).
--
-- @param key string bar key
-- @param settings table bar settings
-- @param common table|nil shared settings
-- @return number how many labels were re-dressed
function Build.Lettering(key, settings, common)
    local list = buttons[key]
    if type(list) ~= "table" or type(settings) ~= "table" then return 0 end

    local size = ns.Probe.Numeric(settings.textSize) or 12
    local outline = settings.textOutline ~= false and "OUTLINE" or ""

    local face = type(common) == "table" and common.font or nil

    local many = 0

    for i = 1, #list do
        local button = list[i]
        if type(button) == "table" then
            -- The count is the one label set SMALLER than the rest: charges
            -- and stack sizes are read, not hunted for, and a large number
            -- argues with the icon.
            local parts = {
                { button.rackHotkey, size },
                { button.rackMacro, size - 1 },
                { button.rackCount, size },
            }

            for at = 1, #parts do
                local text, own = parts[at][1], parts[at][2]
                if type(text) == "table"
                    and type(text.SetFont) == "function" then
                    if pcall(text.SetFont, text,
                        ns.Media.FontArgs(own, outline, face)) then
                        many = many + 1
                    end
                end
            end
        end
    end

    return many
end

--- Lay out a bar's buttons and set the frame size.
--
-- @param key string bar key
-- @param settings table bar settings
-- @return number how many buttons are shown
function Build.Layout(key, settings)
    local frame = frames[key]
    local list = buttons[key]
    if type(frame) ~= "table" or type(list) ~= "table" then return 0 end
    if type(settings) ~= "table" then return 0 end
    if inCombat() then return 0 end

    local Layout = ns.Layout

    local count = math.floor(Layout.Clamp(settings.count, 1, 12, 12))
    local perRow = math.floor(Layout.Clamp(settings.perRow, 1, 12, 12))
    local padding = Layout.Clamp(settings.padding, 0, 32, 6)
    local size = Layout.Clamp(settings.size, Layout.SIZE_MIN,
        Layout.SIZE_MAX, 36)

    local shown = 0

    for i = 1, 12 do
        local button = list[i]
        if button then
            if i <= count then
                local x, y = Layout.Position(i, perRow, padding, size,
                    settings.hgrowth, settings.vgrowth)
                -- The corner the grid counts from follows the growth
                -- direction: counting leftward growth from the top-left corner
                -- would push buttons past the edge of their own bar frame, and
                -- the mover would be left holding empty space.
                local corner = (settings.vgrowth == "UP" and "BOTTOM" or "TOP")
                    .. (settings.hgrowth == "LEFT" and "RIGHT" or "LEFT")

                pcall(function()
                    button:ClearAllPoints()
                    button:SetSize(size, size)
                    button:SetPoint(corner, frame, corner, x, y)
                    button:Show()
                end)
                shown = shown + 1
            else
                pcall(button.Hide, button)
            end
        end
    end

    local width, height = Layout.Extent(count, perRow, padding, size)
    pcall(frame.SetSize, frame, width, height)

    local scale = Layout.Clamp(settings.scale, 0.5, 2, 1)
    pcall(frame.SetScale, frame, scale)

    -- Alpha goes through Layout.FadeAlpha rather than a plain number: a bar
    -- set to fade must already be faded right after the settings are applied,
    -- not from the moment the mouse first leaves it.
    pcall(frame.SetAlpha, frame, Layout.FadeAlpha(settings, false))

    return shown
end

--============================================================================
-- Slots and pages
--============================================================================

--- Tell a bar's buttons their action slots.
--
-- For a bar without paging this is done once and for good: its slots do not
-- change.
--
-- With paging on, the slot depends on the page and the engine owns the page.
-- Such a bar gets per-page attributes instead - "actionpage" plus the
-- _childupdate-page snippet the engine runs on a state change. Computing it
-- in Lua is impossible: pages change in combat, where we have no reach.
--
-- @param key string bar key
-- @param settings table bar settings
-- @return number how many buttons were given a slot
function Build.Assign(key, settings)
    local list = buttons[key]
    if type(list) ~= "table" or type(settings) ~= "table" then return 0 end
    if inCombat() then return 0 end

    -- Pet actions are assigned at creation and do not change: the pet bar has
    -- no pages and nothing to rearrange.
    if key == "pet" or key == "stance" then return 0 end

    local given = 0

    -- Paging on: the snippet assigns the slot as soon as the engine reports a
    -- page. What is set here is the resting page.
    local paging = type(settings.state) == "table"
        and settings.state.enabled == true

    local offset = settings.buttonOffset

    for i = 1, 12 do
        local button = list[i]
        if button then
            -- Which slot of the page this button shows. The rotated number is
            -- stored as an attribute: the paging snippet computes from it, and
            -- that is the only way the offset survives into combat.
            local slot = ns.Slots.Shift(i, offset) or i
            pcall(button.SetAttribute, button, "rackSlot", slot)

            if paging then
                -- The slot is derived from the page number by the same formula
                -- as ns.Slots.Of: (page - 1) * 12 + slot of page.
                local home = ns.Slots.FIRST_PAGE[key] or 1
                pcall(button.SetAttribute, button, "actionpage", home)
                pcall(button.SetAttribute, button, "action",
                    ns.Slots.Of(home, slot))
            else
                local where = ns.Slots.ForBar(key, i, 1, offset)
                if where then
                    pcall(button.SetAttribute, button, "action", where)
                end
            end
            given = given + 1
        end
    end

    return given
end

--============================================================================
-- Cast modifiers - handed to the engine
--============================================================================

-- Three settings the engine handles ITSELF. No snippet and no code of ours in
-- the click: a button on the secure template understands these attributes
-- from birth, and all that is left to us is to set them.
--
-- === Why there is no modifier choice here ===
--
-- Which modifier means "on myself" is not the addon's decision: it is the
-- game's own setting (SELFCAST and FOCUSCAST in its bindings). Adding ours
-- would be a second setting about the same thing, drifting from the one the
-- player already set - and then explaining why Alt works on the bar and not
-- in the spellbook.
--
-- Bartender4 keeps the choice and writes it into the game's setting anyway:
-- one more place for them to disagree.
--
-- === Why they are global and not per bar ===
--
-- Self-casting is a property of the player's hand, not of a bar. Someone who
-- casts on themselves with Alt held does it on every bar; a bar where Alt
-- behaves differently is a source of mistakes in combat, not a setting.

--- The cast-modifier attributes implied by the shared settings.
--
-- Pure, hence verifiable outside the client: the rule for choosing attributes
-- exists, while setting an attribute needs the game.
--
-- A disabled setting yields NOTHING rather than false. To the engine an
-- attribute set to false is still set, and it would keep checking the
-- modifier; only nil clears it. So the table holds either a value or nothing,
-- and every key is listed here in full: an attribute that appeared from
-- rubbish in the saved file would stay on the button until the next login.
--
-- @param settings table|nil shared settings
-- @return table attribute name -> value
function Build.CastRules(settings)
    local out = {}
    if type(settings) ~= "table" then return out end

    if settings.selfCast == true then out.checkselfcast = true end
    if settings.focusCast == true then out.checkfocuscast = true end

    -- Right-click self-cast. "*unit2" means "for mouse button two take this
    -- unit", and "player" in it means oneself. The asterisk asks the engine to
    -- apply it to every kind of press.
    if settings.rightSelfCast == true then out["*unit2"] = "player" end

    return out
end

--- Set the cast-modifier attributes on all of a bar's buttons.
--
-- Setting attributes is protected, so this does not run in combat. No loss:
-- the attributes are set in advance and in combat the engine reads what it
-- has already been told.
--
-- Attributes are CLEARED when a setting is off, which is why the whole set is
-- enumerated rather than only what is enabled. Otherwise a disabled setting
-- would keep working until the next login.
--
-- @param key string bar key
-- @param settings table|nil shared settings
-- @return number how many buttons got the attributes
function Build.Casting(key, settings)
    local list = buttons[key]
    if type(list) ~= "table" then return 0 end
    if inCombat() then return 0 end

    -- Pet and stance buttons have no targets of their own: pet actions apply
    -- to the pet and a form applies to the player, so a target modifier means
    -- nothing to them.
    if key == "pet" or key == "stance" then return 0 end

    local rules = Build.CastRules(settings)
    local given = 0

    for i = 1, #list do
        local button = list[i]
        if button then
            for _, name in ipairs({ "checkselfcast", "checkfocuscast", "*unit2" }) do
                pcall(button.SetAttribute, button, name, rules[name])
            end
            given = given + 1
        end
    end

    return given
end

--============================================================================
-- Disabling a bar
--============================================================================

--- Take away everything the engine decides on a bar's behalf.
--
-- === Why hiding it is not enough ===
--
-- A single Hide stood here for a long time and fell short in two places.
--
-- FIRST: the "visibility" state is special. Handing the engine a condition
-- string also hands it the right to SHOW the frame: a condition that says
-- "show" is acted on by the engine, so a frame we hid surfaced again at the
-- first exit from combat. Only removing the state driver stops it.
--
-- SECOND, and worse: key override bindings. The player's keys are routed to
-- our buttons by an override owned by the bar frame, and it does NOT depend on
-- whether the frame is visible. A player switching the bar off got the game's
-- own bars back and pressed into the void: the key still went to a hidden
-- button.
--
-- The setting's own hint promises the opposite ("nothing is taken away: switch
-- it off and the game's bars come back exactly as they were"), so the promise
-- was being broken silently.
--
-- @param key string bar key
-- @return boolean whether anything was taken away
function Build.Silence(key)
    local frame = frames[key]
    if type(frame) ~= "table" then return false end
    if inCombat() then return false end

    -- Key overrides first. Otherwise there is a moment between clearing the
    -- drivers and clearing the keys in which a key presses something hidden.
    if type(_G.ClearOverrideBindings) == "function" then
        pcall(_G.ClearOverrideBindings, frame)
    end

    if type(UnregisterStateDriver) == "function" then
        for _, state in ipairs({ "visibility", "page",
                                 "target-help", "target-harm", "target-all" }) do
            pcall(UnregisterStateDriver, frame, state)
        end
    end

    pcall(frame.Hide, frame)
    return true
end

--============================================================================
-- Targeting - handed to the engine
--============================================================================

-- Mouseover targeting and auto-assist.
--
-- === Why this is harder than the other rules ===
--
-- Paging and visibility are one rule per bar. Here there are THREE, and which
-- one suits a button depends on what lies on it: a heal wants a friend under
-- the mouse, an attack wants an enemy (Target.lua).
--
-- That cannot be known in advance: the player changes slots whenever they
-- like, combat included. So the question is asked INSIDE the secure handler,
-- at the moment the engine is recomputing the button anyway.
--
-- === How it is assembled ===
--
-- The bar gets the three rules as three states. Each, on change, hands its new
-- value to all its buttons (ChildUpdate), and the button stores it as an
-- attribute - but sets as its unit only the one of the three that suits its
-- spell.
--
-- Which one suits is decided by one shared snippet that the bar holds as an
-- attribute and runs for the button (RunFor). Shared because there are twelve
-- buttons and one rule.

-- The snippet that decides the kind of spell on a button.
--
-- Runs INSIDE the restricted environment: no insecure code, no calls out, and
-- no non-ASCII - everything inside the string goes to the engine.
--
-- The slot number is taken from the button's own attribute rather than from an
-- argument. Bartender4 passes it as an argument - but it also calls this
-- differently: its buttons carry secure code of their own that invokes an
-- "OnStateChanged" attribute on a state change. A button on the BARE template
-- has no such call, so that attribute would never be invoked and targeting
-- would never work, silently.
--
-- So we invoke it ourselves, from two places:
--
--   * from the paging snippet, right after a button is given a new slot: on
--     another page the slot holds another spell;
--   * from the rule handout: the rule changed, so choose among the three again.
--
-- IsSpellHelpful and IsSpellHarmful are missing on some clients. Where they
-- are, the kind counts as "any" and the rule works without telling friend
-- from foe: less precise, but without the spellbook walk Bartender4 uses.
local PICK_TARGET = [[
    self:SetAttribute("rackKind", "all")
    self:SetAttribute("unit", self:GetAttribute("rackAll"))

    local kind, action = GetActionInfo(self:GetAttribute("action"))

    if kind == "spell" and action and action > 0
        and IsSpellHelpful and IsSpellHarmful then
        local helps = IsSpellHelpful(action) and true or false
        local harms = IsSpellHarmful(action) and true or false

        if helps ~= harms then
            if helps then
                self:SetAttribute("rackKind", "help")
                self:SetAttribute("unit", self:GetAttribute("rackHelp"))
            else
                self:SetAttribute("rackKind", "harm")
                self:SetAttribute("unit", self:GetAttribute("rackHarm"))
            end
        end
    end
]]

-- What a button does when one of the three rules sends a new value.
--
-- It always stores the value, then chooses again which of the three suits -
-- and that second step is required. Setting the incoming value as the unit
-- only when it matches the button's kind would not be enough: the kind may
-- never have been computed (a button on the bare template reports no state
-- changes of its own), and the first rule would then disagree with the spell.
--
-- The recompute is asked of the bar: the snippet that decides the kind lives
-- on it as an attribute, and only the bar can run it for a button.
local function childUpdate(keep)
    return ([[
        self:SetAttribute("%s", message)

        local header = self:GetParent()
        local pick = header and header:GetAttribute("rackPickTarget")
        if pick then header:RunFor(self, pick) end
    ]]):format(keep)
end

-- What the bar does when a rule changes: hands it to the buttons.
--
-- Called on SELF, not on "control" as in Bartender4, for the same reason the
-- paging snippet is: "control" does not appear in the list of names of the
-- restricted environment, while a state handler is given "self", "stateid"
-- and "newstate" by name. A name absent from the environment is silently nil,
-- and ChildUpdate on nil drops the whole snippet.
--
-- Regression: "control" stood here, having survived the paging fix - that fix
-- touched paging, and this was another place with the same bug. Symptom:
-- mouseover targeting and auto-assist did not work, with nothing in the log.
local function stateUpdate(name)
    return ([[
        local said = (newstate ~= "nil") and newstate or nil
        self:ChildUpdate("%s", said)
    ]]):format(name)
end

--- Hand the engine the targeting rules.
--
-- Three rules per bar and one shared snippet for all its buttons. A disabled
-- rule is CLEARED rather than left: a rule outliving its setting would keep
-- stealing the spell to the mouse, with nothing to explain it by.
--
-- @param key string bar key
-- @param own table bar settings
-- @param common table|nil shared settings
-- @return boolean whether at least one rule was handed over
function Build.Targeting(key, own, common)
    local frame = frames[key]
    if type(frame) ~= "table" or type(own) ~= "table" then return false end
    if inCombat() then return false end
    if type(RegisterStateDriver) ~= "function" then return false end

    -- Pet and stance buttons have no targets of their own: an ability applies
    -- to the pet, a form to the player.
    if key == "pet" or key == "stance" then return false end

    local list = buttons[key]
    local any = false

    -- The shared snippet is stored on the bar and run for a button: that way
    -- one copy serves twelve.
    pcall(frame.SetAttribute, frame, "rackPickTarget", PICK_TARGET)

    local rules = {
        { kind = "help", state = "target-help", keep = "rackHelp" },
        { kind = "harm", state = "target-harm", keep = "rackHarm" },
        { kind = "all",  state = "target-all",  keep = "rackAll"  },
    }

    for i = 1, #rules do
        local rule = rules[i]
        local said = ns.Target.Driver(rule.kind, own, common)

        pcall(frame.SetAttribute, frame, "_onstate-" .. rule.state,
            stateUpdate(rule.state))

        if said then
            pcall(RegisterStateDriver, frame, rule.state, said)
            any = true
        else
            if type(UnregisterStateDriver) == "function" then
                pcall(UnregisterStateDriver, frame, rule.state)
            end
            -- A cleared rule has to blank what was already handed out, or the
            -- buttons keep a unit from the previous setting.
            pcall(frame.SetAttribute, frame, "state-" .. rule.state, "nil")
        end
    end

    if type(list) == "table" then
        for i = 1, #list do
            local button = list[i]
            if button then
                for j = 1, #rules do
                    local rule = rules[j]
                    pcall(button.SetAttribute, button,
                        "_childupdate-" .. rule.state,
                        childUpdate(rule.keep))
                end
            end
        end
    end

    -- First recompute. Needed because both ordinary triggers may never fire:
    -- the paging snippet does not run on a bar without paging, and the rule
    -- handout does not run on a bar whose rule has not changed since the last
    -- login. Without this pass a button would be left with no kind, and the
    -- first mouseover press would go to the wrong unit.
    --
    -- Execute runs the snippet on the bar itself: insecure code cannot call
    -- RunFor, the bar can.
    if any then
        pcall(frame.Execute, frame, [[
            self:ChildUpdate("pick", 1)
        ]])
    end

    return any
end

--============================================================================
-- Page and visibility - handed to the engine
--============================================================================

--- Hand the engine the paging and visibility rules.
--
-- Both strings go to the secure state handler and are evaluated by it,
-- combat included. Our code takes no part in the decision afterwards.
--
-- @param key string bar key
-- @param settings table bar settings
-- @return boolean whether at least one rule was handed over
function Build.Drivers(key, settings)
    local frame = frames[key]
    if type(frame) ~= "table" or type(settings) ~= "table" then return false end
    if inCombat() then return false end
    if type(RegisterStateDriver) ~= "function" then return false end

    local any = false

    -- Paging. The snippet writes the page number onto the bar itself and the
    -- buttons read it from there: the game does the same, and it survives combat.
    local page = ns.Paging.PageDriver(settings.state,
        ns.Slots.FIRST_PAGE[key] or 1)
    if page then
        -- The snippet COMPUTES the slot rather than only storing the page, and
        -- that is not excess. A button on the secure template knows one thing,
        -- its slot number; "page" means nothing to it, so a bar whose page was
        -- changed would keep showing the old spells. The formula is the one in
        -- ns.Slots.Of: (page - 1) * 12 + button index.
        --
        -- Possess-style control has no page of its own: the game reports the
        -- number through separate calls, and there are four of them - vehicle,
        -- override bar, temp shapeshift and the classic bonus bar. They are
        -- asked inside the snippet rather than here, because insecure code has
        -- no reach into combat, and that is exactly where a player ends up in
        -- someone else's body.
        --
        -- === Why "nothing matched" means DO NOT CHANGE the page ===
        --
        -- This used to fall back to page 12, as Bartender4 does. Page 12 exists
        -- on modern clients; in classic there are TEN pages, and 12 means slots
        -- 133-144 - that is, nothing.
        --
        -- Regression: that cost a player their bars. The "[shapeshift]"
        -- condition is true in classic for anyone standing in a form, this
        -- client has no possess calls at all, and the bar went to an empty
        -- page. On screen it looks like bars that vanished, and nothing
        -- explains it: the buttons are not hidden, they are EMPTY, and empty
        -- buttons are hidden by a setting.
        --
        -- So: no match, no change - the bar stays on the page it was on and
        -- the player keeps seeing their spells.
        --
        -- === Why the BUTTON computes the slot, not the bar ===
        --
        -- The bar did it first: it walked its children and wrote each one a
        -- slot number. That DID NOT WORK, and the player's error log showed
        -- why - "attempt to call a nil value" on line 21 of the snippet:
        --
        --     for i = 1, self:GetNumChildren() do
        --
        -- A secure handler has NO GetNumChildren. The snippet environment is
        -- not the game's Lua: it has a far narrower set of methods and no way
        -- to obtain a list of children. This cannot be checked outside the
        -- game at all, and inside it fails quietly: the error goes to a log the
        -- player does not read, the bar stays on its page, and it looks like
        -- "paging does not work".
        --
        -- The way it is actually done is the same for everyone: the bar calls
        -- ChildUpdate and each button runs its own "_childupdate-page" snippet
        -- (set in Build.Button). Bartender4 and its button library do the same.
        --
        -- It is called on SELF, not on "control" as in Bartender4. The
        -- difference is not pedantry: "control" does not appear in the list of
        -- names of the restricted environment - only "self" and "owner" - while
        -- a state handler is given "self", "stateid" and "newstate" by name. A
        -- name absent from the environment is silently nil, and ChildUpdate on
        -- nil would drop the snippet exactly as GetNumChildren already did.
        --
        -- Explanations stay outside the string: everything inside it is code
        -- bound for the engine.
        pcall(frame.SetAttribute, frame, "_onstate-page", [[
            if newstate == "possess" then
                if HasVehicleActionBar and HasVehicleActionBar() then
                    newstate = GetVehicleBarIndex and GetVehicleBarIndex()
                elseif HasOverrideActionBar and HasOverrideActionBar() then
                    newstate = GetOverrideBarIndex and GetOverrideBarIndex()
                elseif HasTempShapeshiftActionBar
                    and HasTempShapeshiftActionBar() then
                    newstate = GetTempShapeshiftBarIndex
                        and GetTempShapeshiftBarIndex()
                elseif HasBonusActionBar and HasBonusActionBar() then
                    newstate = GetBonusBarIndex and GetBonusBarIndex()
                else
                    newstate = nil
                end

                -- Nothing answered - page eleven.
                --
                -- Not twelve as in Bartender4: possess slots are 121-132, which
                -- is page ELEVEN, while twelve is 133-144, absent from classic
                -- entirely (docs/wow/action-slots.md). A bar sent there is
                -- empty, and that already cost a player every bar at once.
                if not newstate then newstate = 11 end
            end

            local page = tonumber(newstate) or 1
            self:SetAttribute("actionpage", page)

            self:ChildUpdate("page", page)
        ]])
        pcall(RegisterStateDriver, frame, "page", page)
        any = true
    elseif type(UnregisterStateDriver) == "function" then
        pcall(UnregisterStateDriver, frame, "page")
    end

    -- Visibility. The string always exists - a bar with no rules at all is
    -- always visible and hides only in a pet battle - so the driver never has
    -- to be removed here.
    pcall(RegisterStateDriver, frame, "visibility",
        ns.Paging.HideDriver(settings.visibility))
    any = true

    return any
end