Core.lua

--[[
QuestTogether Core (No Ace Dependencies)

This file intentionally contains a lot of explanatory comments.
The goal is to make the addon understandable even for someone new to WoW addon development.

Key responsibilities in this file:
1. Create and expose the global addon table.
2. Initialize and maintain SavedVariables with defaults.
3. Handle addon lifecycle (load, login, enable/disable).
4. Provide utility methods used by the other files (events/comms/options/tests).
5. Implement slash commands and shared behavior like announcements.
]]

local addonName, addonTable = ...
local LibChev = assert(addonTable and addonTable.LibChev, "libchev must load before Core.lua")

-- Reuse an existing global table if it already exists (for safety), otherwise use the loader table.
local QuestTogether = _G.QuestTogether or addonTable or {}
_G.QuestTogether = QuestTogether
QuestTogether.LibChev = LibChev
QuestTogether.Translate = addonTable.Translate
QuestTogether.TranslateForLocale = addonTable.TranslateForLocale
local L = QuestTogether.Translate

local raw_tostring = tostring
local raw_string_match = string.match
local raw_string_find = string.find
local raw_issecretvalue = type(issecretvalue) == "function" and issecretvalue or nil
local raw_canaccessvalue = type(canaccessvalue) == "function" and canaccessvalue or nil
local raw_canaccesstable = type(canaccesstable) == "function" and canaccesstable or nil

local function NormalizeQuestInfoFlagValue(rawValue)
	if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(rawValue) then
		return nil
	end
	if type(rawValue) == "boolean" then
		return rawValue
	end
	local numericFlag = QuestTogether and QuestTogether.SafeToNumber and QuestTogether:SafeToNumber(rawValue) or nil
	if numericFlag ~= nil then
		return numericFlag ~= 0
	end
	return nil
end

local function CanAccessForeignValue(rawValue)
	if raw_canaccessvalue then
		local ok, canAccess = pcall(raw_canaccessvalue, rawValue)
		if not ok or not canAccess then
			return false
		end
	end
	if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(rawValue) then
		return false
	end
	return true
end

local function NormalizeQuestLocationFlag(rawValue)
	if not CanAccessForeignValue(rawValue) then
		return nil
	end
	return NormalizeQuestInfoFlagValue(rawValue)
end

local function MergeQuestLocationFlag(primaryValue, fallbackValue)
	if primaryValue ~= nil then
		return primaryValue
	end
	return fallbackValue
end

local function NormalizeQuestCompletionValue(rawValue)
	if not CanAccessForeignValue(rawValue) then
		return nil
	end
	if type(rawValue) == "boolean" then
		return rawValue
	end
	local numericValue = QuestTogether and QuestTogether.SafeToNumber and QuestTogether:SafeToNumber(rawValue) or nil
	if numericValue ~= nil then
		-- GetQuestLogTitle returns 1 for completed and -1 for failed quests.
		return numericValue == 1
	end
	return nil
end

local function CanAccessForeignTable(rawTable)
	if type(rawTable) ~= "table" then
		return false
	end
	if raw_canaccesstable then
		local ok, canAccess = pcall(raw_canaccesstable, rawTable)
		if not ok or not canAccess then
			return false
		end
	end
	return CanAccessForeignValue(rawTable)
end

---@return string?
local function ReadOptionalString(value)
	if not CanAccessForeignValue(value) or type(value) ~= "string" then
		return nil
	end
	return value
end

local function SanitizeQuestInfoEnumValue(rawValue)
	if not CanAccessForeignValue(rawValue) then
		return nil
	end
	local numericValue = QuestTogether and QuestTogether.SafeToNumber and QuestTogether:SafeToNumber(rawValue) or nil
	if numericValue == nil then
		return nil
	end
	numericValue = math.floor(numericValue + 0.5)
	if numericValue < 0 then
		return nil
	end
	return numericValue
end

local function BuildSanitizedQuestLogInfoRecord(
	questLogIndex,
	titleValue,
	isHeaderValue,
	isHiddenValue,
	isTaskValue,
	isOnMapValue,
	hasLocalPOIValue,
	isCompleteValue,
	questIDValue,
	displayQuestIDValue,
	isWorldQuestValue
)
	local numericQuestLogIndex = QuestTogether
			and QuestTogether.SafeToNumber
			and QuestTogether:SafeToNumber(questLogIndex)
		or nil
	if not numericQuestLogIndex or numericQuestLogIndex <= 0 then
		return nil
	end

	local titleIsSecret = QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(titleValue)
	local sanitizedInfo = {
		title = (type(titleValue) == "string" and not titleIsSecret) and titleValue or nil,
		questLogIndex = math.floor(numericQuestLogIndex + 0.5),
		isHeader = NormalizeQuestInfoFlagValue(isHeaderValue) == true,
		isHidden = NormalizeQuestInfoFlagValue(isHiddenValue) == true,
		isTask = NormalizeQuestInfoFlagValue(isTaskValue) == true,
		isOnMap = NormalizeQuestLocationFlag(isOnMapValue),
		hasLocalPOI = NormalizeQuestLocationFlag(hasLocalPOIValue),
		isComplete = NormalizeQuestCompletionValue(isCompleteValue) == true,
	}

	local numericQuestID = QuestTogether and QuestTogether.SafeToNumber and QuestTogether:SafeToNumber(questIDValue)
		or nil
	if not numericQuestID or numericQuestID <= 0 then
		numericQuestID = QuestTogether
				and QuestTogether.SafeToNumber
				and QuestTogether:SafeToNumber(displayQuestIDValue)
			or nil
	end
	if numericQuestID and numericQuestID > 0 then
		sanitizedInfo.questID = math.floor(numericQuestID + 0.5)
	end

	local normalizedIsWorldQuest = NormalizeQuestInfoFlagValue(isWorldQuestValue)
	if normalizedIsWorldQuest ~= nil then
		sanitizedInfo.isWorldQuest = normalizedIsWorldQuest
	end

	return sanitizedInfo
end

local function BuildSanitizedQuestLogInfoFromRawInfo(questLogIndex, rawInfo)
	if not CanAccessForeignTable(rawInfo) then
		return nil
	end

	local sanitizedInfo = BuildSanitizedQuestLogInfoRecord(
		questLogIndex,
		rawInfo.title,
		rawInfo.isHeader,
		rawInfo.isHidden,
		rawInfo.isTask,
		rawInfo.isOnMap,
		rawInfo.hasLocalPOI,
		rawInfo.isComplete,
		rawInfo.questID,
		rawInfo.displayQuestID,
		rawInfo.isWorldQuest
	)
	if not sanitizedInfo then
		return nil
	end

	-- Some modern records omit completion altogether. Preserve that absence
	-- until the legacy fallback is merged, while retaining explicit false.
	sanitizedInfo.isComplete = NormalizeQuestCompletionValue(rawInfo.isComplete)
	sanitizedInfo.campaignID = SanitizeQuestInfoEnumValue(rawInfo.campaignID)
	sanitizedInfo.frequency = SanitizeQuestInfoEnumValue(rawInfo.frequency)
	sanitizedInfo.questClassification = SanitizeQuestInfoEnumValue(rawInfo.questClassification)
	return sanitizedInfo
end

local function MergeSanitizedQuestLogInfo(primaryInfo, fallbackInfo)
	if type(primaryInfo) ~= "table" then
		return type(fallbackInfo) == "table" and fallbackInfo or nil
	end
	if type(fallbackInfo) ~= "table" then
		primaryInfo.isComplete = primaryInfo.isComplete == true
		return primaryInfo
	end

	local mergedInfo = {}
	mergedInfo.questLogIndex = primaryInfo.questLogIndex or fallbackInfo.questLogIndex
	mergedInfo.title = primaryInfo.title or fallbackInfo.title
	mergedInfo.questID = primaryInfo.questID or fallbackInfo.questID
	mergedInfo.isHeader = primaryInfo.isHeader == true or fallbackInfo.isHeader == true
	mergedInfo.isHidden = primaryInfo.isHidden == true or fallbackInfo.isHidden == true
	mergedInfo.isTask = primaryInfo.isTask == true or fallbackInfo.isTask == true
	mergedInfo.isOnMap = MergeQuestLocationFlag(primaryInfo.isOnMap, fallbackInfo.isOnMap)
	mergedInfo.hasLocalPOI = MergeQuestLocationFlag(primaryInfo.hasLocalPOI, fallbackInfo.hasLocalPOI)
	if primaryInfo.isComplete ~= nil then
		mergedInfo.isComplete = primaryInfo.isComplete == true
	else
		mergedInfo.isComplete = fallbackInfo.isComplete == true
	end
	mergedInfo.campaignID = primaryInfo.campaignID or fallbackInfo.campaignID
	mergedInfo.frequency = primaryInfo.frequency or fallbackInfo.frequency
	mergedInfo.questClassification = primaryInfo.questClassification or fallbackInfo.questClassification
	if primaryInfo.isWorldQuest ~= nil then
		mergedInfo.isWorldQuest = primaryInfo.isWorldQuest == true
	elseif fallbackInfo.isWorldQuest ~= nil then
		mergedInfo.isWorldQuest = fallbackInfo.isWorldQuest == true
	end

	return mergedInfo
end

local function SafeText(value, fallback)
	if QuestTogether and QuestTogether.SafeToString then
		return QuestTogether:SafeToString(value, fallback ~= nil and fallback or "<secret>")
	end

	local ok, textValue = pcall(raw_tostring, value)
	if ok then
		return textValue
	end

	if fallback ~= nil then
		return fallback
	end
	return "<secret>"
end

local function SafeMatch(text, pattern)
	local safeText = SafeText(text, "")
	if safeText == "" then
		return nil
	end

	local ok, first, second, third, fourth = pcall(raw_string_match, safeText, pattern)
	if not ok then
		return nil
	end

	return first, second, third, fourth
end

local function SafeFind(text, pattern, init, plain)
	local safeText = SafeText(text, "")
	if safeText == "" then
		return nil
	end

	local ok, firstIndex, secondIndex = pcall(raw_string_find, safeText, pattern, init, plain)
	if not ok then
		return nil
	end

	return firstIndex, secondIndex
end

local tostring = SafeText

QuestTogether.addonName = addonName or "QuestTogether"
QuestTogether.commPrefix = "QuestTogether2"
QuestTogether.announcementChannelName = "QuestTogether"
QuestTogether.retiredAnnouncementChannelName = "QuestTogetherAnnounce1"
QuestTogether.questLogWindowName = "QuestTogether"
QuestTogether.CHAT_BUBBLE_SIZE_MIN = 80
QuestTogether.CHAT_BUBBLE_SIZE_MAX = 160
QuestTogether.CHAT_BUBBLE_SIZE_STEP = 5
QuestTogether.CHAT_BUBBLE_DURATION_MIN = 1
QuestTogether.CHAT_BUBBLE_DURATION_MAX = 8
QuestTogether.CHAT_BUBBLE_DURATION_STEP = 0.5
QuestTogether.ANNOUNCEMENT_NEARBY_RADIUS = 5
QuestTogether.NEARBY_RANGE_MIN = 5
QuestTogether.NEARBY_RANGE_MAX = 100
QuestTogether.PLAYER_PARTNER_ICON_TEXTURE = "Interface\\AddOns\\QuestTogether\\Media\\QuestTogetherPartnerIcon"
QuestTogether.PLAYER_DEVELOPER_ICON_TEXTURE = "Interface\\AddOns\\QuestTogether\\Media\\QuestTogetherDeveloperIcon"
QuestTogether.PLAYER_VIP_ICON_TEXTURE = "Interface\\AddOns\\QuestTogether\\Media\\QuestTogetherVIPIcon"
QuestTogether.PLAYER_VIP_PARTNER_ICON_TEXTURE = "Interface\\AddOns\\QuestTogether\\Media\\QuestTogetherVIPPartnerIcon"
QuestTogether.PLAYER_DEVELOPER_PARTNER_ICON_TEXTURE =
	"Interface\\AddOns\\QuestTogether\\Media\\QuestTogetherDeveloperPartnerIcon"

-- Runtime state flags.
QuestTogether.isInitialized = QuestTogether.isInitialized or false
QuestTogether.hasLoggedIn = QuestTogether.hasLoggedIn or false
QuestTogether.isEnabled = QuestTogether.isEnabled or false
QuestTogether.activeProfileKey = QuestTogether.activeProfileKey or nil
QuestTogether.activeCharacterKey = QuestTogether.activeCharacterKey or nil
QuestTogether.pendingPingRequests = QuestTogether.pendingPingRequests or {}
QuestTogether.pendingQuestCompareRequests = QuestTogether.pendingQuestCompareRequests or {}
QuestTogether.debugLogLines = QuestTogether.debugLogLines or {}
QuestTogether.debugLogTextLengthSum = QuestTogether.debugLogTextLengthSum or 0
QuestTogether.debugLogStoreNormalized = QuestTogether.debugLogStoreNormalized or false
QuestTogether.isRunningTests = QuestTogether.isRunningTests or false
QuestTogether.DEBUG_LOG_MAX_LINES = 1000
QuestTogether.DEBUG_LOG_MAX_CHARS = 200000
QuestTogether.DEBUG_DEFAULT_CATEGORY = "DEBUG"
QuestTogether.DEBUG_ALL_CATEGORIES = "ALL"

-- Work queues / state tables used by event handlers.
QuestTogether.onQuestLogUpdate = QuestTogether.onQuestLogUpdate or {}
QuestTogether.questsCompleted = QuestTogether.questsCompleted or {}
QuestTogether.pendingQuestRemovals = QuestTogether.pendingQuestRemovals or {}
QuestTogether.worldQuestAreaStateByQuestID = QuestTogether.worldQuestAreaStateByQuestID or {}
QuestTogether.bonusObjectiveAreaStateByQuestID = QuestTogether.bonusObjectiveAreaStateByQuestID or {}

-- Default settings for SavedVariables.
BINDING_HEADER_QUESTTOGETHER = "QuestTogether"
BINDING_NAME_QUESTTOGETHER_PARTY_LOG = L("Toggle Party Quest Log")
BINDING_NAME_QUESTTOGETHER_MENU = L("Open QuestTogether menu")
BINDING_NAME_QUESTTOGETHER_QUEST_PARTNERS = L("Toggle Looking for Questing Partners")
BINDING_NAME_QUESTTOGETHER_STOP_FOLLOW = L("Stop following quest focus")
BINDING_NAME_QUESTTOGETHER_CHAT = L("Open QuestTogether chat")
BINDING_NAME_QUESTTOGETHER_SETTINGS = L("Open QuestTogether settings")

QuestTogether.DEFAULTS = {
	profile = {
		enabled = true,
		announceAccepted = true,
		announceCompleted = true,
		announceReadyToTurnIn = true,
		announceRemoved = true,
		announceProgress = true,
		announceQuestPartners = true,
		announceWorldQuestAreaEnter = true,
		announceWorldQuestAreaLeave = true,
		announceWorldQuestProgress = true,
		announceWorldQuestCompleted = true,
		announceBonusObjectiveAreaEnter = true,
		announceBonusObjectiveAreaLeave = true,
		announceBonusObjectiveProgress = true,
		announceBonusObjectiveCompleted = true,
		showChatBubbles = true,
		hideMyOwnChatBubbles = false,
		announceToNonQTParty = true,
		hidePartyChatReminder = false,
		showChatLogs = true,
		showQTChat = true,
		qtChatScope = "global",
		chatLogDestination = "main",
		mirrorChatLogsToMainChat = false,
		showProgressFor = "party_nearby",
		nearbyAnnouncementRange = 25,
		devLogAllAnnouncements = false,
		chatBubbleSize = 100,
		chatBubbleDuration = 3,
		emoteOnQuestCompletion = true,
		emoteOnNearbyPlayerQuestCompletion = true,
		emoteOnLevelUp = true,
		compareHideOtherQuests = false,
		lightMode = false,
		windowScale = 100,
		questTrackerMode = "both",
		questTrackerHideSolo = true,
		questTrackerSnapToBlizzard = true,
		questFocusOpacity = 75,
		reduceMotion = false,
		compareAutoRefresh = false,
		experimentalLayerDetection = true,
		compareQuestOwnership = "all",
		compareQuestProgress = "all",
		compareQuestAction = "all",
		autoAcceptPartyShareRequests = false,
		sharePartyFocus = true,
		sharePartyWaypoint = true,
		showPartyWaypoints = true,
		autoInviteFriends = false,
		autoInviteWhileLFG = false,
		lookingForQuestPartners = false,
		stopLookingForPartnersOnJoin = false,
		showMinimapButton = true,
		showStartupTips = true,
		minimapButtonPosition = 225,
		sharePlayerLocation = true,
		shareDeveloperDiagnostics = true,
		showPlayerLocations = true,
		showWorldMapData = true,
		clusterPlayerLocations = true,
		onlyShowQuestPartners = false,
		emoteOnNearbyPlayerLevelUp = true,
		nameplateQuestIconEnabled = true,
		nameplatePlayerIconEnabled = true,
		nameplatePlayerIconStyle = "left",
		nameplateQuestIconStyle = "left",
		nameplateQuestHealthColorEnabled = true,
		nameplateQuestHealthColor = {
			r = 0.95,
			g = 0.45,
			b = 0.05,
		},
		-- Stored per profile so each character/profile can pick its own chat tab.
		questLogChatFrameID = nil,
	},
	global = {
		releaseNotesSeenVersion = "",
		availableAddonVersion = "",
		addonUpdateAvailable = false,
		questTrackers = {},
		personalBubbleAnchors = {},
		playerNotes = {},
		recentCompanions = {},
		debugLogCategoryFilter = "ALL",
		debugLogSearchFilter = "",
		debugLogPrefixFilter = "",
	},
}

QuestTogether.nameplateQuestIconStyleLabels = {
	left = "Left",
	right = "Right",
	top = "Top",
	prefix = "Prefix",
}

QuestTogether.nameplateQuestIconStyleOrder = {
	"left",
	"right",
	"top",
	"prefix",
}

QuestTogether.showProgressForLabels = {
	party_nearby = "Party & Nearby Players",
	party_only = "Party Only",
}

QuestTogether.showProgressForOrder = {
	"party_nearby",
	"party_only",
}

QuestTogether.chatLogDestinationLabels = {
	main = "Main Chat Window",
	separate = "Separate Chat Window",
}

QuestTogether.chatLogDestinationOrder = {
	"main",
	"separate",
}
QuestTogether.chatLogLinkType = "questtogetherlog"
QuestTogether.chatLogQuestLinkType = "questtogetherquest"
QuestTogether.chatLogCoordLinkType = "questtogethercoord"
QuestTogether.questTitleLinkEventTypes = {
	QUEST_ACCEPTED = true,
	QUEST_COMPLETED = true,
	QUEST_READY_TO_TURN_IN = true,
	QUEST_REMOVED = true,
	WORLD_QUEST_ENTERED = true,
	WORLD_QUEST_LEFT = true,
	WORLD_QUEST_COMPLETED = true,
	BONUS_OBJECTIVE_ENTERED = true,
	BONUS_OBJECTIVE_LEFT = true,
	BONUS_OBJECTIVE_COMPLETED = true,
}

QuestTogether.DEFAULT_PERSONAL_BUBBLE_ANCHOR = {
	point = "CENTER",
	relativePoint = "CENTER",
	x = 0,
	y = 120,
}

function QuestTogether:IsShowProgressFor(value)
	for _, candidate in ipairs(self.showProgressForOrder) do
		if candidate == value then
			return true
		end
	end
	return false
end

function QuestTogether:IsChatLogDestination(value)
	for _, candidate in ipairs(self.chatLogDestinationOrder) do
		if candidate == value then
			return true
		end
	end
	return false
end

function QuestTogether:GetChatLogDestinationLabel(value)
	return L(self.chatLogDestinationLabels[value]) or tostring(value)
end

function QuestTogether:NormalizeChatBubbleSizeValue(value)
	local numericValue = self:SafeToNumber(value)
	if not numericValue then
		return nil
	end

	local step = self.CHAT_BUBBLE_SIZE_STEP or 5
	numericValue = math.floor((numericValue / step) + 0.5) * step

	if numericValue < self.CHAT_BUBBLE_SIZE_MIN or numericValue > self.CHAT_BUBBLE_SIZE_MAX then
		return nil
	end

	return numericValue
end

function QuestTogether:IsChatBubbleSize(value)
	return self:NormalizeChatBubbleSizeValue(value) ~= nil
end

function QuestTogether:NormalizeChatBubbleDurationValue(value)
	local numericValue = self:SafeToNumber(value)
	if not numericValue then
		return nil
	end

	local step = self.CHAT_BUBBLE_DURATION_STEP or 0.5
	numericValue = math.floor((numericValue / step) + 0.5) * step
	numericValue = math.floor((numericValue * 10) + 0.5) / 10

	if numericValue < self.CHAT_BUBBLE_DURATION_MIN or numericValue > self.CHAT_BUBBLE_DURATION_MAX then
		return nil
	end

	return numericValue
end

function QuestTogether:IsChatBubbleDuration(value)
	return self:NormalizeChatBubbleDurationValue(value) ~= nil
end

function QuestTogether:IsNameplateQuestIconStyle(styleKey)
	for _, candidate in ipairs(self.nameplateQuestIconStyleOrder) do
		if candidate == styleKey then
			return true
		end
	end
	return false
end

function QuestTogether:GetNameplateQuestIconStyleLabel(styleKey)
	return L(self.nameplateQuestIconStyleLabels[styleKey]) or tostring(styleKey)
end

function QuestTogether:GetNameplateQuestIconStyle()
	local configured = self:GetOption("nameplateQuestIconStyle")
	if self:IsNameplateQuestIconStyle(configured) then
		return configured
	end
	return self.DEFAULTS.profile.nameplateQuestIconStyle
end

function QuestTogether:GetNameplatePlayerIconStyle()
	local configured = self:GetOption("nameplatePlayerIconStyle")
	return self:IsNameplateQuestIconStyle(configured) and configured or self.DEFAULTS.profile.nameplatePlayerIconStyle
end

function QuestTogether:GetShowProgressForLabel(value)
	return L(self.showProgressForLabels[value]) or tostring(value)
end

function QuestTogether:GetChatBubbleSizeLabel(sizeKey)
	local numericValue = self:NormalizeChatBubbleSizeValue(sizeKey)
	if not numericValue then
		return tostring(sizeKey)
	end

	return tostring(numericValue) .. "%"
end

function QuestTogether:GetChatBubbleDurationLabel(durationValue)
	local numericValue = self:NormalizeChatBubbleDurationValue(durationValue)
	if not numericValue then
		return tostring(durationValue)
	end

	if math.abs(numericValue - math.floor(numericValue)) < 0.001 then
		return string.format(L("%d sec"), numericValue)
	end

	return string.format(L("%.1f sec"), numericValue)
end

function QuestTogether:GetPersonalBubbleAnchorKey()
	if self:UsesRegionalPlayerNames() then
		return self:GetCurrentCharacterKey()
	end
	if self.GetPlayerFullName then
		local fullName = self:GetPlayerFullName()
		if fullName and fullName ~= "" then
			return fullName
		end
	end

	local playerName = self:GetPlayerName()
	if playerName and playerName ~= "" then
		return playerName
	end

	return "player"
end

function QuestTogether:GetPersonalBubbleAnchorStore()
	if not self.db or not self.db.global then
		return nil
	end

	if type(self.db.global.personalBubbleAnchors) ~= "table" then
		self.db.global.personalBubbleAnchors = {}
	end

	return self.db.global.personalBubbleAnchors
end

function QuestTogether:GetPersonalBubbleAnchor()
	local defaults = self.DEFAULT_PERSONAL_BUBBLE_ANCHOR
	local anchor = {
		point = defaults.point,
		relativePoint = defaults.relativePoint,
		x = defaults.x,
		y = defaults.y,
	}

	local store = self:GetPersonalBubbleAnchorStore()
	local key = self:GetPersonalBubbleAnchorKey()
	local saved = store and store[key] or nil
	if type(saved) ~= "table" then
		return anchor
	end

	if type(saved.point) == "string" and saved.point ~= "" then
		anchor.point = saved.point
	end
	if type(saved.relativePoint) == "string" and saved.relativePoint ~= "" then
		anchor.relativePoint = saved.relativePoint
	end
	local numericX = self:SafeToNumber(saved.x)
	if numericX ~= nil then
		anchor.x = numericX
	end
	local numericY = self:SafeToNumber(saved.y)
	if numericY ~= nil then
		anchor.y = numericY
	end

	return anchor
end

function QuestTogether:SetPersonalBubbleAnchor(point, relativePoint, offsetX, offsetY)
	local store = self:GetPersonalBubbleAnchorStore()
	if not store then
		return false
	end

	local defaults = self.DEFAULT_PERSONAL_BUBBLE_ANCHOR
	local numericOffsetX = self:SafeToNumber(offsetX)
	local numericOffsetY = self:SafeToNumber(offsetY)
	store[self:GetPersonalBubbleAnchorKey()] = {
		point = type(point) == "string" and point ~= "" and point or defaults.point,
		relativePoint = type(relativePoint) == "string" and relativePoint ~= "" and relativePoint
			or defaults.relativePoint,
		x = numericOffsetX ~= nil and numericOffsetX or defaults.x,
		y = numericOffsetY ~= nil and numericOffsetY or defaults.y,
	}

	if self.ApplySavedPersonalBubbleAnchor then
		self:ApplySavedPersonalBubbleAnchor()
	end
	if self.RefreshPersonalBubbleAnchorVisualState then
		self:RefreshPersonalBubbleAnchorVisualState()
	end
	return true
end

function QuestTogether:ResetPersonalBubbleAnchor()
	local store = self:GetPersonalBubbleAnchorStore()
	if not store then
		return false
	end

	store[self:GetPersonalBubbleAnchorKey()] = nil
	if self.ApplySavedPersonalBubbleAnchor then
		self:ApplySavedPersonalBubbleAnchor()
	end
	if self.RefreshPersonalBubbleAnchorVisualState then
		self:RefreshPersonalBubbleAnchorVisualState()
	end
	return true
end

-- Emotes used when celebrating completed quests and level-ups.
QuestTogether.completionEmotes = {
	"applaud",
	"bow",
	"cheer",
	"clap",
	"commend",
	"congratulate",
	"curtsey",
	"dance",
	"golfclap",
	"happy",
	"highfive",
	"huzzah",
	"impressed",
	"praise",
	"proud",
	"roar",
	"sexy",
	"smirk",
	"strut",
	"victory",
}

-- The runtime event list that should only be registered while the addon is enabled.
QuestTogether.runtimeEvents = {
	"CHAT_MSG_ADDON",
	"CHAT_MSG_CHANNEL",
	"CHAT_MSG_SYSTEM",
	"CHANNEL_COUNT_UPDATE",
	"CHANNEL_UI_UPDATE",
	"PLAYER_LEVEL_UP",
	"QUEST_ACCEPTED",
	"QUEST_TURNED_IN",
	"QUEST_REMOVED",
	"UNIT_QUEST_LOG_CHANGED",
	"QUEST_LOG_UPDATE",
	"QUEST_DATA_LOAD_RESULT",
	"QUEST_POI_UPDATE",
	"AREA_POIS_UPDATED",
	"PLAYER_INSIDE_QUEST_BLOB_STATE_CHANGED",
	"ZONE_CHANGED",
	"ZONE_CHANGED_INDOORS",
	"ZONE_CHANGED_NEW_AREA",
	"SHARD_TRANSFER",
	"SHARD_TRANSFER_IMMINENT",
	"PLAYER_REGEN_ENABLED",
	"ADDON_RESTRICTION_STATE_CHANGED",
	"SUPER_TRACKING_CHANGED",
	"USER_WAYPOINT_UPDATED",
	"GROUP_JOINED",
	"GROUP_ROSTER_UPDATE",
	"IGNORELIST_UPDATE",
}

--[[
API wrapper table.

Why this exists:
- Production code uses these wrappers to call WoW globals.
- Tests can replace one or more wrappers to observe behavior without touching global WoW APIs.
]]
-- API wrapper layer:
-- Guard Blizzard calls that can throw (invalid token, secure context, or transient data race)
-- so runtime features fail soft instead of tainting shared execution paths.
QuestTogether.API = QuestTogether.API
	or {
		Delay = function(seconds, callback)
			C_Timer.After(seconds, callback)
		end,
		GetEditModeManagerFrame = function()
			return EditModeManagerFrame
		end,
		LoadEditMode = function()
			local loader = C_AddOns and C_AddOns.LoadAddOn or LoadAddOn
			if type(loader) ~= "function" then
				return false
			end
			local ok, loaded = pcall(loader, "Blizzard_EditMode")
			return ok and CanAccessForeignValue(loaded) and loaded == true
		end,
		ShowUIPanel = function(frame)
			if not QuestTogether:CanAccessForeignFrame(frame) or type(ShowUIPanel) ~= "function" then
				return false
			end
			return pcall(ShowUIPanel, frame)
		end,
		JoinPermanentChannel = function(name, password, chatFrameId, hasVoice)
			return JoinPermanentChannel(name, password, chatFrameId, hasVoice)
		end,
		LeaveChannelByName = function(name)
			return LeaveChannelByName(name)
		end,
		GetChannelName = function(name)
			return GetChannelName(name)
		end,
		GetChatChannelList = function()
			if type(GetChannelList) ~= "function" then
				return nil
			end
			return { GetChannelList() }
		end,
		SwapChatChannelIndices = function(first, second)
			if not C_ChatInfo or type(C_ChatInfo.SwapChatChannelsByChannelIndex) ~= "function" then
				return false
			end
			C_ChatInfo.SwapChatChannelsByChannelIndex(first, second)
			return true
		end,
		GetNumChatWindows = function()
			return NUM_CHAT_WINDOWS or 0
		end,
		GetChatWindowInfo = function(chatFrameID)
			return FCF_GetChatWindowInfo(chatFrameID)
		end,
		GetChatFrameByID = function(chatFrameID)
			local chatFrame = FCF_GetChatFrameByID(chatFrameID)
			if
				QuestTogether
				and QuestTogether.CanAccessForeignFrame
				and not QuestTogether:CanAccessForeignFrame(chatFrame)
			then
				return nil
			end
			return chatFrame
		end,
		GetCVar = function(cvarName)
			if
				not CanAccessForeignValue(cvarName)
				or type(cvarName) ~= "string"
				or cvarName == ""
				or not CanAccessForeignTable(C_CVar)
			then
				return nil, false
			end
			local getter = C_CVar.GetCVar
			if not CanAccessForeignValue(getter) or type(getter) ~= "function" then
				return nil, false
			end
			local ok, value = pcall(getter, cvarName)
			if not ok or not CanAccessForeignValue(value) then
				return nil, false
			end
			-- A missing CVar returns nil successfully. Keep it distinguishable from
			-- a failed or inaccessible read when callers select a legacy fallback.
			return value, true
		end,
		GetInstanceInfo = function()
			if type(GetInstanceInfo) ~= "function" then
				return nil
			end
			local ok, name, instanceType, difficultyID, difficultyName, maxPlayers, dynamicDifficulty, isDynamic, instanceMapID, instanceGroupSize =
				pcall(GetInstanceInfo)
			if not ok then
				return nil
			end
			return {
				name = name,
				instanceType = instanceType,
				difficultyID = difficultyID,
				difficultyName = difficultyName,
				maxPlayers = maxPlayers,
				dynamicDifficulty = dynamicDifficulty,
				isDynamic = isDynamic,
				instanceMapID = instanceMapID,
				instanceGroupSize = instanceGroupSize,
			}
		end,
		RemoveChatWindowChannel = function(chatFrame, channelName)
			if
				QuestTogether
				and QuestTogether.CanAccessForeignFrame
				and not QuestTogether:CanAccessForeignFrame(chatFrame)
			then
				return nil
			end
			if chatFrame and chatFrame.RemoveChannel then
				return chatFrame:RemoveChannel(channelName)
			end
			if type(ChatFrame_RemoveChannel) == "function" and chatFrame then
				return ChatFrame_RemoveChannel(chatFrame, channelName)
			end
			return nil
		end,
		AddMessageEventFilter = function(eventName, filterFunc)
			if type(ChatFrame_AddMessageEventFilter) == "function" then
				ChatFrame_AddMessageEventFilter(eventName, filterFunc)
			end
		end,
		RemoveMessageEventFilter = function(eventName, filterFunc)
			if type(ChatFrame_RemoveMessageEventFilter) == "function" then
				ChatFrame_RemoveMessageEventFilter(eventName, filterFunc)
			end
		end,
		OpenChatWindow = function(name, noDefaultChannels)
			return FCF_OpenNewWindow(name, noDefaultChannels)
		end,
		CloseChatWindow = function(chatFrame)
			if
				QuestTogether
				and QuestTogether.CanAccessForeignFrame
				and not QuestTogether:CanAccessForeignFrame(chatFrame)
			then
				return nil
			end
			return FCF_Close(chatFrame)
		end,
		SetChatWindowFontSize = function(chatFrame, fontSize)
			if
				QuestTogether
				and QuestTogether.CanAccessForeignFrame
				and not QuestTogether:CanAccessForeignFrame(chatFrame)
			then
				return nil
			end
			return FCF_SetChatWindowFontSize(nil, chatFrame, fontSize)
		end,
		RegisterAddonPrefix = function(prefix)
			local ok, result = pcall(C_ChatInfo.RegisterAddonMessagePrefix, prefix)
			return ok and result or nil
		end,
		SendAddonMessage = function(prefix, message, channel, target)
			local ok, result = pcall(C_ChatInfo.SendAddonMessage, prefix, message, channel, target)
			return ok and result or nil
		end,
		SendChannelChatMessage = function(message, channelID)
			local send = C_ChatInfo and C_ChatInfo.SendChatMessage or SendChatMessage
			if type(send) ~= "function" then
				return false
			end
			local ok, result = pcall(send, message, "CHANNEL", nil, channelID)
			return ok and result ~= false
		end,
		SendLocalChatMessage = function(message, distribution)
			if distribution ~= "SAY" and distribution ~= "YELL" then
				return false
			end
			local send = C_ChatInfo and C_ChatInfo.SendChatMessage or SendChatMessage
			if type(send) ~= "function" then
				return false
			end
			local ok, result = pcall(send, message, distribution)
			return ok and result ~= false
		end,
		SendPartyChatMessage = function(message, distribution)
			if distribution ~= "PARTY" and distribution ~= "INSTANCE_CHAT" then
				return false
			end
			local send = C_ChatInfo and C_ChatInfo.SendChatMessage or SendChatMessage
			if type(send) ~= "function" then
				return false
			end
			local ok = pcall(send, message, distribution)
			return ok
		end,
		IsInInstanceGroup = function()
			return IsInGroup(LE_PARTY_CATEGORY_INSTANCE)
		end,
		IsInGroup = function()
			if type(IsInGroup) ~= "function" then
				return false
			end
			local ok, grouped = pcall(IsInGroup)
			return ok and CanAccessForeignValue(grouped) and grouped == true
		end,
		IsInParty = function()
			return UnitInParty("player")
		end,
		IsInRaid = function()
			return IsInRaid()
		end,
		IsInInstance = function()
			local inInstance = IsInInstance()
			return inInstance and true or false
		end,
		InCombatLockdown = function()
			if InCombatLockdown then
				return InCombatLockdown() and true or false
			end
			return false
		end,
		DoEmote = function(emoteToken, target)
			local performEmote = C_ChatInfo and C_ChatInfo.PerformEmote
			if type(performEmote) ~= "function" then
				performEmote = DoEmote
			end
			if type(performEmote) ~= "function" then
				return false
			end
			local ok = pcall(performEmote, emoteToken, target)
			return ok
		end,
		IsMounted = function()
			return IsMounted()
		end,
		GetFaction = function()
			local faction = UnitFactionGroup("player")
			return faction
		end,
		Random = function(low, high)
			return math.random(low, high)
		end,
		GetTime = function()
			return GetTime()
		end,
		ProfileMilliseconds = function()
			if type(debugprofilestop) ~= "function" then
				return nil
			end
			local ok, value = pcall(debugprofilestop)
			return ok and QuestTogether:SafeToNumber(value) or nil
		end,
		GetServerTime = function()
			if type(GetServerTime) ~= "function" then
				return nil
			end
			local ok, value = pcall(GetServerTime)
			return ok and QuestTogether:SafeToNumber(value) or nil
		end,
		ReloadUI = function()
			if type(ReloadUI) ~= "function" then
				return false
			end
			local ok = pcall(ReloadUI)
			return ok and true or false
		end,
		IsModifiedClick = function(action)
			if type(IsModifiedClick) ~= "function" then
				return false
			end
			local ok, modified = pcall(IsModifiedClick, action)
			return ok and modified and true or false
		end,
		UnitExists = function(unitToken)
			local ok, exists = pcall(UnitExists, unitToken)
			return ok and CanAccessForeignValue(exists) and exists == true
		end,
		UnitIsUnit = function(leftUnitToken, rightUnitToken)
			if type(UnitIsUnit) ~= "function" then
				return false
			end
			local ok, isSameUnit = pcall(UnitIsUnit, leftUnitToken, rightUnitToken)
			if not ok or not CanAccessForeignValue(isSameUnit) then
				return false
			end
			return isSameUnit and true or false
		end,
		UnitGUID = function(unitToken)
			local ok, guidValue = pcall(UnitGUID, unitToken)
			if not ok or not CanAccessForeignValue(guidValue) then
				return nil
			end
			return guidValue
		end,
		UnitFullName = function(unitToken)
			local ok, rawUnitName, rawUnitRealm = pcall(UnitFullName, unitToken)
			if not ok then
				return nil, nil
			end
			return ReadOptionalString(rawUnitName), ReadOptionalString(rawUnitRealm)
		end,
		RegionalUniqueNamesEnabled = function()
			if type(RegionalUniqueNamesEnabled) ~= "function" then
				return false
			end
			local ok, enabled = pcall(RegionalUniqueNamesEnabled)
			if ok and CanAccessForeignValue(enabled) and type(enabled) == "boolean" then
				return enabled
			end
			return nil
		end,
		ShouldDisplaySurname = function()
			if not CanAccessForeignTable(C_PlayerInfo) then
				return nil
			end
			local getter = C_PlayerInfo.ShouldDisplaySurname
			if not CanAccessForeignValue(getter) or type(getter) ~= "function" then
				return nil
			end
			local ok, display = pcall(getter)
			if ok and CanAccessForeignValue(display) and type(display) == "boolean" then
				return display
			end
			return nil
		end,
		UnitClass = function(unitToken)
			local ok, rawClassName, rawClassFile = pcall(UnitClass, unitToken)
			if not ok then
				return nil, nil
			end
			return ReadOptionalString(rawClassName), ReadOptionalString(rawClassFile)
		end,
		UnitRace = function(unitToken)
			local ok, raceName = pcall(UnitRace, unitToken)
			if not ok then
				return nil
			end
			if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(raceName) then
				return nil
			end
			return raceName
		end,
		GetPlayerRaceID = function()
			local ok, _, _, raceID = pcall(UnitRace, "player")
			local id = ok and QuestTogether:SafeToNumber(raceID) or nil
			return id and id >= 1 and id <= 100000 and id == math.floor(id) and id or nil
		end,
		GetLocalizedRaceName = function(raceID)
			local id = QuestTogether:SafeToNumber(raceID)
			if not id or id < 1 or id > 100000 or id ~= math.floor(id) or not CanAccessForeignTable(C_CreatureInfo) then
				return nil
			end
			local getter = C_CreatureInfo.GetRaceInfo
			if not CanAccessForeignValue(getter) or type(getter) ~= "function" then
				return nil
			end
			local ok, info = pcall(getter, id)
			if not ok or not CanAccessForeignTable(info) then
				return nil
			end
			return ReadOptionalString(info.raceName)
		end,
		GetLocalizedClassName = function(classFile)
			local token = ReadOptionalString(classFile)
			if not token or not CanAccessForeignTable(LOCALIZED_CLASS_NAMES_MALE) then
				return nil
			end
			return ReadOptionalString(LOCALIZED_CLASS_NAMES_MALE[token])
		end,
		UnitLevel = function(unitToken)
			local ok, levelValue = pcall(UnitLevel, unitToken)
			if not ok then
				return nil
			end
			if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(levelValue) then
				return nil
			end
			return levelValue
		end,
		UnitName = function(unitToken)
			local ok, unitName = pcall(UnitName, unitToken)
			if not ok or not CanAccessForeignValue(unitName) then
				return nil
			end
			return unitName
		end,
		UnitHealth = function(unitToken)
			local ok, unitHealth = pcall(UnitHealth, unitToken)
			if not ok then
				return nil
			end
			if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(unitHealth) then
				return nil
			end
			return unitHealth
		end,
		UnitHealthMax = function(unitToken)
			local ok, maxHealth = pcall(UnitHealthMax, unitToken)
			if not ok then
				return nil
			end
			if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(maxHealth) then
				return nil
			end
			return maxHealth
		end,
		UnitIsDeadOrGhost = function(unitToken)
			if type(UnitIsDeadOrGhost) == "function" then
				local ok, result = pcall(UnitIsDeadOrGhost, unitToken)
				return ok and result and true or false
			end
			if type(UnitIsDead) == "function" then
				local ok, result = pcall(UnitIsDead, unitToken)
				return ok and result and true or false
			end
			return false
		end,
		UnitIsFriend = function(left, right)
			if type(UnitIsFriend) ~= "function" then
				return nil
			end
			local ok, friendly = pcall(UnitIsFriend, left, right)
			if ok and CanAccessForeignValue(friendly) and type(friendly) == "boolean" then
				return friendly
			end
			return nil
		end,
		UnitIsPlayer = function(unitToken)
			local ok, result = pcall(UnitIsPlayer, unitToken)
			return ok and CanAccessForeignValue(result) and result == true
		end,
		GetLayerObservationUnit = function(unitToken)
			-- All results are checked before use; observations never mutate native units.
			for _, query in ipairs({ "UnitExists", "UnitIsVisible" }) do
				local fn = _G[query]
				if type(fn) ~= "function" then
					return nil
				end
				local ok, value = pcall(fn, unitToken)
				if not ok or not CanAccessForeignValue(value) or value ~= true then
					return nil
				end
			end
			if type(UnitPlayerControlled) ~= "function" then
				return nil
			end
			local okControlled, controlled = pcall(UnitPlayerControlled, unitToken)
			local okGUID, guid = pcall(UnitGUID, unitToken)
			if
				not okControlled
				or not CanAccessForeignValue(controlled)
				or type(controlled) ~= "boolean"
				or not okGUID
				or not CanAccessForeignValue(guid)
				or type(guid) ~= "string"
			then
				return nil
			end
			if type(UnitPhaseReason) == "function" then
				local ok, reason = pcall(UnitPhaseReason, unitToken)
				if not ok or not CanAccessForeignValue(reason) or reason ~= nil then
					return nil
				end
			end
			return { guid = guid, controlled = controlled }
		end,
		CanTargetUnitForEmote = function(unitToken)
			if not CanAccessForeignValue(unitToken) or type(unitToken) ~= "string" then
				return false
			end
			-- A name or a map dot is not evidence that the unit is in this layer.
			if
				unitToken ~= "target"
				and unitToken ~= "mouseover"
				and unitToken ~= "focus"
				and not unitToken:match("^nameplate%d+$")
			then
				return false
			end
			for _, query in ipairs({ "UnitExists", "UnitIsPlayer", "UnitIsVisible" }) do
				local fn = _G[query]
				if type(fn) ~= "function" then
					return false
				end
				local ok, value = pcall(fn, unitToken)
				if not ok or not CanAccessForeignValue(value) or value ~= true then
					return false
				end
			end
			if type(UnitPhaseReason) == "function" then
				local ok, reason = pcall(UnitPhaseReason, unitToken)
				if not ok or not CanAccessForeignValue(reason) or reason ~= nil then
					return false
				end
			elseif type(UnitInPhase) == "function" then
				local ok, inPhase = pcall(UnitInPhase, unitToken)
				if not ok or not CanAccessForeignValue(inPhase) or inPhase ~= true then
					return false
				end
			end
			return true
		end,
		GetQuestLogIndexForQuestID = function(questID)
			if InCombatLockdown and InCombatLockdown() then
				return nil
			end
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil
			end
			local snapshotState = QuestTogether
					and QuestTogether.GetQuestSnapshotStateStore
					and QuestTogether:GetQuestSnapshotStateStore()
				or nil
			local snapshotByQuestID = snapshotState and snapshotState.byQuestID or nil
			local snapshot = snapshotByQuestID and snapshotByQuestID[numericQuestID] or nil
			if type(snapshot) == "table" then
				local snapshotQuestLogIndex = QuestTogether
						and QuestTogether.SafeToNumber
						and QuestTogether:SafeToNumber(snapshot.questLogIndex)
					or nil
				if snapshotQuestLogIndex and snapshotQuestLogIndex > 0 then
					local rowIndex = math.floor(snapshotQuestLogIndex + 0.5)
					local row = QuestTogether.API.GetQuestLogInfo(rowIndex)
					if row and QuestTogether:NormalizeQuestID(row.questID) == numericQuestID then
						return rowIndex
					end
				end
			end
			local rawCount = QuestTogether
					and QuestTogether.API
					and QuestTogether.API.GetNumQuestLogEntries
					and QuestTogether.API.GetNumQuestLogEntries()
				or 0
			local numericCount = QuestTogether and QuestTogether.SafeToNumber and QuestTogether:SafeToNumber(rawCount)
				or nil
			if numericCount and numericCount > 0 then
				numericCount = math.floor(numericCount + 0.5)
				for questLogIndex = 1, numericCount do
					local entryInfo = QuestTogether
							and QuestTogether.API
							and QuestTogether.API.GetQuestLogInfo
							and QuestTogether.API.GetQuestLogInfo(questLogIndex)
						or nil
					local normalizedEntryQuestID = entryInfo
							and QuestTogether
							and QuestTogether.NormalizeQuestID
							and QuestTogether:NormalizeQuestID(entryInfo.questID)
						or nil
					if normalizedEntryQuestID == numericQuestID then
						return questLogIndex
					end
				end
			end
			return nil
		end,
		IsQuestFlaggedCompleted = function(questID)
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil
			end
			if C_QuestLog and C_QuestLog.IsQuestFlaggedCompleted then
				local ok, isCompleted = pcall(C_QuestLog.IsQuestFlaggedCompleted, numericQuestID)
				if ok and CanAccessForeignValue(isCompleted) and type(isCompleted) == "boolean" then
					return isCompleted
				end
				return nil
			end
			return nil
		end,
		GetCharacterQuestHistoryStatus = function(questID)
			local id = QuestTogether:SafeToNumber(questID)
			if not id or id < 1 or id > 1000000000 or id % 1 ~= 0
				or QuestTogether:IsRuntimeRestricted() or not CanAccessForeignTable(C_QuestLog) then return "unknown" end
			local function Read(method)
				local fn = C_QuestLog[method]
				if not CanAccessForeignValue(fn) or type(fn) ~= "function" then return nil end
				local ok, value = pcall(fn, id)
				if ok and CanAccessForeignValue(value) and type(value) == "boolean" then return value end
				return nil
			end
			-- Absence from the active log is not itself evidence of completion.
			local active = Read("IsOnQuest")
			if active == true then return "active" end
			if active ~= false then return "unknown" end
			local repeatable = Read("IsRepeatableQuest")
			if repeatable == true then return "repeatable" end
			if repeatable ~= false then return "unknown" end
			local completed = Read("IsQuestFlaggedCompleted")
			if completed == true then return "completed" end
			return completed == false and "incomplete" or "unknown"
		end,
		IsQuestReadyForTurnIn = function(questID)
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil
			end
			if C_QuestLog and C_QuestLog.ReadyForTurnIn then
				local ok, isReady = pcall(C_QuestLog.ReadyForTurnIn, numericQuestID)
				if ok and CanAccessForeignValue(isReady) and type(isReady) == "boolean" then
					return isReady
				end
				return nil
			end
			return nil
		end,
		IsQuestComplete = function(questID)
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil
			end
			if C_QuestLog and C_QuestLog.IsComplete then
				local ok, isComplete = pcall(C_QuestLog.IsComplete, numericQuestID)
				if ok and CanAccessForeignValue(isComplete) and type(isComplete) == "boolean" then
					return isComplete
				end
				return nil
			end
			return nil
		end,
		GetQuestClassification = function(questID)
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil
			end

			if C_QuestInfoSystem and C_QuestInfoSystem.GetQuestClassification then
				local ok, classification = pcall(C_QuestInfoSystem.GetQuestClassification, numericQuestID)
				if ok and CanAccessForeignValue(classification) then
					local normalizedClassification = QuestTogether
							and QuestTogether.SafeToNumber
							and QuestTogether:SafeToNumber(classification)
						or nil
					if normalizedClassification ~= nil and normalizedClassification >= 0 then
						return math.floor(normalizedClassification + 0.5)
					end
				end
			end

			local questLogIndex = QuestTogether
					and QuestTogether.API
					and QuestTogether.API.GetQuestLogIndexForQuestID
					and QuestTogether.API.GetQuestLogIndexForQuestID(numericQuestID)
				or nil
			if not questLogIndex then
				return nil
			end

			local questInfo = QuestTogether
					and QuestTogether.API
					and QuestTogether.API.GetQuestLogInfo
					and QuestTogether.API.GetQuestLogInfo(questLogIndex)
				or nil
			if type(questInfo) ~= "table" then
				return nil
			end

			return SanitizeQuestInfoEnumValue(questInfo.questClassification)
		end,
		GetQuestFrequency = function(questID)
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil
			end

			local questLogIndex = QuestTogether
					and QuestTogether.API
					and QuestTogether.API.GetQuestLogIndexForQuestID
					and QuestTogether.API.GetQuestLogIndexForQuestID(numericQuestID)
				or nil
			if not questLogIndex then
				return nil
			end

			local questInfo = QuestTogether
					and QuestTogether.API
					and QuestTogether.API.GetQuestLogInfo
					and QuestTogether.API.GetQuestLogInfo(questLogIndex)
				or nil
			if type(questInfo) ~= "table" then
				return nil
			end

			return SanitizeQuestInfoEnumValue(questInfo.frequency)
		end,
		GetQuestTagAtlas = function(tagID, worldQuestType)
			if type(QuestUtils_GetQuestTagAtlas) ~= "function" then
				return nil
			end

			local normalizedTagID = SanitizeQuestInfoEnumValue(tagID)
			local normalizedWorldQuestType = SanitizeQuestInfoEnumValue(worldQuestType)
			local ok, atlas = pcall(QuestUtils_GetQuestTagAtlas, normalizedTagID, normalizedWorldQuestType)
			if not ok then
				return nil
			end
			if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(atlas) then
				return nil
			end
			if type(atlas) ~= "string" or atlas == "" then
				return nil
			end

			return atlas
		end,
		GetQuestPoiTagType = function(questID)
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil
			end

			local currentMapID = QuestTogether
					and QuestTogether.API
					and QuestTogether.API.GetPlayerMapID
					and QuestTogether.API.GetPlayerMapID("player")
				or nil
			if not currentMapID then
				return nil
			end

			local questPois = QuestTogether
					and QuestTogether.API
					and QuestTogether.API.GetQuestPOIsOnMap
					and QuestTogether.API.GetQuestPOIsOnMap(currentMapID)
				or nil
			if type(questPois) ~= "table" then
				return nil
			end

			for index = 1, #questPois do
				local poiInfo = questPois[index]
				if type(poiInfo) == "table" then
					local poiQuestID = QuestTogether
							and QuestTogether.NormalizeQuestID
							and QuestTogether:NormalizeQuestID(poiInfo.questID)
						or nil
					if poiQuestID == numericQuestID then
						return SanitizeQuestInfoEnumValue(poiInfo.questTagType)
					end
				end
			end

			return nil
		end,
		IsQuestOnMap = function(questID)
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return false
			end
			if C_QuestLog and C_QuestLog.IsOnMap then
				local ok, isOnMap = pcall(C_QuestLog.IsOnMap, numericQuestID)
				if not ok then
					return false
				end
				if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(isOnMap) then
					return false
				end
				if type(isOnMap) == "boolean" then
					return isOnMap
				end
				local numericFlag = QuestTogether and QuestTogether.SafeToNumber and QuestTogether:SafeToNumber(isOnMap)
					or nil
				if numericFlag ~= nil then
					return numericFlag ~= 0
				end
			end
			return false
		end,
		IsWorldQuest = function(questID)
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil
			end
			if C_QuestLog and C_QuestLog.IsWorldQuest then
				local ok, isWorldQuest = pcall(C_QuestLog.IsWorldQuest, numericQuestID)
				if not ok then
					return nil
				end
				if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(isWorldQuest) then
					return nil
				end
				if type(isWorldQuest) == "boolean" then
					return isWorldQuest
				end
				local numericFlag = QuestTogether
						and QuestTogether.SafeToNumber
						and QuestTogether:SafeToNumber(isWorldQuest)
					or nil
				if numericFlag ~= nil then
					return numericFlag ~= 0
				end
			end
			return nil
		end,
		IsTaskQuestActive = function(questID)
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil
			end
			if C_TaskQuest and C_TaskQuest.IsActive then
				local ok, isActive = pcall(C_TaskQuest.IsActive, numericQuestID)
				if not ok then
					return nil
				end
				if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(isActive) then
					return nil
				end
				if type(isActive) == "boolean" then
					return isActive
				end
				local numericFlag = QuestTogether
						and QuestTogether.SafeToNumber
						and QuestTogether:SafeToNumber(isActive)
					or nil
				if numericFlag ~= nil then
					return numericFlag ~= 0
				end
			end
			return nil
		end,
		GetTaskQuestInfoByQuestID = function(questID)
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil
			end
			if not (C_TaskQuest and C_TaskQuest.GetQuestInfoByQuestID) then
				return nil
			end

			local ok, rawQuestTitle, factionID, capped, displayAsObjective =
				pcall(C_TaskQuest.GetQuestInfoByQuestID, numericQuestID)
			if not ok then
				return nil
			end

			local function NormalizeBooleanFlag(rawValue)
				if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(rawValue) then
					return nil
				end
				if type(rawValue) == "boolean" then
					return rawValue
				end
				local numericFlag = QuestTogether
						and QuestTogether.SafeToNumber
						and QuestTogether:SafeToNumber(rawValue)
					or nil
				if numericFlag ~= nil then
					return numericFlag ~= 0
				end
				return nil
			end

			local questTitle = ReadOptionalString(rawQuestTitle)
			if questTitle == "" then
				questTitle = nil
			end

			local normalizedFactionID = QuestTogether
					and QuestTogether.SafeToNumber
					and QuestTogether:SafeToNumber(factionID)
				or nil
			if normalizedFactionID ~= nil then
				normalizedFactionID = math.floor(normalizedFactionID + 0.5)
				if normalizedFactionID <= 0 then
					normalizedFactionID = nil
				end
			end

			return {
				questTitle = questTitle,
				factionID = normalizedFactionID,
				capped = NormalizeBooleanFlag(capped),
				displayAsObjective = NormalizeBooleanFlag(displayAsObjective),
			}
		end,
		GetTaskInfo = function(questID)
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil, nil, nil, nil, nil
			end
			if type(GetTaskInfo) ~= "function" then
				return nil, nil, nil, nil, nil
			end

			local ok, isInArea, isOnMap, numObjectives, taskName, displayAsObjective =
				pcall(GetTaskInfo, numericQuestID)
			if not ok then
				return nil, nil, nil, nil, nil
			end

			local function NormalizeBooleanFlag(rawValue)
				if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(rawValue) then
					return nil
				end
				if type(rawValue) == "boolean" then
					return rawValue
				end
				local numericFlag = QuestTogether
						and QuestTogether.SafeToNumber
						and QuestTogether:SafeToNumber(rawValue)
					or nil
				if numericFlag ~= nil then
					return numericFlag ~= 0
				end
				return nil
			end

			local normalizedInArea = NormalizeBooleanFlag(isInArea)
			local normalizedOnMap = NormalizeBooleanFlag(isOnMap)
			local normalizedDisplayAsObjective = NormalizeBooleanFlag(displayAsObjective)

			local normalizedObjectiveCount = nil
			if not (QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(numObjectives)) then
				normalizedObjectiveCount = QuestTogether
						and QuestTogether.SafeToNumber
						and QuestTogether:SafeToNumber(numObjectives)
					or nil
				if normalizedObjectiveCount ~= nil then
					normalizedObjectiveCount = math.floor(normalizedObjectiveCount + 0.5)
					if normalizedObjectiveCount < 0 then
						normalizedObjectiveCount = 0
					end
				end
			end

			if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(taskName) then
				taskName = nil
			end
			if type(taskName) ~= "string" or taskName == "" then
				taskName = nil
			end

			return normalizedInArea, normalizedOnMap, normalizedObjectiveCount, taskName, normalizedDisplayAsObjective
		end,
		GetNamePlateForUnit = function(unitToken)
			if not (C_NamePlate and C_NamePlate.GetNamePlateForUnit) then
				return nil
			end
			if type(unitToken) ~= "string" or unitToken == "" then
				return nil
			end

			local ok, namePlateFrameBase = pcall(C_NamePlate.GetNamePlateForUnit, unitToken, false)
			if not ok or not CanAccessForeignValue(namePlateFrameBase) then
				return nil
			end
			return namePlateFrameBase
		end,
		GetNamePlates = function()
			if not (C_NamePlate and C_NamePlate.GetNamePlates) then
				return {}
			end

			local ok, rawNameplates = pcall(C_NamePlate.GetNamePlates, false)
			if not ok or not CanAccessForeignTable(rawNameplates) then
				return {}
			end

			local nameplates = {}
			local okCopy = pcall(function()
				for _, frame in pairs(rawNameplates) do
					if CanAccessForeignValue(frame) then
						nameplates[#nameplates + 1] = frame
					end
				end
			end)
			if not okCopy then
				return {}
			end
			return nameplates
		end,
		GetPlayerMapID = function(unitToken)
			if not (C_Map and C_Map.GetBestMapForUnit) then
				return nil
			end

			local normalizedUnitToken = type(unitToken) == "string" and unitToken ~= "" and unitToken or "player"
			local ok, mapID = pcall(C_Map.GetBestMapForUnit, normalizedUnitToken)
			if not ok then
				return nil
			end
			if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(mapID) then
				return nil
			end
			local numericMapID = QuestTogether and QuestTogether.SafeToNumber and QuestTogether:SafeToNumber(mapID)
				or nil
			if not numericMapID or numericMapID <= 0 then
				return nil
			end
			return math.floor(numericMapID + 0.5)
		end,
		IsWorldMapVisible = function()
			local frame = WorldMapFrame
			if not CanAccessForeignValue(frame) then
				return true
			end
			if not frame then
				return false
			end
			local isShown = QuestTogether:GetAccessibleFrameMember(frame, "IsShown")
			if type(isShown) ~= "function" then
				-- Forbidden/unreadable map state must not permit sensitive reads.
				return true
			end
			local okShown, shown = pcall(isShown, frame)
			if not okShown or not CanAccessForeignValue(shown) or type(shown) ~= "boolean" then
				return true
			end
			return shown
		end,
		GetLocalTaskQuests = function()
			if type(GetTasksTable) ~= "function" then
				return nil
			end

			-- Blizzard's objective tracker uses GetTasksTable() as the local-area task list.
			-- Call it behind pcall for transient quest-log races, then copy only scalar quest IDs
			-- out so we never retain Blizzard-owned tables.
			local ok, tasks = pcall(GetTasksTable)
			if not ok or (QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(tasks)) then
				return nil
			end
			if type(tasks) ~= "table" then
				return nil
			end

			local questIds = {}
			for index = 1, #tasks do
				local questID = tasks[index]
				if not (QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(questID)) then
					local numericQuestID = QuestTogether
							and QuestTogether.SafeToNumber
							and QuestTogether:SafeToNumber(questID)
						or nil
					if numericQuestID and numericQuestID > 0 then
						questIds[#questIds + 1] = math.floor(numericQuestID + 0.5)
					end
				end
			end

			return questIds
		end,
		GetTaskQuestsOnMap = function(mapID)
			local numericMapID = QuestTogether and QuestTogether.SafeToNumber and QuestTogether:SafeToNumber(mapID)
				or nil
			if not numericMapID or numericMapID <= 0 then
				return nil
			end
			numericMapID = math.floor(numericMapID + 0.5)

			if not C_TaskQuest then
				return nil
			end
			local getTaskQuestsForMap = C_TaskQuest.GetQuestsOnMap
			local questIDField = "questID"
			if type(getTaskQuestsForMap) ~= "function" then
				getTaskQuestsForMap = C_TaskQuest.GetQuestsForPlayerByMapID
				questIDField = "questId"
			end
			if type(getTaskQuestsForMap) ~= "function" then
				return nil
			end

			local ok, tasks = pcall(getTaskQuestsForMap, numericMapID)
			if not ok or not CanAccessForeignTable(tasks) then
				return nil
			end

			local questIds = {}
			for index = 1, #tasks do
				local taskInfo = tasks[index]
				if CanAccessForeignTable(taskInfo) then
					local questID = taskInfo[questIDField]
					if CanAccessForeignValue(questID) then
						local numericQuestID = QuestTogether
								and QuestTogether.SafeToNumber
								and QuestTogether:SafeToNumber(questID)
							or nil
						if numericQuestID and numericQuestID > 0 then
							questIds[#questIds + 1] = math.floor(numericQuestID + 0.5)
						end
					end
				end
			end

			return questIds
		end,
		GetTaskQuestTitle = function(questID)
			local numericQuestID = QuestTogether and QuestTogether.SafeToNumber and QuestTogether:SafeToNumber(questID)
				or nil
			if not numericQuestID or numericQuestID <= 0 then
				return nil
			end
			numericQuestID = math.floor(numericQuestID + 0.5)

			if not (C_TaskQuest and C_TaskQuest.GetQuestInfoByQuestID) then
				return nil
			end

			local ok, questTitle = pcall(C_TaskQuest.GetQuestInfoByQuestID, numericQuestID)
			if
				not ok or (QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(questTitle))
			then
				return nil
			end
			if type(questTitle) ~= "string" or questTitle == "" then
				return nil
			end

			return questTitle
		end,
		GetQuestPOIsOnMap = function(mapID)
			local numericMapID = QuestTogether and QuestTogether.SafeToNumber and QuestTogether:SafeToNumber(mapID)
				or nil
			if not numericMapID or numericMapID <= 0 then
				return nil
			end
			numericMapID = math.floor(numericMapID + 0.5)

			if not (C_QuestLog and C_QuestLog.GetQuestsOnMap) then
				return nil
			end

			local ok, pois = pcall(C_QuestLog.GetQuestsOnMap, numericMapID)
			if not ok or not CanAccessForeignTable(pois) then
				return nil
			end

			local sanitized = {}
			for index = 1, #pois do
				local poi = pois[index]
				if CanAccessForeignTable(poi) then
					local questID = poi.questID
					if CanAccessForeignValue(questID) then
						local numericQuestID = QuestTogether
								and QuestTogether.SafeToNumber
								and QuestTogether:SafeToNumber(questID)
							or nil
						if numericQuestID and numericQuestID > 0 then
							local function NormalizeBool(rawValue)
								if not CanAccessForeignValue(rawValue) then
									return nil
								end
								if type(rawValue) == "boolean" then
									return rawValue
								end
								local numericFlag = QuestTogether
										and QuestTogether.SafeToNumber
										and QuestTogether:SafeToNumber(rawValue)
									or nil
								if numericFlag ~= nil then
									return numericFlag ~= 0
								end
								return nil
							end

							local questTagType = nil
							if CanAccessForeignValue(poi.questTagType) then
								questTagType = QuestTogether
										and QuestTogether.SafeToNumber
										and QuestTogether:SafeToNumber(poi.questTagType)
									or nil
								if questTagType ~= nil then
									questTagType = math.floor(questTagType + 0.5)
								end
							end

							sanitized[#sanitized + 1] = {
								questID = math.floor(numericQuestID + 0.5),
								inProgress = NormalizeBool(poi.inProgress),
								isQuestStart = NormalizeBool(poi.isQuestStart),
								isMapIndicatorQuest = NormalizeBool(poi.isMapIndicatorQuest),
								questTagType = questTagType,
							}
						end
					end
				end
			end

			return sanitized
		end,
		IsOnQuest = function(questID)
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil
			end
			if C_QuestLog and C_QuestLog.IsOnQuest then
				local ok, isOnQuest = pcall(C_QuestLog.IsOnQuest, numericQuestID)
				if ok and CanAccessForeignValue(isOnQuest) and type(isOnQuest) == "boolean" then
					return isOnQuest
				end
				return nil
			end
			return nil
		end,
		IsPushableQuest = function(questID)
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil
			end
			if C_QuestLog and C_QuestLog.IsPushableQuest then
				local ok, isPushable = pcall(C_QuestLog.IsPushableQuest, numericQuestID)
				if ok and CanAccessForeignValue(isPushable) and type(isPushable) == "boolean" then
					return isPushable
				end
				return nil
			end
			-- Classic's legacy query applies to the selected quest. Read it only
			-- when selection already matches; never move the user's selection.
			if type(GetQuestLogSelection) == "function" and type(GetQuestLogPushable) == "function" then
				local selectionOK, selection = pcall(GetQuestLogSelection)
				local index = selectionOK and QuestTogether:SafeToNumber(selection) or nil
				local row = index and index > 0 and QuestTogether.API.GetQuestLogInfo(index) or nil
				if row and QuestTogether:NormalizeQuestID(row.questID) == numericQuestID then
					local ok, pushable = pcall(GetQuestLogPushable)
					if ok and CanAccessForeignValue(pushable) and type(pushable) == "boolean" then
						return pushable
					end
				end
			end
			return nil
		end,
		CanShareQuests = function()
			-- Retail/Forever share by log index. Do not fall back to moving the
			-- selected quest on clients with only the legacy sharing API.
			return type(QuestLogPushQuest) == "function"
				and C_QuestLog ~= nil
				and type(C_QuestLog.GetLogIndexForQuestID) == "function"
				and type(C_QuestLog.GetInfo) == "function"
				and type(C_QuestLog.IsPushableQuest) == "function"
		end,
		GetQuestShareResultFormats = function()
			local result = {}
			if QuestTogether:IsRuntimeRestricted() then return result end
			for _, suffix in ipairs({ "ACCEPTED", "ALREADY_DONE", "BUSY", "DEAD", "DECLINED",
				"DIFFERENT_SERVER_DAILY", "INVALID", "LOG_FULL", "NOT_ALLOWED", "NOT_DAILY",
				"NOT_IN_PARTY", "ONQUEST", "SUCCESS", "TIMER_EXPIRED", "TOO_FAR" }) do
				local key = "ERR_QUEST_PUSH_" .. suffix .. "_S"
				local value = _G[key]
				if CanAccessForeignValue(value) and type(value) == "string" and #value > 0 and #value <= 1024 then
					result[key] = value
				end
			end
			return result
		end,
		GetQuestLogIndexForSharing = function(questID)
			local id = QuestTogether:SafeToNumber(questID)
			if not id or id <= 0 or id ~= math.floor(id) or not QuestTogether.API.CanShareQuests() then
				return nil
			end
			-- Resolve live data, not a cached index or the currently selected quest.
			local ok, rawIndex = pcall(C_QuestLog.GetLogIndexForQuestID, id)
			local index = ok and QuestTogether:SafeToNumber(rawIndex) or nil
			if not index or index <= 0 or index ~= math.floor(index) then
				return nil
			end
			local rowOK, row = pcall(C_QuestLog.GetInfo, index)
			if not rowOK or not CanAccessForeignTable(row) then
				return nil
			end
			if
				not CanAccessForeignValue(row.isHeader)
				or row.isHeader == true
				or QuestTogether:SafeToNumber(row.questID) ~= id
			then
				return nil
			end
			return index
		end,
		PushQuestToParty = function(questLogIndex)
			local index = QuestTogether:SafeToNumber(questLogIndex)
			if not index or index <= 0 or index ~= math.floor(index) or not QuestTogether.API.CanShareQuests() then
				return false
			end
			-- The caller rechecks eligibility and restrictions immediately before
			-- dispatch. A successful invocation is an attempt, not acceptance.
			local ok = pcall(QuestLogPushQuest, index)
			return ok
		end,
		GetMinimapAnchor = function()
			return Minimap
		end,
		IsPartyQuestKeyboardInputBlocked = function(frame)
			if not QuestTogether:CanMutateOwnedUI(frame) or QuestTogether:IsRuntimeRestricted() then return true end
			if type(GetCurrentKeyBoardFocus) ~= "function" then return true end
			local ok, focus = pcall(GetCurrentKeyBoardFocus)
			if not ok or not CanAccessForeignValue(focus) or focus ~= nil then return true end
			if Menu and type(Menu.GetManager) == "function" then
				local managerOK, manager = pcall(Menu.GetManager)
				if not managerOK or not CanAccessForeignTable(manager) then return true end
				if type(manager.IsAnyMenuOpen) ~= "function" then return true end
				local menuOK, opened = pcall(manager.IsAnyMenuOpen, manager)
				if not menuOK or not CanAccessForeignValue(opened) or opened == true then return true end
			end
			return false
		end,
		IsMouseOverPartyQuestWindow = function(frame)
			if not QuestTogether:CanMutateOwnedUI(frame) then return false end
			local fn = QuestTogether:GetAccessibleFrameMember(frame, "IsMouseOver")
			if type(fn) ~= "function" then return false end
			local ok, over = pcall(fn, frame)
			return ok and CanAccessForeignValue(over) and over == true
		end,
		OpenKeyBindings = function()
			if QuestTogether:IsWorkBlocked("foreign_frame_mutation") or not Settings
				or type(Settings.OpenToCategory) ~= "function" then return false end
			local id = QuestTogether:SafeToNumber(Settings.KEYBINDINGS_CATEGORY_ID)
			if not id then return false end
			return pcall(Settings.OpenToCategory, id, "QuestTogether")
		end,
		GetPlayerNotesNamespace = function()
			local region = "default"
			if type(GetCurrentRegion) == "function" then
				local ok, value = pcall(GetCurrentRegion)
				local number = ok and QuestTogether:SafeToNumber(value)
				if number then region = tostring(number) end
			end
			local project = QuestTogether:SafeToNumber(WOW_PROJECT_ID) or 0
			return tostring(project) .. ":" .. region .. ":" .. (QuestTogether:UsesRegionalPlayerNames() and "regional" or "realm")
		end,
		GetHintCapabilities = function()
			-- Read capabilities, never the player's current quest, party or map.
			local function Has(object, ...)
				if not CanAccessForeignTable(object) then return false end
				for index = 1, select("#", ...) do
					local value = object[select(index, ...)]
					if not CanAccessForeignValue(value) or type(value) ~= "function" then return false end
				end
				return true
			end
			local focus = Has(C_SuperTrack, "IsSuperTrackingQuest", "GetSuperTrackedQuestID", "SetSuperTrackedQuestID")
			local waypoint = Has(C_Map, "GetUserWaypoint", "SetUserWaypoint") and Has(UiMapPoint, "CreateFromCoordinates")
			local nativeNavigation = waypoint and Has(C_Map, "CanSetUserWaypointOnMap")
				and Has(C_SuperTrack, "SetSuperTrackedUserWaypoint")
			local navigation = nativeNavigation or Has(TomTom, "AddWaypoint")
			local editMode = QuestTogether.API.GetEditModeManagerFrame()
			local hud = QuestTogether:CanAccessForeignFrame(editMode)
				and type(QuestTogether:GetAccessibleFrameMember(editMode, "CanEnterEditMode")) == "function"
			if not hud and Has(C_AddOns, "GetAddOnInfo") then
				local ok, name = pcall(C_AddOns.GetAddOnInfo, "Blizzard_EditMode")
				hud = ok and CanAccessForeignValue(name) and type(name) == "string" and name == "Blizzard_EditMode"
			end
			local retail = CanAccessForeignValue(WOW_PROJECT_ID) and CanAccessForeignValue(WOW_PROJECT_MAINLINE)
				and WOW_PROJECT_MAINLINE ~= nil and WOW_PROJECT_ID == WOW_PROJECT_MAINLINE
				and not QuestTogether:UsesRegionalPlayerNames()
			return {
				menu = Has(MenuUtil, "CreateContextMenu"),
				sharing = QuestTogether.API.CanShareQuests(),
				details = QuestTogether.API.CanOpenQuestDetails(),
				journal = QuestTogether.API.CanOpenQuestJournal(),
				focus = focus, waypoint = waypoint, navigation = navigation,
				navigationFocus = navigation and focus, hud = hud,
				nameplates = Has(C_NamePlate, "GetNamePlateForUnit"),
				worldQuests = retail and Has(C_QuestLog, "IsWorldQuest"),
				bonusObjectives = retail and Has(C_TaskQuest, "GetQuestInfoByQuestID"),
				layers = QuestTogether:UsesRegionalPlayerNames(),
				warMode = QuestTogether:SupportsWarMode() == true,
			}
		end,
		CanOpenQuestDetails = function()
			return C_TooltipInfo ~= nil and type(C_TooltipInfo.GetHyperlink) == "function"
		end,
		GetQuestDetailsLink = function(questID)
			local id = QuestTogether:SafeToNumber(questID)
			if
				not id
				or id <= 0
				or id > 2147483647
				or id ~= math.floor(id)
				or QuestTogether:IsWorkBlocked("foreign_frame_mutation")
				or not QuestTogether.API.CanOpenQuestDetails()
			then
				return nil
			end
			-- Preserve native scaling fields when available; an unowned quest may
			-- not have a cached link. Reading details never opens Blizzard's UI.
			if type(GetQuestLink) == "function" then
				local ok, nativeText = pcall(GetQuestLink, id)
				if ok and CanAccessForeignValue(nativeText) and type(nativeText) == "string" then
					local nativeLink, nativeID = nativeText:match("|H(quest:(%d+):[%d:%-]*)|h[^|]*|h")
					if nativeLink and tonumber(nativeID) == id then
						return nativeLink
					end
				end
			end
			return string.format("quest:%d:0", id)
		end,
		CanOpenQuestJournal = function()
			if
				type(QuestMapFrame_OpenToQuestDetails) ~= "function"
				or type(QuestMapFrame_GetDetailQuestID) ~= "function"
				or not QuestTogether:CanAccessForeignFrame(QuestMapFrame)
			then
				return false
			end
			local details = QuestTogether:GetAccessibleFrameMember(QuestMapFrame, "DetailsFrame")
			return QuestTogether:CanAccessForeignFrame(details)
				and (WorldMapFrame == nil or QuestTogether:CanAccessForeignFrame(WorldMapFrame))
		end,
		OpenQuestJournal = function(questID)
			local id = QuestTogether:SafeToNumber(questID)
			if
				not id
				or id <= 0
				or id ~= math.floor(id)
				or QuestTogether:IsRuntimeRestricted()
				or not QuestTogether.API.CanOpenQuestJournal()
			then
				return false
			end
			-- Use the same quest-by-ID entry point as Blizzard's tracker. It opens
			-- the journal and selects the details without writing our own frame state.
			local ok = pcall(QuestMapFrame_OpenToQuestDetails, id)
			if
				not ok
				or not QuestTogether:CanAccessForeignFrame(WorldMapFrame, true)
				or not QuestTogether:CanAccessForeignFrame(QuestMapFrame, true)
				or not QuestTogether.API.CanOpenQuestJournal()
			then
				return false
			end
			local selectedOK, selectedID = pcall(QuestMapFrame_GetDetailQuestID)
			return selectedOK and QuestTogether:SafeToNumber(selectedID) == id
		end,
		OpenPlayerLocationMap = function(mapID)
			local id = QuestTogether:SafeToNumber(mapID)
			if not id or id <= 0 or id > 2147483647 or id ~= math.floor(id)
				or QuestTogether:IsWorkBlocked("foreign_frame_mutation")
				or type(OpenWorldMap) ~= "function"
				or not QuestTogether:CanAccessForeignFrame(WorldMapFrame) then
				return false
			end
			-- The native opener owns map selection and panel visibility. A silent
			-- decline (for example WorldMapDisabled) is not a successful navigation.
			local ok = pcall(OpenWorldMap, id)
			if not ok or not QuestTogether:CanAccessForeignFrame(WorldMapFrame, true) then return false end
			local getter = QuestTogether:GetAccessibleFrameMember(WorldMapFrame, "GetMapID")
			if type(getter) ~= "function" then return false end
			local readOK, currentID = pcall(getter, WorldMapFrame)
			return readOK and QuestTogether:SafeToNumber(currentID) == id
		end,
		CanOpenQuestJournalWindow = function()
			return type(OpenQuestLog) == "function"
				and QuestTogether:CanAccessForeignFrame(WorldMapFrame)
				and QuestTogether:CanAccessForeignFrame(QuestMapFrame)
		end,
		OpenQuestJournalWindow = function()
			if QuestTogether:IsRuntimeRestricted() or not QuestTogether.API.CanOpenQuestJournalWindow() then
				return false
			end
			-- Retail/Forever expose this non-toggle opener with the world map.
			-- Leave the user's selected quest and journal tab to the native UI.
			local ok = pcall(OpenQuestLog)
			-- The native opener returns nil and can decline to show its panel.
			return ok
				and QuestTogether:CanAccessForeignFrame(WorldMapFrame, true)
				and QuestTogether:CanAccessForeignFrame(QuestMapFrame, true)
		end,
		CreateContextMenu = function(ownerFrame, generator)
			if not MenuUtil or type(MenuUtil.CreateContextMenu) ~= "function" then
				return false
			end
			if not CanAccessForeignValue(ownerFrame) then
				return false
			end
			ownerFrame = ownerFrame or UIParent
			if not QuestTogether:CanAccessForeignFrame(ownerFrame) then
				return false
			end
			local ok, menu = pcall(MenuUtil.CreateContextMenu, ownerFrame, generator)
			return ok and CanAccessForeignValue(menu) and menu ~= nil
		end,
		GetNumQuestLogEntries = function()
			local getter = type(GetNumQuestLogEntries) == "function" and GetNumQuestLogEntries
				or (C_QuestLog and C_QuestLog.GetNumQuestLogEntries)
			if type(getter) ~= "function" then
				return nil
			end
			local ok, count = pcall(getter)
			local numericCount = ok and QuestTogether:SafeToNumber(count) or nil
			if numericCount == nil or numericCount < 0 then
				return nil
			end
			return math.floor(numericCount + 0.5)
		end,
		GetQuestLogInfo = function(questLogIndex)
			local numericQuestLogIndex = QuestTogether
					and QuestTogether.SafeToNumber
					and QuestTogether:SafeToNumber(questLogIndex)
				or nil
			if numericQuestLogIndex == nil then
				return nil
			end
			numericQuestLogIndex = math.floor(numericQuestLogIndex + 0.5)
			if numericQuestLogIndex <= 0 then
				return nil
			end

			local titleInfo = nil
			if type(GetQuestLogTitle) == "function" then
				local okTitle, title, _, _, isHeader, _, isComplete, _, questID, _, displayQuestID, isOnMap, hasLocalPOI, isTask, _ =
					pcall(GetQuestLogTitle, numericQuestLogIndex)
				if okTitle then
					titleInfo = BuildSanitizedQuestLogInfoRecord(
						numericQuestLogIndex,
						title,
						isHeader,
						nil,
						isTask,
						isOnMap,
						hasLocalPOI,
						isComplete,
						questID,
						displayQuestID,
						nil
					)
				end
			end

			if C_QuestLog and C_QuestLog.GetInfo then
				local okInfo, rawInfo = pcall(C_QuestLog.GetInfo, numericQuestLogIndex)
				if okInfo then
					local sanitizedInfo = BuildSanitizedQuestLogInfoFromRawInfo(numericQuestLogIndex, rawInfo)
					if sanitizedInfo then
						return MergeSanitizedQuestLogInfo(sanitizedInfo, titleInfo)
					end
				end
			end

			return titleInfo
		end,
		GetNumQuestLeaderBoards = function(questLogIndex)
			if InCombatLockdown and InCombatLockdown() then
				return 0
			end
			local numericQuestLogIndex = QuestTogether
					and QuestTogether.SafeToNumber
					and QuestTogether:SafeToNumber(questLogIndex)
				or nil
			if numericQuestLogIndex == nil then
				return 0
			end
			numericQuestLogIndex = math.floor(numericQuestLogIndex + 0.5)
			if numericQuestLogIndex <= 0 then
				return 0
			end
			if type(GetNumQuestLeaderBoards) ~= "function" then
				return 0
			end
			local ok, objectiveCount = pcall(GetNumQuestLeaderBoards, numericQuestLogIndex)
			if not ok then
				return 0
			end
			if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(objectiveCount) then
				return 0
			end
			local numericObjectiveCount = QuestTogether
					and QuestTogether.SafeToNumber
					and QuestTogether:SafeToNumber(objectiveCount)
				or nil
			if numericObjectiveCount == nil then
				return 0
			end
			if numericObjectiveCount <= 0 then
				return 0
			end
			return math.floor(numericObjectiveCount + 0.5)
		end,
		GetActiveTrackedQuestID = function()
			-- Scalar navigation state does not query quest tooltips or mutate the map.
			if QuestTogether:IsRuntimeRestricted() or not CanAccessForeignTable(C_SuperTrack) then
				return nil
			end
			local isQuest, getQuest = C_SuperTrack.IsSuperTrackingQuest, C_SuperTrack.GetSuperTrackedQuestID
			if
				not CanAccessForeignValue(isQuest)
				or type(isQuest) ~= "function"
				or not CanAccessForeignValue(getQuest)
				or type(getQuest) ~= "function"
			then
				return nil
			end
			local ok, active = pcall(isQuest)
			if not ok or not CanAccessForeignValue(active) or active ~= true then
				return nil
			end
			local got, id = pcall(getQuest)
			if got then
				id = QuestTogether:SafeToNumber(id)
				if id and id >= 1 and id <= 1000000000 and id == math.floor(id) then
					return id
				end
			end
		end,
		GetPartyNavigationNativeState = function()
			if QuestTogether:IsRuntimeRestricted() then
				return nil
			end
			local result = { questID = -1, mapID = -1, x = 0, y = 0 }
			if
				CanAccessForeignTable(C_SuperTrack)
				and CanAccessForeignValue(C_SuperTrack.IsSuperTrackingQuest)
				and type(C_SuperTrack.IsSuperTrackingQuest) == "function"
				and CanAccessForeignValue(C_SuperTrack.GetSuperTrackedQuestID)
				and type(C_SuperTrack.GetSuperTrackedQuestID) == "function"
			then
				local ok, active = pcall(C_SuperTrack.IsSuperTrackingQuest)
				if not ok or not CanAccessForeignValue(active) or type(active) ~= "boolean" then
					return nil
				end
				if active then
					local id = QuestTogether.API.GetActiveTrackedQuestID()
					if not id then
						return nil
					end
					result.questID = id
				else
					result.questID = 0
					local anything = C_SuperTrack.IsSuperTrackingAnything
					if CanAccessForeignValue(anything) and type(anything) == "function" then
						local got, tracking = pcall(anything)
						if not got or not CanAccessForeignValue(tracking) or type(tracking) ~= "boolean" then
							return nil
						end
						result.questCleared = tracking == false
					end
				end
			end
			if
				CanAccessForeignTable(C_Map)
				and CanAccessForeignValue(C_Map.GetUserWaypoint)
				and type(C_Map.GetUserWaypoint) == "function"
			then
				local ok, point = pcall(C_Map.GetUserWaypoint)
				if not ok or not CanAccessForeignValue(point) then
					return nil
				end
				if point == nil then
					result.mapID = 0
				else
					if not CanAccessForeignTable(point) or not CanAccessForeignTable(point.position) then
						return nil
					end
					local map = QuestTogether:SafeToNumber(point.uiMapID)
					local getter = point.position.GetXY
					if not CanAccessForeignValue(getter) or type(getter) ~= "function" then
						return nil
					end
					local got, x, y = pcall(getter, point.position)
					x, y = QuestTogether:SafeToNumber(x), QuestTogether:SafeToNumber(y)
					if
						not got
						or not map
						or map <= 0
						or map > 1000000
						or map ~= math.floor(map)
						or not x
						or not y
						or x < 0
						or x > 1
						or y < 0
						or y > 1
					then
						return nil
					end
					result.mapID, result.x, result.y = map, x, y
				end
			end
			return result
		end,
		SetPartyNavigationQuest = function(questID)
			if QuestTogether:IsRuntimeRestricted() or not CanAccessForeignTable(C_SuperTrack) then
				return false
			end
			local setter = C_SuperTrack.SetSuperTrackedQuestID
			if not CanAccessForeignValue(setter) or type(setter) ~= "function" then
				return false
			end
			local id = QuestTogether:SafeToNumber(questID)
			if id == 0 then
				local anything = C_SuperTrack.IsSuperTrackingAnything
				if not CanAccessForeignValue(anything) or type(anything) ~= "function" then
					return false
				end
				local ok = pcall(setter, 0)
				if not ok then
					return false
				end
				local got, tracking = pcall(anything)
				return got and CanAccessForeignValue(tracking) and tracking == false
			end
			id = QuestTogether:NormalizeQuestID(id)
			if not id then
				return false
			end
			if QuestTogether.API.IsOnQuest(id) ~= true then
				return false
			end
			local ok = pcall(setter, id)
			return ok and QuestTogether.API.GetActiveTrackedQuestID() == id
		end,
		GetLocalizedQuestTitle = function(questID)
			local id = QuestTogether:SafeToNumber(questID)
			if not id or id <= 0 or id > 1000000000 or id ~= math.floor(id)
				or QuestTogether:IsWorkBlocked("quest_snapshot_refresh") then
				return nil
			end
			local function Title(value)
				if not CanAccessForeignValue(value) or type(value) ~= "string" or #value > 512
					or value:find("[%z\001-\031\127]") then return nil end
				-- Native tooltip headers can be colored. Never retain links, textures,
				-- or other markup in a title that will be put into our own quest link.
				local title = value:gsub("|c%x%x%x%x%x%x%x%x", ""):gsub("|r", "")
				title = QuestTogether:SafeTrimString(title, "")
				if title == "" or title:find("|", 1, true) or title:match("^%d+$")
					or QuestTogether:IsPlaceholderQuestTitle(id, title) then return nil end
				for _, key in ipairs({ "RETRIEVING_DATA", "LOADING", "UNKNOWN", "UNKNOWNOBJECT" }) do
					local placeholder = _G[key]
					if CanAccessForeignValue(placeholder) and type(placeholder) == "string" and title == placeholder then
						return nil
					end
				end
				return title
			end
			local ok, title = pcall(function()
				if CanAccessForeignTable(C_QuestLog) then
					local getter = C_QuestLog.GetTitleForQuestID
					if CanAccessForeignValue(getter) and type(getter) == "function" then
						local got, value = pcall(getter, id)
						local nativeTitle = got and Title(value)
						if nativeTitle then return nativeTitle end
					end
				end
				-- Some clients cache a local hyperlink/tooltip before the quest-title
				-- getter is populated. Read native data only; never select or show UI.
				local hyperlink = string.format("quest:%d:0", id)
				if CanAccessForeignValue(GetQuestLink) and type(GetQuestLink) == "function" then
					local got, link = pcall(GetQuestLink, id)
					if got and CanAccessForeignValue(link) and type(link) == "string" and #link <= 1024 then
						link = link:gsub("^|c%x%x%x%x%x%x%x%x", ""):gsub("|r$", "")
						local nativeLink, nativeID, rawTitle = link:match("^|H(quest:(%d+):[%d:%-]+)|h%[([^|%[%]]+)%]|h$")
						local validFields = nativeLink ~= nil
						if nativeLink then
							for field in nativeLink:sub(#nativeID + 8):gmatch("[^:]+") do
								if not field:match("^%-?%d+$") then validFields = false; break end
							end
						end
						if validFields and tonumber(nativeID) == id then
							hyperlink = nativeLink
							local nativeTitle = Title(rawTitle)
							if nativeTitle then return nativeTitle end
						end
					end
				end
				if not CanAccessForeignTable(C_TooltipInfo) then return nil end
				local getter = C_TooltipInfo.GetHyperlink
				if not CanAccessForeignValue(getter) or type(getter) ~= "function"
					or not CanAccessForeignTable(Enum) or not CanAccessForeignTable(Enum.TooltipDataType)
					or not CanAccessForeignTable(Enum.TooltipDataLineType) then return nil end
				local questType = QuestTogether:SafeToNumber(Enum.TooltipDataType.Quest)
				local titleType = QuestTogether:SafeToNumber(Enum.TooltipDataLineType.QuestTitle)
				local genericType = QuestTogether:SafeToNumber(Enum.TooltipDataLineType.None)
				if not questType or not titleType then return nil end
				local data = QuestTogether.API.GetTooltipDataForHyperlink(hyperlink)
				if not CanAccessForeignTable(data) or not CanAccessForeignValue(data.type) or data.type ~= questType
					or not CanAccessForeignValue(data.id) or (data.id ~= nil and QuestTogether:SafeToNumber(data.id) ~= id)
					or not CanAccessForeignTable(data.lines) then return nil end
				-- The first line is the header. Skipping a missing/loading header to
				-- use a later line could cache objective prose as the quest's name.
				local header = data.lines[1]
				if not CanAccessForeignTable(header) or not CanAccessForeignValue(header.type)
					or (header.type ~= titleType and (genericType == nil or header.type ~= genericType)) then return nil end
				return Title(header.leftText)
			end)
			if ok then return title end
		end,
		RequestLocalizedQuestTitle = function(questID)
			local id = QuestTogether:SafeToNumber(questID)
			if not id or id <= 0 or id > 1000000000 or id ~= math.floor(id)
				or QuestTogether:IsWorkBlocked("quest_snapshot_refresh") or not CanAccessForeignTable(C_QuestLog) then
				return false
			end
			local request = C_QuestLog.RequestLoadQuestByID
			if not CanAccessForeignValue(request) or type(request) ~= "function" then
				return false
			end
			return pcall(request, id)
		end,
		GetQuestObjectiveInfo = function(questID, objectiveIndex, displayComplete)
			if InCombatLockdown and InCombatLockdown() then
				return nil, nil, nil, nil
			end
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil, nil, nil, nil
			end

			local numericObjectiveIndex = QuestTogether
					and QuestTogether.SafeToNumber
					and QuestTogether:SafeToNumber(objectiveIndex)
				or nil
			if numericObjectiveIndex == nil then
				return nil, nil, nil, nil
			end
			numericObjectiveIndex = math.floor(numericObjectiveIndex + 0.5)
			if numericObjectiveIndex <= 0 then
				return nil, nil, nil, nil
			end

			local ok, text, objectiveType, finished, currentValue, requiredValue
			if type(GetQuestObjectiveInfo) == "function" then
				ok, text, objectiveType, finished, currentValue, requiredValue =
					pcall(GetQuestObjectiveInfo, numericQuestID, numericObjectiveIndex, displayComplete)
			elseif C_QuestLog and type(C_QuestLog.GetQuestObjectives) == "function" then
				local queryOK, objectives = pcall(C_QuestLog.GetQuestObjectives, numericQuestID)
				if not queryOK or not CanAccessForeignTable(objectives) then
					return nil, nil, nil, nil
				end
				local objective = objectives[numericObjectiveIndex]
				if not CanAccessForeignTable(objective) then
					return nil, nil, nil, nil
				end
				ok, text, objectiveType, finished, currentValue, requiredValue =
					true,
					objective.text,
					objective.type,
					objective.finished,
					objective.numFulfilled,
					objective.numRequired
			elseif type(GetQuestLogLeaderBoard) == "function" then
				local index = QuestTogether.API.GetQuestLogIndexForQuestID(numericQuestID)
				if not index then
					return nil, nil, nil, nil
				end
				ok, text, objectiveType, finished = pcall(GetQuestLogLeaderBoard, numericObjectiveIndex, index)
			end
			if not ok then
				return nil, nil, nil, nil
			end
			if not CanAccessForeignValue(text) then
				text = nil
			end
			if not CanAccessForeignValue(objectiveType) then
				objectiveType = nil
			end
			if not CanAccessForeignValue(finished) then
				finished = nil
			end
			if not CanAccessForeignValue(currentValue) then
				currentValue = nil
			end
			if not CanAccessForeignValue(requiredValue) then
				requiredValue = nil
			end
			-- Some clients expose the legacy text API and the structured API together.
			-- Only supplement counters when both reads describe the identical row.
			if
				type(GetQuestObjectiveInfo) == "function"
				and requiredValue == nil
				and type(text) == "string"
				and CanAccessForeignTable(C_QuestLog)
				and type(C_QuestLog.GetQuestObjectives) == "function"
			then
				local readOK, rows = pcall(C_QuestLog.GetQuestObjectives, numericQuestID)
				local row = readOK and CanAccessForeignTable(rows) and rows[numericObjectiveIndex] or nil
				if
					CanAccessForeignTable(row)
					and CanAccessForeignValue(row.text)
					and CanAccessForeignValue(row.type)
					and row.text == text
					and row.type == objectiveType
					and CanAccessForeignValue(row.numFulfilled)
					and CanAccessForeignValue(row.numRequired)
					and (currentValue == nil or row.numFulfilled == currentValue)
				then
					currentValue, requiredValue = row.numFulfilled, row.numRequired
				end
			end
			if not CanAccessForeignValue(requiredValue) then
				requiredValue = nil
			end
			return text, objectiveType, finished, currentValue, requiredValue
		end,
		GetQuestProgressBarPercent = function(questID)
			if InCombatLockdown and InCombatLockdown() then
				return nil
			end
			local numericQuestID = QuestTogether
					and QuestTogether.NormalizeQuestID
					and QuestTogether:NormalizeQuestID(questID)
				or nil
			if not numericQuestID then
				return nil
			end

			if type(GetQuestProgressBarPercent) ~= "function" then
				return nil
			end
			local ok, progressValue = pcall(GetQuestProgressBarPercent, numericQuestID)
			if not ok then
				return nil
			end
			if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(progressValue) then
				return nil
			end
			return progressValue
		end,
		GetPartyJoinInfo = function()
			-- Flat copied primitives only. Unknown native state is not solo.
			local function Read(fn, ...)
				if not CanAccessForeignValue(fn) or type(fn) ~= "function" then
					return nil
				end
				local ok, value = pcall(fn, ...)
				if ok and CanAccessForeignValue(value) then
					return value
				end
			end
			local grouped, raid = Read(IsInGroup), Read(IsInRaid)
			local instance = Read(IsInGroup, LE_PARTY_CATEGORY_INSTANCE)
			local count = Read(GetNumGroupMembers)
			if
				type(grouped) ~= "boolean"
				or type(raid) ~= "boolean"
				or type(instance) ~= "boolean"
				or type(count) ~= "number"
				or count ~= count
				or count < 0
				or count > 40
			then
				return nil
			end
			local canInvite = false
			if CanAccessForeignTable(C_PartyInfo) then
				canInvite = Read(C_PartyInfo.CanInvite) == true
			end
			return grouped,
				canInvite and not raid and not instance and count < 5,
				count,
				grouped and not raid and not instance and count >= 2 and count < 5
		end,
		GetPartyVisualLeaderUnit = function()
			if
				QuestTogether:IsRuntimeRestricted()
				or not CanAccessForeignValue(UnitIsGroupLeader)
				or type(UnitIsGroupLeader) ~= "function"
				or not CanAccessForeignValue(IsInRaid)
				or type(IsInRaid) ~= "function"
			then
				return nil
			end
			local ok, raid = pcall(IsInRaid)
			if not ok or not CanAccessForeignValue(raid) or type(raid) ~= "boolean" then
				return nil
			end
			for index = 0, raid and 40 or 4 do
				local unit = index == 0 and "player" or (raid and "raid" or "party") .. index
				local valid, leader = pcall(UnitIsGroupLeader, unit)
				if not valid or not CanAccessForeignValue(leader) or type(leader) ~= "boolean" then
					return nil
				end
				if leader then
					return unit
				end
			end
		end,
		GetPartyJoinLeaderUnit = function()
			if
				QuestTogether:IsRuntimeRestricted()
				or not CanAccessForeignValue(UnitIsGroupLeader)
				or type(UnitIsGroupLeader) ~= "function"
			then
				return nil
			end
			for index = 1, 4 do
				local unit = "party" .. index
				local ok, leader = pcall(UnitIsGroupLeader, unit)
				if not ok or not CanAccessForeignValue(leader) or type(leader) ~= "boolean" then
					return nil
				end
				if leader then
					return unit
				end
			end
		end,
		IsPartyJoinFriend = function(name)
			-- Exact normalized character identity; never use display-name shortening
			-- or sender-provided friendship. This is the character friends list.
			if not CanAccessForeignValue(name) or type(name) ~= "string" then
				return false
			end
			if not CanAccessForeignTable(C_FriendList) then
				return false
			end
			local query = C_FriendList.GetFriendInfo
			if not CanAccessForeignValue(query) or type(query) ~= "function" then
				return false
			end
			local ok, info = pcall(query, name)
			if not ok or not CanAccessForeignTable(info) then
				return false
			end
			local friendName = info.name
			if not CanAccessForeignValue(friendName) or type(friendName) ~= "string" then
				return false
			end
			return QuestTogether:NormalizeMemberName(friendName) == QuestTogether:NormalizeMemberName(name)
		end,
		InviteUnit = function(name)
			if
				QuestTogether:IsRuntimeRestricted()
				or not CanAccessForeignValue(name)
				or type(name) ~= "string"
				or name == ""
			then
				return false
			end
			if not CanAccessForeignTable(C_PartyInfo) then
				return false
			end
			local invite = C_PartyInfo.InviteUnit
			if not CanAccessForeignValue(invite) or type(invite) ~= "function" then
				return false
			end
			local ok, result = pcall(invite, name)
			-- The native API has no success return. This means attempted, not joined.
			return ok and CanAccessForeignValue(result) and result ~= false
		end,
		OpenQTChatComposer = function()
			if QuestTogether:IsRuntimeRestricted() then
				return false
			end
			local openChat
			if CanAccessForeignTable(ChatFrameUtil) then
				openChat = ChatFrameUtil.OpenChat
			end
			if not CanAccessForeignValue(openChat) then
				return false
			end
			if type(openChat) ~= "function" then
				openChat = ChatFrame_OpenChat
			end
			if not CanAccessForeignValue(openChat) or type(openChat) ~= "function" then
				return false
			end
			-- Let Blizzard choose its edit box; pass only text, never the minimap
			-- button as a chat frame. Opening a draft does not send a message.
			local ok, result = pcall(openChat, "/qt ")
			return ok and CanAccessForeignValue(result) and result ~= false
		end,
		SendTell = function(name, chatFrame)
			-- Menus can be anchored to map dots or UIParent. Only a readable
			-- chat frame with an edit box is a native preferred chat destination;
			-- nil lets Blizzard choose its active/default window.
			local editBox = QuestTogether:GetAccessibleFrameMember(chatFrame, "editBox")
			if not QuestTogether:CanAccessForeignFrame(editBox) then
				chatFrame = nil
			end
			if ChatFrameUtil and ChatFrameUtil.SendTell then
				local ok, result = pcall(ChatFrameUtil.SendTell, name, chatFrame)
				return ok and QuestTogether:CanAccessValue(result) and result ~= false
			end
			if type(ChatFrame_SendTell) == "function" then
				local ok, result = pcall(ChatFrame_SendTell, name, chatFrame)
				return ok and QuestTogether:CanAccessValue(result) and result ~= false
			end
			return false
		end,
		AddFriend = function(name)
			if C_FriendList and C_FriendList.AddFriend then
				local ok, result = pcall(C_FriendList.AddFriend, name)
				return ok and result or nil
			end
			return nil
		end,
		AddOrDelIgnore = function(name)
			if C_FriendList and C_FriendList.AddOrDelIgnore then
				-- Ignore-list APIs can throw for invalid names; keep menu actions non-fatal.
				local ok, result = pcall(C_FriendList.AddOrDelIgnore, name)
				return ok and result or nil
			end
			return nil
		end,
		IsOnIgnoredList = function(name)
			if C_FriendList and C_FriendList.IsOnIgnoredList then
				-- Ignore-list lookups can throw on malformed names; treat as "not ignored".
				local ok, result = pcall(C_FriendList.IsOnIgnoredList, name)
				return ok and result or false
			end
			return false
		end,
		IsAddOnLoaded = function(requestedAddonName)
			if C_AddOns and C_AddOns.IsAddOnLoaded then
				local ok, isLoaded = pcall(C_AddOns.IsAddOnLoaded, requestedAddonName)
				return ok and isLoaded and true or false
			end
			local ok, isLoaded = pcall(IsAddOnLoaded, requestedAddonName)
			return ok and isLoaded and true or false
		end,
		GetAddOnMetadata = function(requestedAddonName, fieldName)
			if C_AddOns and C_AddOns.GetAddOnMetadata then
				local ok, metadata = pcall(C_AddOns.GetAddOnMetadata, requestedAddonName, fieldName)
				if not ok then
					return nil
				end
				if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(metadata) then
					return nil
				end
				return metadata
			end
			if type(GetAddOnMetadata) == "function" then
				local ok, metadata = pcall(GetAddOnMetadata, requestedAddonName, fieldName)
				if not ok then
					return nil
				end
				if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(metadata) then
					return nil
				end
				return metadata
			end
			return nil
		end,
		UnitInParty = function(unitToken)
			local ok, result = pcall(UnitInParty, unitToken)
			return ok and result and true or false
		end,
		UnitInRaid = function(unitToken)
			local ok, result = pcall(UnitInRaid, unitToken)
			return ok and result and true or false
		end,
		Ambiguate = function(name, context)
			local ok, result = pcall(Ambiguate, name, context)
			if not ok then
				return nil
			end
			if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(result) then
				return nil
			end
			return result
		end,
		GetRealmName = function()
			local ok, realmName = pcall(GetRealmName)
			if not ok then
				return ""
			end
			if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(realmName) then
				return ""
			end
			return realmName
		end,
		GetBestMapForUnit = function(unitToken)
			if C_Map and C_Map.GetBestMapForUnit then
				local ok, mapID = pcall(C_Map.GetBestMapForUnit, unitToken)
				if not ok then
					return nil
				end
				if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(mapID) then
					return nil
				end
				return mapID
			end
			return nil
		end,
		GetMapInfo = function(mapID)
			if C_Map and C_Map.GetMapInfo then
				local ok, mapInfo = pcall(C_Map.GetMapInfo, mapID)
				if not ok or not CanAccessForeignTable(mapInfo) then
					return nil
				end

				local sanitizedInfo = {}
				for _, key in ipairs({ "mapType", "parentMapID" }) do
					local value = CanAccessForeignValue(mapInfo[key]) and QuestTogether:SafeToNumber(mapInfo[key])
					if value and value >= 0 and value <= 1000000 and value == math.floor(value) then
						sanitizedInfo[key] = value
					end
				end
				local numericMapID = CanAccessForeignValue(mapInfo.mapID)
						and QuestTogether
						and QuestTogether.SafeToNumber
						and QuestTogether:SafeToNumber(mapInfo.mapID)
					or nil
				if not numericMapID then
					numericMapID = QuestTogether and QuestTogether.SafeToNumber and QuestTogether:SafeToNumber(mapID)
						or nil
				end
				if numericMapID and numericMapID > 0 then
					sanitizedInfo.mapID = math.floor(numericMapID + 0.5)
				end

				local mapName = mapInfo.name
				if CanAccessForeignValue(mapName) then
					if type(mapName) == "string" and mapName ~= "" then
						sanitizedInfo.name = mapName
					end
				end

				return sanitizedInfo
			end
			return nil
		end,
		GetPlayerMapPosition = function(mapID, unitToken)
			if C_Map and C_Map.GetPlayerMapPosition then
				local ok, mapPosition = pcall(C_Map.GetPlayerMapPosition, mapID, unitToken)
				if not ok or not CanAccessForeignValue(mapPosition) then
					return nil
				end
				local positionType = type(mapPosition)
				if
					(positionType ~= "table" and positionType ~= "userdata")
					or (positionType == "table" and not CanAccessForeignTable(mapPosition))
				then
					return nil
				end

				local rawX = mapPosition.x
				local rawY = mapPosition.y
				if not CanAccessForeignValue(rawX) or not CanAccessForeignValue(rawY) then
					return nil
				end
				if rawX == nil or rawY == nil then
					local getXY = mapPosition.GetXY
					if CanAccessForeignValue(getXY) and type(getXY) == "function" then
						local okXY, xValue, yValue = pcall(getXY, mapPosition)
						if okXY and CanAccessForeignValue(xValue) and CanAccessForeignValue(yValue) then
							rawX = rawX or xValue
							rawY = rawY or yValue
						end
					end
				end

				local numericX = QuestTogether and QuestTogether.SafeToNumber and QuestTogether:SafeToNumber(rawX)
					or nil
				local numericY = QuestTogether and QuestTogether.SafeToNumber and QuestTogether:SafeToNumber(rawY)
					or nil
				if numericX == nil or numericY == nil then
					return nil
				end

				return {
					x = numericX,
					y = numericY,
				}
			end
			return nil
		end,
		GetTooltipDataForHyperlink = function(hyperlink)
			if C_TooltipInfo and C_TooltipInfo.GetHyperlink and type(hyperlink) == "string" and hyperlink ~= "" then
				local ok, tooltipData = pcall(C_TooltipInfo.GetHyperlink, hyperlink)
				if not ok then
					return nil
				end
				if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(tooltipData) then
					return nil
				end
				return tooltipData
			end
			return nil
		end,
		GetTooltipDataForUnit = function(unitToken)
			if C_TooltipInfo and C_TooltipInfo.GetUnit then
				local ok, tooltipData = pcall(C_TooltipInfo.GetUnit, unitToken)
				if not ok then
					return nil
				end
				if QuestTogether and QuestTogether.IsSecretValue and QuestTogether:IsSecretValue(tooltipData) then
					return nil
				end
				return tooltipData
			end
			return nil
		end,
		SurfaceTooltipDataArgs = function(tooltipData)
			-- SurfaceArgs writes into Blizzard's tables. The tooltip reader already
			-- understands nested args; leave foreign data untouched.
			return CanAccessForeignTable(tooltipData) and tooltipData or nil
		end,
		IsWarModeFeatureEnabled = function()
			if not CanAccessForeignTable(C_PvP) then
				return nil
			end
			local getter = C_PvP.IsWarModeFeatureEnabled
			if not CanAccessForeignValue(getter) or type(getter) ~= "function" then
				return nil
			end
			local ok, enabled = pcall(getter)
			if ok and CanAccessForeignValue(enabled) and type(enabled) == "boolean" then
				return enabled
			end
			return nil
		end,
		IsWarModeActive = function()
			if not CanAccessForeignTable(C_PvP) then
				return nil
			end
			local getter = C_PvP.IsWarModeActive
			if not CanAccessForeignValue(getter) or type(getter) ~= "function" then
				return nil
			end
			-- Desired is a preference and can differ from the player's current mode.
			local ok, active = pcall(getter)
			if ok and CanAccessForeignValue(active) and type(active) == "boolean" then
				return active
			end
			return nil
		end,
		CreateUiMapPoint = function(mapID, x, y)
			if UiMapPoint and UiMapPoint.CreateFromCoordinates then
				return UiMapPoint.CreateFromCoordinates(mapID, x, y)
			end
			return nil
		end,
		CanSetUserWaypointOnMap = function(mapID)
			if C_Map and C_Map.CanSetUserWaypointOnMap then
				local ok, canSet = pcall(C_Map.CanSetUserWaypointOnMap, mapID)
				return ok and CanAccessForeignValue(canSet) and canSet == true
			end
			return false
		end,
		SetUserWaypoint = function(point)
			if C_Map and C_Map.SetUserWaypoint then
				local ok, result = pcall(C_Map.SetUserWaypoint, point)
				return ok and CanAccessForeignValue(result) and result == true
			end
			return false
		end,
		SetSuperTrackedUserWaypoint = function(shouldSuperTrack)
			if C_SuperTrack and C_SuperTrack.SetSuperTrackedUserWaypoint then
				local ok, result = pcall(C_SuperTrack.SetSuperTrackedUserWaypoint, shouldSuperTrack)
				return ok and result or nil
			end
			return nil
		end,
	}

function QuestTogether:IsSecretValue(value)
	if not raw_issecretvalue then
		return false
	end

	local ok, isSecret = pcall(raw_issecretvalue, value)
	return not ok or (isSecret and true or false)
end

function QuestTogether:CanAccessValue(value)
	return CanAccessForeignValue(value)
end

function QuestTogether:CanAccessTable(tableValue)
	return CanAccessForeignTable(tableValue)
end

local function ReadForeignFrameMethod(frame, memberName)
	local ok, method = pcall(function()
		return frame[memberName]
	end)
	if not ok or not CanAccessForeignValue(method) then
		return nil, false
	end
	return method, true
end

function QuestTogether:IsForbiddenFrame(frame)
	local frameType = type(frame)
	if not frame or (frameType ~= "table" and frameType ~= "userdata") then
		return false
	end
	if not CanAccessForeignValue(frame) or (frameType == "table" and not CanAccessForeignTable(frame)) then
		return true
	end
	local method, readable = ReadForeignFrameMethod(frame, "IsForbidden")
	if not readable then
		return true
	end
	if type(method) ~= "function" then
		return false
	end

	local ok, forbidden = pcall(method, frame)
	return not ok or not CanAccessForeignValue(forbidden) or forbidden == true
end

function QuestTogether:IsProtectedFrame(frame)
	if not self:CanAccessValue(frame) then
		return true, false
	end

	local frameType = type(frame)
	if not frame or (frameType ~= "table" and frameType ~= "userdata") then
		return false, false
	end
	if self:IsForbiddenFrame(frame) then
		return true, false
	end
	local method, readable = ReadForeignFrameMethod(frame, "IsProtected")
	if not readable then
		return true, false
	end
	if type(method) ~= "function" then
		return false, false
	end

	local ok, isProtected, isProtectedExplicitly = pcall(method, frame)
	if not ok or not CanAccessForeignValue(isProtected) or not CanAccessForeignValue(isProtectedExplicitly) then
		return true, false
	end
	return isProtected and true or false, isProtectedExplicitly and true or false
end

function QuestTogether:CanAccessForeignFrame(frame, requireShown)
	local frameType = type(frame)
	if not frame or (frameType ~= "table" and frameType ~= "userdata") then
		return false
	end
	if not CanAccessForeignValue(frame) then
		return false
	end
	if self:IsForbiddenFrame(frame) then
		return false
	end

	if requireShown then
		local method, readable = ReadForeignFrameMethod(frame, "IsShown")
		if not readable or type(method) ~= "function" then
			return false
		end
		local okShown, isShown = pcall(method, frame)
		if not okShown or not CanAccessForeignValue(isShown) or not isShown then
			return false
		end
	end

	return true
end

function QuestTogether:GetAccessibleFrameMember(frame, memberName)
	if not self:CanAccessForeignFrame(frame) or type(memberName) ~= "string" or memberName == "" then
		return nil, false
	end

	local ok, value = pcall(function()
		return frame[memberName]
	end)
	if not ok or not self:CanAccessValue(value) then
		return nil, false
	end
	return value, true
end

function QuestTogether:TryAddMessageToChatFrame(chatFrame, message)
	if not self:CanAccessForeignFrame(chatFrame) or type(chatFrame.AddMessage) ~= "function" then
		return false
	end

	local ok = pcall(chatFrame.AddMessage, chatFrame, self:SafeToString(message, ""))
	return ok and true or false
end

function QuestTogether:SafeToNumber(value)
	if not self:CanAccessValue(value) then
		return nil
	end

	local valueType = type(value)
	if valueType == "number" then
		-- Reject NaN/inf to keep downstream math safe and deterministic.
		if value ~= value or value == math.huge or value == -math.huge then
			return nil
		end
		return value
	end

	if valueType ~= "string" then
		return nil
	end

	local trimmedValue = self:SafeTrimString(value, "")
	if trimmedValue == "" then
		return nil
	end

	local numericValue = tonumber(trimmedValue)
	if type(numericValue) ~= "number" then
		return nil
	end

	if numericValue ~= numericValue or numericValue == math.huge or numericValue == -math.huge then
		return nil
	end

	return numericValue
end

function QuestTogether:NormalizeQuestID(questId)
	local numericQuestId = self:SafeToNumber(questId)
	if not numericQuestId or numericQuestId <= 0 then
		return nil
	end

	return math.floor(numericQuestId + 0.5)
end

function QuestTogether:SafeToString(value, fallback)
	if not self:CanAccessValue(value) then
		if fallback ~= nil then
			return fallback
		end
		return "<secret>"
	end

	local valueType = type(value)
	if valueType == "string" then
		return value
	end
	if valueType == "number" or valueType == "boolean" or valueType == "nil" then
		return raw_tostring(value)
	end

	-- String coercion is intentionally shielded so debug/log paths never trigger taint errors.
	local ok, stringValue = pcall(raw_tostring, value)
	if ok then
		return stringValue
	end

	if fallback ~= nil then
		return fallback
	end
	return "<secret>"
end

function QuestTogether:SafeTrimString(value, fallback)
	local fallbackValue = fallback or ""
	if type(value) ~= "string" or not self:CanAccessValue(value) then
		return fallbackValue
	end

	local trimmedValue = string.match(value, "^%s*(.-)%s*$")
	if type(trimmedValue) ~= "string" or not self:CanAccessValue(trimmedValue) then
		return fallbackValue
	end
	return trimmedValue
end

function QuestTogether:SafeStripWhitespace(value, fallback)
	local fallbackValue = fallback or ""
	if type(value) ~= "string" or not self:CanAccessValue(value) then
		return fallbackValue
	end

	local stripped = string.gsub(value, "%s+", "")
	if type(stripped) ~= "string" or not self:CanAccessValue(stripped) then
		return fallbackValue
	end
	return stripped
end

-- Deep copy helper used for defaults merging and tests.
function QuestTogether:DeepCopy(value)
	if type(value) ~= "table" then
		return value
	end

	local copy = {}
	for key, nestedValue in pairs(value) do
		copy[key] = self:DeepCopy(nestedValue)
	end
	return copy
end

local function SortDebugKeys(keys)
	table.sort(keys, function(left, right)
		return tostring(left) < tostring(right)
	end)
end

local function FormatDebugValue(value, depth, visited)
	if QuestTogether:IsSecretValue(value) then
		return "<secret>"
	end

	local valueType = type(value)
	if valueType == "nil" then
		return "nil"
	end
	if valueType == "boolean" or valueType == "number" then
		return tostring(value)
	end
	if valueType == "string" then
		local ok, quoted = pcall(string.format, "%q", value)
		if ok then
			return quoted
		end
		return tostring(value, "<secret>")
	end
	if valueType ~= "table" then
		return "<" .. tostring(valueType) .. ">"
	end

	depth = depth or 0
	if depth >= 2 then
		return "{...}"
	end

	visited = visited or {}
	if visited[value] then
		return "{<cycle>}"
	end
	visited[value] = true

	local keys = {}
	for key in pairs(value) do
		keys[#keys + 1] = key
	end
	SortDebugKeys(keys)

	local parts = {}
	local maxParts = 8
	for index = 1, math.min(#keys, maxParts) do
		local key = keys[index]
		parts[#parts + 1] = tostring(key) .. "=" .. FormatDebugValue(value[key], depth + 1, visited)
	end
	if #keys > maxParts then
		parts[#parts + 1] = string.format("...(%d more)", #keys - maxParts)
	end

	visited[value] = nil
	return "{" .. table.concat(parts, ", ") .. "}"
end

-- Merge defaults into destination recursively without deleting existing values.
function QuestTogether:ApplyDefaults(destination, defaults)
	for key, defaultValue in pairs(defaults) do
		if destination[key] == nil then
			destination[key] = self:DeepCopy(defaultValue)
		elseif type(destination[key]) == "table" and type(defaultValue) == "table" then
			self:ApplyDefaults(destination[key], defaultValue)
		end
	end
end

function QuestTogether:Print(message)
	local text = "|cff33ff99QuestTogether|r: " .. self:SafeToString(message)
	local chatFrame = self:GetChatLogFrame()
	if not self:TryAddMessageToChatFrame(chatFrame, text) then
		print("QuestTogether:", self:SafeToString(message))
	end
end

function QuestTogether:PrintRaw(message)
	local text = self:SafeToString(message)
	local chatFrame = self:GetChatLogFrame()
	if not self:TryAddMessageToChatFrame(chatFrame, text) then
		print(text)
	end
end

function QuestTogether:PrintChatLogSystemMessage(message)
	self:PrintChatLogRaw("|cff33ff99QuestTogether|r: " .. self:SafeToString(message, ""))
end

function QuestTogether:PrintChatLogWarningMessage(message)
	local warningPrefix = "|cffff8800" .. L("Warning:") .. "|r"
	local iconTag = self.GetDefaultAnnouncementIconChatTag and self:GetDefaultAnnouncementIconChatTag(14) or ""
	if iconTag ~= "" then
		warningPrefix = iconTag .. warningPrefix
	end

	self:PrintChatLogRaw(warningPrefix .. " |cffffd200" .. self:SafeToString(message, "") .. "|r")
end

function QuestTogether:PrintChatLogInfoMessage(message)
	local infoPrefix = "|cff33ff99" .. L("Info:") .. "|r"
	local iconTag = self.GetDefaultAnnouncementIconChatTag and self:GetDefaultAnnouncementIconChatTag(14) or ""
	if iconTag ~= "" then
		infoPrefix = iconTag .. infoPrefix
	end

	self:PrintChatLogRaw(infoPrefix .. " |cffffd200" .. self:SafeToString(message, "") .. "|r")
end

function QuestTogether:PrintChatLogWarningDetailMessage(message)
	self:PrintChatLogRaw("|cffff8800 - |r" .. self:SafeToString(message, ""))
end

function QuestTogether:PrintChatLogInfoDetailMessage(message)
	self:PrintChatLogRaw("|cff33ff99 - |r" .. self:SafeToString(message, ""))
end

function QuestTogether:ShouldMirrorChatLogsToMainChat()
	if not self.db or not self.db.profile or self.db.profile.mirrorChatLogsToMainChat ~= true then
		return false
	end

	if self:GetResolvedChatLogDestination() ~= "separate" then
		return false
	end

	local chatFrame = self:FindVisibleQuestLogChatFrame()
	return self:IsChatFrameDocked(chatFrame)
end

function QuestTogether:GetMainChatFrame()
	return DEFAULT_CHAT_FRAME
end

function QuestTogether:GetConfiguredQuestLogChatFrameID()
	if not self.db then
		return nil
	end

	local configuredID = self:SafeToNumber(self.db.profile and self.db.profile.questLogChatFrameID)
	if configuredID and configuredID > 0 then
		return configuredID
	end

	return nil
end

function QuestTogether:SetConfiguredQuestLogChatFrameID(chatFrameID)
	if not self.db then
		return false
	end

	local numericID = self:SafeToNumber(chatFrameID)
	if numericID and numericID > 0 then
		if self.db.profile then
			self.db.profile.questLogChatFrameID = numericID
		end
	else
		if self.db.profile then
			self.db.profile.questLogChatFrameID = nil
		end
	end

	return true
end

function QuestTogether:FindQuestLogChatFrame()
	local chatWindowName = self.questLogWindowName or "QuestTogether"
	local configuredID = self:GetConfiguredQuestLogChatFrameID()
	if configuredID and self.API.GetChatFrameByID and self.API.GetChatWindowInfo then
		local configuredFrame = self.API.GetChatFrameByID(configuredID)
		local configuredName = self.API.GetChatWindowInfo(configuredID)
		if self:CanAccessForeignFrame(configuredFrame) and configuredName == chatWindowName then
			return configuredFrame, configuredID
		end
	end

	local maxWindows = self:SafeToNumber(self.API.GetNumChatWindows and self.API.GetNumChatWindows()) or 0
	for chatFrameID = 1, maxWindows do
		local frameName = self.API.GetChatWindowInfo and self.API.GetChatWindowInfo(chatFrameID)
		if frameName == chatWindowName then
			local chatFrame = nil
			if self.API.GetChatFrameByID then
				chatFrame = self.API.GetChatFrameByID(chatFrameID)
			end
			if not chatFrame then
				chatFrame = _G["ChatFrame" .. tostring(chatFrameID)]
			end
			if self:CanAccessForeignFrame(chatFrame) then
				self:SetConfiguredQuestLogChatFrameID(chatFrameID)
				return chatFrame, chatFrameID
			end
		end
	end

	self:SetConfiguredQuestLogChatFrameID(nil)
	return nil, nil
end

function QuestTogether:GetResolvedChatLogDestination()
	local chatFrame = self:FindVisibleQuestLogChatFrame()
	if chatFrame then
		return "separate"
	end

	return "main"
end

function QuestTogether:FindVisibleQuestLogChatFrame(excludedFrame)
	local chatWindowName = self.questLogWindowName or "QuestTogether"
	local maxWindows = self:SafeToNumber(self.API.GetNumChatWindows and self.API.GetNumChatWindows()) or 0

	for chatFrameID = 1, maxWindows do
		local frameName = self.API.GetChatWindowInfo and self.API.GetChatWindowInfo(chatFrameID)
		if frameName == chatWindowName then
			local chatFrame = nil
			if self.API.GetChatFrameByID then
				chatFrame = self.API.GetChatFrameByID(chatFrameID)
			end
			if not chatFrame then
				chatFrame = _G["ChatFrame" .. tostring(chatFrameID)]
			end
			if
				chatFrame
				and chatFrame ~= excludedFrame
				and self:CanAccessForeignFrame(chatFrame)
				and self:IsQuestLogChatFrameVisible(chatFrame)
			then
				self:SetConfiguredQuestLogChatFrameID(chatFrameID)
				return chatFrame, chatFrameID
			end
		end
	end

	return nil, nil
end

function QuestTogether:IsQuestLogChatFrame(chatFrame)
	if not self:CanAccessForeignFrame(chatFrame) or not chatFrame.GetID then
		return false
	end

	local expectedName = self.questLogWindowName or "QuestTogether"
	local frameID = chatFrame:GetID()
	local configuredID = self:GetConfiguredQuestLogChatFrameID()
	if configuredID and configuredID == frameID then
		return true
	end

	if self.API.GetChatWindowInfo then
		local frameName = self.API.GetChatWindowInfo(frameID)
		if frameName == expectedName then
			return true
		end
	end

	return false
end

function QuestTogether:IsQuestLogChatFrameVisible(chatFrame)
	if not self:CanAccessForeignFrame(chatFrame) or not self:IsQuestLogChatFrame(chatFrame) then
		return false
	end

	local frameShown = chatFrame.IsShown and chatFrame:IsShown()
	if frameShown then
		return true
	end

	local frameName = chatFrame.GetName and chatFrame:GetName()
	if not frameName or frameName == "" then
		return false
	end

	local chatTab = _G[frameName .. "Tab"]
	return self:CanAccessForeignFrame(chatTab) and chatTab.IsShown and chatTab:IsShown() or false
end

function QuestTogether:IsChatFrameDocked(chatFrame)
	if not self:CanAccessForeignFrame(chatFrame) then
		return false
	end

	if chatFrame.IsDocked then
		local ok, isDocked = pcall(chatFrame.IsDocked, chatFrame)
		if ok and type(isDocked) == "boolean" then
			return isDocked
		end
	end

	if type(chatFrame.isDocked) == "boolean" then
		return chatFrame.isDocked
	end

	local frameName = chatFrame.GetName and chatFrame:GetName()
	if frameName and frameName ~= "" then
		local chatTab = _G[frameName .. "Tab"]
		if self:CanAccessForeignFrame(chatTab) and type(chatTab.isDocked) == "boolean" then
			return chatTab.isDocked
		end
	end

	if FCFDock_GetChatFrames and GENERAL_CHAT_DOCK then
		local ok, dockedFrames = pcall(FCFDock_GetChatFrames, GENERAL_CHAT_DOCK)
		if ok and type(dockedFrames) == "table" then
			for _, dockedFrame in ipairs(dockedFrames) do
				if dockedFrame == chatFrame then
					return true
				end
			end
		end
	end

	return false
end

function QuestTogether:HandleQuestLogChatFrameClosed(chatFrame)
	if self.suppressQuestLogChatCloseHook then
		return false
	end
	if self.isLoggingOut then
		return false
	end
	if not self:IsQuestLogChatFrame(chatFrame) then
		return false
	end

	self:SetConfiguredQuestLogChatFrameID(nil)
	local evaluateClose = function()
		if self.isLoggingOut then
			return
		end

		local existingFrame, existingID = self:FindVisibleQuestLogChatFrame(chatFrame)
		if existingFrame then
			self:SetConfiguredQuestLogChatFrameID(existingID)
			self:Debugf(
				"chat",
				"Ignoring QuestTogether chat window close because a visible replacement exists id=%s",
				tostring(existingID)
			)
			if self.RefreshOptionsWindow then
				self:RefreshOptionsWindow()
			end
			return
		end

		self:Debug("QuestTogether chat window was closed; reverting chat log destination to main chat window", "chat")
		if self.RefreshOptionsWindow then
			self:RefreshOptionsWindow()
		end
		if self.isEnabled and self.hasLoggedIn then
			self:PrintChatLogDestinationMessage()
		end
	end

	if self.API and self.API.Delay then
		self.API.Delay(0, evaluateClose)
	else
		evaluateClose()
	end

	return true
end

function QuestTogether:TryInstallChatWindowHooks()
	if self.chatWindowHooksInstalled then
		return
	end
	if type(hooksecurefunc) ~= "function" or type(FCF_Close) ~= "function" then
		return
	end

	hooksecurefunc("FCF_Close", function(frame, fallback)
		local closedFrame = fallback or frame
		QuestTogether:HandleQuestLogChatFrameClosed(closedFrame)
	end)

	self.chatWindowHooksInstalled = true
	self:Debug("Installed chat window hooks", "chat")
end

function QuestTogether:ActivateQuestLogChatFrame(chatFrame)
	if not self:CanAccessForeignFrame(chatFrame) or not chatFrame.GetID then
		return false
	end

	local chatTab = _G[chatFrame:GetName() .. "Tab"]
	local frameShown = chatFrame.IsShown and chatFrame:IsShown()
	local tabShown = self:CanAccessForeignFrame(chatTab) and chatTab.IsShown and chatTab:IsShown() or false
	if frameShown or tabShown then
		return true
	end

	if FCF_CheckShowChatFrame then
		FCF_CheckShowChatFrame(chatFrame)
		if self:CanAccessForeignFrame(chatTab) then
			FCF_CheckShowChatFrame(chatTab)
		end
	end
	if SetChatWindowShown then
		SetChatWindowShown(chatFrame:GetID(), true)
	end
	if FCF_DockFrame and FCFDock_GetChatFrames and GENERAL_CHAT_DOCK then
		FCF_DockFrame(chatFrame, (#FCFDock_GetChatFrames(GENERAL_CHAT_DOCK) + 1), true)
	end
	if FCF_FadeInChatFrame and FCFDock_GetSelectedWindow and GENERAL_CHAT_DOCK then
		local selectedFrame = FCFDock_GetSelectedWindow(GENERAL_CHAT_DOCK)
		if selectedFrame then
			FCF_FadeInChatFrame(selectedFrame)
		end
	end
	if ChatFrameUtil and ChatFrameUtil.SetLastActiveWindow and self:CanAccessForeignFrame(chatFrame.editBox) then
		ChatFrameUtil.SetLastActiveWindow(chatFrame.editBox)
	end

	self:Debugf("chat", "Reactivated existing QuestTogether chat window id=%s", tostring(chatFrame:GetID()))
	return true
end

function QuestTogether:EnsureQuestLogChatFrame()
	local existingFrame, existingID = self:FindQuestLogChatFrame()
	if existingFrame then
		self:ActivateQuestLogChatFrame(existingFrame)
		return existingFrame, existingID
	end

	if not self.API.OpenChatWindow then
		return nil, nil
	end

	local chatFrame, chatFrameID = self.API.OpenChatWindow(self.questLogWindowName or "QuestTogether", true)
	if not self:CanAccessForeignFrame(chatFrame) then
		return nil, nil
	end

	if chatFrame.RemoveAllMessageGroups then
		chatFrame:RemoveAllMessageGroups()
	end
	if chatFrame.RemoveAllChannels then
		chatFrame:RemoveAllChannels()
	end
	self:SetConfiguredQuestLogChatFrameID(chatFrameID)
	self:Debugf("chat", "Created QuestTogether chat window id=%s", tostring(chatFrameID))
	return chatFrame, chatFrameID
end

function QuestTogether:CloseQuestLogChatFrame()
	local chatFrame, chatFrameID = self:FindQuestLogChatFrame()
	if not chatFrame then
		self:SetConfiguredQuestLogChatFrameID(nil)
		return false
	end
	if not self:CanAccessForeignFrame(chatFrame) then
		self:SetConfiguredQuestLogChatFrameID(nil)
		return false
	end

	if self.API.CloseChatWindow then
		self.suppressQuestLogChatCloseHook = true
		-- Closing chat windows can fail in restricted UI states; keep close flow resilient.
		local ok = pcall(self.API.CloseChatWindow, chatFrame)
		self.suppressQuestLogChatCloseHook = false
		if not ok then
			self:Debugf("chat", "Failed to close QuestTogether chat window id=%s", tostring(chatFrameID))
		end
	end

	self:SetConfiguredQuestLogChatFrameID(nil)
	self:Debugf("chat", "Closed QuestTogether chat window id=%s", tostring(chatFrameID))
	if self.isEnabled and self.hasLoggedIn then
		self:PrintChatLogDestinationMessage()
	end
	return true
end

function QuestTogether:ReconcileQuestLogChatDestination()
	local visibleFrame, visibleID = self:FindVisibleQuestLogChatFrame()
	if visibleFrame and visibleID then
		self:SetConfiguredQuestLogChatFrameID(visibleID)
		self:Debugf("chat", "Adopted existing QuestTogether chat window id=%s on login", tostring(visibleID))
		if self.RefreshOptionsWindow then
			self:RefreshOptionsWindow()
		end
		return true
	end

	self:SetConfiguredQuestLogChatFrameID(nil)
	return false
end

function QuestTogether:ApplyMainChatFontSizeToChatFrame(chatFrame)
	if
		not self:CanAccessForeignFrame(chatFrame)
		or not chatFrame.GetID
		or not self.API.GetChatWindowInfo
		or not self.API.SetChatWindowFontSize
	then
		return false
	end
	local mainChatFrame = self:GetMainChatFrame()
	if not self:CanAccessForeignFrame(mainChatFrame) or not mainChatFrame.GetID then
		return false
	end

	local mainChatID = mainChatFrame:GetID()
	local _, fontSize = self.API.GetChatWindowInfo(mainChatID)
	fontSize = self:SafeToNumber(fontSize)
	if not fontSize or fontSize <= 0 then
		return false
	end

	self.API.SetChatWindowFontSize(chatFrame, fontSize)
	self:Debugf(
		"chat",
		"Applied main chat font size=%s to QuestTogether chat frame id=%s",
		tostring(fontSize),
		tostring(chatFrame:GetID())
	)
	return true
end

function QuestTogether:GetChatLogFrame()
	if self:GetResolvedChatLogDestination() == "separate" then
		local chatFrame = self:EnsureQuestLogChatFrame()
		if chatFrame and chatFrame.AddMessage then
			return chatFrame
		end
		self:Debug("Separate QuestTogether chat window unavailable; falling back to main chat", "chat")
	end

	return self:GetMainChatFrame()
end

function QuestTogether:TryAddMessageToConfiguredChatLogFrames(message)
	local text = self:SafeToString(message, "")
	local primaryFrame = self:GetChatLogFrame()
	local wroteMessage = self:TryAddMessageToChatFrame(primaryFrame, text)

	if self:ShouldMirrorChatLogsToMainChat() then
		local mainChatFrame = self:GetMainChatFrame()
		if mainChatFrame and mainChatFrame ~= primaryFrame and self:TryAddMessageToChatFrame(mainChatFrame, text) then
			wroteMessage = true
		end
	end

	return wroteMessage
end

function QuestTogether:PrintChatLogRaw(message)
	local text = self:SafeToString(message, "")
	if not self:TryAddMessageToConfiguredChatLogFrames(text) then
		self:PrintRaw(text)
	end
end

function QuestTogether:GetDefaultAnnouncementIconChatTag(size, targetName)
	local asset, kind = self:ResolvePlayerAnnouncementIcon(self.NAMEPLATE_PLAYER_ICON_TEXTURE, "texture", targetName)
	return self:GetIconChatTagFromAsset(asset, kind, size)
end

function QuestTogether:GetIconChatTagFromAsset(iconAsset, iconKind, size)
	local asset = tostring(iconAsset or "")
	if asset == "" then
		return ""
	end

	local iconSize = math.max(1, math.floor((self:SafeToNumber(size) or 14)))
	if iconKind == "atlas" then
		return "|A:" .. asset .. ":" .. tostring(iconSize) .. ":" .. tostring(iconSize) .. "|a"
	end

	return string.format("|T%s:%d:%d:0:0|t", asset, iconSize, iconSize)
end

function QuestTogether:GetClassColorCode(classFile)
	if not CanAccessForeignValue(classFile) or type(classFile) ~= "string" then
		return "|cffffffff"
	end
	-- CUSTOM_CLASS_COLORS is an optional addon integration, not a Blizzard API.
	-- Validate both the registry and its entry before reading display values.
	local colorTable = nil
	if CanAccessForeignTable(CUSTOM_CLASS_COLORS) then
		local customColor = CUSTOM_CLASS_COLORS[classFile]
		if CanAccessForeignTable(customColor) then
			colorTable = customColor
		end
	end
	if not colorTable and CanAccessForeignTable(RAID_CLASS_COLORS) then
		local defaultColor = RAID_CLASS_COLORS[classFile]
		if CanAccessForeignTable(defaultColor) then
			colorTable = defaultColor
		end
	end

	if not colorTable then
		return "|cffffffff"
	end
	local colorString = ReadOptionalString(colorTable.colorStr)
	if not colorString or not colorString:match("^%x%x%x%x%x%x%x%x$") then
		return "|cffffffff"
	end
	return "|c" .. colorString
end

function QuestTogether:GetPlayerClassFile()
	local _, classFile = self.API.UnitClass("player")
	return classFile or "PRIEST"
end

function QuestTogether:GetAddonVersion()
	local metadata = self.API and self.API.GetAddOnMetadata and self.API.GetAddOnMetadata(self.addonName, "Version")
	if type(metadata) ~= "string" then
		return ""
	end

	local version = self:SafeTrimString(metadata, "")
	if version == "" then
		return ""
	end

	return version
end

function QuestTogether:GetShortDisplayName(name)
	name = self:SafeTrimString(name, "")
	if name == "" then
		return L("Unknown")
	end
	if self:UsesRegionalPlayerNames() then
		local fullName = self:NormalizeMemberName(name) or name
		if self:IsSelfSender(fullName) then
			local getter = self.API and self.API.ShouldDisplaySurname
			local ok, showSurname = false, nil
			if type(getter) == "function" then
				ok, showSurname = pcall(getter)
			end
			if not ok or not self:CanAccessValue(showSurname) or showSurname ~= true then
				return SafeMatch(fullName, "^(%S+)") or fullName
			end
		end
		return fullName
	end

	local ambiguate = self.API.Ambiguate or Ambiguate
	if type(ambiguate) == "function" then
		local ok, displayName = pcall(ambiguate, name, "short")
		if ok then
			return self:SafeTrimString(displayName, name)
		end
	end
	return name
end

function QuestTogether:NormalizeAnnouncementWarModeValue(warMode)
	if not self:CanAccessValue(warMode) then
		return nil
	end
	if type(warMode) == "boolean" then
		return warMode
	end
	if type(warMode) == "string" then
		local normalized = string.lower(warMode)
		if warMode == "1" or normalized == "true" then
			return true
		end
		if warMode == "0" or normalized == "false" then
			return false
		end
	end
	return nil
end

function QuestTogether:SupportsWarMode()
	-- Forever uses regional full names and character roles, not Retail's War
	-- Mode. Shared Mainline exports alone do not establish feature support.
	if self:UsesRegionalPlayerNames() then
		return false
	end
	local getter = self.API and self.API.IsWarModeFeatureEnabled
	if type(getter) ~= "function" then
		return nil
	end
	local ok, enabled = pcall(getter)
	if ok and self:CanAccessValue(enabled) and type(enabled) == "boolean" then
		return enabled
	end
	return nil
end

local function IsQuestRecurringFrequency(frequency)
	local frequencyEnum = Enum and Enum.QuestFrequency or nil
	if not frequencyEnum or frequency == nil then
		return false
	end

	return frequency == frequencyEnum.Daily
		or frequency == frequencyEnum.Weekly
		or frequency == frequencyEnum.ResetByScheduler
end

local function GetQuestClassificationFlags(classification)
	local classificationEnum = Enum and Enum.QuestClassification or nil
	if not classificationEnum or classification == nil then
		return {
			isLegendary = false,
			isRepeatable = false,
			isImportant = false,
			isMeta = false,
			isCampaign = false,
			isCalling = false,
		}
	end

	return {
		isLegendary = classification == classificationEnum.Legendary,
		isRepeatable = classification == classificationEnum.Recurring,
		isImportant = classification == classificationEnum.Important,
		isMeta = classification == classificationEnum.Meta,
		isCampaign = classification == classificationEnum.Campaign,
		isCalling = classification == classificationEnum.Calling,
	}
end

local function ResolveQuestOfferAnnouncementIcon(classification, frequency)
	local flags = GetQuestClassificationFlags(classification)
	if flags.isCampaign then
		return "CampaignAvailableQuestIcon", "atlas"
	elseif flags.isLegendary then
		return "legendaryavailablequesticon", "atlas"
	elseif flags.isCalling then
		return "CampaignAvailableDailyQuestIcon", "atlas"
	elseif flags.isImportant then
		return "importantavailablequesticon", "atlas"
	elseif flags.isMeta then
		return "Wrapperavailablequesticon", "atlas"
	elseif IsQuestRecurringFrequency(frequency) then
		return "Recurringavailablequesticon", "atlas"
	elseif flags.isRepeatable then
		return "Interface/GossipFrame/DailyActiveQuestIcon", "texture"
	end

	return "Interface/GossipFrame/AvailableQuestIcon", "texture"
end

local function ResolveQuestActiveAnnouncementIcon(classification, frequency, isComplete)
	local flags = GetQuestClassificationFlags(classification)
	if isComplete then
		if flags.isCampaign then
			return "CampaignActiveQuestIcon", "atlas"
		elseif flags.isCalling then
			return "CampaignActiveDailyQuestIcon", "atlas"
		elseif IsQuestRecurringFrequency(frequency) then
			return "Recurringactivequesticon", "atlas"
		elseif flags.isLegendary then
			return "legendaryactivequesticon", "atlas"
		elseif flags.isImportant then
			return "importantactivequesticon", "atlas"
		elseif flags.isMeta then
			return "Wrapperactivequesticon", "atlas"
		end

		return "Interface/GossipFrame/ActiveQuestIcon", "texture"
	end

	if flags.isCampaign or flags.isCalling then
		return "CampaignInProgressQuestIcon", "atlas"
	elseif IsQuestRecurringFrequency(frequency) then
		return "RepeatableInProgressquesticon", "atlas"
	elseif flags.isLegendary then
		return "legendaryInProgressquesticon", "atlas"
	elseif flags.isImportant then
		return "importantInProgressquesticon", "atlas"
	elseif flags.isMeta then
		return "WrapperInProgressquesticon", "atlas"
	end

	return "SideInProgressquesticon", "atlas"
end

local function GetQuestAnnouncementLookInfo(addon, questId)
	local numericQuestId = addon and addon.NormalizeQuestID and addon:NormalizeQuestID(questId) or nil
	if not numericQuestId then
		return nil, nil
	end

	local classification = addon.API
			and addon.API.GetQuestClassification
			and addon.API.GetQuestClassification(numericQuestId)
		or nil
	local frequency = addon.API and addon.API.GetQuestFrequency and addon.API.GetQuestFrequency(numericQuestId) or nil
	if classification ~= nil and frequency ~= nil then
		return classification, frequency
	end

	local questLogIndex = addon.API
			and addon.API.GetQuestLogIndexForQuestID
			and addon.API.GetQuestLogIndexForQuestID(numericQuestId)
		or nil
	if not questLogIndex then
		return classification, frequency
	end

	local questInfo = addon.API and addon.API.GetQuestLogInfo and addon.API.GetQuestLogInfo(questLogIndex) or nil
	if type(questInfo) ~= "table" then
		return classification, frequency
	end

	if classification == nil then
		classification = SanitizeQuestInfoEnumValue(questInfo.questClassification)
	end
	if frequency == nil then
		frequency = SanitizeQuestInfoEnumValue(questInfo.frequency)
	end

	return classification, frequency
end

function QuestTogether:GetQuestStateAnnouncementIconInfo(eventType, questId)
	local numericQuestId = self:NormalizeQuestID(questId)
	if numericQuestId and self.API then
		local classification, frequency = GetQuestAnnouncementLookInfo(self, numericQuestId)
		local iconAsset = nil
		local iconKind = nil
		if eventType == "QUEST_ACCEPTED" then
			iconAsset, iconKind = ResolveQuestOfferAnnouncementIcon(classification, frequency)
		else
			local useCompleteIcon = eventType == "QUEST_COMPLETED" or eventType == "QUEST_READY_TO_TURN_IN"
			iconAsset, iconKind = ResolveQuestActiveAnnouncementIcon(classification, frequency, useCompleteIcon)
		end
		if type(iconAsset) == "string" and iconAsset ~= "" then
			return iconAsset, iconKind
		end
	end

	local texturePath = self.NAMEPLATE_PLAYER_ICON_TEXTURE
	if type(texturePath) ~= "string" or texturePath == "" then
		return nil, nil
	end

	return texturePath, "texture"
end

function QuestTogether:GetWorldQuestAnnouncementIconInfo(questId)
	local numericQuestId = self:NormalizeQuestID(questId)
	if not numericQuestId then
		return "worldquest-icon", "atlas"
	end

	local questTagType = self.API and self.API.GetQuestPoiTagType and self.API.GetQuestPoiTagType(numericQuestId) or nil
	if questTagType ~= nil and self.API and self.API.GetQuestTagAtlas then
		local atlas = self.API.GetQuestTagAtlas(nil, questTagType)
		if type(atlas) == "string" and atlas ~= "" then
			return atlas, "atlas"
		end
	end

	return "worldquest-icon", "atlas"
end

function QuestTogether:GetBonusObjectiveAnnouncementIconInfo(eventType, questId)
	local numericQuestId = self:NormalizeQuestID(questId)
	if not numericQuestId then
		return "Bonus-Objective-Star", "atlas"
	end

	local questStateEventType = eventType
	if eventType == "BONUS_OBJECTIVE_ENTERED" then
		questStateEventType = "QUEST_ACCEPTED"
	elseif eventType == "BONUS_OBJECTIVE_PROGRESS" or eventType == "BONUS_OBJECTIVE_LEFT" then
		questStateEventType = "QUEST_PROGRESS"
	elseif eventType == "BONUS_OBJECTIVE_COMPLETED" then
		questStateEventType = "QUEST_COMPLETED"
	end

	local asset, kind = self:GetQuestStateAnnouncementIconInfo(questStateEventType, numericQuestId)
	if type(asset) == "string" and asset ~= "" then
		return asset, kind
	end

	return "Bonus-Objective-Star", "atlas"
end

function QuestTogether:GetAnnouncementIconInfo(eventType, questId)
	if eventType == "QT_CHAT" then
		return "Interface\\AddOns\\QuestTogether\\Media\\ChatBubbleIcon", "texture"
	end
	if eventType == "LOOKING_FOR_QUEST_PARTNERS" then
		return "Interface\\AddOns\\QuestTogether\\Media\\QuestTogetherIcon", "texture"
	end
	if self:IsWorldQuestAnnouncementType(eventType) then
		return self:GetWorldQuestAnnouncementIconInfo(questId)
	end
	if self:IsBonusObjectiveAnnouncementType(eventType) then
		return self:GetBonusObjectiveAnnouncementIconInfo(eventType, questId)
	end

	return self:GetQuestStateAnnouncementIconInfo(eventType, questId)
end

function QuestTogether:ResolveAnnouncementDisplayIcon(eventType, iconAsset, iconKind)
	if eventType == "LOOKING_FOR_QUEST_PARTNERS" then
		return self.PLAYER_PARTNER_ICON_TEXTURE, "texture"
	end
	if type(iconAsset) == "string" and iconAsset ~= "" then
		-- Earlier clients explicitly sent the generic exclamation mark. Treat
		-- that decoration as a fallback too; retain actual quest-specific icons.
		if iconKind ~= "atlas" and iconAsset:lower():gsub("/", "\\") == self.NAMEPLATE_QUEST_ICON_TEXTURE:lower() then
			return self.NAMEPLATE_PLAYER_ICON_TEXTURE, "texture"
		end
		return iconAsset, iconKind
	end
	return self:GetAnnouncementIconInfo(eventType, nil)
end

function QuestTogether:ResolvePlayerAnnouncementIcon(asset, kind, targetName)
	-- Only QT logos carry identity/status decoration. Quest-specific and chat
	-- icons keep their meaning, and received artwork never proves developer identity.
	if kind == "atlas" or type(asset) ~= "string" then return asset, kind end
	local path = asset:lower():gsub("/", "\\"):gsub("%.tga$", "")
	local looking = path == self.PLAYER_PARTNER_ICON_TEXTURE:lower()
		or path == self.PLAYER_DEVELOPER_PARTNER_ICON_TEXTURE:lower()
		or path == self.PLAYER_VIP_PARTNER_ICON_TEXTURE:lower()
	if not looking and path ~= self.NAMEPLATE_PLAYER_ICON_TEXTURE:lower()
		and path ~= self.PLAYER_DEVELOPER_ICON_TEXTURE:lower()
		and path ~= self.PLAYER_VIP_ICON_TEXTURE:lower() then return asset, kind end
	looking = looking or (targetName and self:IsPlayerLookingForQuestPartners(targetName))
	if targetName and self:IsVerifiedDeveloper(targetName) then
		return looking and self.PLAYER_DEVELOPER_PARTNER_ICON_TEXTURE or self.PLAYER_DEVELOPER_ICON_TEXTURE, "texture"
	end
	if targetName and self:IsVerifiedVIP(targetName) then
		return looking and self.PLAYER_VIP_PARTNER_ICON_TEXTURE or self.PLAYER_VIP_ICON_TEXTURE, "texture"
	end
	return looking and self.PLAYER_PARTNER_ICON_TEXTURE or self.NAMEPLATE_PLAYER_ICON_TEXTURE, "texture"
end

function QuestTogether:GetAnnouncementIconChatTag(eventType, size, iconAsset, iconKind, targetName)
	local asset, kind = self:ResolveAnnouncementDisplayIcon(eventType, iconAsset, iconKind)
	asset, kind = self:ResolvePlayerAnnouncementIcon(asset, kind, targetName)
	if type(asset) == "string" and asset ~= "" then
		return self:GetIconChatTagFromAsset(asset, kind, size)
	end
	return self:GetDefaultAnnouncementIconChatTag(size, targetName)
end

function QuestTogether:GetPlayerAnnouncementLocationInfo()
	local mapID = self.API.GetBestMapForUnit and self.API.GetBestMapForUnit("player") or nil
	local zoneName = nil
	if mapID and self.API.GetMapInfo then
		local mapInfo = self.API.GetMapInfo(mapID)
		if type(mapInfo) == "table" and type(mapInfo.name) == "string" and mapInfo.name ~= "" then
			zoneName = mapInfo.name
		end
	end

	local coordX = nil
	local coordY = nil
	if mapID and self.API.GetPlayerMapPosition then
		local position = self.API.GetPlayerMapPosition(mapID, "player")
		if position then
			local rawX = position.x or (position.GetXY and select(1, position:GetXY())) or nil
			local rawY = position.y or (position.GetXY and select(2, position:GetXY())) or nil
			local numericX = self:SafeToNumber(rawX)
			local numericY = self:SafeToNumber(rawY)
			if numericX and numericY then
				coordX = numericX * 100
				coordY = numericY * 100
			end
		end
	end

	local warModeActive
	if self:SupportsWarMode() == true and self.API.IsWarModeActive then
		warModeActive = self:NormalizeAnnouncementWarModeValue(self.API.IsWarModeActive())
	end
	return {
		mapID = mapID,
		zoneName = zoneName or "",
		coordX = coordX,
		coordY = coordY,
		warMode = warModeActive,
	}
end

function QuestTogether:NormalizeNearbyAnnouncementRange(value)
	local number = self:SafeToNumber(value)
	if not number or number < self.NEARBY_RANGE_MIN or number > self.NEARBY_RANGE_MAX then
		return nil
	end
	return math.floor(number + 0.5)
end

function QuestTogether:GetNearbyAnnouncementRange()
	return self:NormalizeNearbyAnnouncementRange(self:GetOption("nearbyAnnouncementRange"))
		or self.DEFAULTS.profile.nearbyAnnouncementRange
end

function QuestTogether:IsAnnouncementSenderNearbyByLocation(locationInfo, entireZone)
	if type(locationInfo) ~= "table" then
		return false
	end

	local localInfo = self.GetPlayerAnnouncementLocationInfo and self:GetPlayerAnnouncementLocationInfo() or nil
	if type(localInfo) ~= "table" then
		return false
	end

	local function ReadMapID(value)
		local mapID = self:SafeToNumber(value)
		if mapID and mapID > 0 and mapID == math.floor(mapID) then
			return mapID
		end
		return nil
	end
	local localMapID = ReadMapID(localInfo.mapID)
	local remoteMapID = ReadMapID(locationInfo.mapID)
	if localMapID and remoteMapID then
		if localMapID ~= remoteMapID then
			return false
		end
	else
		-- Legacy announcements have no map ID; retain their zone-label fallback.
		local localZoneName = type(localInfo.zoneName) == "string" and localInfo.zoneName or ""
		local remoteZoneName = type(locationInfo.zoneName) == "string" and locationInfo.zoneName or ""
		if localZoneName == "" or remoteZoneName == "" or localZoneName ~= remoteZoneName then
			return false
		end
	end

	local supportsWarMode = self:SupportsWarMode()
	if supportsWarMode == nil then
		-- Unknown capability must not establish shared Retail surroundings.
		return false
	elseif supportsWarMode then
		local localWarMode = self:NormalizeAnnouncementWarModeValue(localInfo.warMode)
		local remoteWarMode = self:NormalizeAnnouncementWarModeValue(locationInfo.warMode)
		if localWarMode == nil or remoteWarMode == nil or localWarMode ~= remoteWarMode then
			return false
		end
	end

	-- Partner searches need only a matching zone; ordinary updates retain the
	-- configured radius and coordinate validation below.
	if entireZone then
		return true
	end
	local localCoordX = self:SafeToNumber(localInfo.coordX)
	local localCoordY = self:SafeToNumber(localInfo.coordY)
	local remoteCoordX = self:SafeToNumber(locationInfo.coordX)
	local remoteCoordY = self:SafeToNumber(locationInfo.coordY)
	if not localCoordX or not localCoordY or not remoteCoordX or not remoteCoordY then
		return false
	end

	for _, value in ipairs({ localCoordX, localCoordY, remoteCoordX, remoteCoordY }) do
		if value < 0 or value > 100 then
			return false
		end
	end
	local deltaX, deltaY = localCoordX - remoteCoordX, localCoordY - remoteCoordY
	local oldRange = self.ANNOUNCEMENT_NEARBY_RADIUS
	local inOldRange = deltaX * deltaX + deltaY * deltaY <= oldRange * oldRange
	local range = self:GetNearbyAnnouncementRange()
	-- The slider's minimum exactly preserves the former coordinate check.
	if range == self.NEARBY_RANGE_MIN then
		return inOldRange
	end
	-- Convert both axes to yards so rectangular maps use a circular physical
	-- radius. Percentages describe distance across the full map diagonal, not area.
	local ok, width, height = pcall(self.GetLocationPinMapWorldSize, self, localMapID or remoteMapID)
	width, height = self:SafeToNumber(width), self:SafeToNumber(height)
	if not ok or not width or not height or width <= 0 or height <= 0 then
		return inOldRange
	end
	if width > 1000000 or height > 1000000 then
		return inOldRange
	end
	local radiusSquared = (width * width + height * height) * (range / 100) ^ 2
	deltaX, deltaY = deltaX * width / 100, deltaY * height / 100
	return deltaX * deltaX + deltaY * deltaY <= radiusSquared
end

function QuestTogether:BuildAnnouncementLocationSuffix(locationInfo)
	if type(locationInfo) ~= "table" then
		return ""
	end

	local parts = {}
	local zoneName = type(locationInfo.zoneName) == "string" and locationInfo.zoneName or ""
	if zoneName ~= "" then
		parts[#parts + 1] = zoneName
	end

	local coordX = self:SafeToNumber(locationInfo.coordX)
	local coordY = self:SafeToNumber(locationInfo.coordY)
	if coordX and coordY then
		parts[#parts + 1] = string.format("%.1f, %.1f", coordX, coordY)
	end

	local warMode = self:NormalizeAnnouncementWarModeValue(locationInfo.warMode)
	if self:SupportsWarMode() == true and warMode ~= nil then
		parts[#parts + 1] = warMode and L("WM On") or L("WM Off")
	end

	if #parts == 0 then
		return ""
	end

	return " |cff999999[" .. table.concat(parts, " | ") .. "]|r"
end

function QuestTogether:BuildChatLogSpeakerLabel(targetName, classFile)
	local trimmedTargetName = self:GetShortDisplayName(targetName)
	local speakerLabel = trimmedTargetName ~= "" and trimmedTargetName or "QT"
	local speakerColor = self:GetClassColorCode(classFile)

	if LinkUtil and LinkUtil.FormatLink then
		local linkDisplayText = "[" .. speakerLabel .. "]"
		local linkText =
			LinkUtil.FormatLink(self.chatLogLinkType or "questtogetherlog", linkDisplayText, tostring(targetName or ""))
		return speakerColor .. linkText .. "|r"
	end

	return speakerColor .. speakerLabel .. "|r"
end

function QuestTogether:BuildChatLogQuestLabel(questId, questTitle)
	local numericQuestId = self:SafeToNumber(questId)
	local titleText = tostring(questTitle or "")
	if not numericQuestId or titleText == "" or not LinkUtil or not LinkUtil.FormatLink then
		return titleText
	end

	local linkDisplayText = "[" .. titleText .. "]"
	return LinkUtil.FormatLink(
		self.chatLogQuestLinkType or "questtogetherquest",
		linkDisplayText,
		tostring(numericQuestId)
	)
end

function QuestTogether:DecorateAnnouncementMessageWithQuestLink(message, eventType, questId)
	if not self.questTitleLinkEventTypes or not self.questTitleLinkEventTypes[eventType] then
		return self:SafeToString(message, "")
	end

	local numericQuestId = self:SafeToNumber(questId)
	if not numericQuestId then
		return self:SafeToString(message, "")
	end

	local messageText = self:SafeToString(message, "")
	if string.find(messageText, "|H" .. (self.chatLogQuestLinkType or "questtogetherquest") .. ":", 1, true) then
		return messageText
	end
	local prefixText, questTitle
	local translatedPrefix = self.GetLocalizedEventPrefix and self:GetLocalizedEventPrefix(eventType)
	if translatedPrefix and messageText:sub(1, #translatedPrefix) == translatedPrefix then
		prefixText, questTitle = translatedPrefix, messageText:sub(#translatedPrefix + 1)
	else
		prefixText, questTitle = SafeMatch(messageText, "^(.-:%s+)(.+)$")
	end
	if not prefixText or not questTitle or questTitle == "" then
		return messageText
	end

	return prefixText .. self:BuildChatLogQuestLabel(numericQuestId, questTitle)
end

function QuestTogether:GetQuestStatusLabel(questId)
	local numericQuestId = self:SafeToNumber(questId)
	if not numericQuestId then
		return "Unknown"
	end

	local statusState = self.GetTrackedQuestStatusState and self:GetTrackedQuestStatusState(numericQuestId, true) or nil
	if type(statusState) == "table" then
		if statusState.isFlaggedCompleted == true then
			return "Completed"
		end
		if statusState.isReadyForTurnIn == true then
			return "Ready to Turn In"
		end
		if statusState.isComplete == true then
			return "Objectives Complete"
		end
		if statusState.isTracked == true or statusState.isOnQuest == true then
			return "In Progress"
		end
	end

	return "Not Started"
end

function QuestTogether:GetTrackedQuestStatusState(questId, allowLiveFallback)
	local numericQuestId = self:SafeToNumber(questId)
	if not numericQuestId then
		return nil
	end

	local tracker = self.GetPlayerTracker and self:GetPlayerTracker() or nil
	local trackedQuest = tracker and tracker[numericQuestId] or nil
	local state = {
		isTracked = trackedQuest ~= nil,
		isComplete = trackedQuest and trackedQuest.isComplete == true or false,
		-- Unknown readiness must not establish an unfinished baseline.
		isReadyForTurnIn = trackedQuest and trackedQuest.isReadyForTurnIn,
		isFlaggedCompleted = false,
		isOnQuest = false,
	}

	if type(trackedQuest) == "table" then
		state.isOnQuest = true
	end

	if self.EnsureQuestSnapshotStore then
		self:EnsureQuestSnapshotStore()
	end
	local snapshot = self.GetQuestSnapshot and self:GetQuestSnapshot(numericQuestId) or nil
	if type(snapshot) == "table" then
		state.isTracked = true
		state.isOnQuest = true
		if state.isComplete ~= true then
			state.isComplete = snapshot.isComplete == true
		end
	end

	if allowLiveFallback ~= true then
		return state
	end

	if self.IsWorkBlocked and self:IsWorkBlocked("quest_snapshot_refresh") then
		return state
	end

	for field, method in pairs({
		isFlaggedCompleted = "IsQuestFlaggedCompleted",
		isReadyForTurnIn = "IsQuestReadyForTurnIn",
		isComplete = "IsQuestComplete",
		isOnQuest = "IsOnQuest",
	}) do
		if self.API and type(self.API[method]) == "function" then
			local value = self.API[method](numericQuestId)
			if self:CanAccessValue(value) and type(value) == "boolean" then
				state[field] = value
			end
		end
	end
	if not state.isOnQuest then
		local questLogIndex = self.API
			and self.API.GetQuestLogIndexForQuestID
			and self.API.GetQuestLogIndexForQuestID(numericQuestId)
		local isOnQuest = self.API and self.API.IsOnQuest and self.API.IsOnQuest(numericQuestId)
		state.isOnQuest = (questLogIndex ~= nil) or (isOnQuest and true or false)
	end

	return state
end

function QuestTogether:GetQuestShareableStatusLabel(questId)
	local numericQuestId = self:SafeToNumber(questId)
	if not numericQuestId then
		return "Unknown"
	end

	local statusState = self:GetTrackedQuestStatusState(numericQuestId, true)
	if type(statusState) ~= "table" or statusState.isOnQuest ~= true then
		return "Unknown"
	end

	if self.IsWorkBlocked and self:IsWorkBlocked("quest_snapshot_refresh") then
		return "Unknown"
	end

	local pushable = self.API and self.API.IsPushableQuest and self.API.IsPushableQuest(numericQuestId)
	if not self:CanAccessValue(pushable) or type(pushable) ~= "boolean" then
		return "Unknown"
	end
	return pushable and "Yes" or "No"
end

-- UI text only: never rewrite received snapshots or their revision inputs.
-- Keep quest names bounded and single-line; escaped output is idempotent.
function QuestTogether:NormalizeQuestDisplayTitleText(value)
	if not self:CanAccessValue(value) or type(value) ~= "string" or #value > 1024 then return "" end
	local text = value:gsub("||", "|")
	local previous
	repeat
		previous = text
		text = text:gsub("|H.-|h(.-)|h", "%1"):gsub("|T.-|t", ""):gsub("|A.-|a", "")
		text = text:gsub("|K.-|k", ""):gsub("|c%x%x%x%x%x%x%x%x", ""):gsub("|r", "")
		-- Removing malformed nested markup may expose another tag. Every
		-- changed pass shortens the bounded input; normalize to a fixed point.
	until text == previous
	text = self:SafeTrimString(text:gsub("[%c]", " "), "")
	if #text > 512 then return "" end
	return text:gsub("|", "||")
end

function QuestTogether:NormalizeQuestLinkTitleText(titleText, questId)
	local normalizedText = self:SafeTrimString(titleText, "")
	if string.find(normalizedText, "|H", 1, true) then
		-- Chat hyperlink callbacks may supply the complete formatted message,
		-- including speaker, quest and coordinate links. Only the clicked quest's
		-- display text is a title; never wrap the whole message in another link.
		local numericQuestId = self:SafeToNumber(questId)
		local questLinkType = self.chatLogQuestLinkType or "questtogetherquest"
		local matchedTitle
		for linkType, options, displayStart in string.gmatch(normalizedText, "|H([^:|]+):([^|]*)|h()") do
			if linkType == questLinkType and numericQuestId and self:SafeToNumber(options) == numericQuestId then
				local displayEnd = string.find(normalizedText, "|h", displayStart, true)
				local display = displayEnd and string.sub(normalizedText, displayStart, displayEnd - 1)
				-- Skip malformed outer wrappers from older status messages, but
				-- keep scanning their inner links to recover the actual quest title.
				if display and not string.find(display, "|H", 1, true) then
					matchedTitle = display
					break
				end
			end
		end
		if not matchedTitle then
			return ""
		end
		normalizedText = matchedTitle
	end
	normalizedText = normalizedText:gsub("|c%x%x%x%x%x%x%x%x", ""):gsub("|r", "")
	normalizedText = self:SafeTrimString(normalizedText, "")
	if SafeMatch(normalizedText, "^%[.+%]$") then
		normalizedText = string.sub(normalizedText, 2, -2)
	end
	return normalizedText
end

function QuestTogether:BuildQuestStatusMessage(questId, fallbackTitle)
	local numericQuestId = self:SafeToNumber(questId)
	if not numericQuestId then
		return L("Quest status unavailable.")
	end

	local questTitle = self:GetQuestDisplayTitle(numericQuestId, fallbackTitle)
	local statusLabel = self:GetQuestStatusLabel(numericQuestId)
	local shareableLabel = self:GetQuestShareableStatusLabel(numericQuestId)
	local questLabel = self:BuildChatLogQuestLabel(numericQuestId, questTitle)
	return L("Quest Status: ")
		.. questLabel
		.. " - "
		.. tostring(L(statusLabel))
		.. L(" | Shareable: ")
		.. tostring(L(shareableLabel))
end

function QuestTogether:GetQuestStatusAnnouncementEventType(questId)
	local statusLabel = self:GetQuestStatusLabel(questId)
	if statusLabel == "Completed" or statusLabel == "Objectives Complete" then
		return "QUEST_COMPLETED"
	end
	if statusLabel == "Ready to Turn In" then
		return "QUEST_READY_TO_TURN_IN"
	end
	if statusLabel == "In Progress" then
		return "QUEST_PROGRESS"
	end
	if statusLabel == "Not Started" then
		return "QUEST_ACCEPTED"
	end

	return "QUEST_PROGRESS"
end

function QuestTogether:GetTrackedQuestAnnouncementIcon(questData)
	if type(questData) ~= "table" then
		return nil, nil
	end

	local iconAsset = tostring(questData.iconAsset or "")
	if iconAsset == "" then
		return nil, nil
	end

	local iconKind = tostring(questData.iconKind or "")
	if iconKind == "" then
		return iconAsset, nil
	end

	return iconAsset, iconKind
end

function QuestTogether:RefreshTrackedQuestAnnouncementIcon(questId, questData, eventType)
	local numericQuestId = self:SafeToNumber(questId)
	if not numericQuestId or type(questData) ~= "table" then
		return nil, nil
	end

	local resolvedEventType = eventType or self:GetQuestStatusAnnouncementEventType(numericQuestId)
	local iconAsset, iconKind = self:GetAnnouncementIconInfo(resolvedEventType, numericQuestId)
	questData.iconAsset = iconAsset or nil
	questData.iconKind = iconKind or nil
	return iconAsset, iconKind
end

function QuestTogether:PrintQuestStatus(questId, fallbackTitle)
	local message = self:BuildQuestStatusMessage(questId, fallbackTitle)
	local eventType = self:GetQuestStatusAnnouncementEventType(questId)
	self:PrintConsoleAnnouncement(message, nil, nil, eventType)
end

function QuestTogether:GetQuestCompareRemoteStatusLabel(isComplete)
	if isComplete then
		return "Complete"
	end

	return "In Progress"
end

function QuestTogether:GetQuestCompareShareableToYouLabel(isPushable)
	if type(isPushable) == "boolean" then
		return isPushable and "Yes" or "No"
	end

	if type(isPushable) == "string" then
		local normalized = string.lower(isPushable)
		if isPushable == "1" or normalized == "true" then
			return "Yes"
		end
		if isPushable == "0" or normalized == "false" then
			return "No"
		end
	end

	return "Unknown"
end

function QuestTogether:BuildQuestCompareMessage(_remoteName, compareEntry)
	if type(compareEntry) ~= "table" then
		return L("Quest comparison unavailable.")
	end

	local questId = self:SafeToNumber(compareEntry.questId)
	local questTitle = self:GetQuestDisplayTitle(questId, compareEntry.questTitle)
	local localStatus = self:GetQuestStatusLabel(questId)
	local shareableLabel = self:GetQuestCompareShareableToYouLabel(compareEntry.isPushable)
	local remoteStatus = self:GetQuestCompareRemoteStatusLabel(compareEntry.isComplete)
	local decoratedQuestTitle = self:BuildChatLogQuestLabel(questId, questTitle)

	return tostring(decoratedQuestTitle)
		.. L(" | Them: ")
		.. tostring(L(remoteStatus))
		.. L(" | You: ")
		.. tostring(L(localStatus))
		.. L(" | Shareable to You: ")
		.. tostring(L(shareableLabel))
end

function QuestTogether:PrintQuestCompareMessage(remoteName, compareEntry, classFile)
	local eventType = compareEntry and compareEntry.isComplete and "QUEST_COMPLETED" or "QUEST_PROGRESS"
	local locationInfo = {
		questId = compareEntry and compareEntry.questId or nil,
	}
	self:PrintConsoleAnnouncement(
		self:BuildQuestCompareMessage(remoteName, compareEntry),
		remoteName,
		classFile,
		eventType,
		nil,
		nil,
		locationInfo
	)
end

function QuestTogether:PrintQuestCompareStart(remoteName, classFile)
	self:PrintConsoleAnnouncement(L("Comparing quests..."), remoteName, classFile, "QUEST_PROGRESS")
end

function QuestTogether:PrintQuestCompareDone(remoteName, count, classFile)
	local suffix = ""
	local numericCount = self:SafeToNumber(count)
	if numericCount then
		suffix = string.format(L(" (%d quests)"), numericCount)
	end
	self:PrintConsoleAnnouncement(
		L("Finished comparing quests") .. suffix .. ".",
		remoteName,
		classFile,
		"QUEST_COMPLETED"
	)
end

function QuestTogether:BuildConsoleAnnouncementMessage(
	targetName,
	message,
	classFile,
	eventType,
	iconAsset,
	iconKind,
	locationInfo
)
	local iconTag = self:GetAnnouncementIconChatTag(eventType, 14, iconAsset, iconKind, targetName)
	local questId = type(locationInfo) == "table" and locationInfo.questId or nil
	local trimmedMessage = self:DecorateAnnouncementMessageWithQuestLink(tostring(message or ""), eventType, questId)
	local body = trimmedMessage
	local speakerText = self:BuildChatLogSpeakerLabel(targetName, classFile)
	local textColor = eventType == "QT_CHAT" and "|cffffffff" or "|cffffd200"

	if iconTag ~= "" then
		return iconTag .. speakerText .. textColor .. ": " .. body .. "|r"
	end

	return speakerText .. textColor .. ": " .. body .. "|r"
end

function QuestTogether:BuildPingResponseMessage(pongData)
	if type(pongData) ~= "table" then
		return L("|cff33ff99QuestTogether|r: Pong: <invalid payload>")
	end

	local senderName = pongData.senderName or L("Unknown")
	local speakerLabel = self:GetShortDisplayName(senderName)
	local speakerColor = self:GetClassColorCode(pongData.classFile)
	local coloredName = speakerColor .. tostring(speakerLabel or L("Unknown")) .. "|r"
	local realmName = tostring(pongData.realmName or "")
	local identityOK, raceName, className = pcall(
		self.GetPlayerTooltipIdentity,
		self,
		{ name = senderName, race = pongData.raceName, className = pongData.className, classFile = pongData.classFile }
	)
	if not identityOK then
		raceName, className = pongData.raceName, pongData.className
	end
	raceName, className = tostring(raceName or ""), tostring(className or pongData.classFile or "")
	local level = self:SafeToNumber(pongData.level)

	local parts = {}
	parts[#parts + 1] = coloredName
	if not self:UsesRegionalPlayerNames() and realmName ~= "" then
		parts[#parts + 1] = "(" .. realmName .. ")"
	end
	if level then
		parts[#parts + 1] = L("Lvl ") .. tostring(math.floor(level))
	end
	if raceName ~= "" then
		parts[#parts + 1] = raceName
	end
	if className ~= "" then
		parts[#parts + 1] = className
	end
	local addonVersion = tostring(pongData.addonVersion or "")
	if addonVersion ~= "" then
		parts[#parts + 1] = L("QT v") .. addonVersion
	end

	local locationBits = {}
	local zoneName = tostring(pongData.zoneName or "")
	local mapID = self:SafeToNumber(pongData.mapID)
	if
		not self:IsRuntimeRestricted()
		and mapID
		and mapID > 0
		and mapID == math.floor(mapID)
		and self.API.GetMapInfo
	then
		local ok, info = pcall(self.API.GetMapInfo, mapID)
		if ok and self:CanAccessTable(info) then
			local localized = self:SafeTrimString(info.name, "")
			if localized ~= "" then
				zoneName = localized
			end
		end
	end
	if zoneName ~= "" then
		locationBits[#locationBits + 1] = zoneName
	end
	local coordX = self:SafeToNumber(pongData.coordX)
	local coordY = self:SafeToNumber(pongData.coordY)
	if coordX and coordY then
		locationBits[#locationBits + 1] = self:BuildPingCoordinateLabel(pongData.mapID, coordX, coordY)
	end
	local warMode = self:NormalizeAnnouncementWarModeValue(pongData.warMode)
	if self:SupportsWarMode() == true and warMode ~= nil then
		locationBits[#locationBits + 1] = warMode and L("WM On") or L("WM Off")
	end
	if #locationBits > 0 then
		parts[#parts + 1] = "- " .. table.concat(locationBits, " | ")
	end
	if pongData.developer then
		parts[#parts + 1] = "- " .. L("Share my location") .. ": " .. (pongData.locationShared and L("On") or L("Off"))
	end

	return L("|cff33ff99QuestTogether|r: Pong: ") .. table.concat(parts, " ")
end

function QuestTogether:BuildPingCoordinateLabel(mapID, coordX, coordY)
	local numericX = self:SafeToNumber(coordX)
	local numericY = self:SafeToNumber(coordY)
	if not numericX or not numericY then
		return ""
	end

	local bracketedText = string.format("[%.1f, %.1f]", numericX, numericY)
	local numericMapID = self:SafeToNumber(mapID)
	if not numericMapID or not LinkUtil or not LinkUtil.FormatLink then
		return bracketedText
	end

	local linkData = string.format("%d:%.1f:%.1f", numericMapID, numericX, numericY)
	return LinkUtil.FormatLink(self.chatLogCoordLinkType or "questtogethercoord", bracketedText, linkData)
end

function QuestTogether:PrintPingResponse(pongData)
	self:PrintChatLogRaw(self:BuildPingResponseMessage(pongData))
end

function QuestTogether:CreateTomTomWaypoint(mapID, coordX, coordY)
	local numericMapID = self:SafeToNumber(mapID)
	local numericX = self:SafeToNumber(coordX)
	local numericY = self:SafeToNumber(coordY)
	if not numericMapID or not numericX or not numericY then
		return false
	end

	if not (self.API and self.API.IsAddOnLoaded and self.API.IsAddOnLoaded("TomTom")) then
		return false
	end

	local tomTom = _G.TomTom
	if not self:CanAccessTable(tomTom) then
		return false
	end
	local addWaypoint = tomTom.AddWaypoint
	if not self:CanAccessValue(addWaypoint) or type(addWaypoint) ~= "function" then
		return false
	end

	-- TomTom may reject waypoint creation during transient map states; keep fallback path alive.
	local ok = pcall(addWaypoint, tomTom, numericMapID, numericX / 100, numericY / 100, {
		title = string.format("QuestTogether %.1f, %.1f", numericX, numericY),
		from = "QuestTogether/ping",
	})
	return ok and true or false
end

function QuestTogether:CreateBlizzardWaypoint(mapID, coordX, coordY)
	local numericMapID = self:SafeToNumber(mapID)
	local numericX = self:SafeToNumber(coordX)
	local numericY = self:SafeToNumber(coordY)
	if not numericMapID or not numericX or not numericY then
		return false
	end
	-- Disabled runtime has no restriction-release wakeups, and enabling resets
	-- its deferred lifetime. Reject a blocked click instead of accepting work
	-- that cannot run. Unrestricted explicit clicks remain available.
	if self.isEnabled ~= true and self.IsWorkBlocked and self:IsWorkBlocked("waypoint_mutation") then
		return false
	end

	local function applyWaypoint()
		if not (self.API and self.API.CanSetUserWaypointOnMap and self.API.CanSetUserWaypointOnMap(numericMapID)) then
			return false
		end

		local point = self.API.CreateUiMapPoint
			and self.API.CreateUiMapPoint(numericMapID, numericX / 100, numericY / 100)
		if not point then
			return false
		end

		if not self.API.SetUserWaypoint then
			return false
		end
		local ok, wasSet = pcall(self.API.SetUserWaypoint, point)
		if not ok or not self:CanAccessValue(wasSet) or wasSet ~= true then
			return false
		end
		if self.API.SetSuperTrackedUserWaypoint then
			pcall(self.API.SetSuperTrackedUserWaypoint, true)
		end
		return true
	end

	if self.RunOrDeferWork then
		self:SetPendingWaypointIntent({
			mapID = numericMapID,
			coordX = numericX,
			coordY = numericY,
		})
		local applied = false
		local ranNow = self:RunOrDeferWork("waypoint_mutation", "user_waypoint", function()
			local pending = self.GetRuntimeWorkStateStore and self:GetRuntimeWorkStateStore().pendingWaypointIntent
				or nil
			self:SetPendingWaypointIntent(nil)
			if pending then
				applied = applyWaypoint()
			end
		end, 0.2, "CreateBlizzardWaypoint")
		if not ranNow then
			return true
		end
		return applied
	end

	return applyWaypoint()
end

function QuestTogether:OpenPingWaypoint(mapID, coordX, coordY)
	-- Explicit coordinate navigation also ends following when TomTom handles it.
	self:StopPartyQuestFollow()
	if self:CreateTomTomWaypoint(mapID, coordX, coordY) then
		return true
	end

	return self:CreateBlizzardWaypoint(mapID, coordX, coordY)
end

function QuestTogether:PrintConsoleAnnouncement(
	message,
	targetName,
	classFile,
	eventType,
	iconAsset,
	iconKind,
	locationInfo
)
	local speakerName = targetName
	local isRemoteSpeaker = false
	if speakerName == nil or speakerName == "" then
		speakerName = self:GetPlayerFullName() or self:GetPlayerName()
	end
	local resolvedClassFile = classFile
	if not resolvedClassFile or resolvedClassFile == "" then
		if speakerName ~= nil and speakerName ~= "" and self.NormalizeMemberName then
			local normalizedSpeaker = self:NormalizeMemberName(speakerName)
			local normalizedPlayer = self:NormalizeMemberName(self:GetPlayerFullName() or self:GetPlayerName() or "")
			isRemoteSpeaker = normalizedSpeaker and normalizedPlayer and normalizedSpeaker ~= normalizedPlayer and true
				or false
			if isRemoteSpeaker then
				resolvedClassFile = self.GetGroupedSenderClassFile and self:GetGroupedSenderClassFile(speakerName)
					or nil
			end
		end
		if (not resolvedClassFile or resolvedClassFile == "") and not isRemoteSpeaker then
			resolvedClassFile = self:GetPlayerClassFile()
		end
	end
	self:PrintChatLogRaw(
		self:BuildConsoleAnnouncementMessage(
			speakerName,
			message,
			resolvedClassFile,
			eventType,
			iconAsset,
			iconKind,
			locationInfo
		)
	)
end

function QuestTogether:ShowChatLogSpeakerMenu(ownerFrame, speakerName, firstAction)
	if not MenuUtil or not MenuUtil.CreateContextMenu then
		return false
	end

	MenuUtil.CreateContextMenu(ownerFrame, function(_, rootDescription)
		self:PopulateChatLogSpeakerMenu(rootDescription, ownerFrame, speakerName, firstAction)
	end)
	return true
end

function QuestTogether:IsIgnoredPlayerName(playerName)
	local fullName = self:SafeTrimString(playerName, "")
	if fullName == "" or not self.API or not self.API.IsOnIgnoredList then
		return false
	end

	if self.API.IsOnIgnoredList(fullName) then
		return true
	end
	-- Hiding our surname is presentation only; never query social identity
	-- using a first-name-only label that could identify somebody else.
	if self:UsesRegionalPlayerNames() then
		return false
	end

	local shortName = self:GetShortDisplayName(fullName)
	if shortName ~= "" and shortName ~= fullName and self.API.IsOnIgnoredList(shortName) then
		return true
	end

	return false
end

function QuestTogether:InviteChatLogSpeaker(speakerName)
	local fullName = tostring(speakerName or "")
	if fullName == "" or not self.API or not self.API.InviteUnit then
		return false
	end

	local ok, sent = pcall(self.API.InviteUnit, fullName)
	return ok and sent == true
end

function QuestTogether:WhisperChatLogSpeaker(speakerName, ownerFrame)
	local fullName = tostring(speakerName or "")
	if fullName == "" or not self.API or not self.API.SendTell then
		return false
	end

	return self.API.SendTell(fullName, ownerFrame) == true
end

function QuestTogether:AddFriendFromChatLogSpeaker(speakerName)
	local fullName = tostring(speakerName or "")
	if fullName == "" or not self.API or not self.API.AddFriend then
		return false
	end

	self.API.AddFriend(fullName)
	return true
end

function QuestTogether:ToggleIgnoreChatLogSpeaker(speakerName)
	local fullName = tostring(speakerName or "")
	if fullName == "" or not self.API or not self.API.AddOrDelIgnore then
		return false
	end

	self.API.AddOrDelIgnore(fullName)
	if self.IGNORELIST_UPDATE then
		self:IGNORELIST_UPDATE()
	end
	return true
end

function QuestTogether:CompareQuestsWithChatLogSpeaker(speakerName)
	local fullName = self:NormalizeMemberName(speakerName) or tostring(speakerName or "")
	if fullName == "" or not self.OpenPlayerQuestCompare then
		return false
	end

	return self:OpenPlayerQuestCompare(fullName)
end

function QuestTogether:PopulateChatLogSpeakerMenu(rootDescription, ownerFrame, speakerName, firstAction)
	if not rootDescription then
		return false
	end

	local fullName = tostring(speakerName or "")
	local shortName = self:GetShortDisplayName(fullName)
	local isIgnored = false
	-- Context menus should stay usable even if ignored-list lookups fail for edge-case names.
	local ignoredOk, ignoredResult = pcall(function()
		return self:IsIgnoredPlayerName(fullName)
	end)
	if ignoredOk and ignoredResult then
		isIgnored = true
	end

	rootDescription:CreateTitle(shortName ~= "" and shortName or "QuestTogether")
	if self:IsPlayerLookingForQuestPartners(fullName) then
		rootDescription:CreateTitle(L("Looking for Questing Partners"))
	end

	if fullName ~= "" then
		if firstAction then
			firstAction(rootDescription)
		end
		local requestJoin = self.ShouldRequestPartyJoin and self:ShouldRequestPartyJoin(fullName)
		rootDescription:CreateButton(requestJoin and L("Request to Join") or L("Invite"), function()
			if requestJoin then
				self:RequestPartyJoin(fullName)
			else
				self:InviteChatLogSpeaker(fullName)
			end
		end)
		rootDescription:CreateButton(L("Whisper"), function()
			self:WhisperChatLogSpeaker(fullName, ownerFrame)
		end)
		rootDescription:CreateButton(L("Add Friend"), function()
			self:AddFriendFromChatLogSpeaker(fullName)
		end)
		rootDescription:CreateButton(isIgnored and L("Unignore") or L("Ignore"), function()
			self:ToggleIgnoreChatLogSpeaker(fullName)
		end)
		rootDescription:CreateButton(L("Compare Quests"), function()
			self:CompareQuestsWithChatLogSpeaker(fullName)
		end)
		if self:CanFindPlayerOnMap(fullName) then
			rootDescription:CreateButton(L("Find on Map"), function()
				self:FindPlayerOnMap(fullName)
			end)
		end
		self:PopulatePlayerNotesMenu(rootDescription, fullName)
	end

	self:PopulatePartyFocusMenu(rootDescription, fullName)
	return true
end

function QuestTogether:PopulateChatLogDestinationMenu(rootDescription)
	local isSeparate = self:GetOption("chatLogDestination") == "separate"
	local buttonText = isSeparate and L("Move QuestTogether Logs to Main Window")
		or L("Move QuestTogether Logs to Separate Window")
	rootDescription:CreateButton(buttonText, function()
		if self:IsRuntimeRestricted() then
			return
		end
		self:SetOption("chatLogDestination", isSeparate and "main" or "separate")
		if self.RefreshOptionsWindow then
			self:RefreshOptionsWindow()
		end
	end)
end

function QuestTogether:HandleChatLogSpeakerLink(_link, _text, linkData, contextData)
	local speakerName = linkData and linkData.options
	if not speakerName or speakerName == "" then
		return LinkProcessorResponse.Handled
	end
	if self.API and self.API.IsModifiedClick and self.API.IsModifiedClick("CHATLINK") then
		return LinkProcessorResponse.Handled
	end
	return self:ShowChatLogSpeakerMenu(contextData and contextData.frame or UIParent, speakerName)
			and LinkProcessorResponse.Handled
		or LinkProcessorResponse.Handled
end

function QuestTogether:HandleChatLogQuestLink(_link, text, linkData, contextData)
	if not self:CanAccessTable(linkData) then
		return LinkProcessorResponse.Handled
	end
	local questId = self:SafeToNumber(linkData.options)
	if not questId or questId <= 0 or questId ~= math.floor(questId) then
		return LinkProcessorResponse.Handled
	end
	if self.API and self.API.IsModifiedClick and self.API.IsModifiedClick("CHATLINK") then
		return LinkProcessorResponse.Handled
	end

	if not self:CanAccessValue(contextData) then
		return LinkProcessorResponse.Handled
	end
	if contextData ~= nil and not self:CanAccessTable(contextData) then
		return LinkProcessorResponse.Handled
	end
	if not self:ShowChatLogQuestMenu(contextData and contextData.frame, questId, self:SafeTrimString(text, "")) then
		self:Print(L("Quest menu is unavailable."))
	end
	return LinkProcessorResponse.Handled
end

function QuestTogether:GetQuestShareAvailability(questId)
	local id = self:SafeToNumber(questId)
	if not id or id <= 0 or id ~= math.floor(id) then
		return nil, L("Invalid quest."), "invalid"
	end
	if not self.isEnabled then
		return nil, L("Enable QuestTogether to share quests."), "disabled"
	end
	if self:IsWorkBlocked("quest_share") then
		return nil, L("Quest sharing is unavailable while restricted."), "restricted"
	end
	if not self.API.CanShareQuests or self.API.CanShareQuests() ~= true then
		return nil, L("Quest sharing is unavailable on this client."), "unsupported"
	end
	if not self.API.IsInGroup or self.API.IsInGroup() ~= true then
		return nil, L("Join a party to share quests."), "group"
	end
	local index = self:SafeToNumber(self.API.GetQuestLogIndexForSharing(id))
	if not index or index <= 0 or index ~= math.floor(index) then
		return nil, L("This quest is not available in your quest log."), "not_owned"
	end
	local pushable = self.API.IsPushableQuest(id)
	if not self:CanAccessValue(pushable) or type(pushable) ~= "boolean" then
		return nil, L("Quest shareability is unavailable."), "unknown"
	end
	if not pushable then
		return nil, L("This quest cannot be shared."), "not_shareable"
	end
	return index
end

function QuestTogether:ShareQuestFromChatLog(questId)
	-- A menu can outlive its initial eligibility check. Never retain its index
	-- or queue this manual action for a later party/restriction state.
	local index, reason = self:GetQuestShareAvailability(questId)
	if not index then
		self:Print(reason)
		return false
	end
	if not self.API.PushQuestToParty(index) then
		self:Print(L("Unable to share that quest."))
		return false
	end
	return true
end

function QuestTogether:GetQuestJournalAvailability(questId)
	local id = self:SafeToNumber(questId)
	if not id or id <= 0 or id ~= math.floor(id) then
		return nil, L("Invalid quest.")
	end
	if self:IsWorkBlocked("foreign_frame_mutation") then
		return nil, L("Opening the quest log is unavailable while restricted.")
	end
	if not self.API.CanOpenQuestJournal or self.API.CanOpenQuestJournal() ~= true then
		return nil, L("Opening the quest log is unavailable on this client.")
	end
	local index = self:SafeToNumber(self.API.GetQuestLogIndexForQuestID(id))
	if not index or index <= 0 or index ~= math.floor(index) then
		return nil, L("This quest is not in your quest log.")
	end
	return id
end

function QuestTogether:OpenQuestJournalFromChatLog(questId)
	-- Recheck the quest and restrictions when clicked; never open stale or
	-- deferred journal entries after the player has moved on.
	local id, reason = self:GetQuestJournalAvailability(questId)
	if not id then
		self:Print(reason)
		return false
	end
	if self.API.OpenQuestJournal(id) ~= true then
		self:Print(L("Unable to open that quest in your quest log."))
		return false
	end
	return true
end

function QuestTogether:GetQuestDetailsAvailability(questId)
	local id = self:SafeToNumber(questId)
	if not id or id <= 0 or id > 2147483647 or id ~= math.floor(id) then
		return nil, L("Invalid quest.")
	end
	if self:IsWorkBlocked("foreign_frame_mutation") then
		return nil, L("Quest details are unavailable while restricted.")
	end
	if not self.API.CanOpenQuestDetails or self.API.CanOpenQuestDetails() ~= true then
		return nil, L("Quest details are unavailable on this client.")
	end
	return id
end

function QuestTogether:OpenQuestDetailsFromChatLog(questId, fallbackTitle)
	local id, reason = self:GetQuestDetailsAvailability(questId)
	if not id then
		self:Print(reason)
		return false
	end
	if self:ShowQuestDetails(id, fallbackTitle) ~= true then
		self:Print(L("Unable to show details for that quest."))
		return false
	end
	return true
end

function QuestTogether:PopulateChatLogQuestMenu(rootDescription, questId, fallbackTitle)
	local details = rootDescription:CreateButton(L("Quest Details"), function()
		self:OpenQuestDetailsFromChatLog(questId, fallbackTitle)
	end)
	local detailsID, detailsReason = self:GetQuestDetailsAvailability(questId)
	details:SetEnabled(detailsID ~= nil)
	details:SetTooltip(function(tooltip)
		if self:CanAccessForeignFrame(tooltip) then
			tooltip:SetText(detailsReason or L("Show the game's available information for this quest."))
		end
	end)
	local share = rootDescription:CreateButton(L("Share"), function()
		self:ShareQuestFromChatLog(questId)
	end)
	local index, reason = self:GetQuestShareAvailability(questId)
	share:SetEnabled(index ~= nil)
	share:SetTooltip(function(tooltip)
		if self:CanAccessForeignFrame(tooltip) then
			tooltip:SetText(reason or L("Share this quest with your party."))
		end
	end)
	local journal = rootDescription:CreateButton(L("Open in Quest Log"), function()
		self:OpenQuestJournalFromChatLog(questId)
	end)
	local journalID, journalReason = self:GetQuestJournalAvailability(questId)
	journal:SetEnabled(journalID ~= nil)
	journal:SetTooltip(function(tooltip)
		if self:CanAccessForeignFrame(tooltip) then
			tooltip:SetText(journalReason or L("Open this quest in your quest log."))
		end
	end)
	local compare = rootDescription:CreateButton(L("Party Quest Log"), function()
		if self.isEnabled and not self:IsRuntimeRestricted() then
			self:OpenPartyQuestCompare()
		end
	end)
	compare:SetEnabled(self.isEnabled == true)
end

function QuestTogether:ShowChatLogQuestMenu(ownerFrame, questId, fallbackTitle)
	return self.API.CreateContextMenu(ownerFrame, function(_, rootDescription)
		self:PopulateChatLogQuestMenu(rootDescription, questId, fallbackTitle)
	end)
end

function QuestTogether:HandleChatLogCoordLink(_link, _text, linkData, _contextData)
	local options = tostring(linkData and linkData.options or "")
	local mapID, coordX, coordY = SafeMatch(options, "^([^:]+):([^:]+):([^:]+)$")
	if not mapID or not coordX or not coordY then
		return LinkProcessorResponse.Handled
	end
	if self.API and self.API.IsModifiedClick and self.API.IsModifiedClick("CHATLINK") then
		return LinkProcessorResponse.Handled
	end

	if not self:OpenPingWaypoint(mapID, coordX, coordY) then
		self:Print(L("Unable to set that waypoint."))
	end
	return LinkProcessorResponse.Handled
end

function QuestTogether:TryInstallChatLogLinkHandler()
	self:InitializeChatLogPlayerTooltips()
	if self.chatLogLinkHandlerInstalled then
		return
	end
	if not LinkUtil or not LinkUtil.RegisterLinkHandler then
		return
	end

	local speakerRegistered = LinkUtil.IsLinkHandlerRegistered
		and LinkUtil.IsLinkHandlerRegistered(self.chatLogLinkType)
	if not speakerRegistered then
		LinkUtil.RegisterLinkHandler(self.chatLogLinkType, function(link, text, linkData, contextData)
			return QuestTogether:HandleChatLogSpeakerLink(link, text, linkData, contextData)
		end)
	end

	local questRegistered = LinkUtil.IsLinkHandlerRegistered
		and LinkUtil.IsLinkHandlerRegistered(self.chatLogQuestLinkType)
	if not questRegistered then
		LinkUtil.RegisterLinkHandler(self.chatLogQuestLinkType, function(link, text, linkData, contextData)
			return QuestTogether:HandleChatLogQuestLink(link, text, linkData, contextData)
		end)
	end
	local coordRegistered = LinkUtil.IsLinkHandlerRegistered
		and LinkUtil.IsLinkHandlerRegistered(self.chatLogCoordLinkType)
	if not coordRegistered then
		LinkUtil.RegisterLinkHandler(self.chatLogCoordLinkType, function(link, text, linkData, contextData)
			return QuestTogether:HandleChatLogCoordLink(link, text, linkData, contextData)
		end)
	end
	local tipType = "questtogethertip"
	if not (LinkUtil.IsLinkHandlerRegistered and LinkUtil.IsLinkHandlerRegistered(tipType)) then
		LinkUtil.RegisterLinkHandler(tipType, function(_, _, linkData)
			if QuestTogether:CanAccessTable(linkData)
				and not (QuestTogether.API.IsModifiedClick and QuestTogether.API.IsModifiedClick("CHATLINK")) then
				QuestTogether:HandleHintActionLink(QuestTogether:SafeToString(linkData.options, ""))
			end
			return LinkProcessorResponse.Handled
		end)
	end
	self.chatLogLinkHandlerInstalled = true
end

function QuestTogether:PrintChatLogDestinationMessage()
	self:PrintConsoleAnnouncement(L("You will now see QuestTogether logs here."))
end

function QuestTogether:GetPlayerName()
	local playerName = self.API and self.API.UnitName and self.API.UnitName("player") or nil
	return playerName or L("Unknown")
end

function QuestTogether:IsSelfSender(sender)
	if not self:CanAccessValue(sender) or type(sender) ~= "string" or sender == "" then
		return false
	end
	local playerName = self:GetPlayerFullName()
	return playerName ~= nil and self:NormalizeMemberName(sender) == self:NormalizeMemberName(playerName)
end

function QuestTogether:GetAnnouncementOptionKey(eventType)
	local keysByType = {
		QUEST_ACCEPTED = "announceAccepted",
		LOOKING_FOR_QUEST_PARTNERS = "announceQuestPartners",
		QUEST_COMPLETED = "announceCompleted",
		QUEST_READY_TO_TURN_IN = "announceReadyToTurnIn",
		QUEST_REMOVED = "announceRemoved",
		QUEST_PROGRESS = "announceProgress",
		WORLD_QUEST_ENTERED = "announceWorldQuestAreaEnter",
		WORLD_QUEST_LEFT = "announceWorldQuestAreaLeave",
		WORLD_QUEST_PROGRESS = "announceWorldQuestProgress",
		WORLD_QUEST_COMPLETED = "announceWorldQuestCompleted",
		BONUS_OBJECTIVE_ENTERED = "announceBonusObjectiveAreaEnter",
		BONUS_OBJECTIVE_LEFT = "announceBonusObjectiveAreaLeave",
		BONUS_OBJECTIVE_PROGRESS = "announceBonusObjectiveProgress",
		BONUS_OBJECTIVE_COMPLETED = "announceBonusObjectiveCompleted",
	}

	return keysByType[eventType]
end

function QuestTogether:IsWorldQuestAnnouncementType(eventType)
	return eventType == "WORLD_QUEST_ENTERED"
		or eventType == "WORLD_QUEST_LEFT"
		or eventType == "WORLD_QUEST_PROGRESS"
		or eventType == "WORLD_QUEST_COMPLETED"
end

function QuestTogether:IsBonusObjectiveAnnouncementType(eventType)
	return eventType == "BONUS_OBJECTIVE_ENTERED"
		or eventType == "BONUS_OBJECTIVE_LEFT"
		or eventType == "BONUS_OBJECTIVE_PROGRESS"
		or eventType == "BONUS_OBJECTIVE_COMPLETED"
end

function QuestTogether:ShouldDisplayAnnouncementType(eventType)
	local optionKey = self:GetAnnouncementOptionKey(eventType)
	if not optionKey then
		return true
	end
	return self:GetOption(optionKey) and true or false
end

function QuestTogether:GetQuestTitle(questId, questInfo)
	local numericQuestId = self:NormalizeQuestID(questId)
	if not numericQuestId then
		return L("Quest ") .. tostring(questId)
	end

	if questInfo and type(questInfo.title) == "string" and questInfo.title ~= "" then
		return questInfo.title
	end

	if self.EnsureQuestSnapshotStore then
		self:EnsureQuestSnapshotStore()
	end
	local snapshot = self.GetQuestSnapshot and self:GetQuestSnapshot(numericQuestId) or nil
	if snapshot and type(snapshot.title) == "string" and snapshot.title ~= "" then
		return snapshot.title
	end

	return L("Quest ") .. tostring(numericQuestId)
end

function QuestTogether:IsPlaceholderQuestTitle(questId, title)
	local numericQuestId = self:NormalizeQuestID(questId)
	if not numericQuestId then
		return false
	end

	return type(title) == "string" and title == (L("Quest ") .. tostring(numericQuestId))
end

function QuestTogether:NormalizeQuestProgressPercent(progressValue)
	local numericProgress = self:SafeToNumber(progressValue)
	if numericProgress == nil then
		return nil
	end

	-- Blizzard progress bars can return floating values; format chat/objectives as whole percents.
	if numericProgress < 0 then
		numericProgress = 0
	elseif numericProgress > 100 then
		numericProgress = 100
	end

	return math.floor(numericProgress + 0.5)
end

function QuestTogether:StripTrailingParentheticalPercent(objectiveText)
	if type(objectiveText) ~= "string" or objectiveText == "" or self:IsSecretValue(objectiveText) then
		return objectiveText
	end

	local strippedText = string.gsub(objectiveText, "%s*%(%d+%%%s*%)%s*$", "")
	if strippedText == "" then
		return objectiveText
	end

	return strippedText
end

function QuestTogether:GetQuestLogIndexForQuest(questId, questInfo)
	if self.IsWorkBlocked and self:IsWorkBlocked("quest_snapshot_refresh") then
		return nil
	end
	local questLogIndex = questInfo and self:SafeToNumber(questInfo.questLogIndex) or nil
	if questLogIndex ~= nil then
		questLogIndex = math.floor(questLogIndex + 0.5)
		if questLogIndex <= 0 then
			questLogIndex = nil
		end
	end

	if questLogIndex then
		local row = self.API and self.API.GetQuestLogInfo and self.API.GetQuestLogInfo(questLogIndex)
		if not row or self:NormalizeQuestID(row.questID) ~= self:NormalizeQuestID(questId) then
			questLogIndex = nil
		end
	end

	if not questLogIndex and self.API and self.API.GetQuestLogIndexForQuestID then
		local normalizedQuestId = self:NormalizeQuestID(questId)
		if normalizedQuestId then
			local resolvedQuestLogIndex = self.API.GetQuestLogIndexForQuestID(normalizedQuestId)
			questLogIndex = self:SafeToNumber(resolvedQuestLogIndex)
			if questLogIndex ~= nil then
				questLogIndex = math.floor(questLogIndex + 0.5)
				if questLogIndex <= 0 then
					questLogIndex = nil
				end
			end
		end
	end

	return questLogIndex
end

function QuestTogether:NormalizeQuestObjectiveCounters(kind, finished, current, required)
	-- Forever can report 1/1 for an unfinished one-step objective (for
	-- example, Use Walk on Air). Its explicit completion flag is authoritative.
	-- Percentage objectives have a separate source and must not use this rule.
	if kind ~= "progressbar" and finished == false and current == 1 and required == 1 then
		current = 0
	end
	return current, required
end

function QuestTogether:GetNormalizedQuestObjectiveInfo(questId, objectiveIndex, displayComplete)
	local objectiveText, objectiveType, finished, currentValue, requiredValue = nil, nil, nil, nil, nil
	if self.API and self.API.GetQuestObjectiveInfo then
		objectiveText, objectiveType, finished, currentValue, requiredValue =
			self.API.GetQuestObjectiveInfo(questId, objectiveIndex, displayComplete)
	end
	if objectiveText == nil and objectiveType == nil and currentValue == nil then
		objectiveText = ""
	end

	if objectiveType == "progressbar" then
		local baseObjectiveText = self:StripTrailingParentheticalPercent(objectiveText)
		if type(baseObjectiveText) ~= "string" then
			baseObjectiveText = type(objectiveText) == "string" and objectiveText or ""
		end

		local progress = self.API
			and self.API.GetQuestProgressBarPercent
			and self.API.GetQuestProgressBarPercent(questId)
		local roundedProgress = self:NormalizeQuestProgressPercent(progress)
		if roundedProgress ~= nil then
			if baseObjectiveText ~= "" then
				objectiveText = tostring(roundedProgress) .. "% " .. baseObjectiveText
			else
				objectiveText = tostring(roundedProgress) .. "%"
			end
			currentValue = roundedProgress
		else
			objectiveText = baseObjectiveText
			-- The objective counter is not a percentage when the percent read is unavailable.
			currentValue = nil
		end
	end

	currentValue, requiredValue =
		self:NormalizeQuestObjectiveCounters(objectiveType, finished, currentValue, requiredValue)
	return objectiveText, objectiveType, finished, currentValue, requiredValue
end

function QuestTogether:GetPlayerTracker()
	local characterKey = self.activeCharacterKey or self:GetCurrentCharacterKey() or self:GetPlayerName() or "Unknown"
	if not self.db.global.questTrackers[characterKey] then
		self.db.global.questTrackers[characterKey] = {}
	end
	return self.db.global.questTrackers[characterKey]
end

function QuestTogether:GetMonitoredQuestCount()
	if not self:GetRuntimeFlag("questTrackerReady", false) or not self.db or not self.db.global then
		return nil
	end
	local count = 0
	for id, quest in pairs(self:GetPlayerTracker()) do
		if self:NormalizeQuestID(id) and type(quest) == "table" then
			count = count + 1
		end
	end
	return count
end

function QuestTogether:QueueQuestLogTask(taskFn)
	if type(taskFn) == "function" then
		table.insert(self.onQuestLogUpdate, taskFn)
		-- QUEST_ACCEPTED and UNIT_QUEST_LOG_CHANGED can precede readable log
		-- data. Only QUEST_LOG_UPDATE may release this batch into the scheduler.
	end
end

function QuestTogether:ResetQuestEventState()
	self:ResetObjectiveAnnouncements()
	self.onQuestLogUpdate = {}
	self.questsCompleted = {}
	self.pendingQuestRemovals = {}
	self.pendingQuestAcceptances = {}
	self.retiredQuestIds = {}
end

function QuestTogether:RegisterRuntimeEvents()
	self.registeredRuntimeEvents = self.registeredRuntimeEvents or {}
	wipe(self.registeredRuntimeEvents)

	for _, eventName in ipairs(self.runtimeEvents) do
		-- Event lists vary slightly by client flavor/build; register best-effort.
		local ok = pcall(self.eventFrame.RegisterEvent, self.eventFrame, eventName)
		if ok then
			self.registeredRuntimeEvents[eventName] = true
		else
			self:Debugf("events", "Skipping unavailable runtime event=%s", tostring(eventName))
		end
	end
end

function QuestTogether:UnregisterRuntimeEvents()
	for eventName in pairs(self.registeredRuntimeEvents or {}) do
		-- Unregister should not block disable if Blizzard already removed an event.
		pcall(self.eventFrame.UnregisterEvent, self.eventFrame, eventName)
	end

	if self.registeredRuntimeEvents then
		wipe(self.registeredRuntimeEvents)
	end
end

function QuestTogether:Enable()
	self.db.profile.enabled = true

	if not self.hasLoggedIn then
		-- We only fully enable after PLAYER_LOGIN when WoW APIs are guaranteed to be ready.
		return true
	end
	if self.isEnabled then
		return true
	end

	self:RegisterRuntimeEvents()
	self.API.RegisterAddonPrefix(self.commPrefix)
	self.isEnabled = true
	if self.ResumeCommsWorldSession then
		self:ResumeCommsWorldSession()
	end
	if self.RefreshMinimapPartnerGlow then
		self:RefreshMinimapPartnerGlow()
	end
	self:ResetQuestEventState()
	-- Events may have been missed while disabled/offline, including a repeatable
	-- quest being accepted again. Start a fresh observation lifetime on enable.
	wipe(self:GetPlayerTracker())
	if self.ResetTaskAreaStateStore then
		self:ResetTaskAreaStateStore()
	end
	if self.ResetRuntimeWorkStateStore then
		self:ResetRuntimeWorkStateStore()
	end
	if self.InitializeTransport then
		self:InitializeTransport()
	end
	if self.InitializeGeographicComms then
		self:InitializeGeographicComms()
	end
	if self.API.LeaveChannelByName then
		pcall(self.API.LeaveChannelByName, self.retiredAnnouncementChannelName)
	end
	if self.EnsureAnnouncementChannelJoined then
		self:EnsureAnnouncementChannelJoined()
		self:ScheduleAnnouncementChannelOrder()
	end
	if self.RefreshTaskAreaStates then
		self:RefreshTaskAreaStates(false)
	end

	if self.EnableNameplateAugmentation then
		self:EnableNameplateAugmentation()
	end
	if self.TryInstallPersonalBubbleEditModeHooks then
		self:TryInstallPersonalBubbleEditModeHooks()
	end
	if self.RefreshPersonalBubbleAnchorVisualState then
		self:RefreshPersonalBubbleAnchorVisualState()
	end

	self:Debug(L("Addon enabled."), "core")

	if self.RefreshPartyRoster then
		self:RefreshPartyRoster()
	end

	-- Delay initial scan briefly so quest log APIs are stable right after login/reload.
	local enabledWorkState = self:GetDeferredWorkStateStore()
	self.API.Delay(0.25, function()
		if self.isEnabled and self:GetDeferredWorkStateStore() == enabledWorkState then
			self:ScanQuestLog()
		end
	end)
	if self.InitializePlayerLocations then
		self:InitializePlayerLocations()
	end
	if self.InitializeRuntimeCoordinator then
		self:InitializeRuntimeCoordinator()
	end

	return true
end

function QuestTogether:Disable()
	self.db.profile.enabled = false
	self.pendingQuestScanAnnouncement = nil

	if not self.isEnabled then
		return true
	end
	self:RecordRecentCompanions(true)
	self:ResetRecentCompanionObservation()
	self:DismissRecentCompanions()
	if self.WithdrawPartyNavigation then
		self:WithdrawPartyNavigation()
	end
	if self.EndCommsWorldSession then
		self:EndCommsWorldSession()
	end
	if self.BroadcastQTPlayerPresence then
		self:BroadcastQTPlayerPresence(true)
	end
	if self.BroadcastPlayerLocation then
		self:BroadcastPlayerLocation(true, true)
	end
	if self.FlushGeographicDeparture then
		self:FlushGeographicDeparture()
	end

	self:UnregisterRuntimeEvents()
	if self.ResetRuntimeCoordinator then
		self:ResetRuntimeCoordinator()
	end
	self.isEnabled = false
	if self.RefreshMinimapPartnerGlow then
		self:RefreshMinimapPartnerGlow()
	end
	self:ResetQuestEventState()
	if self.ResetTaskAreaStateStore then
		self:ResetTaskAreaStateStore()
	end
	if self.ResetRuntimeWorkStateStore then
		self:ResetRuntimeWorkStateStore()
	end
	if self.LeaveAnnouncementChannel then
		self:LeaveAnnouncementChannel()
	end

	if self.DisableNameplateAugmentation then
		self:DisableNameplateAugmentation()
	end
	if self.RefreshPersonalBubbleAnchorVisualState then
		self:RefreshPersonalBubbleAnchorVisualState()
	end

	self:Debug(L("Addon disabled."), "core")
	return true
end

function QuestTogether:OpenHudEditMode()
	-- This explicit UI action must not initialize or open Blizzard panels while
	-- restrictions are active, including encounter/map states outside combat.
	if self:IsRuntimeRestricted() or not self.API or type(self.API.GetEditModeManagerFrame) ~= "function" then
		return false
	end
	local manager = self.API.GetEditModeManagerFrame()
	if not self:CanAccessValue(manager) then
		return false
	end
	if manager == nil then
		if type(self.API.LoadEditMode) ~= "function" or self.API.LoadEditMode() ~= true then
			return false
		end
		manager = self.API.GetEditModeManagerFrame()
	end
	if not self:CanAccessForeignFrame(manager) or self:IsRuntimeRestricted() then
		return false
	end
	local canEnter = self:GetAccessibleFrameMember(manager, "CanEnterEditMode")
	if type(canEnter) ~= "function" then
		return false
	end
	local ok, allowed = pcall(canEnter, manager)
	if not ok or not self:CanAccessValue(allowed) or allowed ~= true or self:IsRuntimeRestricted() then
		return false
	end

	-- ShowUIPanel owns the panel lifecycle; its OnShow initializes Edit Mode.
	-- Calling EnterEditMode directly activates editing with no visible manager.
	if type(self.API.ShowUIPanel) ~= "function" or self.API.ShowUIPanel(manager) ~= true then
		return false
	end
	return self:CanAccessForeignFrame(manager, true)
end

function QuestTogether:InitializeSlashCommands()
	SLASH_QUESTTOGETHER1 = "/qt"
	SLASH_QUESTTOGETHER2 = "/questtogether"
	SLASH_QUESTTOGETHER3 = "/questogether"

	SlashCmdList.QUESTTOGETHER = function(input)
		QuestTogether:HandleSlashCommand(input or "")
	end

	SLASH_QUESTTOGETHERDUMP1 = "/qtd"
	SlashCmdList.QUESTTOGETHERDUMP = function(input)
		local normalizedInput = QuestTogether:SafeTrimString(input, "")
		if normalizedInput ~= "" then
			QuestTogether:HandleSlashCommand("dump " .. normalizedInput)
			return
		end
		QuestTogether:ShowDebugWindow()
	end
end

function QuestTogether:ParseBoolean(text)
	if not text then
		return nil
	end
	local normalized = string.lower(text)
	if normalized == "true" or normalized == "1" or normalized == "on" or normalized == "yes" then
		return true
	end
	if normalized == "false" or normalized == "0" or normalized == "off" or normalized == "no" then
		return false
	end
	return nil
end

function QuestTogether:PrintHelp()
	self:Print(L("Commands:"))
	self:Print(L("/qt <message> - Chat with QuestTogether players (recognized commands still run)"))
	self:Print(L("/qt options - Open the QuestTogether options window"))
	self:Print(L("/qt enable | disable - Enable or disable runtime behavior"))
	self:Print(L("/qt set <option> <value> - Set a boolean option (e.g. emoteOnQuestCompletion off)"))
	self:Print(L("/qt get <option> - Read an option value"))
	self:Print(L("/qt pql - Open Party Quest Log"))
	self:Print(L("/qt companions - Open your private recent companions list"))
	self:Print(L("/qt vip - Learn about VIP rewards and activate your cosmetics"))
	self:Print(L("/qt tip | hint - Show another QuestTogether tip"))
	self:Print("/qt resetlayout - " .. L("Reset window layout"))
	self:Print(L("/qt lfg [on|off|toggle|status] - Set or check Looking for Questing Partners (no argument toggles)"))
	self:Print(L("/qt notes | changelog | patchnotes - Open the latest welcome and patch notes"))
	self:Print(L("/qt scan - Rescan your quest log now"))
	self:Print(L("/qt help debug - Show debugging and developer commands"))
end

function QuestTogether:PrintDebugHelp()
	self:Print(L("Debugging and developer commands:"))
	self:PrintPreviewHelp()
	self:Print(L("/qt debug - Open the shared QuestTogether debug window"))
	self:Print(L("/qt devlogall [on|off|toggle] - Show or control dev all-announcements logging"))
	self:Print(L("/qt test - Run in-game unit tests, then open /qt dump filtered to TEST"))
	self:Print(L("/qt dump [clear|CATEGORY] - Open the shared QuestTogether debug window"))
	self:Print(L("/qt diagnostics [questID] - Copy client, runtime, and recent event diagnostics"))
	self:Print(L("/qtd - Shortcut for /qt dump"))
end

function QuestTogether:PrintPreviewHelp()
	self:Print(
		L(
			"/qt preview share|join|partychat|bubble|discord|focus|unfollow - Preview a QT dialog without changing settings"
		)
	)
	self:Print(L("/qt preview compare - Preview Party Quest Log with mock data (no sharing)"))
	self:Print(L("/qt preview notes - Preview the welcome and patch-notes window"))
	self:Print(L("/qt preview announcement <text> - Run a local bubble preview for your current target"))
	self:Print(
		L(
			'/qt preview announcement "<player>" <text> - Run a local bubble preview for a nearby visible player (no target)'
		)
	)
	self:Print(L("Player names can be unquoted: Name-Realm, or First Surname on Forever."))
end

function QuestTogether:HandlePreviewCommand(input)
	local kind, arguments = SafeMatch(input, "^%s*(%S*)%s*(.-)$")
	kind = string.lower(kind or "")
	-- Only normalize the selector. Names, quotes and message text retain case.
	if kind == "announcement" then
		return self:PreviewBubbleAnnouncement(arguments or "")
	end
	if arguments and arguments ~= "" then
		self:PrintPreviewHelp()
		return false
	end
	if kind == "compare" then
		return self:OpenPartyQuestComparePreview()
	end
	if kind == "notes" or kind == "welcome" then
		return self:OpenReleaseNotes()
	end
	if
		kind == "share"
		or kind == "join"
		or kind == "partychat"
		or kind == "bubble"
		or kind == "discord"
		or kind == "focus"
		or kind == "unfollow"
	then
		return self:ShowDialogPreview(kind)
	end
	-- Empty/unknown preview commands are help, never outgoing QT chat.
	self:PrintPreviewHelp()
	return kind == "" or kind == "help"
end

function QuestTogether:PreviewBubbleAnnouncement(rest)
	if rest == nil or rest == "" then
		self:Print(L("Usage: /qt preview announcement <text>"))
		self:Print(L('   or: /qt preview announcement "<player>" <text> (without a target)'))
		return
	end
	if not self.SendBubbleAnnouncementTest then
		self:Print(L("Bubble test is unavailable."))
		return
	end

	local senderName = nil
	local testText = rest
	if not (self.API.UnitExists and self.API.UnitExists("target")) then
		local explicitSenderName, explicitText
		if string.sub(rest, 1, 1) == '"' then
			-- Quotes delimit a complete identity without consuming preview text.
			explicitSenderName, explicitText = SafeMatch(rest, '^"([^"]+)"%s+(.+)$')
		else
			explicitSenderName, explicitText = SafeMatch(rest, "^(%S+)%s+(.+)$")
			if
				explicitSenderName
				and self:UsesRegionalPlayerNames()
				and not string.find(explicitSenderName, "-", 1, true)
			then
				-- Native regional names have a first name and surname. Preserve
				-- legacy First-Surname inputs as a single identity token.
				local surname
				surname, explicitText = SafeMatch(explicitText, "^(%S+)%s+(.+)$")
				explicitSenderName = surname and (explicitSenderName .. " " .. surname) or nil
			end
		end
		senderName = self:SafeTrimString(explicitSenderName, "")
		testText = self:SafeTrimString(explicitText, "")
		if senderName == "" or testText == "" then
			self:Print(L('Usage without a target: /qt preview announcement "<player>" <text>'))
			return
		end
	end

	local ok, senderNameOrError = self:SendBubbleAnnouncementTest(testText, senderName)
	if not ok then
		self:Print(senderNameOrError)
		return
	end
	self:Print(L("Ran local bubble preview for ") .. tostring(self:GetShortDisplayName(senderNameOrError)))
	return
end

function QuestTogether:HandleSlashCommand(input)
	local compareCommand = string.lower(self:SafeTrimString(input, ""))
	if compareCommand == "partychatpreview" then
		return self:HandlePreviewCommand("partychat")
	elseif compareCommand == "pql" or compareCommand == "compare" then
		self:ClosePartyQuestComparePreview()
		return self:OpenPartyQuestCompare()
	elseif compareCommand:match("^compare%s+debug$") then
		return self:HandlePreviewCommand("compare")
	end
	local command, rest = SafeMatch(input, "^%s*(%S*)%s*(.-)$")
	command = string.lower(command or "")

	if command == "resetlayout" then
		return self:ResetWindowLayouts()
	end
	if command == "companions" then
		return self:OpenRecentCompanions()
	end
	if command == "vip" then return self:OpenVIPWindow() end
	if command == "tip" or command == "hint" then
		if not self:ShowHint() then self:Print(L("Tips are unavailable right now.")) end
		return
	end
	if command == "preview" then
		return self:HandlePreviewCommand(rest)
	end
	if command == "bubbletest" then
		return self:HandlePreviewCommand("announcement " .. (rest or ""))
	end
	if command == "discord" then
		return self:OpenDiscordSupport()
	end
	if command == "ad" then
		return self:HandleAdvertisementCommand(rest)
	end

	if command == "" or command == "options" then
		self:OpenOptionsWindow()
		return
	end
	if command == "notes" or command == "changelog" or command == "patchnotes" then
		return self:OpenReleaseNotes()
	end
	if command == "lfg" then
		return self:HandleQuestPartnerCommand(rest)
	end

	-- Help is presentation only; do not delegate topics to executable debug commands.
	if command == "help" then
		if string.lower(self:SafeTrimString(rest, "")) == "debug" then
			self:PrintDebugHelp()
		else
			self:PrintHelp()
		end
		return
	end

	-- Generic debug commands and their presentation belong to the shared controller.
	if (command == "diagnostics" or command == "diag") and string.lower(self:SafeTrimString(rest, "")) == "cursor" then
		local captured, reason = self:CapturePlayerNoteCursorDiagnostics()
		if not captured and reason then self:Print(reason) end
		return captured
	end
	if command == "debug" and rest ~= "" and rawget(self, "isLocalDeveloper") == true then
		return self:RequestRemoteDiagnostics(rest)
	end
	local debugCommand = command == "debuglog" and "dump" or command
	if (debugCommand == "dump" or debugCommand == "debug") and rest ~= "" then
		debugCommand = "dump " .. rest
	end
	local handled = self:GetDebugController():HandleCommand(debugCommand, rest)
	if handled then
		return
	end

	if command == "enable" then
		self:Enable()
		self:Print(L("QuestTogether enabled."))
		return
	end

	if command == "disable" then
		self:Disable()
		self:Print(L("QuestTogether disabled."))
		return
	end

	if command == "devlogall" then
		local flag = string.lower(rest or "")
		if flag == "" then
			self:Print("devLogAllAnnouncements = " .. tostring(self:GetOption("devLogAllAnnouncements")))
			return
		end
		if flag == "toggle" then
			self:SetOption("devLogAllAnnouncements", not self:GetOption("devLogAllAnnouncements"))
		else
			local boolValue = self:ParseBoolean(flag)
			if boolValue == nil then
				self:Print(L("Usage: /qt devlogall on|off|toggle"))
				return
			end
			self:SetOption("devLogAllAnnouncements", boolValue)
		end
		self:Print("devLogAllAnnouncements = " .. tostring(self:GetOption("devLogAllAnnouncements")))
		return
	end

	if command == "set" then
		local optionKey, optionValueText = SafeMatch(rest, "^(%S+)%s+(.+)$")
		if not optionKey or not optionValueText then
			self:Print(L("Usage: /qt set <option> <value>"))
			return
		end
		local boolValue = self:ParseBoolean(optionValueText)
		if boolValue == nil then
			self:Print(L("Only boolean values are supported here: true/false, on/off, 1/0"))
			return
		end
		if self:GetOption(optionKey) == nil then
			self:Print(L("Unknown option key: ") .. tostring(optionKey))
			return
		end
		if type(self.DEFAULTS.profile[optionKey]) ~= "boolean" then
			self:Print(L("This command only changes on/off settings."))
			return
		end
		self:SetOption(optionKey, boolValue)
		self:Print(optionKey .. " = " .. tostring(self:GetOption(optionKey)))
		if self.RefreshOptionsWindow then
			self:RefreshOptionsWindow()
		end
		return
	end

	if command == "get" then
		local optionKey = SafeMatch(rest, "^(%S+)$")
		if not optionKey then
			self:Print(L("Usage: /qt get <option>"))
			return
		end
		self:Print(optionKey .. " = " .. tostring(self:GetOption(optionKey)))
		return
	end

	if command == "scan" then
		self:ScanQuestLog()
		return
	end

	if command == "ping" then
		if
			rawget(self, "isLocalDeveloper") ~= true
			or not self.SendPingRequest
			or (rest ~= "" and string.lower(rest) ~= "global")
		then
			self:Print(L("Ping is unavailable."))
			return
		end

		local ok, requestIdOrError = self:SendPingRequest()
		if not ok then
			self:Print(tostring(requestIdOrError))
			return
		end

		self:PrintChatLogSystemMessage(L("Ping sent."))
		return
	end

	if not self:SendQTChannelChat(input) then
		self:Print(L("Unable to send QuestTogether chat. The addon must be enabled and its chat channel available."))
	end
end

-- Full quest log scan to build local objective snapshots.
function QuestTogether:ReconcileQuestTracking(snapshot)
	if
		not self:GetRuntimeFlag("questTrackerReady", false)
		or not self.db
		or not self.db.global
		or not snapshot
		or snapshot.lastUnreadableRow
	then
		return
	end
	local tracker = self:GetPlayerTracker()
	-- Later complete log data can contain quests missing from an initially
	-- empty/partial login snapshot. Initialize only missing entries; acceptance
	-- and removal events retain ownership of their own lifecycle and messages.
	for _, questID in ipairs(snapshot.order or {}) do
		local info = snapshot.byQuestID[questID]
		if
			info
			and not info.isHidden
			and not tracker[questID]
			and not (self.pendingQuestAcceptances and self.pendingQuestAcceptances[questID])
			and not (self.retiredQuestIds and self.retiredQuestIds[questID])
		then
			self:WatchQuest(questID, info)
		end
	end
end

function QuestTogether:PrintQuestScanAnnouncement(monitoredCount)
	if self:IsLocalVIPVerificationPending() and not self:IsVerifiedDeveloper(self:GetPlayerFullName()) then
		-- Only the local presentation waits. Keep at most the latest scan count;
		-- quest tracking and the wire announcement retain their normal timing.
		self.pendingQuestScanAnnouncement = { count = monitoredCount, lifetime = self:GetDeferredWorkStateStore() }
		return
	end
	self.pendingQuestScanAnnouncement = nil
	self:PrintConsoleAnnouncement(self:GetMonitoredQuestCountText(monitoredCount))
end

function QuestTogether:FlushPendingQuestScanAnnouncement()
	local pending = self.pendingQuestScanAnnouncement
	if not pending then return end
	if not self.isEnabled or self.isLoggingOut or pending.lifetime ~= self:GetDeferredWorkStateStore() then
		self.pendingQuestScanAnnouncement = nil
		return
	end
	if self:IsLocalVIPVerificationPending() then return end
	self.pendingQuestScanAnnouncement = nil
	self:PrintConsoleAnnouncement(self:GetMonitoredQuestCountText(pending.count))
end

function QuestTogether:ScanQuestLog(shouldAnnounceTaskAreas)
	if not self.db or not self.db.global then
		return
	end

	if self.IsWorkBlocked and self:IsWorkBlocked("quest_log_drain") then
		self:ScheduleDeferredWork("quest_log_drain", "full_scan", function()
			self:ScanQuestLog(shouldAnnounceTaskAreas)
		end)
		return
	end
	local snapshot
	if self.RebuildQuestSnapshotStore then
		snapshot = self:RebuildQuestSnapshotStore()
		if snapshot and snapshot.lastUnreadableRow then
			-- Keep one retry intent for the next real log update. A successful
			-- snapshot refresh alone does not initialize objective tracking.
			self:SetRuntimeFlag("pendingQuestLogScan", true)
			return
		end
	end
	self:SetRuntimeFlag("pendingQuestLogScan", false)

	local tracker = self:GetPlayerTracker()
	local pendingAcceptances = self.pendingQuestAcceptances or {}
	local seenQuestIDs = {}

	local snapshotByQuestID = self.GetQuestSnapshotByQuestID and self:GetQuestSnapshotByQuestID() or nil
	local snapshotOrder = self.GetQuestSnapshotOrder and self:GetQuestSnapshotOrder() or {}
	for index = 1, #snapshotOrder do
		local questID = snapshotOrder[index]
		local questInfo = snapshotByQuestID and snapshotByQuestID[questID] or nil
		if
			questInfo
			and questInfo.isHidden ~= true
			and not (self.retiredQuestIds and self.retiredQuestIds[questID])
		then
			seenQuestIDs[questID] = true
			-- Acceptance owns its readiness checks and announcement. A readable
			-- snapshot ID alone must not consume its still-unreadable title/type.
			if not pendingAcceptances[questID] then
				self:WatchQuest(questID, questInfo)
			end
		end
	end

	if self.RefreshTaskAreaStates then
		self:RefreshTaskAreaStates(shouldAnnounceTaskAreas == true, snapshot)
	end

	-- Area task quests can exist outside normal quest-log rows.
	-- Add them explicitly so progress announcements can still operate on them.
	if self.GetActiveWorldQuestAreaSnapshot then
		for questId, questTitle in pairs(self:GetActiveWorldQuestAreaSnapshot()) do
			seenQuestIDs[questId] = true
			if not tracker[questId] and not pendingAcceptances[questId] then
				self:WatchQuest(questId, { title = questTitle })
			end
		end
	end
	if self.GetActiveBonusObjectiveAreaSnapshot then
		for questId, questTitle in pairs(self:GetActiveBonusObjectiveAreaSnapshot()) do
			seenQuestIDs[questId] = true
			if not tracker[questId] and not pendingAcceptances[questId] then
				self:WatchQuest(questId, { title = questTitle })
			end
		end
	end

	for questID in pairs(tracker) do
		if not seenQuestIDs[questID] then
			tracker[questID] = nil
		end
	end
	self:SetRuntimeFlag("questTrackerReady", true)
	local monitoredCount = self:GetMonitoredQuestCount()
	local scanMessage = self:GetMonitoredQuestCountText(monitoredCount)
	self:PrintQuestScanAnnouncement(monitoredCount)
	if self.BuildLocalAnnouncementEvent and self.SendAnnouncementWireEvent then
		local eventData = self:BuildLocalAnnouncementEvent("SCAN_STATUS", scanMessage, nil, {
			eventFacts = self:BuildAnnouncementFacts("SCAN_STATUS", nil, nil, nil, monitoredCount),
		})
		if eventData then
			self:SendAnnouncementWireEvent(eventData)
		end
	end
end

-- Store the current objective text state for one quest.
function QuestTogether:WatchQuest(questId, questInfo)
	local numericQuestId = self:NormalizeQuestID(questId)

	if not numericQuestId or (self.retiredQuestIds and self.retiredQuestIds[numericQuestId]) then
		return
	end

	if not questInfo and self.GetQuestSnapshot then
		questInfo = self:GetQuestSnapshot(numericQuestId)
	end
	if not questInfo then
		return
	end

	local tracker = self:GetPlayerTracker()
	local questLogIndex = self.GetQuestLogIndexForQuest and self:GetQuestLogIndexForQuest(numericQuestId, questInfo)
		or nil
	local questTitle = self:GetQuestTitle(numericQuestId, questInfo)
	local existingTrackedQuest = tracker[numericQuestId]
	if self:IsPlaceholderQuestTitle(numericQuestId, questTitle) then
		local existingTitle = existingTrackedQuest and existingTrackedQuest.title or nil
		if
			type(existingTitle) == "string"
			and existingTitle ~= ""
			and not self:IsPlaceholderQuestTitle(numericQuestId, existingTitle)
		then
			if existingTrackedQuest.titleLocale == self:GetEventLocale() then
				questTitle = existingTitle
			end
		end
	end
	local initialStatusState = self.GetTrackedQuestStatusState and self:GetTrackedQuestStatusState(numericQuestId, true)
		or nil

	tracker[numericQuestId] = {
		title = questTitle,
		titleLocale = self:GetEventLocale(),
		taskAnnouncementType = self:GetTaskAnnouncementType(numericQuestId),
		objectives = {},
		-- Cached numeric objective values used to gate progress announcements.
		-- This avoids noisy chat lines caused by text-only objective rewrites.
		objectiveValues = {},
		objectiveProgressHighWater = existingTrackedQuest and existingTrackedQuest.objectiveProgressHighWater or {},
		objectiveProgressObservations = existingTrackedQuest and existingTrackedQuest.objectiveProgressObservations
			or {},
		isComplete = initialStatusState and initialStatusState.isComplete == true or false,
		isReadyForTurnIn = initialStatusState and initialStatusState.isReadyForTurnIn,
		-- Scans establish a silent baseline, including quests whose objectives
		-- are already complete before ReadyForTurnIn has caught up. Preserve
		-- the milestone across rescans and transient false live reads. A new
		-- acceptance or enable lifetime starts with a fresh tracker instead.
		readyForTurnInObserved = (
			existingTrackedQuest
			and (existingTrackedQuest.readyForTurnInObserved == true or existingTrackedQuest.isReadyForTurnIn == true)
		)
			or (initialStatusState and initialStatusState.isReadyForTurnIn == true)
			or (not existingTrackedQuest and ((initialStatusState and initialStatusState.isComplete == true) or questInfo.isComplete == true))
			or false,
	}

	if not questLogIndex then
		return
	end

	local numObjectives = self.API
			and self.API.GetNumQuestLeaderBoards
			and self.API.GetNumQuestLeaderBoards(questLogIndex)
		or 0
	for objectiveIndex = 1, numObjectives do
		local objectiveText, _, _, currentValue =
			self:GetNormalizedQuestObjectiveInfo(numericQuestId, objectiveIndex, false)
		if self.UpdateTrackedObjectiveProgress then
			self:UpdateTrackedObjectiveProgress(tracker[numericQuestId], objectiveIndex, objectiveText, currentValue)
		else
			tracker[numericQuestId].objectives[objectiveIndex] = objectiveText
			tracker[numericQuestId].objectiveValues[objectiveIndex] = self:SafeToNumber(currentValue)
		end
	end
end

function QuestTogether:OnInitialize()
	self:InitializeDatabase()
	if self.EnsureRuntimeStateStore then
		self:EnsureRuntimeStateStore()
	end
	if self.InitializePartyState then
		self:InitializePartyState()
	end
	if self.TryInstallNameplateHooks then
		self:TryInstallNameplateHooks()
	end
	if self.TryInstallPersonalBubbleEditModeHooks then
		self:TryInstallPersonalBubbleEditModeHooks()
	end
	self:TryInstallChatLogLinkHandler()
	self:TryInstallChatWindowHooks()
	self:InitializeSlashCommands()
	if self.InitializeOptionsWindow then
		self:InitializeOptionsWindow()
	end
	self.isInitialized = true
end

function QuestTogether:OnLogin()
	self.hasLoggedIn = true
	self.isLoggingOut = false
	self:ReconcileQuestLogChatDestination()
	if self.db.profile.enabled then
		self:Enable()
	end
	if self.InitializeMinimapLauncher then
		self:InitializeMinimapLauncher()
	end
	self:NotifyAddonUpdate()
	self:InitializeReleaseNotes()
	self:ScheduleStartupHint()
end

-- Bootstrap event handlers always registered.
function QuestTogether:ADDON_LOADED(_, loadedAddonName)
	if self.TryInstallNameplateHooks and self.isInitialized then
		self:TryInstallNameplateHooks()
	end
	if loadedAddonName == "Blizzard_EditMode" and self.TryInstallPersonalBubbleEditModeHooks then
		self:TryInstallPersonalBubbleEditModeHooks()
	end

	if loadedAddonName ~= self.addonName then
		return
	end
	if not self.isInitialized then
		self:OnInitialize()
	end
end

function QuestTogether:PLAYER_LOGIN()
	if not self.isInitialized then
		self:OnInitialize()
	end
	self:OnLogin()
end

function QuestTogether:PLAYER_ENTERING_WORLD()
	self:ResetPlayerPhases()
	self.isLoggingOut = false
	if not self.isEnabled then
		return
	end
	self:RefreshPartyRoster()
	if self.ResumeCommsWorldSession then
		self:ResumeCommsWorldSession()
	end
	-- Refresh after loading screens without synthetic enter/leave announcements.
	self:SetRuntimeFlag("pendingScheduledTaskAreaRefreshShouldAnnounce", false)
	self:RefreshTaskAreaStates(false)
	if self.EnsureAnnouncementChannelJoined and self.isEnabled then
		self:EnsureAnnouncementChannelJoined()
		self:ScheduleAnnouncementChannelOrder()
	end
end

function QuestTogether:PLAYER_LEAVING_WORLD()
	self:ResetPlayerPhases()
	self:ResetObjectiveAnnouncements()
	self:RecordRecentCompanions(true)
	self:ResetRecentCompanionObservation()
	if self.isEnabled then
		if self.EndCommsWorldSession then
			self:EndCommsWorldSession(true)
		end
		if self.BroadcastQTPlayerPresence then
			self:BroadcastQTPlayerPresence(true)
		end
		if self.BroadcastPlayerLocation then
			self:BroadcastPlayerLocation(true, true)
		end
		if self.FlushGeographicDeparture then
			self:FlushGeographicDeparture()
		end
	end
	self.isLoggingOut = true
end

function QuestTogether:PLAYER_LOGOUT()
	self:RecordRecentCompanions(true)
	self:ResetRecentCompanionObservation()
	if self.SavePlayerLocationCache then
		self:SavePlayerLocationCache()
	end
	self.isLoggingOut = true
end

-- Shared event dispatcher for all WoW events this addon listens for.
local function DispatchEvent(addon, eventName, ...)
	local handler = addon[eventName]
	if type(handler) ~= "function" then
		return
	end

	local ok, err
	if addon.RunGuardedCallback then
		ok, err = addon:RunGuardedCallback(eventName, handler, addon, eventName, ...)
	else
		ok, err = pcall(handler, addon, eventName, ...)
	end
	if not ok then
		if type(geterrorhandler) == "function" then
			geterrorhandler()(err)
		end
	end
end

-- Bootstrap lifecycle and diagnostic events outlive the enabled runtime. Keep
-- registration on the addon-owned frame so private tests use this exact path.
function QuestTogether:RegisterBootstrapEvents()
	self.eventFrame:SetScript("OnEvent", function(_, eventName, ...)
		DispatchEvent(self, eventName, ...)
	end)
	for _, eventName in ipairs({
		"ADDON_LOADED",
		"PLAYER_ENTERING_WORLD",
		"PLAYER_LEAVING_WORLD",
		"PLAYER_LOGIN",
		"PLAYER_LOGOUT",
		"ADDON_ACTION_BLOCKED",
		"ADDON_ACTION_FORBIDDEN",
	}) do
		self.eventFrame:RegisterEvent(eventName)
	end
	for _, eventName in ipairs({ "DISPLAY_SIZE_CHANGED", "UI_SCALE_CHANGED" }) do
		pcall(self.eventFrame.RegisterEvent, self.eventFrame, eventName)
	end
end

QuestTogether.eventFrame = QuestTogether.eventFrame or CreateFrame("Frame")
QuestTogether:RegisterBootstrapEvents()