Core.lua

-- Manners -- core: the addon object, secret-safe access, failure handling,
-- defaults and their repair, the capability probe, which buff for which
-- person, unit inspection, names, and the lifecycle with its events.
--
-- Blizzard will not let an addon cast a spell on its own: CastSpellByName and
-- friends are protected and only run from a hardware event. So this addon does
-- every part of the job except the keypress -- it decides who deserves a buff
-- and parks that decision on a secure button. Prompt.lua owns that button;
-- this file and the seven after it in Manners.toc work out what goes on it:
--
--   Range.lua      how near a passer-by has to be
--   Speech.lua     the phrase sets and the line said with a click
--   Queue.lua      debts, refusals, the never-offer list, friends, BuildQueue
--   Requests.lua   people who ask for a buff in chat
--   Favours.lua    noticing that somebody buffed you
--   Clicks.lua     what became of a press, the global cooldown, the macro
--   Commands.lua   first run, test console, snooze, sharing, slash commands
--
-- A local that one of them needs from another is put on ns where it is
-- defined. A file that loads later copies it into a local of its own at load;
-- one that loads earlier (this one, for the lifecycle) reads it off ns inside
-- the function that needs it, since at load it does not exist yet. Where a
-- comment in another file says "Core", it means this file and those seven.

-- The file's arguments are the addon's folder name and its namespace table.
local ns = select(2, ...)
-- Player-facing text, in the client's language: see Locales/Init.lua.
local L = ns.L

local addon = LibStub("AceAddon-3.0"):NewAddon((...), "AceEvent-3.0", "AceConsole-3.0", "AceTimer-3.0")
ns.addon = addon

local MANA = (Enum and Enum.PowerType and Enum.PowerType.Mana) or 0
ns.MANA = MANA

-- The label for Bindings.xml's entry under Options > Keybindings (this client's
-- game menu has no Key Bindings entry). A CLICK binding's name is not a Lua
-- identifier, so the label is set through _G.
_G["BINDING_NAME_CLICK MannersPrompt:LeftButton"] = L["Buff the prompted player"]

---------------------------------------------------------------------------
-- secret-safe access
---------------------------------------------------------------------------

local issecretvalue = _G.issecretvalue
local InCombatLockdown = _G.InCombatLockdown
local GetTime = _G.GetTime

-- Anything the API hands back may be a secret value. Secrets throw on
-- comparison and arithmetic, so everything we branch on passes through here
-- and becomes nil when we are not allowed to look at it.
local function plain(v)
	if issecretvalue and issecretvalue(v) then return nil end
	return v
end
ns.plain = plain

local function safecall(fn, ...)
	if type(fn) ~= "function" then return nil end
	local ok, a, b, c = pcall(fn, ...)
	if not ok then return nil end
	return plain(a), plain(b), plain(c)
end
ns.safecall = safecall

-- One token swapped for one piece of text, with the text never read as a
-- pattern. A string replacement is a gsub template in which "%" is an escape,
-- and the reason lines and phrases are typed by the player ("10% left"); a
-- function replacement is returned verbatim. Shared here so Core and Prompt
-- cannot disagree. The parentheses drop gsub's second return, the match count.
function ns.Swap(text, token, value)
	return ((text or ""):gsub(token, function() return value or "" end))
end

---------------------------------------------------------------------------
-- failure handling
--
-- Script errors are invisible unless the player turned them on, and a repeating
-- timer whose function throws simply stops. Anything that can fail goes through
-- here so the failure is named instead.
---------------------------------------------------------------------------

-- The last thirty failures (Guard wraps the tick, so one can repeat 2.5 times a
-- second), the count of all of them ever, and which labels have been announced.
ns.errors = {}
ns.errorCount = 0
ns.shouted = {}

function ns.Guard(label, fn, ...)
	local ok, err = pcall(fn, ...)
	if ok then return true end

	-- This function is the thing that stops a failure being silent, so it must
	-- never be the thing that throws.
	label = tostring(label)
	err = tostring(err)
	ns.errorCount = (ns.errorCount or 0) + 1
	ns.errors[#ns.errors + 1] = { at = date("%H:%M:%S"), where = label, err = err }
	while #ns.errors > 30 do table.remove(ns.errors, 1) end

	if not ns.shouted[label] then
		ns.shouted[label] = true
		if ns.addon and ns.addon.Print then
			-- The label is the code's own name for the handler and the command
			-- is typed as it stands, so neither is the translator's to change.
			ns.addon:Print(L["|cffff4040something broke in %s|r -- %s |cff808080(%s for the rest)|r"]
				:format(label, err, "/manners errors"))
		end
		-- Repaint Diagnostics once per new failure, but not for a failure of
		-- the repaint itself, which would only fail again.
		if ns.RepaintOptions and label ~= "options repaint" and label ~= "broker text" then
			ns.RepaintOptions()
		end
	end
	return false
end

---------------------------------------------------------------------------
-- telling the settings UI that something changed under it
--
-- AceConfig reads a control's value, name and `hidden` only while drawing, and
-- the broker text is assigned once, so anything that changes a setting outside
-- its own control (slash commands, the minimap right-click, a fight starting
-- or ending) calls this. Both halves are optional and guarded: Options.lua may
-- not have loaded, and a failed repaint must not take down the caller.
---------------------------------------------------------------------------

function ns.RepaintOptions()
	if ns.RefreshOptionsDisplay then
		ns.Guard("options repaint", ns.RefreshOptionsDisplay)
	end
	if ns.RefreshBrokerText then
		ns.Guard("broker text", ns.RefreshBrokerText)
	end
end

---------------------------------------------------------------------------
-- defaults
---------------------------------------------------------------------------

-- LibSharedMedia ships only "None", so Prompt.lua registers a sound of our own.
-- A file id rather than a path, because Register rejects paths under Sound\.
ns.SOUND_KEY = "Manners alert"
ns.SOUND_FILE = 567458

local defaults = {
	profile = {
		enabled = true,
		verbose = true, -- "X buffed you", and why a cast failed
		debugClicks = false, -- raw attribute dump on every click; on via /manners clicks

		buff = {
			choice = "auto",
			-- The class's spells switched off, as a sparse set (absent = on).
			-- Keys are class-unique, so a shared profile cannot cross classes.
			skip = {},
		},

		sources = {
			owed = true, -- people who buffed us
			group = true, -- party/raid missing it
			strangers = true, -- nearby non-group players
			owedClassBuffsOnly = true, -- ignore stray HoTs and procs
			-- People who ask for your buff in chat. Off, because reading chat is
			-- guesswork, so the player should choose it.
			asked = false,
		},

		-- The order of the queue, not who is on it.
		priority = {
			target = true, -- a deliberate target outranks a favour owed
			-- Friends and guildmates ahead of the rest of their kind. On,
			-- because it only reorders people who were offered anyway.
			friends = true,
		},

		-- People never to offer anything to, as a set of filed names. Somebody
		-- on it who buffs you is still offered the favour back (STATUS.md).
		never = {},

		filters = {
			relevantOnly = true, -- skip people the buff does nothing for
			requireInRange = true,
			-- How near a passer-by has to be: cast | near | beside. Not "cast",
			-- because thirty yards of a city square is twenty-odd nameplates.
			proximity = "near",
			-- Passers-by only where the game calls you resting. Off, because
			-- it takes away offers somebody gets today.
			restingOnly = false,
			reachableOnly = true, -- hide people we cannot actually reach
			restoreTarget = true, -- hand your target back after buffing
			whenBuffed = "skip", -- skip | refresh | always
			refreshUnder = 5, -- minutes left before a top-up is offered
			minLevel = 1,
			-- Off, because a press on a mount dismounts you, which somebody
			-- buffing from the saddle may want. Dead, taxi and vehicle need no
			-- switch: nothing can be cast there, so BuildQueue offers nobody.
			hideMounted = false,
		},

		timing = {
			reciprocateWindow = 120,
			retryCooldown = 12,
			scanInterval = 0.4,
			graceSeconds = 45,
			-- Whether a debt survives a reload or disconnect.
			keepDebts = true,
		},

		prompt = {
			locked = true,
			-- Just above the action bars rather than over the play area, where
			-- it would swallow clicks. The bottom edge keeps that distance at
			-- any resolution, which a CENTER offset does not.
			point = "BOTTOM",
			relPoint = "BOTTOM",
			x = 0,
			y = 300,
			width = 220,
			height = 44,
			scale = 1,
			alpha = 1,
			-- Only suppresses the click-outcome flash in a fight: Hide() on a
			-- protected frame is refused in combat. The key keeps its old name
			-- because renaming it would silently reset everyone's setting.
			hideInCombat = false,

			style = "glass",
			accentByReason = true,
			-- standard | colourblind: which four reason colours (Prompt.lua).
			reasonPalette = "standard",
			accentMode = "icon", -- icon | stripe | both | off
			flashStyle = "pulse", -- pulse | once | off
			-- /thank somebody who buffs you (Favours.lua). Off: an emote is
			-- seen by everybody nearby, so the player chooses to make one.
			thankEmote = false,
			-- full | calm: calm is the prompt without the animations.
			effects = "full",
			-- The global cooldown swept over the spell icon.
			showCooldown = true,

			showIcon = true,
			iconSize = 30,
			roundIcon = false,
			showCount = true,
			showQueue = false,
			queueRows = 3,

			font = "Friz Quadrata TT",
			fontSize = 13,
			fontColor = { 1, 1, 1, 1 },
			bgColor = { 0.04, 0.04, 0.06, 0.88 },
			accentColor = { 0.45, 0.4, 0.9, 1 },

			format = "{name}",
			showSub = true,
			-- Short to fit the 220px default width. They start in the player's
			-- language; AceDB stores a line only once somebody types their own.
			-- Each reason has its own words, so colour is never the only cue.
			reasonTarget = L["your target"],
			reasonOwed = L["buffed you"],
			reasonGroup = L["in your group"],
			reasonNearby = L["needs {buff}"],
			reasonAsked = L["asked for it"],
			-- A top-up gets its own line rather than qualifying the player's
			-- text. {time} is what their current aura has left.
			reasonRefresh = L["expires in {time}"],
			reasonUnknown = L["unverified"],
			classColor = true,
		},

		speech = {
			enabled = false,
			channel = "SAY",
			onlyWhenReturning = true,
			-- Filled in at load from the Roleplay set.
			phrases = "",
		},

		-- owedOnly, to match the flash, which only pulses for a favour owed.
		sound = { enabled = false, file = ns.SOUND_KEY, owedOnly = true },
		minimap = { hide = false },
	},
}
ns.defaults = defaults

-- Whether the prompt's first line says anything at all; shared by the repair at
-- load and the box's setter so they agree on what an empty line is.
function ns.UsableFormat(text)
	return type(text) == "string" and text:find("%S") ~= nil
end

---------------------------------------------------------------------------
-- capability probe
---------------------------------------------------------------------------

local caps = { buffs = {} }
ns.caps = caps

local playerClass
-- For the files that load after this one, which cannot see the local, and
-- read it when they run: the probe sets it again each time it runs.
function ns.PlayerClass() return playerClass end

-- The client's own name for a spell id, or nil when this client does not have
-- the id. Both generations of the call are tried.
local function SpellNameFor(id)
	return safecall(C_Spell and C_Spell.GetSpellName, id)
		or safecall(_G.GetSpellInfo, id)
end
ns.SpellNameFor = SpellNameFor

-- Whether UnitName's second return is a surname here rather than a realm. Reads
-- ns.Flavour, settled at load, because callers can run before the first probe;
-- caps.unitNameIsSurname is set from this so the two cannot disagree.
local function SurnameClient()
	return (ns.Flavour and ns.Flavour.flavour) == "camelot"
end

-- The probe's helpers, in a block of their own for the main chunk's 200 locals.
do
	local function ProbeBuff(buff)
		local info = { key = buff.key, buff = buff }

		for _, id in ipairs(buff.ranks) do
			if safecall(_G.IsSpellKnown, id) == true or safecall(_G.IsPlayerSpell, id) == true then
				info.known = true
				info.topRank = info.topRank or id
			end
		end
		for _, id in ipairs(buff.group or {}) do
			if safecall(_G.IsSpellKnown, id) == true or safecall(_G.IsPlayerSpell, id) == true then
				info.knownGroup = true
			end
		end

		-- The name resolves whether or not we know the rank, and every rank shares
		-- it, so the macro can cast by name and let the game pick the best one.
		info.name = SpellNameFor(buff.ranks[1])
		info.icon = safecall(C_Spell and C_Spell.GetSpellTexture, buff.ranks[1])

		-- Ids this client has never heard of. A wrong id has no symptom but silence,
		-- so the mismatch is named in /manners debug and on the Diagnostics page.
		-- Every aura id, since a dead group id only breaks the "already has it"
		-- check. A diagnostic line rather than a popup, because a client still
		-- loading spell data answers nil for everything (the probe re-runs on
		-- SPELLS_CHANGED).
		info.unresolved = {}
		for _, id in ipairs(buff.auraIds) do
			if not SpellNameFor(id) then
				info.unresolved[#info.unresolved + 1] = id
			end
		end

		-- Secrecy is decided per spell. Long-duration class buffs are the most
		-- likely to stay readable, which is what the "who is missing it" feature
		-- rests on, so record every id rather than sampling one.
		info.secrecy = {}
		local readable = 0
		for _, id in ipairs(buff.auraIds) do
			local secret
			if C_Secrets and type(C_Secrets.ShouldSpellAuraBeSecret) == "function" then
				secret = safecall(C_Secrets.ShouldSpellAuraBeSecret, id)
			end
			if secret == nil and C_Secrets and type(C_Secrets.GetSpellAuraSecrecy) == "function" then
				local level = safecall(C_Secrets.GetSpellAuraSecrecy, id)
				if level ~= nil and Enum and Enum.SecrecyLevel then
					secret = (level ~= Enum.SecrecyLevel.NeverSecret)
				end
			end
			info.secrecy[id] = secret
			if secret == false then readable = readable + 1 end
		end
		info.readable = caps.getUnitAuraBySpellID and readable > 0

		return info
	end

	-- Does this client still hand addons the combat log? Where it is gone,
	-- registration throws, so one pcall'd RegisterEvent answers it. A frame of our
	-- own (Ace's registry would keep the subscription), made once because this
	-- re-runs on every SPELLS_CHANGED.
	local probeFrame
	local function ProbeCombatLog()
		if type(_G.CreateFrame) ~= "function" then return nil end
		if not probeFrame then
			local made, frame = pcall(_G.CreateFrame, "Frame")
			if not made then return nil end
			probeFrame = frame
		end
		if type(probeFrame) ~= "table" or type(probeFrame.RegisterEvent) ~= "function" then
			return nil
		end

		local ok = pcall(probeFrame.RegisterEvent, probeFrame, "COMBAT_LOG_EVENT_UNFILTERED")
		if ok then
			pcall(probeFrame.UnregisterEvent, probeFrame, "COMBAT_LOG_EVENT_UNFILTERED")
		end
		return ok
	end

	function ns.ProbeCapabilities()
		wipe(caps)
		caps.buffs = {}

		-- What measures nearness depends on the spellbook, bags and libraries, and
		-- this runs whenever those may have changed (SPELLS_CHANGED).
		ns.ForgetProximity()

		playerClass = plain(select(2, UnitClass("player")))
		caps.class = playerClass

		caps.getUnitAuraBySpellID = type(C_UnitAuras and C_UnitAuras.GetUnitAuraBySpellID) == "function"
		caps.hasSecrets = type(C_Secrets) == "table"
		caps.namePlates = type(C_NamePlate and C_NamePlate.GetNamePlates) == "function"

		if C_Secrets and type(C_Secrets.ShouldAurasBeSecret) == "function" then
			caps.aurasSecretNow = safecall(C_Secrets.ShouldAurasBeSecret)
		end

		---------------------------------------------------------------------
		-- what this client is, and what follows from that
		---------------------------------------------------------------------

		-- Flavour.lua decided all of this at load; copied so one table answers
		-- "what am I allowed to do here" for /manners debug and the saved probe.
		local flavour = ns.Flavour or {}
		caps.flavour = flavour.flavour
		caps.family = flavour.family
		caps.interface = flavour.interface
		caps.recognised = flavour.recognised == true

		-- Whether secrets are enforced right now. C_Secrets exists on clients
		-- where nothing is restricted, so caps.hasSecrets is not this answer.
		caps.secretRestrictions = safecall(C_Secrets and C_Secrets.HasSecretRestrictions)

		-- The combat log: the family answers it for a named client, and the probe
		-- only for one nobody here has seen. The probe can prove the log gone (a
		-- throw), never present. Never probed on a known modern client, where
		-- registering may raise ADDON_ACTION_FORBIDDEN, a popup with our name on it.
		if caps.recognised and caps.family == "modern" then
			caps.combatLogProbe = nil
		else
			caps.combatLogProbe = ProbeCombatLog()
		end
		if flavour.recognised then
			caps.combatLog = caps.family == "classic"
		else
			caps.combatLog = caps.combatLogProbe == true
		end

		-- Whether the client parses macro conditionals like [@party1,help] at all.
		-- It says nothing about whether a name resolves inside one.
		caps.unitConditionals = type(_G.SecureCmdOptionParse) == "function"

		-- ASSUMPTION: whether /cast [@Name] can replace /target, cast, target back.
		-- No API answers it, and [@Name] resolves only for group members, so
		-- Camelot keeps the /target route, the only one verified in game. Nothing
		-- reads this yet.
		caps.conditionalTargeting = flavour.flavour ~= "camelot"

		-- /targetexact matches the whole name where /target matches a prefix
		-- ("/target Mort" can find Mortimer). A client command, so probed.
		local secureCommands = _G.SecureCmdList
		caps.targetExact = (type(secureCommands) == "table"
				and type(secureCommands.TARGET_EXACT) == "function")
			or type(_G.SLASH_TARGET_EXACT1) == "string"

		-- UnitName's second return is a surname on Camelot (joined with a space)
		-- and a realm elsewhere (a dash, or dropped). Nothing in the value says
		-- which, so this is a flavour branch.
		caps.unitNameIsSurname = SurnameClient()

		caps.anyKnown = false
		caps.anyReadable = false
		-- How many of this class's buffs carry an id this client does not have.
		caps.unresolvedBuffs = 0
		for _, buff in ipairs(ns.GetClassBuffs(playerClass) or {}) do
			local info = ProbeBuff(buff)
			caps.buffs[buff.key] = info
			if info.known then caps.anyKnown = true end
			if info.readable then caps.anyReadable = true end
			if #info.unresolved > 0 then caps.unresolvedBuffs = caps.unresolvedBuffs + 1 end
		end

		caps.hasClassBuffs = ns.GetClassBuffs(playerClass) ~= nil

		return caps
	end
end

function ns.BuffInfo(buff)
	return buff and caps.buffs[buff.key]
end

function ns.BuffName(buff)
	local info = ns.BuffInfo(buff)
	return (info and info.name) or buff and buff.key or "?"
end

function ns.IsBuffKnown(buff)
	local info = ns.BuffInfo(buff)
	return info and info.known == true
end

---------------------------------------------------------------------------
-- which buff for which person
---------------------------------------------------------------------------

-- The spell Automatic would name: reached only in Automatic (ResolveBuff answers
-- pins), so neverAuto is skipped outright. Honours the per-spell switches like
-- CastableBuffs, so the login line and previews never name a switched-off spell.
local function FirstKnownBuff()
	local db = addon.db and addon.db.profile
	local skip = db and db.buff and db.buff.skip
	for _, buff in ipairs(ns.GetClassBuffs(playerClass) or {}) do
		if ns.IsBuffKnown(buff) and not buff.neverAuto
			and not (skip and skip[buff.key]) then
			return buff
		end
	end
end

-- Everything of this class the player can actually cast, in list order, once
-- per scan. A neverAuto buff (Unending Breath) and a switched-off one are left
-- out unless pinned: a pin is a deliberate ask, and the options page hides the
-- switches while a spell is pinned.
function ns.CastableBuffs()
	local db = addon.db and addon.db.profile
	local pinned = db and db.buff.choice
	local out = {}
	for _, buff in ipairs(ns.GetClassBuffs(playerClass) or {}) do
		if ns.IsBuffKnown(buff)
			and (pinned == buff.key or not (db and db.buff.skip and db.buff.skip[buff.key]))
			and (not buff.neverAuto or pinned == buff.key) then
			out[#out + 1] = buff
		end
	end
	return out
end

-- Whether everything this character could offer reaches only its party (a
-- warrior's Battle Shout), so "passers-by" means nothing for them. Computed
-- from the switches and pin rather than listed by class; shared by the options
-- page, the greeting and the favour line so they agree. `castable` is
-- CastableBuffs' answer when the caller already has it.
function ns.OnlyReachesGroup(castable)
	castable = castable or ns.CastableBuffs()
	if #castable == 0 then return false end
	for _, buff in ipairs(castable) do
		if not buff.partyOnly then return false end
	end
	return true
end

-- The spell pinned for this character, or nil for Automatic (and for another
-- class's pin). Shared by the walk and the options page so they agree.
function ns.PinnedBuff()
	local db = addon.db and addon.db.profile
	local choice = db and db.buff and db.buff.choice
	if not choice or choice == "auto" then return nil end
	return ns.FindBuff(playerClass, choice)
end

-- PickBuffFor in a block of its own with the helpers only it reads, to spare
-- the main chunk's locals (Lua 5.1 allows 200; tests/validate.py counts them).
do
	-- Split in two because the exclusive branch needs the halves apart: "wrong
	-- spell for this person" holds for the scan, "tried a moment ago" is a
	-- cooldown. inParty, not inGroup: a shout reaches only the caster's
	-- subgroup (see SameParty).
	local function Castable(opts, buff)
		if opts.relevantOnly and buff.manaOnly and opts.hasMana == false then return false end
		if buff.partyOnly and not opts.inParty then return false end
		return true
	end

	-- opts.blocked is handed opts, so the caller's answer can be a file-level
	-- function rather than a closure made per person.
	local function Blocked(opts, buff)
		if not opts.blocked then return false end
		return opts.blocked(buff, opts) == true
	end

	local function Eligible(opts, buff)
		return Castable(opts, buff) and not Blocked(opts, buff)
	end

	-- The candidate list a pin reduces the walk to, reused for every call.
	local PINNED_ONLY = {}

	-- Which of their buffs this person should be offered, or nil for none. Every
	-- castable buff is walked, so holding the first one never hides somebody.
	--
	-- `candidates` comes from CastableBuffs. `has(buff)` answers only the aura
	-- question: has, remaining, and mine (their copy is our cast; nil unknown).
	--   offerAnyway  offer even when they are covered: we owe them a favour, and
	--                a refresh takes nothing away.
	--   rotate       false where there is nothing to walk along: the tokenless
	--                owed path has one buff per favour and cannot verify it.
	--
	-- Returns the buff, whether they hold it (true, false, or nil for "nobody
	-- could tell", which callers keep apart from false), and for a top-up how
	-- long theirs has left.
	function ns.PickBuffFor(candidates, opts, has)
		local db = addon.db and addon.db.profile
		if not db or #candidates == 0 then return nil end

		-- A pin means "only ever this one", no walk. A pin of another class's
		-- (a profile shared with a priest alt) reads as Automatic.
		local pinned = ns.PinnedBuff()
		if pinned then
			if not ns.IsBuffKnown(pinned) then return nil end
			PINNED_ONLY[1] = pinned
			candidates = PINNED_ONLY
		end

		-- Blessings overwrite each other, so holding any one of yours counts as
		-- covered and walking would replace it. Another paladin's blessing
		-- covers nothing of ours (they stack) but is not ours to give; one that
		-- names nobody we can read counts as ours, or ours would be walked over.
		-- Never rotated: rotating would take the blessing just given away again,
		-- where offering the same one twice only refreshes it (ns.RotatesBuffs).
		if ns.EXCLUSIVE_BUFFS[playerClass] then
			local pick, allRead, onCooldown = nil, true, false
			-- The first blessing they carry from another paladin, kept for a debt
			-- with nothing else left to give: see the end of this branch.
			local theirs
			for _, buff in ipairs(candidates) do
				-- Castable rather than Eligible: the blessing we tried moments ago
				-- is the one they most likely carry, so it must still be read.
				if Castable(opts, buff) then
					local held, remaining, mine = has(buff)
					if held == true and mine == false then
						-- Another paladin's: ours of the same kind would only
						-- replace it, so move on to a kind they lack -- unless we
						-- offered this one moments ago, which still means "wait".
						if Blocked(opts, buff) then
							onCooldown = true
						elseif not theirs then
							theirs = buff
						end
					elseif held == true then
						-- Covered, and for this class that is the end of it. First
						-- the cooldown: offered one moments ago means wait.
						if Blocked(opts, buff) then return nil, true end

						-- The top-up, safest on this class: recasting a blessing
						-- replaces it with itself. Ahead of the debt, as on the
						-- ordinary path, since only `remaining` puts the top-up
						-- wording on the prompt.
						if opts.whenBuffed == "refresh" and remaining
							and remaining <= (opts.refreshUnder or 5) * 60 then
							return buff, true, remaining
						end

						-- A debt is repaid with the blessing they already hold
						-- from us (or from nobody we can name), which refreshes it.
						if not opts.offerAnyway then return nil, true end
						return buff, true
					else
						-- "None of mine" only once every one has read back a
						-- definite no: BuildQueue promotes over a debt on has ==
						-- false, and the prompt drops the unverified wording.
						if held ~= false then allRead = false end
						if Blocked(opts, buff) then
							onCooldown = true
						elseif not pick then
							pick = buff
						end
					end
				end
			end
			-- A blessing on cooldown means this person was just offered one: leave
			-- them alone until it lifts, readable or not. The aura cache is three
			-- seconds deep, so a "none of yours" here is usually the reading from
			-- before the cast, and acting on it would replace the blessing just given.
			if onCooldown then return nil, nil end
			-- A debt, and every blessing we could give is already on them from
			-- another paladin: offer anyway, as the debt policy does for every class.
			if not pick and opts.offerAnyway and theirs then return theirs, true end
			-- Spelled out: `allRead and false or nil` is always nil.
			if allRead then return pick, false end
			return pick, nil
		end

		-- Three answers per candidate: they have it, they definitely do not, and
		-- the client would not say. Something lacked outright wins, in list order.
		local expiring, expiringRemaining
		-- Where the rotation below starts, and what it falls back to, gathered on
		-- the way past rather than as a list (this runs 2.5 times a second).
		local last = ns.lastGave and ns.lastGave[opts.name]
		local firstUnknown, afterLast, seenLast
		-- The first thing they are known to carry, for a debt: the offer that
		-- takes nothing away.
		local firstHeld
		for _, buff in ipairs(candidates) do
			if Eligible(opts, buff) then
				local held, remaining = has(buff)
				if held == false then return buff, false end
				if held ~= true then
					if not firstUnknown then firstUnknown = buff end
					if seenLast and not afterLast then afterLast = buff end
					if buff.key == last then seenLast = true end
				else
					if not firstHeld then firstHeld = buff end
					if opts.whenBuffed == "refresh" and remaining
						and remaining <= (opts.refreshUnder or 5) * 60 and not expiring then
						expiring, expiringRemaining = buff, remaining
					end
				end
			end
		end

		-- Nothing definitely missing, but something nobody could read: with no
		-- truth to go on, rotate past whatever was given last rather than offering
		-- the top of the list forever. The tokenless owed path (rotate == false)
		-- asks for the first thing it could cast.
		if firstUnknown then
			if opts.rotate == false then return firstUnknown, nil end
			return afterLast or firstUnknown, nil
		end

		if expiring then return expiring, true, expiringRemaining end

		-- Nothing missing, nothing running out, and a favour outstanding: offer
		-- what they already hold, with `true` saying they are covered.
		if opts.offerAnyway and firstHeld then return firstHeld, true end

		return nil, true
	end
end

-- The one spell named as "the spell you are about to cast" (login line,
-- preview, Roll a few, {spell}, /manners look), so it must be one the queue
-- would really offer, or nil. hasMana is passed in so the caller can reuse it.
function ns.ResolveBuff(hasMana)
	local db = addon.db and addon.db.profile
	if not db then return nil end

	-- A pin is the only spell the walk considers, learned or not, so an
	-- unlearned pin names nothing rather than falling through to Automatic.
	local pinned = ns.PinnedBuff()
	if pinned then return ns.IsBuffKnown(pinned) and pinned or nil end

	-- The switches and the never-automatic rule apply here as in the walk.
	local auto = ns.CLASS_AUTO[playerClass]
	if auto then
		local key = hasMana and auto.mana or auto.other
		local buff = ns.FindBuff(playerClass, key)
		if buff and ns.IsBuffKnown(buff) and not buff.neverAuto
			and not (db.buff.skip and db.buff.skip[key]) then
			return buff
		end
	end

	return FirstKnownBuff()
end

-- Why ResolveBuff has nothing to name, said as the setting that decides it, so
-- a priest with every spell switched off is not sent to a trainer.
function ns.NothingToCast()
	local pinned = ns.PinnedBuff()
	if pinned and not ns.IsBuffKnown(pinned) then
		return L["%s is pinned and not learned on this character"]:format(ns.BuffName(pinned))
	end
	if not caps.anyKnown then return L["no buff learned"] end
	local db = addon.db and addon.db.profile
	local skip = db and db.buff and db.buff.skip
	for _, buff in ipairs(ns.GetClassBuffs(playerClass) or {}) do
		-- Learned, switched on and still not chosen: a spell Automatic never
		-- reaches for, which is not a switch anybody can find turned off.
		if ns.IsBuffKnown(buff) and not (skip and skip[buff.key]) then
			return L["Automatic never offers %s"]:format(ns.BuffName(buff))
		end
	end
	return L["every spell you know is switched off under Who to buff"]
end

-- Whether the buff walk reads ns.lastGave back for this character. Not for a
-- paladin, deliberately: blessings overwrite each other, so rotating takes away
-- what the last click gave. Nothing may write ns.lastGave for them either.
function ns.RotatesBuffs()
	return not ns.EXCLUSIVE_BUFFS[playerClass]
end

---------------------------------------------------------------------------
-- shared state
---------------------------------------------------------------------------

-- Nameplate tokens come from NAME_PLATE_UNIT_ADDED rather than off the frames,
-- because namePlateUnitToken read from a frame is a secret value here.
ns.nameplateUnits = {}

---------------------------------------------------------------------------
-- unit inspection
---------------------------------------------------------------------------

-- auraCache[guid][buffKey] = { at, has, expires, mine }, swept periodically
-- because a city puts hundreds of players through here. Keyed by player so
-- UNIT_AURA, the hot path, forgets a whole player in one assignment; the count
-- is of players.
local auraCache = {}
local auraCacheCount = 0

local function ForgetUnitAuras(guid)
	if not guid or not auraCache[guid] then return end
	auraCache[guid] = nil
	auraCacheCount = auraCacheCount - 1
end
ns.ForgetUnitAuras = ForgetUnitAuras

local lastSweep = 0

local function SweepAuraCache(now)
	if auraCacheCount < 400 then return end
	-- A big table stays big in a city, so the sweep is also rate-limited.
	if (now - lastSweep) < 10 then return end
	lastSweep = now

	for guid, perUnit in pairs(auraCache) do
		local newest
		for _, entry in pairs(perUnit) do
			if not newest or entry.at > newest then newest = entry.at end
		end
		if not newest or (now - newest) > 10 then ForgetUnitAuras(guid) end
	end
end

-- Returns has, secondsRemaining, mine. `has` is nil when the client refuses any
-- one of the buff's ids (the hidden one may be the one they wear);
-- `secondsRemaining` is nil when the timer is unreadable, not "about to expire";
-- `mine` is nil when the aura names nobody we can read.
local function UnitHasBuff(unit, buff, guid)
	local info = ns.BuffInfo(buff)
	if not info or not info.readable then return nil, nil end

	local now = GetTime()
	local perUnit = guid and auraCache[guid]
	local cached = perUnit and perUnit[buff.key]
	if cached and (now - cached.at) < 3 then
		return cached.has, cached.expires and (cached.expires - now) or nil, cached.mine
	end

	-- Refusals (an id declared secret, a read that throws or comes back secret)
	-- are counted, not read as absence: BuildQueue promotes a target over a debt
	-- on a definite no, and the prompt drops its unverified wording.
	local has, expires, mine, refused = false, nil, nil, false
	for _, id in ipairs(buff.auraIds) do
		if info.secrecy[id] == true then
			refused = true
		else
			local ok, aura = pcall(C_UnitAuras.GetUnitAuraBySpellID, unit, id)
			if not ok or (issecretvalue and issecretvalue(aura)) then
				refused = true
			elseif type(aura) == "table" then
				has = true
				local expiration = plain(aura.expirationTime)
				if type(expiration) == "number" and expiration > 0 then expires = expiration end
				-- Whose it is, for a paladin's blessings. isFromPlayerOrPlayerPet
				-- is true for any player's aura, so only a readable token answers.
				local source = plain(aura.sourceUnit)
				if type(source) == "string" then
					local same = safecall(UnitIsUnit, source, "player")
					if same ~= nil then mine = same == true end
				end
				break
			end
		end
	end
	if not has and refused then has = nil end

	-- Negative answers are cached too (a refusal as nil), or the walk re-reads
	-- every buff for every person on every tick.
	if guid then
		if not perUnit then
			perUnit = {}
			auraCache[guid] = perUnit
			auraCacheCount = auraCacheCount + 1
		end
		-- A stale reading is rewritten in place: nothing else holds one, and a
		-- crowd turns them all over every three seconds.
		if cached then
			cached.at, cached.has, cached.expires, cached.mine = now, has, expires, mine
		else
			perUnit[buff.key] = { at = now, has = has, expires = expires, mine = mine }
		end
	end
	return has, expires and (expires - now) or nil, mine
end
ns.UnitHasBuff = UnitHasBuff

-- Classes that have a mana bar, for when the client will not tell us a unit's
-- power (always, on the tokenless owed path). Monk and evoker have one; death
-- knight and demon hunter do not.
local MANA_CLASSES = {
	MAGE = true, PRIEST = true, WARLOCK = true,
	DRUID = true, PALADIN = true, HUNTER = true, SHAMAN = true,
	MONK = true, EVOKER = true,
}
ns.MANA_CLASSES = MANA_CLASSES

-- Returns true, false, or nil for "cannot tell". UnitPowerMax is a secret value
-- for players outside your group here; class is not, so it answers instead.
local function UnitHasMana(unit)
	local maxMana = plain(UnitPowerMax(unit, MANA))
	if maxMana ~= nil then return maxMana > 0 end

	local class = plain(select(2, UnitClass(unit)))
	if class then return MANA_CLASSES[class] == true end

	return nil
end
ns.UnitHasMana = UnitHasMana

-- Returns ok and, when ok is false, whether the rejection was about the person
-- rather than the token: dead, hostile, offline or too low is a judgement the
-- tokenless owed fallback has to honour too, while "no such unit" or "that is
-- you" says nothing about anybody. Only the first return may be tested for
-- truth; the second is advisory.
local function IsBuffableUnit(unit, f)
	if not unit or not plain(UnitExists(unit)) then return false end
	if plain(UnitIsUnit(unit, "player")) then return false end
	if plain(UnitIsPlayer(unit)) ~= true then return false end
	if plain(UnitIsDeadOrGhost(unit)) == true then return false, true end
	-- Only a definite refusal is a judgement about the person: a withheld
	-- answer is nil, and the tokenless fallback exists to reach exactly those.
	local canAssist = plain(UnitCanAssist("player", unit))
	if canAssist ~= true then return false, canAssist == false end
	if plain(UnitIsConnected(unit)) == false then return false, true end

	if f.minLevel and f.minLevel > 1 then
		local lvl = plain(UnitLevel(unit))
		if lvl and lvl > 0 and lvl < f.minLevel then return false, true end
	end

	return true
end
ns.IsBuffableUnit = IsBuffableUnit

-- nil means "could not tell", which we treat as worth offering rather than
-- silently dropping somebody who is probably standing right next to you.
local function InRange(unit, buff)
	local info = ns.BuffInfo(buff)
	local name = ns.BuffName(buff)

	-- By id first: a name has to be resolved against the spellbook, and this
	-- client is unreliable about exactly that.
	local r
	if info and info.topRank then
		r = safecall(C_Spell and C_Spell.IsSpellInRange, info.topRank, unit)
	end
	if r == nil then r = safecall(C_Spell and C_Spell.IsSpellInRange, name, unit) end
	if r == nil then r = safecall(_G.IsSpellInRange, name, unit) end
	if r == nil then return nil end
	return (r == true or r == 1)
end
ns.InRange = InRange

-- Whether a partyOnly buff the player casts reaches this unit. In a raid a
-- vanilla shout reaches only the caster's subgroup (ns.PARTY_IS_SUBGROUP; later
-- flavours made it raid-wide): UnitInSubgroup where the client has it, as the
-- Camelot class-buff reminder uses, else the raid roster. `inRaid` is the
-- scan's reading of IsInRaid; nil asks here.
local function SameParty(unit, inRaid)
	if not unit then return false end
	if inRaid == nil then inRaid = plain(IsInRaid and IsInRaid()) == true end
	if not inRaid then
		return plain(UnitInParty and UnitInParty(unit)) == true
	end
	if not ns.PARTY_IS_SUBGROUP then
		return type(plain(UnitInRaid and UnitInRaid(unit))) == "number"
	end
	if type(_G.UnitInSubgroup) == "function" then
		return safecall(_G.UnitInSubgroup, unit) == true
	end
	local index = plain(UnitInRaid and UnitInRaid(unit))
	local mine = plain(UnitInRaid and UnitInRaid("player"))
	if type(index) ~= "number" or type(mine) ~= "number" then return false end
	local _, _, theirs = safecall(_G.GetRaidRosterInfo, index)
	local _, _, ours = safecall(_G.GetRaidRosterInfo, mine)
	return theirs ~= nil and theirs == ours
end
ns.SameParty = SameParty

-- Whether a shout would reach this unit: true, false, or nil for nothing could
-- tell. InRange cannot answer it: a self-cast spell has no range to anybody.
--
-- The follow prompt (CheckInteractDistance 4, about 28 yards) first, where a
-- refusal stays a refusal. LibRangeCheck only after it and only to say yes
-- within 30 yards, since its "far" can be a refusal in disguise (see
-- DirectCheck). Both are looser than an untalented shout (20 yards, 30 with all
-- of Booming Voice) on purpose: they are there to stop the sixty-yard or
-- other-zone case, not to measure exactly. Never the follow prompt in a fight:
-- the game blocks it for a friendly unit and names the addon, which no pcall
-- catches. LibRangeCheck is still asked in a fight, because it switches to its
-- in-combat checkers by itself.
local function ShoutReach(unit)
	if not InCombatLockdown() then
		local follow = safecall(_G.CheckInteractDistance, unit, 4)
		if follow ~= nil then return follow == true or follow == 1 end
	end

	local stub = _G.LibStub
	local lib = type(stub) == "table" and type(stub.GetLibrary) == "function"
		and safecall(stub.GetLibrary, stub, "LibRangeCheck-3.0", true) or nil
	if type(lib) == "table" and type(lib.GetRange) == "function" then
		local _, maxRange = safecall(lib.GetRange, lib, unit)
		if type(maxRange) == "number" and maxRange <= 30 then return true end
	end
	return nil
end
ns.ShoutReach = ShoutReach

-- Whether the buff reaches this unit right now, asked the way the scan asks it
-- for entry.ranged. The prompt's press asks again just before its macro runs:
-- the scan can be a tick old, and somebody who walked off since would still be
-- spoken to over a /cast that fails.
function ns.ReachNow(unit, buff)
	if not (unit and buff) then return nil end
	local ranged = InRange(unit, buff)
	if ranged == nil and buff.selfCast then ranged = ShoutReach(unit) end
	return ranged
end

---------------------------------------------------------------------------
-- names
---------------------------------------------------------------------------

-- Strips a cross-realm suffix, keeping any surname: "Petra Stonewell-Realm" gives
-- "Petra Stonewell". This is the display name.
local function ShortName(name)
	if type(name) ~= "string" then return nil end
	return name:match("^([^%-]+)") or name
end
ns.ShortName = ShortName

-- Just the first word: "Petra" out of "Petra Stonewell", nil for a name that is
-- one word already. Never on a /target line (the first-name fallback was
-- removed deliberately: see ExpirePendingClick); it feeds {first} in /manners
-- try and the settle path, since the game may report either spelling.
local function FirstName(name)
	if type(name) ~= "string" then return nil end
	local first = name:match("^([^%s%-]+)")
	if first and first ~= name then return first end
	return nil
end
ns.FirstName = FirstName

-- Names go into macro text, so anything that could break out of the [@target]
-- clause is rejected outright. The length cap fits the longest key there is: a
-- name and a surname of 12 letters each, 4 bytes a letter at most, and a space.
local function SafeForMacro(name)
	if type(name) ~= "string" or name == "" then return false end
	if #name > 97 then return false end
	if name:find("[%[%]\n\r;|]") then return false end
	return true
end
ns.SafeForMacro = SafeForMacro

-- The name somebody is filed under, given UnitName's two halves: the key for
-- debts (on disk), the tried table and the rotation pointer. The /target
-- spelling is ns.TargetName. On Camelot the second half is a surname, joined
-- with a space (verified in game); elsewhere it is a realm, present only for a
-- cross-realm player and joined with a dash as the game does. nil for a name
-- withheld or unsafe for macro text. One function for the aura scan and the
-- combat log (GetPlayerInfoByGUID), so both spell a person the same way.
local function JoinName(name, second)
	if not name then return nil end

	local full = name
	if second and second ~= "" then
		full = name .. (SurnameClient() and " " or "-") .. second
	end
	if not SafeForMacro(full) then return nil end
	return full
end
ns.JoinName = JoinName

-- plain() collapses to a single value, so both of UnitName's returns have to be
-- taken before either is inspected or the second is silently lost.
function ns.UnitFullName(unit)
	local rawName, rawSecond = UnitName(unit)
	return JoinName(plain(rawName), plain(rawSecond))
end

-- The spelling that goes on the /target line, from the filed name (the
-- tokenless fallback has nothing else). On Camelot the key unchanged: its join
-- is the only form verified there. Elsewhere the realm comes off, on the
-- reasoning (untested live) that /target searches names of units drawn in and
-- a realm is not part of what it searches.
function ns.TargetName(name)
	if type(name) ~= "string" then return nil end
	if SurnameClient() then return name end
	return ShortName(name)
end

---------------------------------------------------------------------------
-- lifecycle
---------------------------------------------------------------------------

-- A profile can be hand-edited, or carried over from a version with other
-- limits; out of range, it means a prompt sized zero or a scan every frame.
local VALID_ANCHORS = {
	TOP = true, BOTTOM = true, LEFT = true, RIGHT = true, CENTER = true,
	TOPLEFT = true, TOPRIGHT = true, BOTTOMLEFT = true, BOTTOMRIGHT = true,
}

-- Somewhere to put the prompt without the unlock, drag, lock dance. Each is
-- anchored to its own screen edge so it stays put at any resolution. A list,
-- because the dropdown needs an order.
ns.POSITION_PRESETS = {
	{ key = "bars", name = L["Above the action bars"],
		point = "BOTTOM", relPoint = "BOTTOM", x = 0, y = 300 },
	{ key = "minimap", name = L["Under the minimap"],
		point = "TOPRIGHT", relPoint = "TOPRIGHT", x = -20, y = -220 },
	{ key = "centre", name = L["Middle of the screen"],
		point = "CENTER", relPoint = "CENTER", x = 0, y = -140 },
}

-- Which preset the prompt is sitting on, or nil once dragged elsewhere: asked
-- rather than remembered, so it cannot go stale.
function ns.CurrentPositionPreset()
	local p = addon.db and addon.db.profile.prompt
	if not p then return nil end
	for _, preset in ipairs(ns.POSITION_PRESETS) do
		if preset.point == p.point and preset.relPoint == p.relPoint
			and preset.x == p.x and preset.y == p.y then
			return preset.key
		end
	end
	return nil
end

function ns.ApplyPositionPreset(key)
	local p = addon.db and addon.db.profile.prompt
	if not p then return false end
	for _, preset in ipairs(ns.POSITION_PRESETS) do
		if preset.key == key then
			p.point, p.relPoint, p.x, p.y = preset.point, preset.relPoint, preset.x, preset.y
			-- Never touches `locked`: an unlocked prompt cannot cast.
			ns.Prompt:ApplyStyle()
			return true
		end
	end
	return false
end

local LIMITS = {
	{ "timing", "scanInterval", 0.1, 2 },
	{ "timing", "reciprocateWindow", 15, 600 },
	{ "timing", "retryCooldown", 3, 60 },
	{ "timing", "graceSeconds", 10, 180 },
	{ "filters", "minLevel", 1, 60 },
	{ "filters", "refreshUnder", 1, 60 },
	{ "prompt", "width", 80, 500 },
	{ "prompt", "height", 20, 120 },
	{ "prompt", "scale", 0.5, 3 },
	{ "prompt", "alpha", 0.1, 1 },
	{ "prompt", "fontSize", 6, 32 },
	{ "prompt", "iconSize", 12, 64 },
	{ "prompt", "queueRows", 1, 5 },
}

-- The largest icon a prompt of this size can hold: eight pixels shorter than
-- the panel and sixty narrower, never under the slider's floor. Asked by the
-- clamp below and by the notice on the options page.
function ns.IconCeiling(p)
	local d = ns.defaults.profile.prompt
	local height = type(p.height) == "number" and p.height or d.height
	local width = type(p.width) == "number" and p.width or d.width
	return math.max(12, math.min(height - 8, width - 60))
end

function ns.ClampSettings()
	local profile = addon.db and addon.db.profile
	if not profile then return end
	-- AceDB fills defaults only into a table, and a damaged or hand-edited
	-- file can hold anything, so a section that is not one is replaced whole
	-- (with a copy: AceDB strips values equal to the default table itself).
	local function copy(t)
		local out = {}
		for k, v in pairs(t) do out[k] = type(v) == "table" and copy(v) or v end
		return out
	end
	for key, default in pairs(ns.defaults.profile) do
		if type(default) == "table" and type(profile[key]) ~= "table" then
			profile[key] = copy(default)
		end
	end
	for _, limit in ipairs(LIMITS) do
		local group, key, low, high = limit[1], limit[2], limit[3], limit[4]
		local value = profile[group] and profile[group][key]
		if type(value) ~= "number" then
			profile[group][key] = ns.defaults.profile[group][key]
		elseif value < low then
			profile[group][key] = low
		elseif value > high then
			profile[group][key] = high
		end
	end

	local p = profile.prompt
	-- Every wording that goes through the substitution must be a string, or
	-- the swap throws on every repaint. Only the first line has to say
	-- something; an empty reason line is a wish (no second line) and is kept.
	if not ns.UsableFormat(p.format) then p.format = ns.defaults.profile.prompt.format end
	for _, key in ipairs({ "reasonTarget", "reasonOwed", "reasonGroup",
		"reasonNearby", "reasonAsked", "reasonRefresh", "reasonUnknown" }) do
		if type(p[key]) ~= "string" then
			p[key] = ns.defaults.profile.prompt[key]
		end
	end

	-- skipIfBuffed became a three-way choice. Here rather than OnInitialize
	-- so every profile is carried over when it becomes active, not only the
	-- one active at login.
	local filters = profile.filters
	if filters and filters.skipIfBuffed ~= nil then
		if filters.skipIfBuffed == false then filters.whenBuffed = "always" end
		filters.skipIfBuffed = nil
	end

	-- The icon is bound to the panel by both dimensions, or it overhangs it
	-- and pushes the name off; clamped here as well as in the slider, since a
	-- profile written under a taller prompt survives the height being lowered.
	local iconMax = ns.IconCeiling(p)
	if p.iconSize > iconMax then p.iconSize = iconMax end
	if not ns.CHANNEL_COMMANDS[profile.speech.channel] then profile.speech.channel = "SAY" end


	-- An empty phrase box refilled from the set the dropdown names, so the two
	-- agree (nil for a set that no longer exists). Here, not OnInitialize: a
	-- new, copied or reset profile only comes back through RefreshConfig.
	local speech = profile.speech
	if type(speech.phrases) ~= "string" or speech.phrases:match("^%s*$") then
		speech.phrases = ns.PhraseSetText(speech.presetChoice) or ns.PhraseSetText("roleplay")
	end
	-- A set's English text is what an English-only build wrote into the box,
	-- not something the player typed, so it follows the client's language.
	-- On an English client the two are the same text and nothing changes.
	local englishSet = ns.EnglishPhraseSet(speech.phrases)
	local translatedSet = englishSet and ns.PhraseSetText(englishSet)
	if translatedSet and translatedSet ~= speech.phrases then speech.phrases = translatedSet end
	-- The same for "In character", whose examples differ per character, so
	-- Phrases.lua recognises its own.
	if ns.InCharacter then ns.InCharacter.Repair(speech) end

	-- Everything with a fixed set of values, checked against that set: an
	-- unrecognised value falls through every branch that handles it.
	local function oneOf(tbl, key, allowed, fallback)
		if not allowed[tbl[key]] then tbl[key] = fallback end
	end

	-- The same for a plain yes or no: a string there is truthy forever, and a
	-- checkbox cannot show it.
	local function boolean(tbl, key, fallback)
		if type(tbl[key]) ~= "boolean" then tbl[key] = fallback end
	end

	oneOf(profile.filters, "whenBuffed", { skip = true, refresh = true, always = true }, "skip")
	-- Built from the tier list, so a new distance is never rejected here.
	local proximities = {}
	for _, tier in ipairs(ns.PROXIMITY) do proximities[tier.key] = true end
	oneOf(profile.filters, "proximity", proximities, "near")
	boolean(profile.filters, "restoreTarget", true)
	boolean(profile.filters, "hideMounted", false)
	boolean(profile.sound, "owedOnly", true)
	boolean(profile.timing, "keepDebts", true)
	boolean(profile.priority, "target", true)
	boolean(profile.priority, "friends", true)
	boolean(profile.filters, "restingOnly", false)

	-- The never-offer list is read on every scan; the repair at the top made
	-- it a table. An entry that is not a name set to true is dropped: there is
	-- no telling who it was meant to be.
	for name, flag in pairs(profile.never) do
		if type(name) ~= "string" or not name:find("%S") or flag ~= true then
			profile.never[name] = nil
		end
	end

	-- The set of switched-off spells, indexed on every scan by CastableBuffs.
	if type(profile.buff.skip) ~= "table" then profile.buff.skip = {} end
	-- The look once called "blizzard" is "framed" now; carried across rather
	-- than reset to the default by the oneOf below.
	if p.style == "blizzard" then p.style = "framed" end
	oneOf(p, "style", { glass = true, framed = true, minimal = true }, "glass")
	oneOf(p, "accentMode", { icon = true, stripe = true, both = true, off = true }, "icon")
	oneOf(p, "reasonPalette", { standard = true, colourblind = true }, "standard")
	oneOf(p, "flashStyle", { pulse = true, once = true, off = true }, "pulse")
	boolean(p, "thankEmote", false)
	oneOf(p, "effects", { full = true, calm = true }, "full")
	boolean(p, "showCooldown", true)

	-- Beta.1 moved the default anchor from the middle of the screen to the
	-- bottom edge; AceDB strips values equal to their default, so a 0.9.x
	-- prompt on the middle kept only its offsets, and a negative one lands off
	-- screen. It is carried back to the middle. A beta.1-3 Y slider setting
	-- looks the same on disk, so the player is told how to undo it. Once per
	-- profile, stamped in a key with no default so AceDB never strips it.
	if p.anchorCarried ~= true then
		if p.point == "BOTTOM" and p.relPoint == "BOTTOM"
			and type(p.y) == "number" and p.y < 0 then
			p.point, p.relPoint = "CENTER", "CENTER"
			ns.anchorCarriedNote = true
		end
		p.anchorCarried = true
	end

	-- Up to beta.4 offsets were in scaled units; they are UIParent's now
	-- (ApplyStyle, FinishDrag), so a prompt dragged at any scale but 1 has its
	-- offsets multiplied by that scale once. One on a preset is left there.
	-- Stamped like the carry-over above.
	if p.offsetsUnscaled ~= true then
		if p.scale ~= 1 and not ns.CurrentPositionPreset()
			and type(p.x) == "number" and type(p.y) == "number" then
			p.x, p.y = math.floor(p.x * p.scale + 0.5), math.floor(p.y * p.scale + 0.5)
		end
		p.offsetsUnscaled = true
	end
	oneOf(p, "point", VALID_ANCHORS, "CENTER")
	oneOf(p, "relPoint", VALID_ANCHORS, "CENTER")
	-- An offset no screen has, which only a hand-edited file can write and
	-- SetPoint takes without complaint, leaving the prompt nowhere. The whole
	-- position goes back to the default, since half of one is meaningless.
	local function offset(v)
		return type(v) == "number" and v == v and v <= 10000 and v >= -10000
	end
	if not offset(p.x) or not offset(p.y) then
		local d = ns.defaults.profile.prompt
		p.point, p.relPoint, p.x, p.y = d.point, d.relPoint, d.x, d.y
	end

	-- Only a sound key that is not a string is repaired: a sound pack loading
	-- after this addon has not registered its sounds yet. PlayPromptSound
	-- falls back to ours when the key is missing at play time.
	local snd = profile.sound
	if type(snd.file) ~= "string" then snd.file = ns.SOUND_KEY end

	-- A pin nobody's class has goes. Another class's pin stays, since the
	-- profile is shared by every character; PickBuffFor reads it as Automatic.
	local choice = profile.buff.choice
	if choice ~= "auto" and not ns.AnyClassHasBuff(choice) then
		profile.buff.choice = "auto"
	end

	-- Colours are read as four numbers without checking. Repaired with a copy
	-- of the default, never the default table itself: AceDB strips values
	-- equal to their default at a profile switch, and would strip it bare.
	for _, key in ipairs({ "fontColor", "bgColor", "accentColor" }) do
		local c = p[key]
		if type(c) ~= "table" or type(c[1]) ~= "number" or type(c[2]) ~= "number"
			or type(c[3]) ~= "number" then
			local d = ns.defaults.profile.prompt[key]
			p[key] = { d[1], d[2], d[3], d[4] }
		end
	end
end

-- The line for a prompt the anchor carry-over has just moved. Not said by the
-- clamp, which runs at load before the chat frame exists: at login it waits
-- for the build line, on a profile switch it follows the clamp. Once.
function ns.SayAnchorCarried()
	if not ns.anchorCarriedNote then return end
	ns.anchorCarriedNote = nil
	addon:Print(L["the prompt was moved onto its new anchor, the middle of the screen. If you had put it at the bottom edge on purpose, drag it back or pick a place under |cffffd100Put it|r on the options page."])
end

function addon:OnInitialize()
	self.db = LibStub("AceDB-3.0"):New("MannersDB", defaults, true)
	ns.db = self.db


	self.db.RegisterCallback(self, "OnProfileChanged", "RefreshConfig")
	self.db.RegisterCallback(self, "OnProfileCopied", "RefreshConfig")
	self.db.RegisterCallback(self, "OnProfileReset", "RefreshConfig")
	-- Deleting a profile only ends an import's undo made on the deleted one.
	self.db.RegisterCallback(self, "OnProfileDeleted", "ProfileDeleted")
	self.db.RegisterCallback(self, "OnDatabaseShutdown", "SaveDebts")

	-- Probe first: ClampSettings validates the pinned buff against caps.class.
	ns.Guard("ProbeCapabilities", ns.ProbeCapabilities)
	-- Guarded: a repair that fails must not take the debts, the ledger, the
	-- options and the slash commands with it.
	ns.Guard("ClampSettings", ns.ClampSettings)
	-- After the clamp, so debts meet a validated window. Once per session, not
	-- on PLAYER_ENTERING_WORLD, which would resurrect debts already settled.
	ns.Guard("RestoreDebts", ns.RestoreDebts)
	-- After the debts are back, so the ledger can check its owed rows.
	ns.TellLedger("Load")
	ns.Guard("SetupOptions", ns.SetupOptions)
	ns.Guard("Prompt:Create", function() ns.Prompt:Create() end)

	self:RegisterChatCommand("manners", "HandleSlash")
	self:RegisterChatCommand("mnr", "HandleSlash")
end

function addon:OnEnable()
	-- Registering an event the client does not have throws; each is guarded
	-- so one cannot abort the rest, the scanner with it.
	for _, event in ipairs({
		"UNIT_AURA",
		"PLAYER_ENTERING_WORLD",
		"PLAYER_REGEN_ENABLED",
		-- The prompt freezes when a fight starts and must show it at once.
		"PLAYER_REGEN_DISABLED",
		"SPELLS_CHANGED",
		"NAME_PLATE_UNIT_ADDED",
		"NAME_PLATE_UNIT_REMOVED",
		"UNIT_SPELLCAST_SENT",
		"UNIT_SPELLCAST_SUCCEEDED",
		"UNIT_SPELLCAST_FAILED",
		-- The sweep over the prompt's icon follows casts starting, pushed back,
		-- stopped early, and cooldowns the client takes back.
		"UNIT_SPELLCAST_START",
		"UNIT_SPELLCAST_DELAYED",
		"UNIT_SPELLCAST_INTERRUPTED",
		"SPELL_UPDATE_COOLDOWN",
		"UI_ERROR_MESSAGE",
		-- A back-off lifts when the player targets that person themselves.
		"PLAYER_TARGET_CHANGED",
		"PLAYER_UNGHOST",
		"PLAYER_ALIVE",
		"PLAYER_DEAD",
		-- People asking for a buff. Registered whether that source is on or
		-- not: the handler asks the switch first.
		"CHAT_MSG_SAY",
		"CHAT_MSG_YELL",
		"CHAT_MSG_PARTY",
		"CHAT_MSG_PARTY_LEADER",
		"CHAT_MSG_RAID",
		"CHAT_MSG_RAID_LEADER",
		"CHAT_MSG_INSTANCE_CHAT",
		"CHAT_MSG_INSTANCE_CHAT_LEADER",
		"CHAT_MSG_WHISPER",
	}) do
		ns.Guard("RegisterEvent " .. event, function() self:RegisterEvent(event) end)
	end

	-- The combat log only where the client is believed to have one: Forever
	-- and retail 12.0+ forbid the registration, and asking there would print
	-- a red line on every login. Armed only once the call went through, and
	-- everything that cares reads the flag, not caps.combatLog.
	if caps.combatLog then
		ns.Guard("RegisterEvent COMBAT_LOG_EVENT_UNFILTERED", function()
			self:RegisterEvent("COMBAT_LOG_EVENT_UNFILTERED")
			ns.combatLogArmed = true
			ns.logScan.armed = true
		end)
	end

	ns.Guard("StartScanner", function() self:StartScanner() end)
	ns.Guard("ApplyStyle", function() ns.Prompt:ApplyStyle() end)

	-- Say so out loud: silence is indistinguishable from failure.
	C_Timer.After(2, function()
		local buff = ns.ResolveBuff(true)
		-- A class with nothing to cast gets the greeting's sentence, not "no
		-- buff learned".
		local nothingToGive = caps.class ~= nil and ns.CLASSES_WITHOUT_BUFFS ~= nil
			and ns.CLASSES_WITHOUT_BUFFS[caps.class] == true
		-- The profile is shared, so off on one character is off on every alt.
		local off = not self.db.profile.enabled
		if not buff and nothingToGive then
			self:Print(L["build |cffffd100%s|r -- this class has no buffs to cast on other players."]:format(tostring(ns.BUILD)))
		elseif off then
			self:Print(L["build |cffffd100%s|r -- |cffff8080switched off on this profile|r; |cffffd100/manners on|r to start."]
				:format(tostring(ns.BUILD)))
		elseif buff then
			self:Print(L["build |cffffd100%s|r watching for buffs. Ready to cast |cffffd100%s|r."]:format(
				tostring(ns.BUILD), ns.BuffName(buff)))
		else
			-- Translators: its own sentence, since the slot above takes a
			-- spell's name and a reason does not fit there in every language.
			self:Print(L["build |cffffd100%s|r watching for buffs. Ready to cast |cffffd100nothing -- %s|r."]:format(
				tostring(ns.BUILD), ns.NothingToCast()))
		end
		-- Why the prompt is somewhere else this session, if an update moved it.
		ns.SayAnchorCarried()
		-- The macro an older version made, while nothing else is going on.
		ns.SettleOldMacro()
		-- And, on this character's first login, what the thing is for: on the
		-- same delay, since nothing printed before the chat frame exists is
		-- seen. Guarded so it cannot take the build line with it; told whether
		-- that line just said the profile is off.
		ns.Guard("Welcome", ns.Welcome, false, off)
	end)
end

function addon:StartScanner()
	if self.scanTimer then self:CancelTimer(self.scanTimer) end
	self.scanTimer = self:ScheduleRepeatingTimer("Tick", self.db.profile.timing.scanInterval or 0.4)
end

function addon:Tick()
	-- A repeating timer whose function errors simply stops running, silently.
	ns.Guard("Tick", addon.TickBody, self)
end

function addon:TickBody()
	local now = GetTime()
	-- All but the aura cache live in files that load after this one
	-- (Queue.lua, Clicks.lua), so they are read here and not at load.
	local owed, tried, LiveExpiry, TellLedger = ns.owed, ns.tried, ns.DebtExpiry, ns.TellLedger
	local SweepPendingClick, PruneSettled = ns.SweepPendingClick, ns.PruneSettled
	SweepAuraCache(now)
	-- On the tick, because the case it decides has no event: a /target that
	-- resolves nobody leaves the /cast with no aim, and the game says nothing.
	SweepPendingClick(now)
	-- Casts that went out and were not refused in their window have landed,
	-- which is what forgets a person's refusals.
	PruneSettled(now)
	ns.SweepRefusals(now)
	for name, entry in pairs(owed) do
		if LiveExpiry(entry) <= now then
			owed[name] = nil
			TellLedger("LetGo", name)
		end
	end
	for key, expiry in pairs(tried) do
		if expiry <= now then tried[key] = nil end
	end
	-- Before the repaint, which then puts the prompt back.
	ns.EndSnoozeIfDue(now)
	ns.Prompt:Refresh()
end

function addon:ProfileDeleted(event, _, name)
	ns.ProfileChangedForUndo(event, name)
end

-- `event` is AceDB's, and nil when an import or its undo calls this itself.
function addon:RefreshConfig(event)
	ns.Guard("ClampSettings", ns.ClampSettings)
	-- A profile switched to may just have been carried over; chat exists now.
	ns.SayAnchorCarried()
	ns.Prompt:ApplyStyle()
	ns.Prompt:InvalidateMacro()
	-- Guarded: nil if Options.lua failed to load, and a throw here would take
	-- StartScanner with it.
	ns.Guard("RefreshMinimapButton", ns.RefreshMinimapButton)
	-- An import's undo belongs to the profile it was made on:
	-- ProfileChangedForUndo decides what a switch, copy or reset does to it,
	-- and an import or its undo calling this ends it (an import sets it again).
	if event == nil then
		ns.ForgetImportUndo()
	else
		ns.ProfileChangedForUndo(event)
	end
	self:StartScanner()
	-- Every setting changed at once, the on switch among them, and the
	-- launcher's text is only put back from here.
	ns.RepaintOptions()
end

---------------------------------------------------------------------------
-- events
--
-- The client's events that are no one section's own: the spellbook changing,
-- your target, dying and coming back, and a fight starting and ending.
---------------------------------------------------------------------------

local lastProbe = 0

-- SPELLS_CHANGED fires often, so the probe is rate-limited -- with a trailing
-- edge, so a buff learned in the middle of a burst (a trainer visit) is still
-- noticed.
local probeQueued = false
function addon:SPELLS_CHANGED()
	local now = GetTime()
	if now - lastProbe < 5 then
		if not probeQueued and C_Timer and C_Timer.After then
			probeQueued = true
			C_Timer.After(5 - (now - lastProbe), function()
				probeQueued = false
				lastProbe = GetTime()
				ns.Guard("ProbeCapabilities", ns.ProbeCapabilities)
			end)
		end
		return
	end
	lastProbe = now
	ns.Guard("ProbeCapabilities", ns.ProbeCapabilities)
end

-- A deliberate choice of somebody backed off (see NoteRefusal) tries them
-- again: the back-off must never keep the player from somebody they point at.
-- The prompt's own macro targets and hands back inside a press, and those are
-- not choices, so a change this close to a press is ignored.
function addon:PLAYER_TARGET_CHANGED()
	local at = ns.pressAt
	if at and GetTime() - at < 0.5 then return end
	ns.LiftBackoff(ns.UnitFullName("target"))
end

function addon:PLAYER_DEAD() if ns.Prompt then ns.Prompt:Refresh() end end
function addon:PLAYER_ALIVE() if ns.Prompt then ns.Prompt:Refresh() end end
function addon:PLAYER_UNGHOST() if ns.Prompt then ns.Prompt:Refresh() end end

-- Combat freezes the secure attributes: until the fight ends the button runs
-- whatever macro it had when the fight started, and the panel must show that
-- hold. The client fires this just before lockdown begins (InCombatLockdown()
-- is still false; other addons call protected methods from it), so a Refresh
-- now re-aims the macro while it still can, and a second one next frame,
-- under lockdown, paints the hold.
function addon:PLAYER_REGEN_DISABLED()
	-- First, while the button can still be touched: a drag held into the pull
	-- is let go of and its position kept, rather than released in the fight.
	if ns.Prompt then ns.Guard("drag at fight start", ns.Prompt.FinishDragForFight, ns.Prompt) end
	-- Somebody who asked for a buff is not let go while you cannot offer it.
	ns.Guard("requests at fight start", ns.HoldRequestsForFight)
	-- The macro armed now serves every press in the fight whatever the player
	-- targets meanwhile, so it hands the target back even for somebody who is
	-- the target now. See STRATEGIES.target.
	if ns.Prompt then ns.Prompt.armedForFight = true end
	if ns.Prompt then ns.Guard("combat hold", ns.Prompt.Refresh, ns.Prompt) end
	C_Timer.After(0, function()
		if ns.Prompt then ns.Guard("combat hold", ns.Prompt.Refresh, ns.Prompt) end
	end)
	-- The Prompt tab's controls cannot act in a fight and the tab says so while
	-- drawn, so it is redrawn at both ends of the fight.
	ns.RepaintOptions()
end

function addon:PLAYER_REGEN_ENABLED()
	-- Secure frames cannot be restyled or retargeted in combat, so what was
	-- deferred is flushed here. ApplyStyle ends in a Refresh; with nothing
	-- deferred, a Refresh alone takes the hold off now rather than at the next
	-- scan. The macro stops being built for a fight first, so that Refresh
	-- drops the hand-back for somebody already the target.
	if ns.Prompt then ns.Prompt.armedForFight = false end
	-- Requests held through the fight get their minute from now, before the
	-- Refresh below so it can offer them.
	ns.Guard("requests after the fight", ns.RequestsAfterFight)
	if ns.Prompt and ns.Prompt.pendingStyle then
		ns.Prompt:ApplyStyle()
	elseif ns.Prompt then
		ns.Guard("combat release", ns.Prompt.Refresh, ns.Prompt)
	end

	-- And the notice on the Prompt tab comes off, over controls that work again.
	ns.RepaintOptions()

	-- A first greeting stood down by a fight (the prompt cannot be shown in
	-- lockdown) gets another go; free on every other fight in the
	-- character's life -- the flag is read first and this returns at once.
	ns.Guard("Welcome", ns.Welcome)
	-- And the old macro, for the same reason: it cannot be edited in a fight.
	if ns.SettleOldMacro then ns.SettleOldMacro() end
end

-- Kept in SavedVariables so the probe -- and whatever the console has printed
-- since -- can be read off disk without logging in or transcribing chat.
function ns.WriteProbe()
	MannersDB = MannersDB or {}
	MannersDB.console = ns.console
	local dump = {
		at = date("%Y-%m-%d %H:%M:%S"),
		version = (GetBuildInfo()),
		toc = select(4, GetBuildInfo()),
		-- The identity /manners debug prints, for a report that arrives as a
		-- copy of SavedVariables.
		flavour = caps.flavour,
		family = caps.family,
		-- Which spell tables the flavour was given: flavours share sets, and an
		-- unrecognised client gets one by guess.
		buffData = ns.BUFFS_SOURCE,
		buffDataMissing = ns.BUFFS_MISSING,
		combatLog = caps.combatLog,
		combatLogProbe = caps.combatLogProbe,
		-- What the second source actually did, beside what the client was
		-- thought to allow: armed and silent is a different bug from never armed.
		combatLogArmed = ns.logScan.armed,
		combatLogSeen = ns.logScan.applied,
		combatLogFiled = ns.logScan.noted,
		secretRestrictions = caps.secretRestrictions,
		conditionalTargeting = caps.conditionalTargeting,
		unitConditionals = caps.unitConditionals,
		targetExact = caps.targetExact,
		unitNameIsSurname = caps.unitNameIsSurname,
		class = caps.class,
		getUnitAuraBySpellID = caps.getUnitAuraBySpellID,
		hasSecrets = caps.hasSecrets,
		aurasSecretNow = caps.aurasSecretNow,
		namePlates = caps.namePlates,
		anyKnown = caps.anyKnown,
		anyReadable = caps.anyReadable,
		buffs = {},
	}
	for key, info in pairs(caps.buffs) do
		dump.buffs[key] = {
			name = info.name,
			known = info.known,
			knownGroup = info.knownGroup,
			topRank = info.topRank,
			readable = info.readable,
			secrecy = info.secrecy,
			-- The ids this client does not have, listed: fixing it means editing
			-- exactly those.
			unresolved = info.unresolved,
		}
	end
	MannersDB.probe = dump
end