aura: cache fallback for out-of-range group auras (server delta gap)

The server resends out-of-range party/raid stats as deltas only, so a
member seen in range and then moved away again leaves an empty party-
stats aura array (it's cleared when they become visible and never re-
sent), and C_UnitAuras showed nothing until a full roster resync (relog).
Their auras still sit in the Aura::Source cache from when we observed them
in range, so the four group enumerate paths now fall back to the cache
when the group array is empty -- gated by GroupArrayHasVisibleAura, the
same "container non-empty => authoritative" rule the descriptor path uses
(DescriptorHasVisibleAura). A populated array is trusted as-is (no
phantoms); only the empty-array gap consults the cache, deduped and
visibility/playerOnly-filtered.

AddOns/!!!ClassicAPI/!!!ClassicAPI.toc

@@ -12,7 +12,6 @@ Util\Print.lua
 Util\Mixin.lua
 Util\Color.lua
 Util\Constants.lua
-Util\String.lua
 Util\TableUtil.lua
 Util\MathUtil.lua
 Util\PixelUtil.lua
@@ -39,3 +38,7 @@ Util\LinkUtil.lua
 Util\TradeSkillLink.lua
 Util\IconDataProvider.lua
 Util\GameTooltip.lua
+Util\Rectangle.lua
+Util\Vector2D.lua
+Util\Vector3D.lua
+Util\Vector4D.lua

AddOns/!!!ClassicAPI/Util/AddOnCompat.lua

@@ -38,4 +38,8 @@ if C_AddOns.DoesAddOnExist('pfUI') then
             end)
         end
     end)
-end
+end
+
+if C_AddOns.DoesAddOnExist("SpecialTalentUI") then
+    EventUtil.ContinueOnAddOnLoaded("SpecialTalentUI", CAPI_ApplyStandardColorGlobals)
+end

AddOns/!!!ClassicAPI/Util/Color.lua

@@ -24,8 +24,14 @@ function ColorMixin:GetRGB()
     return self.r, self.g, self.b
 end
 
+function ColorMixin:GetHSL()
+    local r, g, b, a = self.r, self.g, self.b, self.a
+    local h, s, l = C_ColorUtil.ConvertHSVToHSL(C_ColorUtil.ConvertRGBToHSV(r, g, b))
+    return h, s, l, a or 1
+end
+
 function ColorMixin:GetRGBAsBytes()
-    return self.r * 255, self.g * 255, self.b * 255
+    return Round(self.r * 255), Round(self.g * 255), Round(self.b * 255)
 end
 
 function ColorMixin:GetRGBA()
@@ -33,14 +39,14 @@ function ColorMixin:GetRGBA()
 end
 
 function ColorMixin:GetRGBAAsBytes()
-    return self.r * 255, self.g * 255, self.b * 255, (self.a or 1) * 255
+    return Round(self.r * 255), Round(self.g * 255), Round(self.b * 255), Round((self.a or 1) * 255)
 end
 
 function ColorMixin:SetRGBA(r, g, b, a)
     self.r = r
     self.g = g
     self.b = b
-    self.a = a
+    self.a = a or 1
 end
 
 function ColorMixin:SetRGB(r, g, b)
@@ -48,56 +54,27 @@ function ColorMixin:SetRGB(r, g, b)
 end
 
 function ColorMixin:GenerateHexColor()
-    return string.format("ff%.2x%.2x%.2x", self:GetRGBAsBytes())
+    return C_ColorUtil.GenerateTextColorCode(self)
+end
+
+function ColorMixin:GenerateHexColorNoAlpha()
+    return string.format("%.2X%.2X%.2X", self:GetRGBAsBytes())
 end
 
 function ColorMixin:GenerateHexColorMarkup()
     return "|c"..self:GenerateHexColor()
 end
 
-function ColorMixin:GenerateHexColorNoAlpha()
-    return string.format("%.2x%.2x%.2x", self:GetRGBAsBytes())
-end
-
-function ColorMixin:GetHSL()
-    local r, g, b, a = self.r, self.g, self.b, self.a
-    local max, min = math.max(r, g, b), math.min(r, g, b)
-    local h, s, l
-    l = (max + min) / 2
-    if max == min then
-        h, s = 0, 0 -- achromatic
-    else
-        local d = max - min
-        if l > 0.5 then
-            s = d / (2 - max - min)
-        else
-            s = d / (max + min)
-        end
-        if max == r then
-            h = (g - b) / d
-            if g < b then
-                h = h + 6
-            end
-        elseif max == g then
-            h = (b - r) / d + 2
-        elseif max == b then
-            h = (r - g) / d + 4
-        end
-        h = h / 6
-    end
-    return h, s, l, a or 1
-end
-
 function ColorMixin:WrapTextInColorCode(text)
-    return WrapTextInColorCode(text, self:GenerateHexColor())
+    return C_ColorUtil.WrapTextInColor(text, self)
 end
 
 function WrapTextInColorCode(text, colorHexString)
-    return string.format("|c%s%s|r", colorHexString, text)
+    return C_ColorUtil.WrapTextInColorCode(text, colorHexString)
 end
 
 function WrapTextInColor(text, color)
-    return WrapTextInColorCode(text, color:GenerateHexColor())
+    return C_ColorUtil.WrapTextInColor(text, color)
 end
 
 function ColorMixin:WrapTextInColorTableCode(text)
@@ -108,11 +85,14 @@ for _, v in pairs(ITEM_QUALITY_COLORS) do
     v.color = CreateColor(v.r, v.g, v.b, 1)
 end
 
-do
+function CAPI_ApplyStandardColorGlobals()
     local envTbl = _G
     for _, dbColor in ipairs(C_UIColor.GetColors()) do
-        local color = CreateColor(dbColor.color.r, dbColor.color.g, dbColor.color.b, dbColor.color.a)
-        envTbl[dbColor.baseTag] = color
-        envTbl[dbColor.baseTag.."_CODE"] = color:GenerateHexColorMarkup()
+        if not envTbl[dbColor.baseTag] or not envTbl[dbColor.baseTag].GetRGB then
+            local color = CreateColor(dbColor.color.r, dbColor.color.g, dbColor.color.b, dbColor.color.a)
+            envTbl[dbColor.baseTag] = color
+            envTbl[dbColor.baseTag.."_CODE"] = color:GenerateHexColorMarkup()
+        end
     end
 end
+CAPI_ApplyStandardColorGlobals()

AddOns/!!!ClassicAPI/Util/ColorUtil.lua

@@ -1,3 +1,8 @@
+COLOR_FORMAT_RGBA = "RRGGBBAA"
+COLOR_FORMAT_RGB = "RRGGBB"
+COLOR_FORMAT_ARGB = "AARRGGBB"
+FONT_COLOR_CODE_CLOSE = "|r"
+
 do
 	local ColorMixin = ColorMixin
 	for _, classColor in pairs(RAID_CLASS_COLORS) do
@@ -12,30 +17,40 @@ function ExtractColorValueFromHex(str, index)
 end
 
 function CreateColorFromHexString(hexColor)
-	if string.len(hexColor) == 8 then
+	if string.len(hexColor) == string.len(COLOR_FORMAT_ARGB) then
 		local a, r, g, b = ExtractColorValueFromHex(hexColor, 1), ExtractColorValueFromHex(hexColor, 3), ExtractColorValueFromHex(hexColor, 5), ExtractColorValueFromHex(hexColor, 7);
 		return CreateColor(r, g, b, a);
-	else
-		error("CreateColorFromHexString input must be hexadecimal digits in this format: AARRGGBB.", 2);
 	end
+	error("CreateColorFromHexString input must be hexadecimal digits in this format: "..COLOR_FORMAT_ARGB..".", 2);
+	return nil;
 end
 
 function CreateColorFromRGBAHexString(hexColor)
-	if string.len(hexColor) == 8 then
+	if string.len(hexColor) == string.len(COLOR_FORMAT_RGBA) then
 		local r, g, b, a = ExtractColorValueFromHex(hexColor, 1), ExtractColorValueFromHex(hexColor, 3), ExtractColorValueFromHex(hexColor, 5), ExtractColorValueFromHex(hexColor, 7);
 		return CreateColor(r, g, b, a);
-	else
-		error("CreateColorFromRGBAHexString input must be hexadecimal digits in this format: RRGGBBAA.", 2);
 	end
+	error("CreateColorFromRGBAHexString input must be hexadecimal digits in this format: "..COLOR_FORMAT_RGBA..".", 2);
+	return nil;
 end
 
 function CreateColorFromRGBHexString(hexColor)
-	if string.len(hexColor) == 6 then
+	if string.len(hexColor) == string.len(COLOR_FORMAT_RGB) then
 		local r, g, b = ExtractColorValueFromHex(hexColor, 1), ExtractColorValueFromHex(hexColor, 3), ExtractColorValueFromHex(hexColor, 5);
 		return CreateColor(r, g, b, 1);
-	else
-		error("CreateColorFromRGBHexString input must be hexadecimal digits in this format: RRGGBB.", 2);
 	end
+	error("CreateColorFromRGBHexString input must be hexadecimal digits in this format: "..COLOR_FORMAT_RGB..".", 2);
+	return nil;
+end
+
+function CreateColorFromBestRGBHexString(hexColor)
+	if string.len(hexColor) == string.len(COLOR_FORMAT_RGBA) then
+		return CreateColorFromRGBAHexString(hexColor);
+	elseif string.len(hexColor) == string.len(COLOR_FORMAT_RGB) then
+		return CreateColorFromRGBHexString(hexColor);
+	end
+	error("CreateColorFromBestRGBHexString input must be hexadecimal digits in either of these formats: "..COLOR_FORMAT_RGBA.." / "..COLOR_FORMAT_RGB..".", 2);
+	return nil;
 end
 
 function CreateColorFromBytes(r, g, b, a)
@@ -68,9 +83,7 @@ end
 function GetClassColoredTextForUnit(unit, text)
 	local _, classFilename = UnitClass(unit);
 	local color = GetClassColorObj(classFilename);
-	if (color) then
-		return color:WrapTextInColorCode(text);
-	end
+	return color and color:WrapTextInColorCode(text) or text;
 end
 
 function GetFactionColor(factionGroupTag)
@@ -82,7 +95,7 @@ function GetFactionColor(factionGroupTag)
 end
 
 function RGBToColorCode(r, g, b)
-	return string.format("|cff%.2x%.2x%.2x", r * 255, g * 255, b * 255);
+	return string.format("|cff%02x%02x%02x", r * 255, g * 255, b * 255);
 end
 
 function RGBTableToColorCode(rgbTable)

AddOns/!!!ClassicAPI/Util/ItemUtil.lua

@@ -15,8 +15,6 @@
 --   - 1.12 has no concept of an item GUID and no public item-lock API,
 --     so those return nil / no-op.
 
-C_Item.GetItemInfo = GetItemInfo
-
 ----------------------------------------------------------------------
 
 Item = {}

AddOns/!!!ClassicAPI/Util/MathUtil.lua

@@ -11,12 +11,19 @@ local random = math.random
 local atan2 = math.atan2
 local sqrt = math.sqrt
 
-math.huge = 1 / 0
+MathUtil =
+{
+	Epsilon = .000001,
+};
 
-function CreateCounter(initialCount)
+MathUtil.ApproxZero = MathUtil.Epsilon;
+MathUtil.ApproxOne = 1.0 - MathUtil.Epsilon;
+
+function CreateCounter(initialCount, step)
     local count = initialCount or 0
+    step = step or 1
     return function()
-        count = count + 1
+        count = count + step
         return count
     end
 end
@@ -130,3 +137,31 @@ end
 function CalculateAngleBetween(x1, y1, x2, y2)
     return atan2(y2 - y1, x2 - x1)
 end
+
+AccumulatorMixin = {};
+
+function AccumulatorMixin:Init(initialCount)
+	self.count = initialCount or 0;
+end
+
+function AccumulatorMixin:Add(count)
+	self.count = self.count + count;
+	return self.count;
+end
+
+function AccumulatorMixin:Subtract(count)
+	self.count = self.count - count;
+	return self.count;
+end
+
+function AccumulatorMixin:Count()
+	return self.count;
+end
+
+function AccumulatorMixin:Reset(resetCount)
+	self.count = resetCount or 0;
+end
+
+function CreateAccumulator(initialCount)
+	return CreateAndInitFromMixin(AccumulatorMixin, initialCount);
+end

AddOns/!!!ClassicAPI/Util/Mixin.lua

@@ -1,24 +1,11 @@
--- Backport of 3.3.5 FrameXML/Mixin.lua to vanilla 1.12 / Lua 5.0.
+-- `Mixin` and `CreateFromMixins` are engine (DLL) natives — see
+-- src/baselib/Mixin.cpp — so they exist whenever ClassicAPI is injected,
+-- even with this addon disabled, mirroring retail where they live in
+-- TableUtil as C functions. Only the composite helper (which calls a Lua
+-- `:Init` method) stays here, like retail's Mixin.lua.
 --
--- Implementation differences from the 3.3.5 source:
---   - Lua 5.0 has no select(); inside a vararg function the args are
---     gathered into an implicit `arg` table (`arg.n` for the count).
-
-function Mixin(object, ...)
-    for i = 1, arg.n do
-        local mixin = arg[i]
-        if mixin then
-            for k, v in pairs(mixin) do
-                object[k] = v
-            end
-        end
-    end
-    return object
-end
-
-function CreateFromMixins(...)
-    return Mixin({}, unpack(arg))
-end
+-- Lua 5.0 note: varargs arrive in the implicit `arg` table (`arg.n` count),
+-- so we forward them with unpack(arg) rather than 5.1's `...`.
 
 function CreateAndInitFromMixin(mixin, ...)
     local object = CreateFromMixins(mixin)

AddOns/!!!ClassicAPI/Util/PlayerUtil.lua

@@ -28,7 +28,7 @@ function PlayerUtil.GetClassColor()
 end
 
 function PlayerUtil.GetCurrentSpeed()
-    return GetUnitSpeed("player") / 7 * 100
+    return GetUnitSpeed("player") / BASE_MOVEMENT_SPEED * 100
 end
 
 function GetPlayerGuid()

AddOns/!!!ClassicAPI/Util/Rectangle.lua

@@ -0,0 +1,141 @@
+RectangleMixin = {};
+
+function CreateRectangle(left, right, top, bottom)
+	local rectangle = CreateFromMixins(RectangleMixin);
+	rectangle:OnLoad(left, right, top,  bottom);
+	return rectangle;
+end
+
+function RectangleMixin:OnLoad(left, right, top, bottom)
+	self:SetSides(left or 0.0, right or 0.0, top or 0.0, bottom or 0.0);
+end
+
+function RectangleMixin:SetSides(left, right, top, bottom)
+	self.left = left;
+	self.right = right;
+	self.top = top;
+	self.bottom = bottom;
+end
+
+function RectangleMixin:Reset()
+	self.left = 0.0;
+	self.right = 0.0;
+	self.top = 0.0;
+	self.bottom = 0.0;
+end
+
+function RectangleMixin:Stretch(x, y)
+	self:Adjust(-x, x, -y, y);
+end
+
+function RectangleMixin:Move(x, y)
+	self:Adjust(x, x, y, y);
+end
+
+function RectangleMixin:Adjust(left, right, top, bottom)
+	self.left = self.left + left;
+	self.right = self.right + right;
+	self.top = self.top + top;
+	self.bottom = self.bottom + bottom;
+end
+
+function RectangleMixin:IsEmpty()
+	return self.left == self.right or self.top == self.bottom;
+end
+
+function RectangleMixin:IsInsideOut()
+	return self.left > self.right or self.top > self.bottom;
+end
+
+function RectangleMixin:EnclosesPoint(x, y)
+	return x >= self.left and x <= self.right and y >= self.top and y <= self.bottom;
+end
+
+function RectangleMixin:EnclosesRect(otherRect)
+	return self:EnclosesPoint(otherRect:GetLeft(), otherRect:GetTop()) and self:EnclosesPoint(otherRect:GetRight(), otherRect:GetBottom());
+end
+
+function RectangleMixin:IntersectsRect(otherRect)
+	return not (
+		self.left > otherRect.right or
+		self.right < otherRect.left or
+		self.top > otherRect.bottom or
+		self.bottom < otherRect.top
+	);
+end
+
+function RectangleMixin:GetTop()
+	return self.top;
+end
+
+function RectangleMixin:GetBottom()
+	return self.bottom;
+end
+
+function RectangleMixin:GetLeft()
+	return self.left;
+end
+
+function RectangleMixin:GetRight()
+	return self.right;
+end
+
+function RectangleMixin:GetWidth()
+	return self.right - self.left;
+end
+
+function RectangleMixin:GetHeight()
+	return self.bottom - self.top;
+end
+
+function RectangleMixin:GetCenter()
+	return Lerp(self.left, self.right, .5), Lerp(self.top, self.bottom, .5);
+end
+
+function RectangleMixin:GetCenterH()
+	return Lerp(self.left, self.right, .5);
+end
+
+function RectangleMixin:GetCenterV()
+	return Lerp(self.top, self.bottom, .5);
+end
+
+function RectangleMixin:SetTop(top)
+	self.top = top;
+end
+
+function RectangleMixin:SetBottom(bottom)
+	self.bottom = bottom;
+end
+
+function RectangleMixin:SetLeft(left)
+	self.left = left;
+end
+
+function RectangleMixin:SetRight(right)
+	self.right = right;
+end
+
+function RectangleMixin:SetWidth(width)
+	self.right = self.left + width;
+end
+
+function RectangleMixin:SetHeight(height)
+	self.bottom = self.top + height;
+end
+
+function RectangleMixin:SetSize(width, height)
+	self:SetWidth(width);
+	self:SetHeight(height);
+end
+
+function RectangleMixin:SetCenter(x, y)
+	local width = self:GetWidth();
+	local height = self:GetHeight();
+
+	self.left = x - width * .5;
+	self.right = x + width * .5;
+
+	self.top = y - height * .5;
+	self.bottom = y + height * .5;
+end

AddOns/!!!ClassicAPI/Util/String.lua

@@ -1,13 +0,0 @@
-
-function string.match(s, pattern, init)
-    if s == nil then return nil end
-    local r1, r2, c1, c2, c3, c4, c5, c6, c7, c8, c9 =
-        string.find(s, pattern, init)
-    if r1 == nil then return nil end
-    if c1 ~= nil then
-        return c1, c2, c3, c4, c5, c6, c7, c8, c9
-    end
-    return string.sub(s, r1, r2)
-end
-
-string.gmatch = string.gfind

AddOns/!!!ClassicAPI/Util/TradeSkillLink.lua

@@ -248,7 +248,7 @@ end
 local function CreateFrame_TradeSkillLink()
 	local f = CreateFrame("Frame", "ClassicAPITradeSkillLinkFrame", UIParent);
 	f:SetSize(FRAME_W, FRAME_H);
-	f:SetPoint("CENTER", 0, 0);
+	f:SetPoint("CENTER");
 	f:SetMovable(true);
 	f:EnableMouse(true);
 	f:SetHitRectInsets(LO.hit[1], LO.hit[2], LO.hit[3], LO.hit[4]);
@@ -259,6 +259,9 @@ local function CreateFrame_TradeSkillLink()
 	f:Hide();
 	tinsert(UISpecialFrames, f:GetName())
 
+	f:SetScript("OnShow", function() PlaySound("igCharacterInfoOpen"); end);
+	f:SetScript("OnHide", function() PlaySound("igCharacterInfoClose"); end);
+
 	local portrait = f:CreateTexture(nil, "BACKGROUND");
 	portrait:SetSize(60, 60);
 	portrait:SetPoint("TOPLEFT", 7, -6);
@@ -296,7 +299,7 @@ local function CreateFrame_TradeSkillLink()
 	local exit = CreateFrame("Button", nil, f, "UIPanelButtonTemplate");
 	exit:SetSize(80, 22);
 	exit:SetPoint(LO.exit[1], f, LO.exit[2], LO.exit[3], LO.exit[4]);
-	exit:SetText(EXIT or "Exit");
+	exit:SetText(EXIT);
 	exit:SetScript("OnClick", function() f:Hide(); end);
 
 	local bar = CreateFrame("StatusBar", nil, f);
@@ -393,29 +396,13 @@ local function CreateFrame_TradeSkillLink()
 		"ClassicAPITradeSkillLinkDetailScroll", f, DETAIL_SCROLL_TEMPLATE);
 	detailScroll:SetSize(LO.detail[3], LO.detail[4]);
 	detailScroll:SetPoint("TOPLEFT", LO.detail[1], LO.detail[2]);
-	detailScroll.scrollBarHideable = 1;  -- template sets this too; belt-and-suspenders
-	f.detailScroll = detailScroll;
-	-- Off until a recipe overflows the pane (toggled in RenderDetail).
-	-- The template shows its slider and enables the wheel by default; on
-	-- the roomy Turtle pane that leaves a dead scrollbar that still eats
-	-- wheel events and over-scrolls a hair. Start both disabled.
+	-- Bar visibility + wheel are driven per-render by SetDetailBarShown (from
+	-- the computed overflow). `scrollBarHideable` still lets the template's
+	-- ScrollFrame_OnScrollRangeChanged manage the slider on range changes.
+	-- Start with the wheel off; the first RenderDetail/ClearDetail sets it.
+	detailScroll.scrollBarHideable = 1;
 	detailScroll:EnableMouseWheel(false);
-	local detailSB = getglobal("ClassicAPITradeSkillLinkDetailScrollScrollBar");
-	if detailSB then
-		detailSB:Hide();
-	end
-	-- The template re-shows its slider when the frame transitions to shown
-	-- (on first open, before the auto-selected recipe's RenderDetail runs),
-	-- leaving a dead scrollbar until the first click. Re-assert the hidden
-	-- state on show unless the current recipe genuinely overflows.
-	detailScroll:SetScript("OnShow", function()
-		f:UpdateDetailScrollbar();
-		RunNextFrame(function()
-			if f:IsShown() then
-				f:UpdateDetailScrollbar();
-			end
-		end);
-	end);
+	f.detailScroll = detailScroll;
 
 	local detailChild = CreateFrame("Frame",
 		"ClassicAPITradeSkillLinkDetailChild", detailScroll);
@@ -514,18 +501,20 @@ local function CreateFrame_TradeSkillLink()
 		return btn;
 	end
 
-	-- Show the detail slider + enable the wheel only when the current
-	-- recipe overflows the pane (tracked by `detailNeedScroll`).
-	function f:UpdateDetailScrollbar()
-		local need = self.detailNeedScroll and true or false;
-		self.detailScroll:EnableMouseWheel(need);
+	-- Show the detail bar/borders only when the content overflows the pane.
+	-- Driven by our own computed overflow, NOT the engine: scrollBarHideable's
+	-- auto-hide only fires on a range CHANGE (so content that fits from the
+	-- start never hides), and GetVerticalScrollRange isn't reliably readable
+	-- the same tick as UpdateScrollChildRect.
+	function f:SetDetailBarShown(show)
+		self.detailScroll:EnableMouseWheel(show);
 		local base = "ClassicAPITradeSkillLinkDetailScroll";
 		local sb = getglobal(base .. "ScrollBar");
-		if sb then sb:SetShown(need) end
+		if sb then sb:SetShown(show) end
 		local top = getglobal(base .. "Top");
-		if top then top:SetShown(need) end
+		if top then top:SetShown(show) end
 		local bottom = getglobal(base .. "Bottom");
-		if bottom then bottom:SetShown(need) end
+		if bottom then bottom:SetShown(show) end
 	end
 
 	function f:RenderDetail(entry)
@@ -571,19 +560,21 @@ local function CreateFrame_TradeSkillLink()
 		local total = table.getn(reagents);
 		for i = 1, total do
 			local btn = AcquireReagent(i);
-			local r = reagents[i];
-			local name, tex, link = itemInfo(r.itemID);
+			local reagent = reagents[i];
+			local name, tex, link = itemInfo(reagent.itemID);
 			btn:SetNormalTexture(tex or "Interface\\Icons\\INV_Misc_QuestionMark");
 			btn.itemLink = link;
-			btn.nameText:SetText(name or ("item:" .. r.itemID));
-			local need = r.count or 1;
-			local have = C_Item.GetItemCount(r.itemID) or 0;
+			btn.nameText:SetText(name or ("item:" .. reagent.itemID));
+			local need = reagent.count or 1;
+			local have = C_Item.GetItemCount(reagent.itemID) or 0;
 			if have >= need then
-				btn:GetNormalTexture():SetVertexColor(1, 1, 1);
-				btn.nameText:SetTextColor(HIGHLIGHT_FONT_COLOR:GetRGB());
+				local r, g, b = HIGHLIGHT_FONT_COLOR:GetRGB()
+				btn:GetNormalTexture():SetVertexColor(r, g, b);
+				btn.nameText:SetTextColor(r, g, b);
 			else
-				btn:GetNormalTexture():SetVertexColor(0.5, 0.5, 0.5);
-				btn.nameText:SetTextColor(GRAY_FONT_COLOR:GetRGB());
+				local r, g, b = GRAY_FONT_COLOR:GetRGB()
+				btn:GetNormalTexture():SetVertexColor(r, g, b);
+				btn.nameText:SetTextColor(r, g, b);
 			end
 			local haveText = (have >= 100) and "*" or tostring(have);
 			btn.count:SetText(haveText .. " /" .. need);
@@ -594,29 +585,32 @@ local function CreateFrame_TradeSkillLink()
 			self.reagents[i]:Hide();
 		end
 
-		-- Grow the scroll child to the content height so the pane scrolls
-		-- once the header + reagent rows exceed the visible area. Reagent
-		-- row 0 sits ~67px below the child top (icon + label); add the
-		-- wrapped description height for spell recipes.
-		local descH = (descText ~= "") and self.prodDesc:GetHeight() or 0;
-		local rows = math.ceil(total / 2);
-		local contentH = 67 + descH + rows * REAGENT_ROW_HEIGHT + 8;
-		self.detailChild:SetHeight(math.max(contentH, LO.detail[4]));
-		-- Reset to the top and manage the slider explicitly: a range that
-		-- stays 0 (content fits, e.g. Turtle's roomy pane) never fires the
-		-- range-changed event that `scrollBarHideable` relies on, so the
-		-- slider would otherwise sit visible-but-useless. Show it only when
-		-- the content actually overflows.
-		self.detailNeedScroll = contentH > LO.detail[4];
+		local function applyContentHeight()
+			local contentH = LO.detail[4];
+			if total > 0 then
+				local childTop = self.detailChild:GetTop();
+				local lastBtn = self.reagents[total];
+				local lastBottom = lastBtn and lastBtn:GetBottom();
+				if childTop and lastBottom then
+					-- +22: ~12px name-plate overhang below the icon + ~10px pad.
+					contentH = (childTop - lastBottom) + 22;
+				end
+			end
+			self.detailChild:SetHeight(math.max(contentH, LO.detail[4]));
+			-- Recompute the scroll range from the child's new height, then
+			-- show the bar only if the content actually overflows the pane.
+			self.detailScroll:UpdateScrollChildRect();
+			self:SetDetailBarShown(contentH > LO.detail[4] + 0.5);
+		end
+		applyContentHeight();
 		local sb = getglobal("ClassicAPITradeSkillLinkDetailScrollScrollBar");
 		if sb then
 			sb:SetValue(0);
 		end
 		self.detailScroll:SetVerticalScroll(0);
-		self:UpdateDetailScrollbar();
 		RunNextFrame(function()
-			if self:IsShown() then
-				self:UpdateDetailScrollbar();
+			if self:IsShown() and self.selectedSpellID == entry.spellID then
+				applyContentHeight();
 			end
 		end)
 	end
@@ -639,8 +633,8 @@ local function CreateFrame_TradeSkillLink()
 			self.reagents[i]:Hide();
 		end
 		self.detailChild:SetHeight(LO.detail[4]);
-		self.detailNeedScroll = false;
-		self:UpdateDetailScrollbar();
+		self.detailScroll:UpdateScrollChildRect();
+		self:SetDetailBarShown(false);
 		self.detailScroll:SetVerticalScroll(0);
 	end
 

AddOns/!!!ClassicAPI/Util/Vector2D.lua

@@ -0,0 +1,142 @@
+-- Verbatim backport of retail's Blizzard_SharedXML/Vector2D.lua. Pure vector
+-- math on CreateFromMixins (a ClassicAPI C native) + Lua 5.0 math.*; no 1.12
+-- adaptation needed. (Retail's "used in secure code" note doesn't apply here —
+-- vanilla has no taint system.)
+local cos = math.cos;
+local sin = math.sin;
+local atan2 = math.atan2;
+local sqrt = math.sqrt;
+
+function Vector2D_ScaleBy(scalar, x, y)
+	return x * scalar, y * scalar;
+end
+
+function Vector2D_DivideBy(divisor, x, y)
+	return x / divisor, y / divisor;
+end
+
+function Vector2D_Add(leftX, leftY, rightX, rightY)
+	return leftX + rightX, leftY + rightY;
+end
+
+function Vector2D_Subtract(leftX, leftY, rightX, rightY)
+	return leftX - rightX, leftY - rightY;
+end
+
+function Vector2D_Cross(leftX, leftY, rightX, rightY)
+	return leftX * rightY - leftY * rightX;
+end
+
+function Vector2D_Dot(leftX, leftY, rightX, rightY)
+	return leftX * rightX + leftY * rightY;
+end
+
+function Vector2D_GetLengthSquared(x, y)
+	return Vector2D_Dot(x, y, x, y);
+end
+
+function Vector2D_GetLength(x, y)
+	return sqrt(Vector2D_GetLengthSquared(x, y));
+end
+
+function Vector2D_Normalize(x, y)
+	return Vector2D_DivideBy(Vector2D_GetLength(x, y), x, y);
+end
+
+function Vector2D_CalculateAngleBetween(leftX, leftY, rightX, rightY)
+	return atan2(Vector2D_Cross(leftX, leftY, rightX, rightY), Vector2D_Dot(leftX, leftY, rightX, rightY));
+end
+
+function Vector2D_RotateDirection(rotationRadians, x, y)
+	local cosValue = cos(rotationRadians);
+	local sinValue = sin(rotationRadians);
+	return x * cosValue - y * sinValue, x * sinValue + y * cosValue;
+end
+
+Vector2DMixin = {};
+
+function CreateVector2D(x, y)
+	local vector = CreateFromMixins(Vector2DMixin);
+	vector:OnLoad(x, y);
+	return vector;
+end
+
+function AreVector2DEqual(left, right)
+	if left and right then
+		return left:IsEqualTo(right);
+	end
+	return left == right;
+end
+
+function Vector2DMixin:OnLoad(x, y)
+	self:SetXY(x, y);
+end
+
+function Vector2DMixin:IsEqualTo(otherVector)
+	return self.x == otherVector.x
+	   and self.y == otherVector.y;
+end
+
+function Vector2DMixin:GetXY()
+	return self.x, self.y;
+end
+
+function Vector2DMixin:SetXY(x, y)
+	self.x = x;
+	self.y = y;
+end
+
+function Vector2DMixin:ScaleBy(scalar)
+	self:SetXY(Vector2D_ScaleBy(scalar, self:GetXY()));
+	return self;
+end
+
+function Vector2DMixin:DivideBy(scalar)
+	self:SetXY(Vector2D_DivideBy(scalar, self:GetXY()));
+	return self;
+end
+
+function Vector2DMixin:Add(other)
+	self:SetXY(Vector2D_Add(self.x, self.y, other:GetXY()));
+	return self;
+end
+
+function Vector2DMixin:Subtract(other)
+	self:SetXY(Vector2D_Subtract(self.x, self.y, other:GetXY()));
+	return self;
+end
+
+function Vector2DMixin:Cross(other)
+	self:SetXY(Vector2D_Cross(self.x, self.y, other:GetXY()));
+	return self;
+end
+
+function Vector2DMixin:Dot(other)
+	return Vector2D_Dot(self.x, self.y, other:GetXY());
+end
+
+function Vector2DMixin:IsZero()
+	return self.x == 0 and self.y == 0;
+end
+
+function Vector2DMixin:GetLengthSquared()
+	return Vector2D_GetLengthSquared(self:GetXY());
+end
+
+function Vector2DMixin:GetLength()
+	return Vector2D_GetLength(self:GetXY());
+end
+
+function Vector2DMixin:Normalize()
+	self:SetXY(Vector2D_Normalize(self:GetXY()));
+	return self;
+end
+
+function Vector2DMixin:RotateDirection(rotationRadians)
+	self:SetXY(Vector2D_RotateDirection(rotationRadians, self:GetXY()));
+	return self;
+end
+
+function Vector2DMixin:Clone()
+	return CreateVector2D(self:GetXY());
+end

AddOns/!!!ClassicAPI/Util/Vector3D.lua

@@ -0,0 +1,173 @@
+-- Verbatim backport of retail's Blizzard_SharedXML/Vector3D.lua. Pure vector
+-- math on CreateFromMixins (a ClassicAPI C native) + Lua 5.0 math.*; no 1.12
+-- adaptation needed. (Retail's "used in secure code" note doesn't apply here —
+-- vanilla has no taint system.)
+local cos = math.cos;
+local sin = math.sin;
+local atan2 = math.atan2;
+local asin = math.asin;
+local sqrt = math.sqrt;
+
+function Vector3D_ScaleBy(scalar, x, y, z)
+	return x * scalar, y * scalar, z * scalar;
+end
+
+function Vector3D_DivideBy(divisor, x, y, z)
+	return x / divisor, y / divisor, z / divisor;
+end
+
+function Vector3D_Add(leftX, leftY, leftZ, rightX, rightY, rightZ)
+	return leftX + rightX, leftY + rightY, leftZ + rightZ;
+end
+
+function Vector3D_Subtract(leftX, leftY, leftZ, rightX, rightY, rightZ)
+	return leftX - rightX, leftY - rightY, leftZ - rightZ;
+end
+
+function Vector3D_Cross(leftX, leftY, leftZ, rightX, rightY, rightZ)
+	return leftY * rightZ - leftZ * rightY, leftZ * rightX - leftX * rightZ, leftX * rightY - leftY * rightX;
+end
+
+function Vector3D_Dot(leftX, leftY, leftZ, rightX, rightY, rightZ)
+	return leftX * rightX + leftY * rightY + leftZ * rightZ;
+end
+
+function Vector3D_GetLengthSquared(x, y, z)
+	return Vector3D_Dot(x, y, z, x, y, z);
+end
+
+function Vector3D_GetLength(x, y, z)
+	return sqrt(Vector3D_GetLengthSquared(x, y, z));
+end
+
+function Vector3D_Normalize(x, y, z)
+	return Vector3D_DivideBy(Vector3D_GetLength(x, y, z), x, y, z);
+end
+
+function Vector3D_AddVector(left, right)
+	local clone = left:Clone();
+	clone:Add(right);
+	return clone;
+end
+
+function Vector3D_SubtractVector(left, right)
+	local clone = left:Clone();
+	clone:Subtract(right);
+	return clone;
+end
+
+function Vector3D_NormalizeVector(vector)
+	local clone = vector:Clone();
+	clone:Normalize();
+	return clone;
+end
+
+function Vector3D_ScaleVector(scalar, vector)
+	local clone = vector:Clone();
+	clone:ScaleBy(scalar);
+	return clone;
+end
+
+function Vector3D_CalculateNormalFromYawPitch(yaw, pitch)
+	return	cos(-pitch) * cos(yaw),
+			cos(-pitch) * sin(yaw),
+			sin(-pitch);
+end
+
+function Vector3D_CalculateYawPitchFromNormal(x, y, z)
+	if x ~= 0 or y ~= 0 then
+		return atan2(y, x), asin(-z);
+	end
+
+	return 0, asin(-z);
+end
+
+function Vector3D_CalculateYawPitchFromNormalVector(vector)
+	return Vector3D_CalculateYawPitchFromNormal(vector:GetXYZ());
+end
+
+
+function Vector3D_CreateNormalVectorFromYawPitch(yawRadians, pitchRadians)
+	return CreateVector3D(Vector3D_CalculateNormalFromYawPitch(yawRadians, pitchRadians));
+end
+
+Vector3DMixin = {};
+
+function CreateVector3D(x, y, z)
+	local vector = CreateFromMixins(Vector3DMixin);
+	vector:OnLoad(x, y, z);
+	return vector;
+end
+
+function AreVector3DEqual(left, right)
+	if left and right then
+		return left:IsEqualTo(right);
+	end
+	return left == right;
+end
+
+function Vector3DMixin:OnLoad(x, y, z)
+	self:SetXYZ(x, y, z);
+end
+
+function Vector3DMixin:IsEqualTo(otherVector)
+	return self.x == otherVector.x
+	   and self.y == otherVector.y
+	   and self.z == otherVector.z;
+end
+
+function Vector3DMixin:GetXYZ()
+	return self.x, self.y, self.z;
+end
+
+function Vector3DMixin:SetXYZ(x, y, z)
+	self.x = x;
+	self.y = y;
+	self.z = z;
+end
+
+function Vector3DMixin:ScaleBy(scalar)
+	self:SetXYZ(Vector3D_ScaleBy(scalar, self:GetXYZ()));
+	return self;
+end
+
+function Vector3DMixin:DivideBy(scalar)
+	self:SetXYZ(Vector3D_DivideBy(scalar, self:GetXYZ()));
+	return self;
+end
+
+function Vector3DMixin:Add(other)
+	self:SetXYZ(Vector3D_Add(self.x, self.y, self.z, other:GetXYZ()));
+	return self;
+end
+
+function Vector3DMixin:Subtract(other)
+	self:SetXYZ(Vector3D_Subtract(self.x, self.y, self.z, other:GetXYZ()));
+	return self;
+end
+
+function Vector3DMixin:Cross(other)
+	self:SetXYZ(Vector3D_Cross(self.x, self.y, self.z, other:GetXYZ()));
+	return self;
+end
+
+function Vector3DMixin:Dot(other)
+	return Vector3D_Dot(self.x, self.y, self.z, other:GetXYZ());
+end
+
+function Vector3DMixin:GetLengthSquared()
+	return Vector3D_GetLengthSquared(self:GetXYZ());
+end
+
+function Vector3DMixin:GetLength()
+	return Vector3D_GetLength(self:GetXYZ());
+end
+
+function Vector3DMixin:Normalize()
+	self:SetXYZ(Vector3D_Normalize(self:GetXYZ()));
+	return self;
+end
+
+function Vector3DMixin:Clone()
+	return CreateVector3D(self:GetXYZ());
+end

AddOns/!!!ClassicAPI/Util/Vector4D.lua

@@ -0,0 +1,143 @@
+-- Verbatim backport of retail's Blizzard_SharedXML/Vector4D.lua. Pure vector
+-- math on CreateFromMixins (a ClassicAPI C native) + Lua 5.0 math.*; no 1.12
+-- adaptation needed. (Retail's "used in secure code" note doesn't apply here —
+-- vanilla has no taint system.)
+local cos = math.cos;
+local sin = math.sin;
+local atan2 = math.atan2;
+local asin = math.asin;
+local sqrt = math.sqrt;
+
+function Vector4D_ScaleBy(scalar, x, y, z, w)
+	return x * scalar, y * scalar, z * scalar, w * scalar;
+end
+
+function Vector4D_DivideBy(divisor, x, y, z, w)
+	return x / divisor, y / divisor, z / divisor, w / divisor;
+end
+
+function Vector4D_Add(leftX, leftY, leftZ, leftW, rightX, rightY, rightZ, rightW)
+	return leftX + rightX, leftY + rightY, leftZ + rightZ, leftW + rightW;
+end
+
+function Vector4D_Subtract(leftX, leftY, leftZ, leftW, rightX, rightY, rightZ, rightW)
+	return leftX - rightX, leftY - rightY, leftZ - rightZ, leftW - rightW;
+end
+
+function Vector4D_Dot(leftX, leftY, leftZ, leftW, rightX, rightY, rightZ, rightW)
+	return leftX * rightX + leftY * rightY + leftZ * rightZ + leftW * rightW;
+end
+
+function Vector4D_GetLengthSquared(x, y, z, w)
+	return Vector4D_Dot(x, y, z, w, x, y, z, w);
+end
+
+function Vector4D_GetLength(x, y, z, w)
+	return sqrt(Vector4D_GetLengthSquared(x, y, z, w));
+end
+
+function Vector4D_Normalize(x, y, z, w)
+	return Vector4D_DivideBy(Vector4D_GetLength(x, y, z, w), x, y, z, w);
+end
+
+function Vector4D_AddVector(left, right)
+	local clone = left:Clone();
+	clone:Add(right);
+	return clone;
+end
+
+function Vector4D_SubtractVector(left, right)
+	local clone = left:Clone();
+	clone:Subtract(right);
+	return clone;
+end
+
+function Vector4D_NormalizeVector(vector)
+	local clone = vector:Clone();
+	clone:Normalize();
+	return clone;
+end
+
+function Vector4D_ScaleVector(scalar, vector)
+	local clone = vector:Clone();
+	clone:ScaleBy(scalar);
+	return clone;
+end
+
+Vector4DMixin = {};
+
+function CreateVector4D(x, y, z, w)
+	local vector = CreateFromMixins(Vector4DMixin);
+	vector:OnLoad(x, y, z, w);
+	return vector;
+end
+
+function AreVector4DEqual(left, right)
+	if left and right then
+		return left:IsEqualTo(right);
+	end
+	return left == right;
+end
+
+function Vector4DMixin:OnLoad(x, y, z, w)
+	self:SetXYZW(x, y, z, w);
+end
+
+function Vector4DMixin:IsEqualTo(otherVector)
+	return self.x == otherVector.x
+	   and self.y == otherVector.y
+	   and self.z == otherVector.z
+	   and self.w == otherVector.w;
+end
+
+function Vector4DMixin:GetXYZW()
+	return self.x, self.y, self.z, self.w;
+end
+
+function Vector4DMixin:SetXYZW(x, y, z, w)
+	self.x = x;
+	self.y = y;
+	self.z = z;
+	self.w = w;
+end
+
+function Vector4DMixin:ScaleBy(scalar)
+	self:SetXYZW(Vector4D_ScaleBy(scalar, self:GetXYZW()));
+	return self;
+end
+
+function Vector4DMixin:DivideBy(scalar)
+	self:SetXYZW(Vector4D_DivideBy(scalar, self:GetXYZW()));
+	return self;
+end
+
+function Vector4DMixin:Add(other)
+	self:SetXYZW(Vector4D_Add(self.x, self.y, self.z, self.w, other:GetXYZW()));
+	return self;
+end
+
+function Vector4DMixin:Subtract(other)
+	self:SetXYZW(Vector4D_Subtract(self.x, self.y, self.z, self.w, other:GetXYZW()));
+	return self;
+end
+
+function Vector4DMixin:Dot(other)
+	return Vector4D_Dot(self.x, self.y, self.z, self.w, other:GetXYZW());
+end
+
+function Vector4DMixin:GetLengthSquared()
+	return Vector4D_GetLengthSquared(self:GetXYZW());
+end
+
+function Vector4DMixin:GetLength()
+	return Vector4D_GetLength(self:GetXYZW());
+end
+
+function Vector4DMixin:Normalize()
+	self:SetXYZW(Vector4D_Normalize(self:GetXYZW()));
+	return self;
+end
+
+function Vector4DMixin:Clone()
+	return CreateVector4D(self:GetXYZW());
+end

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.10)
 
-project(ClassicAPI LANGUAGES CXX)
+project(ClassicAPI LANGUAGES CXX RC)
 
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
@@ -77,17 +77,20 @@ add_library(${PROJECT_NAME} SHARED
 # `CLASSIC_API_VERSION >= X` always pass during local development;
 # CI release builds overwrite it via `-DCLASSICAPI_TAG=vX.Y.Z`.
 set(CLASSICAPI_VERSION_VALUE 99999999)
+set(CLASSICAPI_VER_MAJOR 9999)
+set(CLASSICAPI_VER_MINOR 99)
+set(CLASSICAPI_VER_PATCH 99)
 
 set(CLASSICAPI_TAG
     ""
     CACHE STRING "Release tag like v1.2.3")
 
 if(CLASSICAPI_TAG MATCHES "^v([0-9]+)\\.([0-9]+)\\.([0-9]+)$")
-  set(_MAJOR "${CMAKE_MATCH_1}")
-  set(_MINOR "${CMAKE_MATCH_2}")
-  set(_PATCH "${CMAKE_MATCH_3}")
+  set(CLASSICAPI_VER_MAJOR "${CMAKE_MATCH_1}")
+  set(CLASSICAPI_VER_MINOR "${CMAKE_MATCH_2}")
+  set(CLASSICAPI_VER_PATCH "${CMAKE_MATCH_3}")
   math(EXPR CLASSICAPI_VERSION_VALUE
-       "${_MAJOR} * 10000 + ${_MINOR} * 100 + ${_PATCH}")
+       "${CLASSICAPI_VER_MAJOR} * 10000 + ${CLASSICAPI_VER_MINOR} * 100 + ${CLASSICAPI_VER_PATCH}")
 elseif(CLASSICAPI_TAG)
   message(
     FATAL_ERROR
@@ -99,10 +102,25 @@ target_compile_definitions(
   ${PROJECT_NAME}
   PRIVATE CLASSICAPI_VERSION_VALUE=${CLASSICAPI_VERSION_VALUE})
 
+# Stamp the PE VERSIONINFO resource from the same version components, so the
+# DLL's file/product version (Explorer -> Properties -> Details) matches the
+# CLASSIC_API_VERSION Lua global. The .rsrc section the resource lands in is
+# untouched by the .rdata/.pdata section merges below.
+set(CLASSICAPI_VER_STRING
+    "${CLASSICAPI_VER_MAJOR}.${CLASSICAPI_VER_MINOR}.${CLASSICAPI_VER_PATCH}.0")
+set(CLASSICAPI_VERSION_RC "${CMAKE_BINARY_DIR}/generated/version.rc")
+configure_file(
+    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/version.rc.in"
+    "${CLASSICAPI_VERSION_RC}"
+    @ONLY)
+target_sources(${PROJECT_NAME} PRIVATE "${CLASSICAPI_VERSION_RC}")
+
 # ole32: COM (CoInitializeEx / CoCreateInstance / CoTaskMemFree) for the
 # SAPI text-to-speech backend in src/voicechat/Tts.cpp. The SAPI GUIDs are
 # instantiated in that TU via <initguid.h>, so no sapi.lib is needed.
-target_link_libraries(${PROJECT_NAME} PRIVATE minhook advapi32 ole32)
+# user32: Win32 clipboard API (OpenClipboard / SetClipboardData) for
+# CopyToClipboard in src/clipboard/Copy.cpp.
+target_link_libraries(${PROJECT_NAME} PRIVATE minhook advapi32 ole32 user32)
 
 target_include_directories(
   ${PROJECT_NAME} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src

README.md

@@ -19,32 +19,35 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 |-----------|-------|
 | [Action](docs/API.md#action) | `GetActionInfo` |
 | [AddOns](docs/API.md#addons) | `C_AddOns.DoesAddOnExist`, `C_AddOns.GetAddOnName`, `C_AddOns.GetAddOnNotes`, `C_AddOns.GetAddOnOptionalDependencies`, `C_AddOns.GetAddOnSecurity`, `C_AddOns.GetAddOnTitle`, `C_AddOns.IsAddOnLoadable`, `C_AddOns.IsAddOnLoaded` |
+| [AuctionHouse](docs/API.md#auctionhouse) | `C_AuctionHouse.PostItem` |
 | [Chat](docs/API.md#chat) | `GetCurrentChatGUID` |
+| [ChatBubbles](docs/API.md#chatbubbles) | `C_ChatBubbles.GetAllChatBubbles` |
 | [Class](docs/API.md#class) | `FillLocalizedClassList` |
+| [ColorUtil](docs/API.md#colorutil) | `C_ColorUtil.ConvertRGBToHSV`, `C_ColorUtil.ConvertHSVToRGB`, `C_ColorUtil.ConvertHSVToHSL`, `C_ColorUtil.ConvertHSLToHSV`, `C_ColorUtil.ConvertHSLToRGB`, `C_ColorUtil.GenerateTextColorCode`, `C_ColorUtil.WrapTextInColor`, `C_ColorUtil.WrapTextInColorCode` |
 | [Combat](docs/API.md#combat) | `InCombatLockdown` |
 | [CVar](docs/API.md#cvar) | `C_CVar.GetCVarBool` |
 | [Cursor](docs/API.md#cursor) | `GetCursorInfo` |
-| [Container](docs/API.md#container) | `C_Container.CalculateTotalNumberOfFreeBagSlots`, `C_Container.GetContainerItemCharges`, `C_Container.GetContainerItemDurability`, `C_Container.GetContainerItemID`, `C_Container.GetContainerItemRepairCost`, `C_Container.GetContainerNumFreeSlots`, `C_Container.GetItemCooldown`, `C_Container.HasContainerItem`, `C_Container.IsContainerItemOpenable`, `C_Container.MoveItem`, `C_Container.PlayerHasHearthstone`, `C_Container.SwapItems`, `C_Container.UseHearthstone`, `GetItemCooldown` |
-| [Coroutine](docs/API.md#coroutine) | `coroutine.create`, `coroutine.resume`, `coroutine.yield`, `coroutine.status`, `coroutine.wrap` |
+| [Container](docs/API.md#container) | `C_Container.CalculateTotalNumberOfFreeBagSlots`, `C_Container.GetContainerItemCharges`, `C_Container.GetContainerItemDurability`, `C_Container.GetContainerItemID`, `C_Container.GetContainerItemInfo`, `C_Container.GetContainerItemRepairCost`, `C_Container.GetContainerNumFreeSlots`, `C_Container.GetItemCooldown`, `C_Container.HasContainerItem`, `C_Container.IsContainerItemOpenable`, `C_Container.MoveItem`, `C_Container.PlayerHasHearthstone`, `C_Container.SwapItems`, `C_Container.UseHearthstone`, `GetItemCooldown` |
 | [Creature](docs/API.md#creature) | `C_CreatureInfo.GetCreatureID`, `C_CreatureInfo.GetCreatureInfoByID`, `C_CreatureInfo.RequestLoadCreatureByID`, `C_CreatureInfo.GetRaceInfo`, `C_CreatureInfo.GetClassInfo`, `C_CreatureInfo.GetCreatureFamilyInfo`, `C_CreatureInfo.GetCreatureFamilyIDs`, `C_CreatureInfo.GetFactionInfo`, `C_CreatureInfo.GetCreatureTypeInfo`, `C_CreatureInfo.GetCreatureTypeIDs` |
 | EncodingUtil | `C_EncodingUtil.CompressString`, `C_EncodingUtil.DecompressString`, `C_EncodingUtil.EncodeBase64`, `C_EncodingUtil.DecodeBase64`, `C_EncodingUtil.EncodeHex`, `C_EncodingUtil.DecodeHex`, `C_EncodingUtil.SerializeJSON`, `C_EncodingUtil.DeserializeJSON`, `C_EncodingUtil.SerializeCBOR`, `C_EncodingUtil.DeserializeCBOR` |
 | [EquipmentSet](docs/API.md#equipmentset) | `C_EquipmentSet.CanUseEquipmentSets`, `C_EquipmentSet.ClearIgnoredSlotsForSave`, `C_EquipmentSet.CreateEquipmentSet`, `C_EquipmentSet.DeleteEquipmentSet`, `C_EquipmentSet.EquipmentSetContainsLockedItems`, `C_EquipmentSet.GetEquipmentSetID`, `C_EquipmentSet.GetEquipmentSetIDs`, `C_EquipmentSet.GetEquipmentSetInfo`, `C_EquipmentSet.GetIgnoredSlots`, `C_EquipmentSet.GetItemIDs`, `C_EquipmentSet.GetItemLocations`, `C_EquipmentSet.GetNumEquipmentSets`, `C_EquipmentSet.IgnoreSlotForSave`, `C_EquipmentSet.IsSlotIgnoredForSave`, `C_EquipmentSet.ModifyEquipmentSet`, `C_EquipmentSet.SaveEquipmentSet`, `C_EquipmentSet.UnignoreSlotForSave`, `C_EquipmentSet.UseEquipmentSet` |
-| [Events](docs/API.md#events) | `C_EventUtils.IsEventValid` |
+| [Events](docs/API.md#events) | `C_EventUtils.IsEventValid`, `GetFramesRegisteredForEvent` |
 | [Expansion](docs/API.md#expansion) | `ClassicExpansionAtLeast`, `ClassicExpansionAtMost`, `GetClassicExpansionLevel` |
 | [Faction](docs/API.md#faction) | `C_Reputation.GetFactionDataByIndex`, `C_Reputation.GetFactionStandings`, `C_Reputation.GetLastStandingChange`, `C_Reputation.GetWatchedFactionData`, `C_Reputation.SetWatchedFactionByID`, `GetFactionIDByIndex`, `GetFactionInfoByID`, `GetFactionParentID` |
 | [Focus](docs/API.md#focus) | `ClearFocus`, `FocusUnit` |
 | [Frame](docs/API.md#frame) | `region:SetPoint("point")` (one-arg form), `region:SetSize`, `region:GetSize`, `frame:SetShown`, `frame:SetResizeBounds`, `frame:HookScript`, `frame:IsEventRegistered` |
 | [FriendList](docs/API.md#friendlist) | `C_FriendList.IsWhoQueryPending`, `C_FriendList.SendWhoQueryByName` |
-| [GameObject](docs/API.md#gameobject) | `C_GameObjectInfo.GetGameObjectInfoByID`, `C_GameObjectInfo.RequestLoadGameObjectByID` |
+| [GameObject](docs/API.md#gameobject) | `C_GameObjectInfo.GetGameObjectInfoByID`, `C_GameObjectInfo.RequestLoadGameObjectByID`, `ClosestGameObjectPosition` |
 | [Gossip](docs/API.md#gossip) | `C_GossipInfo.CloseGossip`, `C_GossipInfo.GetActiveQuests`, `C_GossipInfo.GetAvailableQuests`, `C_GossipInfo.GetNumActiveQuests`, `C_GossipInfo.GetNumAvailableQuests`, `C_GossipInfo.GetNumOptions`, `C_GossipInfo.GetOptions`, `C_GossipInfo.GetText`, `C_GossipInfo.SelectActiveQuest`, `C_GossipInfo.SelectAvailableQuest`, `C_GossipInfo.SelectOption`, `C_GossipInfo.SelectOptionByIndex` |
-| [GameTooltip](docs/API.md#gametooltip) | `GameTooltip:GetGameObject`, `GameTooltip:GetItem`, `GameTooltip:GetOwner`, `GameTooltip:GetSpell`, `GameTooltip:GetUnitGUID`, `GameTooltip:HasGameObject`, `GameTooltip:HasItem`, `GameTooltip:HasSpell`, `GameTooltip:HasUnit`, `GameTooltip:IsEquippedItem`, `GameTooltip:SetEquipmentSet`, `GameTooltip:SetHyperlinkCompareItem`, `GameTooltip:SetInventoryItemByID`, `GameTooltip:SetItemByGUID`, `GameTooltip:SetItemByID`, `GameTooltip:SetSpellByID`, `GameTooltip:SetTalentByID`, `GameTooltip:SetUnitAura`, `OnTooltipSetItem` (script) |
+| [GameTooltip](docs/API.md#gametooltip) | `GameTooltip:AddSpellByID`, `GameTooltip:GetGameObject`, `GameTooltip:GetItem`, `GameTooltip:GetOwner`, `GameTooltip:GetSpell`, `GameTooltip:GetUnitGUID`, `GameTooltip:HasGameObject`, `GameTooltip:HasItem`, `GameTooltip:HasSpell`, `GameTooltip:HasUnit`, `GameTooltip:IsEquippedItem`, `GameTooltip:SetEquipmentSet`, `GameTooltip:SetHyperlinkCompareItem`, `GameTooltip:SetInventoryItemByID`, `GameTooltip:SetItemByGUID`, `GameTooltip:SetItemByID`, `GameTooltip:SetSpellByID`, `GameTooltip:SetTalentByID`, `GameTooltip:SetTotem`, `GameTooltip:SetUnitAura`, `OnTooltipSetItem`, `OnTooltipSetSpell`, `OnTooltipSetUnit`, `OnTooltipSetGameObject` (scripts) |
 | [Hooks](docs/API.md#hooks) | `hooksecurefunc` |
 | [Input](docs/API.md#input) | `GetMouseButtonClicked`, `IsLeftAltKeyDown`, `IsLeftControlKeyDown`, `IsLeftShiftKeyDown`, `IsModifierKeyDown`, `IsMouseButtonDown`, `IsRightAltKeyDown`, `IsRightControlKeyDown`, `IsRightShiftKeyDown` |
 | [Instance](docs/API.md#instance) | `GetInstanceInfo` |
-| [Item](docs/API.md#item) | `C_Item.DoesItemExist`, `C_Item.DoesItemExistByID`, `C_Item.EquipItemByName`, `C_Item.GetCurrentItemLevel`, `C_Item.GetDetailedItemLevelInfo`, `C_Item.GetEnchantInfo`, `C_Item.GetItemCount`, `C_Item.GetItemFamily`, `C_Item.GetItemGUID`, `C_Item.GetItemIcon`, `C_Item.GetItemIconByID`, `C_Item.GetItemID`, `C_Item.GetItemInfoInstant`, `C_Item.GetItemInventorySlotInfo`, `C_Item.GetItemInventorySlotKey`, `C_Item.GetItemInventoryType`, `C_Item.GetItemInventoryTypeByID`, `C_Item.GetItemLink`, `C_Item.GetItemLocation`, `C_Item.GetItemMaxStackSize`, `C_Item.GetItemMaxStackSizeByID`, `C_Item.GetItemName`, `C_Item.GetItemNameByID`, `C_Item.GetItemQuality`, `C_Item.GetItemQualityByID`, `C_Item.GetItemSellPrice`, `C_Item.GetItemSellPriceByID`, `C_Item.GetItemSetID`, `C_Item.GetItemSetIDByID`, `C_Item.GetItemSetInfo`, `C_Item.GetItemSpell`, `C_Item.GetItemStatDelta`, `C_Item.GetItemStats`, `C_Item.GetItemSubClassInfo`, `C_Item.GetItemUniqueness`, `C_Item.GetItemUniquenessByID`, `C_Item.GetStackCount`, `C_Item.GetWeaponEnchantInfo`, `C_Item.IsBound`, `C_Item.IsConsumableItem`, `C_Item.IsEquippableItem`, `C_Item.IsEquippedItem`, `C_Item.IsItemDataCached`, `C_Item.IsItemDataCachedByID`, `C_Item.IsItemGUIDInInventory`, `C_Item.IsItemInRange`, `C_Item.IsItemOpenable`, `C_Item.IsLocked`, `C_Item.LockItem`, `C_Item.LockItemByGUID`, `C_Item.PickupItem`, `C_Item.UnlockAllItems`, `C_Item.UnlockItem`, `C_Item.RequestLoadItemData`, `C_Item.RequestLoadItemDataByID`, `C_Item.UseAtCursor`, `C_Item.UseAtUnit`, `C_Item.UseItemByName`, `GetAuctionItemID`, `GetAuctionSellItemID`, `GetAverageItemLevel`, `GetCraftReagentItemID`, `GetInboxItemID`, `GetInventoryItemDurability`, `GetInventoryItemID`, `GetInventoryItemsForSlot`, `GetInventoryItemRepairCost`, `GetItemIcon`, `GetLootRollItemID`, `GetLootSlotItemID`, `GetMerchantItemID`, `GetQuestItemID`, `GetQuestLogItemID`, `GetTradePlayerItemID`, `GetTradeSkillItemID`, `GetTradeSkillReagentItemID`, `GetTradeTargetItemID`, `OffhandHasWeapon` |
+| [Item](docs/API.md#item) | `C_Item.DoesItemExist`, `C_Item.DoesItemExistByID`, `C_Item.EquipItemByName`, `C_Item.GetCurrentItemLevel`, `C_Item.GetDetailedItemLevelInfo`, `C_Item.GetEnchantInfo`, `C_Item.GetItemCount`, `C_Item.GetItemFamily`, `C_Item.GetItemGUID`, `C_Item.GetItemIcon`, `C_Item.GetItemIconByID`, `C_Item.GetItemID`, `C_Item.GetItemInfo`, `C_Item.GetItemInfoInstant`, `C_Item.GetItemInventorySlotInfo`, `C_Item.GetItemInventorySlotKey`, `C_Item.GetItemInventoryType`, `C_Item.GetItemInventoryTypeByID`, `C_Item.GetItemLink`, `C_Item.GetItemLocation`, `C_Item.GetItemMaxStackSize`, `C_Item.GetItemMaxStackSizeByID`, `C_Item.GetItemName`, `C_Item.GetItemNameByID`, `C_Item.GetItemQuality`, `C_Item.GetItemQualityByID`, `C_Item.GetItemSellPrice`, `C_Item.GetItemSellPriceByID`, `C_Item.GetItemSetID`, `C_Item.GetItemSetIDByID`, `C_Item.GetItemSetInfo`, `C_Item.GetItemSpell`, `C_Item.GetItemStatDelta`, `C_Item.GetItemStats`, `C_Item.GetItemClassInfo`, `C_Item.GetItemSubClassInfo`, `C_Item.GetItemUniqueness`, `C_Item.GetItemUniquenessByID`, `C_Item.GetStackCount`, `C_Item.GetWeaponEnchantInfo`, `C_Item.IsBound`, `C_Item.IsConsumableItem`, `C_Item.IsEquippableItem`, `C_Item.IsEquippedItem`, `C_Item.IsItemDataCached`, `C_Item.IsItemDataCachedByID`, `C_Item.IsItemGUIDInInventory`, `C_Item.IsItemInRange`, `C_Item.IsItemOpenable`, `C_Item.IsLocked`, `C_Item.LockItem`, `C_Item.LockItemByGUID`, `C_Item.PickupItem`, `C_Item.UnlockAllItems`, `C_Item.UnlockItem`, `C_Item.RequestLoadItemData`, `C_Item.RequestLoadItemDataByID`, `C_Item.UseAtCursor`, `C_Item.UseAtUnit`, `C_Item.UseItemByName`, `GetAuctionItemID`, `GetAuctionSellItemID`, `GetAverageItemLevel`, `GetCraftReagentItemID`, `GetInboxItemID`, `GetInventoryItemDurability`, `GetInventoryItemID`, `GetInventoryItemsForSlot`, `GetInventoryItemRepairCost`, `GetItemClassInfo`, `GetItemIcon`, `GetItemSubClassInfo`, `GetLootRollItemID`, `GetLootSlotItemID`, `GetMerchantItemID`, `GetQuestItemID`, `GetQuestLogItemID`, `GetTradePlayerItemID`, `GetTradeSkillItemID`, `GetTradeSkillReagentItemID`, `GetTradeTargetItemID`, `OffhandHasWeapon` |
 | [Loot](docs/API.md#loot) | `C_Loot.GetNearbyLootableUnits`, `C_Loot.GetLastScanResults`, `C_Loot.IsScanInProgress`, `C_Loot.LootUnit`, `C_Loot.LootUnitItem`, `C_Loot.ScanNearbyLoot` |
 | [LootHistory](docs/API.md#loothistory) | `C_LootHistory.GetNumItems`, `C_LootHistory.GetItem`, `C_LootHistory.GetPlayerInfo`, `C_LootHistory.Clear` |
 | [LossOfControl](docs/API.md#lossofcontrol) | `C_LossOfControl.GetActiveLossOfControlData`, `C_LossOfControl.GetActiveLossOfControlDataCount` |
+| [Lua](docs/API.md#lua) | `coroutine.create`, `coroutine.resume`, `coroutine.status`, `coroutine.wrap`, `coroutine.yield`, `CreateFromMixins`, `math.fmod`, `math.huge`, `math.modf`, `Mixin`, `select`, `string.gmatch`, `string.match`, `string.reverse`, `strjoin`, `strreplace`, `strrev`, `strsplit`, `strtrim`, `table.count`, `table.wipe` |
 | [Macros](docs/API.md#macros) | `GetLooseMacroIcons`, `GetLooseMacroItemIcons`, `GetMacroIcons`, `GetMacroItemIcons`, `GetMacroSpell` |
 | [Mail](docs/API.md#mail) | `GetInboxItemLink`, `GetSendMailItemLink` |
 | [Map](docs/API.md#map) | `C_Map.GetAreaInfo`, `C_Map.GetAreas`, `C_Map.GetAreaTriggerInfo`, `C_Map.GetAreaTriggers`, `C_Map.GetBestMapForUnit`, `C_Map.GetMapAreaIDs`, `C_Map.GetMapOverlays`, `C_Map.GetMapWorldSize` |
@@ -54,18 +57,19 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | [NameCache](docs/API.md#namecache) | `C_PlayerCache.GetPlayerInfoByName`, `C_PlayerCache.IsEnabled`, `C_PlayerCache.IsScanEnabled`, `C_PlayerCache.RememberPlayer`, `C_PlayerCache.SetEnabled`, `C_PlayerCache.SetScanEnabled`, `GetPlayerInfoByGUID`, `UnitNameFromGUID` |
 | [NewItems](docs/API.md#newitems) | `C_NewItems.ClearAll`, `C_NewItems.IsNewItem`, `C_NewItems.RemoveNewItem` |
 | [PlayerInfo](docs/API.md#playerinfo) | `C_PlayerInfo.CanUseItem`, `C_PlayerInfo.GetClass`, `C_PlayerInfo.GetName`, `C_PlayerInfo.GetRace`, `C_PlayerInfo.GetSex`, `C_PlayerInfo.GUIDIsCreature`, `C_PlayerInfo.GUIDIsGameObject`, `C_PlayerInfo.GUIDIsPet`, `C_PlayerInfo.GUIDIsPlayer`, `C_PlayerInfo.IsConnected` |
-| [Quest](docs/API.md#quest) | `C_QuestLog.GetNumQuestObjectives`, `C_QuestLog.GetQuestDetails`, `C_QuestLog.GetQuestIDForLogIndex`, `C_QuestLog.GetTitleForQuestID`, `C_QuestLog.IsOnQuest`, `C_QuestLog.IsQuestDataCachedByID`, `C_QuestLog.IsUnitOnQuest`, `C_QuestLog.RequestLoadQuestByID`, `GetQuestLogLeaderBoardID` |
-| [Screen](docs/API.md#screen) | `GetPhysicalScreenSize` |
-| [Spell](docs/API.md#spell) | `C_Spell.CancelSpellByID`, `C_Spell.CastAtCursor`, `C_Spell.CastAtUnit`, `C_Spell.CastingInfo`, `C_Spell.ChannelInfo`, `C_Spell.DoesSpellExist`, `C_Spell.GetSchoolString`, `C_Spell.GetSpellCooldown`, `C_Spell.GetSpellDescription`, `C_Spell.GetSpellInfo`, `C_Spell.GetSpellLevelInfo`, `C_Spell.GetSpellLink`, `C_Spell.GetSpellMechanicByID`, `C_Spell.GetSpellName`, `C_Spell.GetSpellPowerCost`, `C_Spell.GetSpellRadius`, `C_Spell.GetSpellReagents`, `C_Spell.GetSpellRequiredTargetLevel`, `C_Spell.GetSpellSubtext`, `C_Spell.GetSpellTexture`, `C_Spell.IsAutoAttackSpell`, `C_Spell.IsCurrentSpell`, `C_Spell.IsRangedAutoAttackSpell`, `C_Spell.IsSelfBuff`, `C_Spell.IsSpellHarmful`, `C_Spell.IsSpellHelpful`, `C_Spell.IsSpellInRange`, `C_Spell.IsSpellPassive`, `C_Spell.IsSpellUsable`, `C_Spell.SpellHasRange`, `C_Spell.UnitCastingInfo`, `C_Spell.UnitChannelInfo`, `CancelSpellByName`, `CastSpellNoToggle`, `GetCraftSpellID`, `GetSpellInfo`, `GetSpellLink`, `GetSpellRadius`, `GetSpellRequiredTargetLevel`, `GetSpellSchool`, `IsHarmfulSpell`, `IsHelpfulSpell`, `IsPassiveSpell`, `IsPlayerSpell`, `IsSpellKnown`, `IsUsableSpell`, `SpellHasRange` |
+| [Quest](docs/API.md#quest) | `C_QuestLog.GetNumQuestObjectives`, `C_QuestLog.GetQuestDetails`, `C_QuestLog.GetHeaderIndexForQuest`, `C_QuestLog.GetLogIndexForQuestID`, `C_QuestLog.GetQuestIDForLogIndex`, `C_QuestLog.GetTitleForQuestID`, `C_QuestLog.IsOnQuest`, `C_QuestLog.IsQuestDataCachedByID`, `C_QuestLog.IsUnitOnQuest`, `C_QuestLog.RequestLoadQuestByID`, `GetQuestLogLeaderBoardID` |
+| [Spell](docs/API.md#spell) | `C_Spell.CancelSpellByID`, `C_Spell.CastAtCursor`, `C_Spell.CastAtUnit`, `C_Spell.CastingInfo`, `C_Spell.ChannelInfo`, `C_Spell.DoesSpellExist`, `C_Spell.GetSchoolString`, `C_Spell.GetSpellCooldown`, `C_Spell.GetSpellDescription`, `C_Spell.GetSpellEffectMechanics`, `C_Spell.GetSpellInfo`, `C_Spell.GetSpellLevelInfo`, `C_Spell.GetSpellLink`, `C_Spell.GetSpellMechanicByID`, `C_Spell.GetSpellName`, `C_Spell.GetSpellPowerCost`, `C_Spell.GetSpellRadius`, `C_Spell.GetSpellReagents`, `C_Spell.GetSpellRequiredTargetLevel`, `C_Spell.GetSpellSubtext`, `C_Spell.GetSpellTexture`, `C_Spell.IsAutoAttackSpell`, `C_Spell.IsCurrentSpell`, `C_Spell.IsRangedAutoAttackSpell`, `C_Spell.IsSelfBuff`, `C_Spell.IsSpellHarmful`, `C_Spell.IsSpellHelpful`, `C_Spell.IsSpellInRange`, `C_Spell.IsSpellPassive`, `C_Spell.IsSpellUsable`, `C_Spell.SpellHasRange`, `C_Spell.UnitCastingInfo`, `C_Spell.UnitChannelInfo`, `CanDualWield`, `CancelSpellByName`, `CastSpellNoToggle`, `GetCraftSpellID`, `GetSpellBonusDamage`, `GetSpellBonusHealing`, `GetSpellInfo`, `GetSpellLink`, `GetSpellRadius`, `GetSpellRequiredTargetLevel`, `GetSpellSchool`, `IsHarmfulSpell`, `IsHelpfulSpell`, `IsPassiveSpell`, `IsPlayerSpell`, `IsSpellKnown`, `IsUsableSpell`, `SpellHasRange` |
 | [SpellBook](docs/API.md#spellbook) | `C_SpellBook.GetCurrentLevelSpells`, `C_SpellBook.GetSkillLineName`, `C_SpellBook.GetSkillLineRank`, `C_SpellBook.GetSpellLevelLearned`, `C_SpellBook.GetSpellSkillLine`, `C_SpellBook.IsAutoAttackSpellBookItem`, `C_SpellBook.IsRangedAutoAttackSpellBookItem`, `FindSpellBookSlotByID` |
 | [State](docs/API.md#state) | `CancelShapeshiftForm`, `Dismount`, `GetMirrorTimerInfo`, `GetMirrorTimerProgress`, `GetShapeshiftFormID`, `IsAssistingRitual`, `IsFalling`, `IsInGroup`, `IsInRaid`, `IsLoggedIn`, `IsMounted`, `IsStealthed`, `IsSwimming` |
-| [Table](docs/API.md#table) | `table.wipe` |
+| [System](docs/API.md#system) | `CopyToClipboard`, `GetPhysicalScreenSize` |
 | [Talent](docs/API.md#talent) | `GetTalentIDByIndex`, `GetTalentSpellID` |
-| [TaxiMap](docs/API.md#taximap) | `C_TaxiMap.GetTaxiNodesForMap`, `C_TaxiMap.GetAllTaxiNodes` |
+| [Targeting](docs/API.md#targeting) | `GetPlayerFacing`, `TargetDirectionEnemy`, `TargetDirectionFriend`, `TargetNearest`, `TargetNearestEnemyPlayer`, `TargetNearestFriendPlayer` |
+| [TaxiMap](docs/API.md#taximap) | `C_TaxiMap.GetTaxiNodesForMap`, `C_TaxiMap.GetAllTaxiNodes`, `C_TaxiMap.GetTaxiPaths`, `C_TaxiMap.GetTaxiPathWaypoints`, `C_TaxiMap.GetTaxiRoute` |
 | [Time](docs/API.md#time) | `C_DateAndTime.AdjustTimeByDays`, `C_DateAndTime.AdjustTimeByMinutes`, `C_DateAndTime.CompareCalendarTime`, `C_DateAndTime.GetCalendarTimeFromEpoch`, `C_DateAndTime.GetCurrentCalendarTime`, `C_DateAndTime.GetSecondsUntilDailyReset`, `C_DateAndTime.GetServerTimeLocal`, `C_Timer.After`, `C_Timer.NewTicker`, `C_Timer.NewTimer`, `GetServerTime` |
+| [Totem](docs/API.md#totem) | `GetTotemInfo`, `GetTotemTimeLeft`, `GetTotemDuration`, `TargetTotem` |
 | [TradeSkillUI](docs/API.md#tradeskillui) | `C_TradeSkillUI.GetTradeSkillListLink`, `C_TradeSkillUI.GetCraftListLink`, `C_TradeSkillUI.GetTradeSkillListRecipes` |
 | [UIColor](docs/API.md#uicolor) | `C_UIColor.GetColors` |
-| [Unit](docs/API.md#unit) | `GetUnitSpeed`, `UnitClassBase`, `UnitCreatureFamilyID`, `UnitCreatureTypeID`, `UnitDistanceSquared`, `UnitGUID`, `UnitInLineOfSight`, `UnitInRange`, `UnitIsAFK`, `UnitIsDND`, `UnitIsFeignDeath`, `UnitIsInMyGuild`, `UnitIsMinion`, `UnitIsOtherPlayersPet`, `UnitIsPet`, `UnitIsPossessed`, `UnitPower`, `UnitPowerMax`, `UnitPowerType`, `UnitRaceBase`, `UnitStandState`, `UnitSubName`, `UnitTokenFromGUID` |
+| [Unit](docs/API.md#unit) | `ClosestUnitPosition`, `GetUnitSpeed`, `UnitClassBase`, `UnitCreatureFamilyID`, `UnitCreatureTypeID`, `UnitDistanceSquared`, `UnitGUID`, `UnitHealthMissing`, `UnitInLineOfSight`, `UnitInRange`, `UnitIsAFK`, `UnitIsDND`, `UnitIsFeignDeath`, `UnitIsInMyGuild`, `UnitIsMinion`, `UnitIsOtherPlayersPet`, `UnitIsPet`, `UnitIsPossessed`, `UnitOwnerGUID`, `UnitPower`, `UnitPowerMax`, `UnitPowerMissing`, `UnitPowerType`, `UnitRaceBase`, `UnitSpellHaste`, `UnitStandState`, `UnitSubName`, `UnitTokenFromGUID` |
 | [UnitAuras](docs/API.md#unitauras) | `C_UnitAuras.GetAuraDataByIndex`, `C_UnitAuras.GetAuraDataBySpellName`, `C_UnitAuras.GetAuraDispelTypeColor`, `C_UnitAuras.GetBuffDataByIndex`, `C_UnitAuras.GetDebuffDataByIndex`, `C_UnitAuras.GetPlayerAuraBySpellID`, `C_UnitAuras.GetUnitAuraBySpellID`, `C_UnitAuras.GetUnitAuras`, `C_UnitAuras.RegisterComboDuration` |
 | [VoiceChat](docs/API.md#voicechat) | `C_VoiceChat.GetTtsVoices`, `C_VoiceChat.GetRemoteTtsVoices`, `C_VoiceChat.SpeakText`, `C_VoiceChat.StopSpeakingText`, `C_TTSSettings.GetSpeechRate`, `C_TTSSettings.GetSpeechVolume`, `C_TTSSettings.GetSpeechVoiceID`, `C_TTSSettings.GetVoiceOptionName`, `C_TTSSettings.SetSpeechRate`, `C_TTSSettings.SetSpeechVolume`, `C_TTSSettings.SetVoiceOption`, `C_TTSSettings.SetVoiceOptionByName`, `C_TTSSettings.SetDefaultSettings`, `C_TTSSettings.RefreshVoices` |
 | [XMLUtil](docs/API.md#xmlutil) | `C_XMLUtil.DoesTemplateExist`, `C_XMLUtil.GetTemplateInfo`, `C_XMLUtil.GetTemplates` |
@@ -144,6 +148,7 @@ when launching with `-console`), not as Lua functions. See the
 | `PLAYER_STOPPED_MOVING` | *(none)* |
 | `PLAYER_STARTED_TURNING` | *(none)* |
 | `PLAYER_STOPPED_TURNING` | *(none)* |
+| `PLAYER_TOTEM_UPDATE` | `totemSlot` |
 | `QUEST_ACCEPTED` | `questLogIndex, questID` |
 | `QUEST_DATA_LOAD_RESULT` | `questID, success` |
 | `QUEST_REMOVED` | `questID` |
@@ -166,6 +171,8 @@ when launching with `-console`), not as Lua functions. See the
 | Addon security | `Enum.AddOnSecurityStatus.{Secure,Insecure,Banned,NotAvailable}` |
 | Power type | `Enum.PowerType.{HealthCost,None,Mana,Rage,Focus,Energy,Happiness}` |
 | Inventory type | `Enum.InventoryType.Index*Type` (0–34, e.g. `IndexHeadType`=1 … `IndexRelicType`=28) |
+| Item class | `Enum.ItemClass.{Consumable,Container,Weapon,Gem,Armor,Reagent,Projectile,Tradegoods,ItemEnhancement,Recipe,Quiver,Questitem,Key,Miscellaneous,…}` (0–19) |
+| Item quality | `Enum.ItemQuality.{Poor,Common,Uncommon,Rare,Epic,Legendary,Artifact}` (0–6) |
 
 ### Unit tokens
 

cmake/version.rc.in

@@ -0,0 +1,38 @@
+// Generated from cmake/version.rc.in by CMake configure_file().
+// Stamps the PE VERSIONINFO resource so Explorer -> Properties -> Details
+// and GetFileVersionInfo() report the same version as the CLASSIC_API_VERSION
+// Lua global. Both derive from the CLASSICAPI_TAG (vMAJOR.MINOR.PATCH) cache
+// var; an untagged dev build gets the 9999.99.99 "newer than everything"
+// sentinel.
+
+#include <winver.h>
+
+VS_VERSION_INFO VERSIONINFO
+ FILEVERSION    @CLASSICAPI_VER_MAJOR@,@CLASSICAPI_VER_MINOR@,@CLASSICAPI_VER_PATCH@,0
+ PRODUCTVERSION @CLASSICAPI_VER_MAJOR@,@CLASSICAPI_VER_MINOR@,@CLASSICAPI_VER_PATCH@,0
+ FILEFLAGSMASK  VS_FFI_FILEFLAGSMASK
+ FILEFLAGS      0x0L
+ FILEOS         VOS_NT_WINDOWS32
+ FILETYPE       VFT_DLL
+ FILESUBTYPE    VFT2_UNKNOWN
+BEGIN
+    BLOCK "StringFileInfo"
+    BEGIN
+        BLOCK "040904b0"
+        BEGIN
+            VALUE "CompanyName",      "ClassicAPI Team"
+            VALUE "FileDescription",  "ClassicAPI - modern WoW API backport for 1.12.1"
+            VALUE "FileVersion",      "@CLASSICAPI_VER_STRING@"
+            VALUE "InternalName",     "ClassicAPI"
+            VALUE "LegalCopyright",   "Licensed under GPLv3"
+            VALUE "OriginalFilename", "ClassicAPI.dll"
+            VALUE "ProductName",      "ClassicAPI"
+            VALUE "ProductVersion",   "@CLASSICAPI_VER_STRING@"
+        END
+    END
+    BLOCK "VarFileInfo"
+    BEGIN
+        // 0x0409 = U.S. English, 1200 = Unicode codepage.
+        VALUE "Translation", 0x409, 1200
+    END
+END

src/Game.cpp

@@ -57,7 +57,8 @@ namespace Lua {
     F(Resume,      lua_resume,      LUA_RESUME)       \
     F(Yield,       lua_yield,       LUA_YIELD)        \
     F(ArgError,    luaL_argerror,   LUAL_ARG_ERROR)   \
-    F(SetN,        luaL_setn,       LUAL_SETN)
+    F(SetN,        luaL_setn,       LUAL_SETN)         \
+    F(CheckStack,  lua_checkstack,  LUA_CHECK_STACK)
 
 #define CLASSICAPI_BIND_LUA(Name, Typedef, Offset) \
     const Typedef##_t Name = reinterpret_cast<Typedef##_t>(Offsets::Offset);

src/Game.h

@@ -100,6 +100,7 @@ using lua_resume_t = int(__fastcall *)(void *L, int nargs);
 using lua_yield_t = int(__fastcall *)(void *L, int nresults);
 using luaL_argerror_t = void(__fastcall *)(void *L, int narg, const char *msg);
 using luaL_setn_t = void(__fastcall *)(void *L, int t, int n);
+using lua_checkstack_t = int(__fastcall *)(void *L, int size);
 
 extern const lua_isnumber_t IsNumber;
 extern const lua_isstring_t IsString;
@@ -142,6 +143,7 @@ extern const lua_resume_t Resume;
 extern const lua_yield_t Yield;
 extern const luaL_argerror_t ArgError;
 extern const luaL_setn_t SetN;
+extern const lua_checkstack_t CheckStack;
 
 // Returns the global `lua_State *` (read on demand from the engine's global).
 // Callable outside a Lua callback, e.g. during LoadScriptFunctions setup.

src/Offsets.h

@@ -140,6 +140,23 @@ enum Offsets {
     //   and call the inner invoker, which is self-contained.
     FUN_GAMETOOLTIP_SCRIPT_RESOLVER = 0x005295D0,
     FUN_FRAME_INVOKE_SCRIPT = 0x00704D50,
+    // The other per-object tooltip builders, co-hooked the same way as
+    // FUN_GAMETOOLTIP_BUILD_ITEM to back OnTooltipSetSpell / OnTooltipSetUnit /
+    // OnTooltipSetGameObject (see Tooltip::SetEvents). Each is the single funnel
+    // its Set*/mouseover paths converge on and clears the tooltip
+    // (FUN_00530050) before repopulating, so firing after it covers every way
+    // that object type gets set:
+    //   - Spell FUN_GAMETOOLTIP_BUILD_SPELL_TOOLTIP (0x0052E610, 7 stack args,
+    //     RET 0x1c) — SetSpell/SetSpellByID/SetTalent/SetShapeshift funnel.
+    //   - Unit  (0x00529fe0, __thiscall(self, guid*), RET 4) — SetUnit +
+    //     the two engine mouseover paths (FUN_004919d0 / FUN_00492890).
+    //     Returns an int the caller (Script_GameTooltip_SetUnit) tests, so the
+    //     co-hook must forward the original's return value.
+    //   - GameObject (0x0052aa20, __thiscall(self, guid*), RET 4) — the GO
+    //     hover populator; resolves the GO (OBJ_TYPE_GAMEOBJECT) and writes the
+    //     GO field at +0x370.
+    FUN_GAMETOOLTIP_BUILD_UNIT = 0x00529FE0,
+    FUN_GAMETOOLTIP_BUILD_GAMEOBJECT = 0x0052AA20,
     FUN_GAMETOOLTIP_ADD_LINE = 0x00530270,        // __thiscall(self, left, right, lColorBGRA*, rColorBGRA*, wrap)
     OFF_GAMETOOLTIP_NUM_LINES = 0x31C,            // int — live line count (AddLine index; +0x320 is the cap)
     // The displayed item's identity is read via the existing
@@ -454,6 +471,39 @@ enum Offsets {
     // pointer the inventory routines expect.
     FUN_RESOLVE_UNIT_TOKEN = 0x00515940,
 
+    // Set the player's current target to a GUID —
+    // `__fastcall(uint64_t *guid)`. Validates the GUID resolves to a unit
+    // (typemask 8) then commits the selection (CMSG_SET_SELECTION +
+    // client-side target). This is what `Script_TargetUnit` (0x004899D0)
+    // calls after resolving its token→GUID; we call it directly with a
+    // GUID we already have (e.g. a totem creature). NOTE: reads `guid[0]`
+    // (lo) and `guid[1]` (hi) through the pointer.
+    FUN_TARGET_BY_GUID = 0x00489A40,
+
+    // Tab-targeting internals, shared with our backported TargetNearest* /
+    // TargetDirection* family (`target/Nearest.cpp`).
+    //
+    // `FUN_TARGET_CANDIDATE_VALID` (0x00493E40) — the engine's per-mode
+    // candidate validity predicate used by the native `TargetNearestEnemy`
+    // / `TargetNearestFriend` cycle. `__fastcall(CGUnit *player /*ecx*/,
+    // CGUnit *candidate /*edx*/, int mode) → int` (nonzero = valid). Modes:
+    // 1 = enemy (attackable + alive + not-critter), 2 = friend (assistable +
+    // alive), 3 = party, 4 = raid. Wraps the reaction cores
+    // `FUN_00606980` (can-attack) / `FUN_006066f0` (can-assist), so calling
+    // it gives us the engine's exact hostility semantics for free.
+    FUN_TARGET_CANDIDATE_VALID = 0x00493E40,
+    // `FUN_SET_SELECTION_BY_GUID` (0x00493540) — canonical target setter the
+    // native tab-cycle commits through. `__cdecl(uint32_t guidLo, uint32_t
+    // guidHi)`. Validates + fires CMSG_SET_SELECTION + client target +
+    // event 0xC3, and maintains the current-selection globals below.
+    // Passing {0,0} clears the target.
+    FUN_SET_SELECTION_BY_GUID = 0x00493540,
+    // Current target-selection GUID (lo/hi), written by
+    // `FUN_SET_SELECTION_BY_GUID`. We read it to detect whether the player's
+    // target changed out from under an in-progress tab-cycle.
+    VAR_CURRENT_SELECTION_GUID_LO = 0x00B4E2D8,
+    VAR_CURRENT_SELECTION_GUID_HI = 0x00B4E2DC,
+
     // Local-player CGObject-like global. Not the same pointer as
     // ResolveUnitToken("player") returns — that one's the canonical
     // CGPlayer_C used by inventory etc. This pointer's +0xC0 field
@@ -631,6 +681,25 @@ enum Offsets {
     // The live (new) value is NOT passed — read it from the object (the
     // engine's bag callback reads the invMgr GUID array).
 
+    // ---- Unit-event token observers (Unit::TokenObserver) ---------------
+    // The engine makes target/party/raid/pet/mouseover units fire per-token
+    // unit events (UNIT_HEALTH, UNIT_MANA, UNIT_AURA, …) by watching bank-UNIT
+    // descriptor fields: FUN_0051bbb0 loops event index i in
+    // [0, EVENT_NAME_UNIT_MAX); for each whose static name slot is non-null it
+    // registers a bank-3 observer on field i*4 (per-index size below) with
+    // callback FUN_0051bd50 → the broadcast FUN_00515e50(guid, i), which fires
+    // event i once per token referencing the guid. The FIELD INDEX IS THE EVENT
+    // ID (health field +0x40 → event 16 = UNIT_HEALTH). Unit::TokenObserver
+    // replicates that exact loop with a caller's own callback to make synthetic
+    // tokens (focus, nameplateN) first-class; the registrar always appends a
+    // fresh node (FUN_00467f00, no dedup), so ours coexists with the engine's —
+    // a unit that is also the target fires both "target" and our token. The
+    // broadcast always fires with format "%s" + the token (DAT_0082e280).
+    //   Per-index watched size (FUN_0051bbb0's switch): i∈{0,2,4,10}=8,
+    //   0x29=0xD8 (UNIT_FIELD_AURA), 0x6B=0x30, 0xA7/0xAE=0x1C, else 4.
+    VAR_EVENT_NAME_TABLE_STATIC = 0x00BE1198, // char*[] boot name array; slot i (base+i*4) non-null ⇒ real event i
+    EVENT_NAME_UNIT_MAX = 0xB6,               // FUN_0051bbb0's loop bound
+
     // The engine's inventory observer setup — registers the bag-slot
     // GUID-field observers above, once per enter-world (sole caller is the
     // enter-world initializer FUN_004908C0, latched by DAT_00B4B424).
@@ -646,6 +715,7 @@ enum Offsets {
     OFF_DESC_PLAYER_EQUIP_FIRST = 0x4A8,
     DESC_PLAYER_EQUIP_SLOTS = 19,
     DESC_OBSERVER_BANK_PLAYER = 4,
+    DESC_OBSERVER_BANK_UNIT = 3, // CGUnit descriptor bank (FUN_0051bbb0's watch loop)
 
     // ITEM_FIELD_DURABILITY, ITEM-bank-relative: descriptor-absolute
     // +0xA0 (field index 0x28, which counts the 6 OBJECT fields) minus
@@ -773,6 +843,15 @@ enum Offsets {
     // mana/rage/focus/energy/happiness order as POWER1..5). Vanilla
     // 1.12 has 5 power types; the WotLK additions (Runes / Runic Power)
     // don't exist in this descriptor layout.
+
+    // UNIT_MOD_CAST_SPEED — the cast-time multiplier float (1.0 = normal,
+    // <1.0 = faster). The server folds it into `SpellEntry::GetCastTime`
+    // (`castTime *= GetFloatValue(UNIT_MOD_CAST_SPEED)`); the client reads it
+    // in `FUN_006e3340` at descriptor `+0x22c`. Backs `UnitSpellHaste`
+    // (`haste% = (1/mult - 1) * 100`). nampower surfaces the raw float as its
+    // `modCastSpeed` unit field.
+    OFF_UNIT_MOD_CAST_SPEED = 0x22C,
+
     UNIT_POWER_MIN_TYPE = 0,
     UNIT_POWER_MAX_TYPE = 4, // happiness; types 5/6 only valid post-WotLK
 
@@ -798,6 +877,19 @@ enum Offsets {
     //   mov edx, [eax + 0x110]
     //   movzx eax, byte ptr [edx + 0x7B]
     OFF_UNIT_DESCRIPTOR_POWER_TYPE_BYTE = 0x7B,
+    // UNIT_FIELD_STAT0..4 — the fully-computed (base+item+buff) primary
+    // stats, broadcast in the descriptor. Order Str/Agi/Sta/Int/Spirit;
+    // STAT4 (Spirit) = fieldIndex 0x94 → +0x250 (from the UpdateField name
+    // table; cross-checked in-game: descriptor +0x250 read 173→182 when a
+    // +9-Spirit item was equipped). What GetStat(STAT_SPIRIT) returns
+    // server-side; used by GetSpellBonusHealing for the Spiritual-Guidance
+    // (aura 175) spirit→healing conversion.
+    OFF_UNIT_FIELD_STAT_SPIRIT = 0x250,
+    // UNIT_FIELD_RESISTANCES[0] = armor (the fully-computed total), fieldIndex
+    // 0x95 → +0x254 (7 resistances: armor, then the 6 magic schools). What
+    // GetArmor() / GetResistance(SPELL_SCHOOL_NORMAL) returns; used by
+    // GetSpellBonusHealing for Turtle's Ironclad (aura 199) armor→healing.
+    OFF_UNIT_FIELD_RESISTANCE_ARMOR = 0x254,
     OFF_UNIT_FIELD_FLAGS = 0xA0,
     UNIT_FLAG_PLAYER_CONTROLLED = 0x08,
     // Bit 19 of UNIT_FIELD_FLAGS — `Script_UnitAffectingCombat` at
@@ -868,6 +960,27 @@ enum Offsets {
     UNIT_AURA_TOTAL = 48,
     UNIT_AURA_VISIBLE_MASK = 0x0E,             // nibble mask used by the engine's visibility gate
 
+    // PLAYER_FIELD_MOD_DAMAGE_DONE_POS/NEG — the player's per-school spell
+    // damage bonus. Offsets from the engine's own UpdateField name/index
+    // table in `.rdata` (20-byte entries `{char* name, u32 fieldIndex, u32
+    // count, ...}` at VA 0x83B6C8): POS = fieldIndex 0x3F5 count 7 → byte
+    // offset fieldIndex*4 = 0xFD4; NEG = 0x3FC → 0xFF0. Seven int32 each,
+    // one per school (0 physical .. 6 arcane); net bonus = POS − NEG.
+    //
+    // **Read these off `[player + OFF_CGPLAYER_INFO]` (the +0xE68 CGPlayer
+    // sub-struct), NOT the broadcast descriptor at +0x110.** The descriptor
+    // copy is never sent to the client and reads zero (verified in-game: the
+    // whole post-skills PLAYER descriptor region is zero on a geared L60 —
+    // vanilla never displayed spell power, so the server doesn't broadcast
+    // it). The +0xE68 struct holds the client's fully-computed value
+    // (gear + enchants + buffs + talents + sets baked in). Same base +
+    // offsets nampower's GetSpellPower uses; verified 613 generic / 647 Fire
+    // on a geared mage. Read by GetSpellBonusDamage in [src/spell/BonusDamage.cpp].
+    // (No MOD_HEALING_DONE equivalent — vanilla lacks the field entirely;
+    // GetSpellBonusHealing is derived instead.)
+    OFF_PLAYER_FIELD_MOD_DAMAGE_DONE_POS = 0xFD4,
+    OFF_PLAYER_FIELD_MOD_DAMAGE_DONE_NEG = 0xFF0,
+
     // Reusable "is this spell record a user-visible aura" predicate.
     // `__fastcall(spellRecord*) -> bool`. Checks Spell.dbc Attributes
     // (high bit of byte at +0x18 must be clear), AttributesEx bit
@@ -1433,6 +1546,15 @@ enum Offsets {
     // `0x0048BACF` / `0x0048BADC`.
     OFF_CGOBJECT_VTBL_GET_POSITION = 0x14,
 
+    // CGUnit movement-block orientation (facing) in radians, 0..2*pi. Lives
+    // right after the {x,y,z} position block (at +0x9B8), i.e. pos+0xC. The
+    // `GetPosition` virtual copies only x/y/z into the caller's buffer, so
+    // read facing off the object directly. Backs `GetPlayerFacing`. Empirically
+    // located by probing the player object across a known 180-degree turn
+    // (value flipped by ~pi, stayed in range); mirrored at +0x9F8 / +0xC98
+    // (last-sent / render copies) — +0x9C4 is the authoritative one.
+    OFF_UNIT_FACING = 0x9C4,
+
     // CGObject `m_objectType` field — 0 = (base) object, 1 = item,
     // 2 = container, 3 = unit, 4 = player, 5 = gameobject, … Read as
     // `*(int *)(obj + 0x14)`. (Distinct from GET_POSITION above, which
@@ -1804,6 +1926,16 @@ enum Offsets {
     // last use"). Negative = single-use, destroyed when count hits 0.
     // `GetItemCount(includeUses=true)` uses abs() for the multiplier.
     OFF_DESCRIPTOR_SPELL_CHARGES_0 = 0x28,
+    // ITEM_FIELD_ENCHANTMENT block (fields 16..36, per the +0x48
+    // enchant-charges note above) — 7 enchant slots, 3 dwords each
+    // `{enchantID, duration, charges}`. Slot 0 = permanent enchant,
+    // slot 1 = temporary (weapon oils / sharpening stones). The
+    // enchant ID indexes SpellItemEnchantment.dbc. Block base = field
+    // 16 = +0x40 (field 15 FLAGS at +0x3C precedes it); slot stride
+    // 0x0C, enchant ID at slot+0x00. Used by spell/BonusDamage.cpp to
+    // fold enchant-granted spell power into GetSpellBonusDamage.
+    OFF_DESCRIPTOR_ENCHANTMENT_ID = 0x40,
+    DESCRIPTOR_ENCHANTMENT_SLOT_STRIDE = 0x0C,
     // ITEM_FIELD_DURABILITY (current) and ITEM_FIELD_MAXDURABILITY (max) live
     // adjacent to each other in the descriptor as plain dwords. Verified in
     // `Script_GetInventoryItemBroken` (`0x004C8590`): after resolving the
@@ -1812,6 +1944,12 @@ enum Offsets {
     // no durability concept (consumables, materials) have both fields 0.
     OFF_DESCRIPTOR_DURABILITY = 0xA0,
     OFF_DESCRIPTOR_MAX_DURABILITY = 0xA4,
+    // Per-instance "readable text" id (letters / mail-scroll items carry a
+    // server-assigned text id here). Drives the `readable` return of
+    // `Script_GetContainerItemInfo` (`0x004F9670`): at `0x004F97C1` it reads
+    // `[descriptor+0x9C]` and, when non-zero, reports the slot as readable
+    // even when the static ItemStats page-text is 0. Field index 0x27.
+    OFF_DESCRIPTOR_READABLE_TEXT_ID = 0x9C,
 
     // Per-item repair-cost helper used by Script_GameTooltip_SetInventoryItem
     // (3rd return value). __fastcall(ecx = CGItem *) -> int copperCost.
@@ -2346,6 +2484,29 @@ enum Offsets {
     // "DISTANT" / other) — the node's reachability for the open session.
     FUN_TAXI_NODE_TYPE = 0x004DC4E0,
 
+    // Per-slot computed route (the chain that TakeTaxiNode sends to the
+    // server). Derived from FUN_004dc8d0 (the TakeTaxiNode worker) and the
+    // route builder FUN_004dbce0:
+    //   +0x0C (byte)  nonzero when the multi-hop route array below is built
+    //   +0x14 (int*)  array of TaxiNodes.dbc IDs, current->dest in flight
+    //                 order, length at +0x18
+    //   +0x18 (int)   route length (node count; hops = count - 1)
+    // A direct hop (a TaxiPath edge exists current->dest) is flown as just
+    // {current, dest} and does NOT populate +0x14 — see VAR_TAXI_ADJACENCY.
+    OFF_TAXI_SLOT_MULTIHOP = 0x0C,
+    OFF_TAXI_SLOT_ROUTE = 0x14,
+    OFF_TAXI_SLOT_ROUTE_COUNT = 0x18,
+
+    // Pointer to the CURRENT flight master's TaxiNodes.dbc record (id @ +0);
+    // the origin of every route. Used by FUN_004dc8d0 / FUN_004dbce0.
+    VAR_TAXI_CURRENT_REC = 0x00BB4A80,
+
+    // Node x node -> pathID adjacency matrix (256-wide rows, int cells; cell
+    // [from*0x100 + to] is the direct TaxiPath id, or 0 if none). Backs the
+    // direct-hop test FUN_004dbad0. IDs are 1..256.
+    VAR_TAXI_ADJACENCY = 0x00B7365C,
+    TAXI_ADJACENCY_DIM = 0x100,
+
     // TaxiPath.dbc (4 fields, 0x10 bytes): {id, fromNode@+0x04, toNode@+0x08,
     // cost}. A real flight master is a node some flight path connects to;
     // Northshire Abbey / spurious duplicate rows / standalone markers are not
@@ -2354,6 +2515,23 @@ enum Offsets {
     VAR_TAXIPATH_COUNT = 0x00C0D69C,
     OFF_TAXIPATH_FROM = 0x04,
     OFF_TAXIPATH_TO = 0x08,
+    OFF_TAXIPATH_COST = 0x0C,
+
+    // TaxiPathNode.dbc — the per-path flight waypoints. 1-based
+    // record-pointer array (records/count slots per docs/DBCs.md). Record
+    // (verified against the extracted DBC + the loading-screen spline
+    // reader FUN_004075A0, which reads mapID@+0xC, X@+0x10, Y@+0x14):
+    //   {ID@+0, pathID@+4, nodeIndex@+8, mapID@+0xC,
+    //    X@+0x10, Y@+0x14, Z@+0x18 (float), flags@+0x1C, delay@+0x20}
+    // Waypoints of a path share pathID and order by nodeIndex.
+    VAR_TAXIPATHNODE_RECORDS = 0x00C0D6AC,
+    VAR_TAXIPATHNODE_COUNT = 0x00C0D6B0,
+    OFF_TAXIPATHNODE_PATH_ID = 0x04,
+    OFF_TAXIPATHNODE_INDEX = 0x08,
+    OFF_TAXIPATHNODE_MAP = 0x0C,
+    OFF_TAXIPATHNODE_X = 0x10,
+    OFF_TAXIPATHNODE_Y = 0x14,
+    OFF_TAXIPATHNODE_Z = 0x18,
 
     // Engine player-info cache — populated by the
     // SMSG_NAME_QUERY_RESPONSE handler (opcode 0x51) at 0x005551A0,
@@ -3130,6 +3308,18 @@ enum Offsets {
     // size matches Spell.dbc's row count. Pre-login the slot is NULL.
     VAR_PLAYER_SPELL_BITMAP = 0x00B710FC,
 
+    // Player spell-knowledge writers — the two functions that mutate the
+    // bitmap above. Learn (`FUN_004b25b0`) sets the bit, rebuilds the
+    // spellbook arrays, and fires SPELLS_CHANGED; unlearn (`FUN_004b2c50`)
+    // clears the bit and removes the spell. Both `__fastcall`: learn is
+    // (uint spellID, int notify, uint replacedSpellID), unlearn is
+    // (uint spellID, int). Co-hooked (spell/Info.cpp) to bump
+    // Player::StatSignal so a talent respec invalidates GetSpellBonusHealing's
+    // talent-conversion cache. They fire at login (SMSG_INITIAL_SPELLS) and on
+    // each learn/unlearn — never per-frame, so cool hook targets.
+    FUN_LEARN_SPELL = 0x004B25B0,
+    FUN_UNLEARN_SPELL = 0x004B2C50,
+
     // Spell-rank-chain knowledge check — `char __thiscall(player /*ecx*/,
     // spellID)`. Walks `spellID`'s forward rank chain (the class/race-
     // resolved chain via `0x0060C7C0`) and returns nonzero if the player
@@ -3606,6 +3796,60 @@ enum Offsets {
     GROUP_MEMBER_STATUS_ONLINE = 0x1,
     FUN_GROUP_MEMBER_SLOT_LOOKUP = 0x00496420,
 
+    // Health/power fields within the two group-member blocks — the
+    // out-of-range fallback the engine's UnitHealth/UnitMana (and their Max
+    // variants) use when a groupmate has no live CGUnit (different map / out
+    // of range), sourced from SMSG_PARTY_MEMBER_STATS. The two blocks have
+    // DIFFERENT layouts (all u16):
+    //
+    //   Stats block (FUN_GROUP_MEMBER_STATS_LOOKUP): statusFlags@+8,
+    //     powerType@+9, health@+0xa, maxHealth@+0xc, power@+0xe, maxPower@+0x10,
+    //     level@+0x12, areaId@+0x14. The full record.
+    //   Raid slot (FUN_GROUP_MEMBER_SLOT_LOOKUP): powerType@+0x58,
+    //     health@+0x5c, maxHealth@+0x5e, power@+0x60, maxPower@+0x62. Leaner —
+    //     no level/area/flags.
+    //
+    // Power values are raw (divide by the power divisor for display). Verified
+    // from Script_UnitHealth (0x005174d0) / Script_UnitHealthMax (0x005175b0)
+    // / Script_UnitMana (0x00517670) / Script_UnitManaMax (0x005177e0).
+    OFF_GROUP_MEMBER_STATS_HEALTH = 0xa,
+    OFF_GROUP_MEMBER_STATS_MAX_HEALTH = 0xc,
+    OFF_GROUP_MEMBER_STATS_POWER_TYPE = 0x9,
+    OFF_GROUP_MEMBER_STATS_POWER = 0xe,
+    OFF_GROUP_MEMBER_STATS_MAX_POWER = 0x10,
+    OFF_GROUP_MEMBER_STATS_LEVEL = 0x12,
+    OFF_RAID_SLOT_POWER_TYPE = 0x58,
+    OFF_RAID_SLOT_HEALTH = 0x5c,
+    OFF_RAID_SLOT_MAX_HEALTH = 0x5e,
+    OFF_RAID_SLOT_POWER = 0x60,
+    OFF_RAID_SLOT_MAX_POWER = 0x62,
+    // Remaining raid-member-struct fields, mapped from Script_GetRaidRosterInfo
+    // (0x004bb560). Same struct FUN_GROUP_MEMBER_SLOT_LOOKUP returns; all
+    // object-independent (readable for out-of-range raiders). Name + class are
+    // NOT here — GetRaidRosterInfo reads those from the NameCache by GUID.
+    OFF_RAID_SLOT_SUBGROUP = 0x08,   // u32, 0-based (roster UI shows +1)
+    OFF_RAID_SLOT_RANK = 0x0c,       // u32
+    OFF_RAID_SLOT_FLAGS = 0x18,      // u32
+    OFF_RAID_SLOT_LEVEL = 0x22,      // u16
+    OFF_RAID_SLOT_AREA_ID = 0x24,    // u16 -> AreaTable.dbc
+    RAID_SLOT_FLAG_ONLINE = 0x1,
+    RAID_SLOT_FLAG_DEAD = 0x4,
+
+    // Group-member aura spell-ID arrays — the out-of-range fallback the
+    // engine's Script_UnitBuff (0x00519500) / Script_UnitDebuff (0x005198f0)
+    // read when a groupmate has no live CGUnit. The server transmits a
+    // member's current auras (spell IDs only — no caster/duration/stacks) in
+    // SMSG_PARTY_MEMBER_STATS via GROUP_UPDATE_FLAG_AURAS (buffs, slots 0..31)
+    // + GROUP_UPDATE_FLAG_AURAS_NEGATIVE (debuffs, slots 32..47); the client
+    // keeps them in the two group-member blocks. Both arrays are 48 u16
+    // entries (UNIT_AURA_TOTAL) indexed by the same absolute slot the
+    // descriptor uses. Spell IDs are truncated to u16 on the wire, so custom
+    // IDs > 65535 come through wrong (same limitation as the built-in
+    // UnitBuff/UnitDebuff). Read the party array only when the member's online
+    // flag (OFF_GROUP_MEMBER_STATUS_FLAGS bit 0) is set — the engine does.
+    OFF_GROUP_MEMBER_STATS_AURAS = 0x1a,  // party stats block (FUN_00496400)
+    OFF_RAID_SLOT_AURAS = 0x64,           // raid slot (FUN_00496420)
+
     // Per-slot GUID tables — used to map party/raid token strings
     // ("party1", "raid17") to GUIDs without going through
     // `FUN_RESOLVE_UNIT_TOKEN`, which only resolves to a local CGUnit
@@ -3734,6 +3978,35 @@ enum Offsets {
     // `rawset(nil)` clear leaves it stale and subsequent `table.insert`
     // appends past the wiped slots.
     LUAL_SETN = 0x6F4EA0,
+    // `lua_checkstack(L, n)` — `int __fastcall(L /*ecx*/, n /*edx*/)`.
+    // Ensures room for `n` more stack values, growing if needed; returns 0
+    // (without growing) when `(top-base)/16 + n` would exceed LUA_MAXCSTACK
+    // (0x800 = 2048), 1 otherwise. Verified by the `cmp reg, 0x800` overflow
+    // test at 0x006F2F43. Needed by any C function that pushes an unbounded
+    // number of results (e.g. `strsplit`) — pushing past the ~20-slot
+    // C-call guarantee without growing corrupts the stack.
+    LUA_CHECK_STACK = 0x006F2F30,
+    // `str_find` — the Lua 5.0 string-library `string.find` C function
+    // (`int __fastcall(void *L)`), entry in the strlib luaL_reg table at
+    // `0x00822dd0`. Returns `1` (nil pushed, no match), `2` (start, end),
+    // or `2 + ncaptures`. `string.match` (a Lua 5.1 addition, missing here)
+    // shares the exact same pattern engine — it's `find` that yields the
+    // captures / whole match instead of the indices — so `BaseLib::StringLib`
+    // calls this and transforms the result rather than reimplementing the
+    // matcher. Verified by decoding the function at this address.
+    FUN_LUA_STR_FIND = 0x007FC3B0,
+    // `str_gfind` — the Lua 5.0 `string.gfind` C function (strlib entry at
+    // `0x00822dd8`). 5.1 renamed it to `string.gmatch` with identical
+    // behaviour (returns a stateful iterator closure over the matches), so
+    // `BaseLib::StringLib` registers `string.gmatch` as a direct alias of
+    // this function pointer — no wrapper.
+    FUN_LUA_STR_GFIND = 0x007FCFA0,
+    // `math_fmod` — the Lua 5.0 `math.mod` C function (mathlib entry at
+    // `0x00822cb0`): `luaL_checknumber(1/2)` → `fmod(x, y)` → `lua_pushnumber`.
+    // 5.1 renamed the Lua-facing name to `math.fmod` with the identical C
+    // implementation, so `BaseLib::MathLib` registers `math.fmod` as a direct
+    // alias of this function pointer — no wrapper. Verified by decode.
+    FUN_LUA_MATH_FMOD = 0x007FAFD0,
     // `lua_iscfunction(L, idx)` — returns 1 if value is a function
     // closure with the `isC` byte set (`Closure.c.isC == 1`), 0
     // otherwise. Used by `coroutine.create` to reject C functions
@@ -3814,6 +4087,10 @@ enum Offsets {
     // the frame into the matching entry's chain.
     VAR_EVENT_TABLE_BASE_PTR = 0x00CEEF68,
     VAR_EVENT_TABLE_COUNT = 0x00CEEF64,
+    // The FrameScript_EventObject is a `{cap@+0, count@+4, data@+8}` at
+    // 0x00CEEF60, so COUNT/BASE above are its +4/+8. `Event::Custom::Grow`
+    // writes all three (base, cap, count) when it enlarges the table.
+    VAR_EVENT_TABLE_CAP = 0x00CEEF60,
     EVENT_ENTRY_STRIDE = 0x10,
     OFF_EVENT_ENTRY_NAME = 0x00,
     OFF_EVENT_ENTRY_HEAD = 0x0C,
@@ -3854,6 +4131,17 @@ enum Offsets {
     // table after the rebuild settles. Kept for reference.
     FUN_REBUILD_EVENT_TABLE = 0x00703D90,
 
+    // Event-table allocator — `__thiscall(EventObject *this, uint32 count)`.
+    // Called by `RebuildEventTable` to (re)size the entry array. SuperWoW and
+    // nampower co-hook it to destructively clamp the FrameXML count (`> 200`;
+    // glue is smaller) to 700. We deliberately DON'T hook it: our default is
+    // claim-NULL into the engine's ~200 low gaps (which always suffices), and
+    // when a grow IS needed `Event::Custom::Grow` reallocates the buffer +
+    // swaps the globals directly (bypassing this clamp) rather than routing a
+    // size through here. Also documents the empty-entry init the grow mirrors
+    // ({name=0, +4=0, +8=&self, +0xC=(&self)|1}). Kept for reference.
+    FUN_FRAMESCRIPT_SET_EVENT_COUNT = 0x007053B0,
+
     // `FireEvent` — the engine's event dispatcher. 149 callers in the
     // binary. `__cdecl void(int eventID, const char *format, ...)`.
     // Indexes into `[VAR_EVENT_TABLE_BASE_PTR] + eventID * 0x10` and walks
@@ -4067,6 +4355,16 @@ enum Offsets {
     // from `SMemAlloc` (which it requires).
     FUN_STORM_SSTRDUP = 0x0064A620,
 
+    // Storm allocator/free — the pair the engine uses for the event-table
+    // buffer, so its reload teardown `SMemFree`s our grown buffer as its own.
+    // Both `__stdcall`, 4 args (`ret 0x10`); SMemAlloc flag bit 8 (`& 8`)
+    // zero-fills. `Event::Custom::Grow` uses them to reallocate the event
+    // buffer. (Same addresses as FUN_STORM_SMEM_ALLOC / _FREE above.)
+    //   void*  __stdcall SMemAlloc(uint size, const char *file, int line, int flags)
+    //   char   __stdcall SMemFree (void *ptr, const char *file, int line, int flags)
+    FUN_STORM_SMEMALLOC = 0x006462E0,
+    FUN_STORM_SMEMFREE = 0x00646430,
+
     // Talent system — per-player talent state populated at login from
     // (class, race) + Talent.dbc / TalentTab.dbc. The engine maintains
     // one `TabInfo *` per talent tab in the array at
@@ -4128,6 +4426,31 @@ enum Offsets {
     VAR_TALENT_DBC_RECORDS = 0x00C0D6E8,
     VAR_TALENT_DBC_COUNT = 0x00C0D6EC,
 
+    // Flat (row-order) DBC arrays used by the talent-tree builder
+    // `FUN_004f2c00` — DISTINCT from the sparse by-ID index above. The builder
+    // walks TalentTab.dbc in row order, filtering each tab by
+    // `FUN_004f2e50(race, class, raceMask@+0x2c, classMask@+0x30)` (a plain
+    // bitmask test; mask 0 = all), then walks Talent.dbc in row order grouping
+    // contiguous TabID runs — so `GetTalentInfo(tab, idx)` ordering IS just
+    // "TalentTab rows for the class in row order" × "Talent.dbc rows for that
+    // TabID in row order". Reading these arrays with the same walk (but an
+    // arbitrary class-mask) reproduces the engine's ordering for any class,
+    // which is how `GetTalentIDByIndex`'s optional classID arg works.
+    //
+    // Each global holds a base POINTER (deref) to the contiguous record array;
+    // the sibling +4 holds the record count. Strides match the by-ID records:
+    // TalentTab 0x3c, Talent 0x54 (TALENT_ENTRY_STRIDE).
+    //   TalentTab record: ID@+0x00, raceMask@+0x2c, classMask@+0x30
+    //   Talent record:    ID@+0x00, TabID@+0x04 (rest per the by-ID layout)
+    VAR_TALENTTAB_DBC_FLAT_RECORDS = 0x00C0D6CC,
+    VAR_TALENTTAB_DBC_FLAT_COUNT = 0x00C0D6D0,
+    TALENTTAB_ENTRY_STRIDE = 0x3c,
+    OFF_TALENTTAB_ID = 0x00,
+    OFF_TALENTTAB_CLASS_MASK = 0x30,
+    VAR_TALENT_DBC_FLAT_RECORDS = 0x00C0D6E0,
+    VAR_TALENT_DBC_FLAT_COUNT = 0x00C0D6E4,
+    OFF_TALENT_DBC_TAB_ID = 0x04,
+
     // Engine's `Script_GetTalentInfo` Lua C function. We call it from
     // `GetTalentSpellID` to derive the player's currentRank without
     // re-implementing the spell-knowledge checks at `0x0060C740` /
@@ -4896,8 +5219,27 @@ enum Offsets {
     // Auction sell slot — holds a single CGItem GUID for the item
     // currently sitting in the "sell" frame. Engine resolves it via
     // a typed object lookup; pass `OBJECT_TYPE_ITEM` and the GUID.
+    // `Script_StartAuction` posts whatever GUID is here, so writing an
+    // arbitrary bag item's GUID + calling it posts that item — no cursor,
+    // no ClickAuctionSellItemButton. Used by `AuctionHouse::PostItem`.
     VAR_AUCTION_SELL_GUID_LO = 0x00B72608,
     VAR_AUCTION_SELL_GUID_HI = 0x00B7260C,
+    // Auctioneer NPC GUID — set while an auction house window is open;
+    // `Script_StartAuction` writes it as the packet target and bails if
+    // it's zero (so this doubles as an "AH is open" probe).
+    VAR_AUCTION_AUCTIONEER_GUID_LO = 0x00B725F8,
+    VAR_AUCTION_AUCTIONEER_GUID_HI = 0x00B725FC,
+    // `Script_StartAuction` (`0x004CE770`) — `int __fastcall(void *L)`;
+    // reads (minBid, buyout, runTime) from L[1..3], validates the sell
+    // slot + auctioneer + runTime, and sends CMSG_AUCTION_SELL_ITEM
+    // (opcode 0x256 = { auctioneerGuid, sellItemGuid, bid, buyout,
+    // runTime }). Reused verbatim by `AuctionHouse::PostItem` per stack.
+    FUN_SCRIPT_START_AUCTION = 0x004CE770,
+    // Valid `runTime` values `Script_StartAuction` accepts, in minutes:
+    // {120, 480, 1440} = 2h / 8h / 24h (vanilla's three durations). The
+    // modern `duration` arg (1/2/3) indexes this table.
+    VAR_AUCTION_DURATION_TABLE = 0x00807028,
+    AUCTION_DURATION_TABLE_COUNT = 3,
     // `__fastcall(ECX = typeCode, EDX = unused, [stack] = guidLo,
     //             [stack] = guidHi, [stack] = anyInt) → CGObject *`.
     // Returns NULL when no object matches or the type doesn't match.
@@ -4996,6 +5338,12 @@ enum Offsets {
     // (form ID for shapeshift, channel index for periodic, etc.).
     OFF_SPELL_RECORD_EFFECT_APPLY_AURA_NAME = 0x16C,  // int32[3]
     OFF_SPELL_RECORD_EFFECT_MISC_VALUE = 0x1A8,       // int32[3]
+    // Per-effect SpellMechanic ids (EffectMechanic[3]). One int32[3] (0xC)
+    // after EffectBasePoints (0x130); cross-checked against EffectRadiusIndex
+    // (0x160) and EffectApplyAuraName (0x16C). Vanilla often stores a spell's
+    // mechanic on an effect rather than the spell-level Mechanic (0x14), so
+    // bleed / DoT detection needs this array in addition to that field.
+    OFF_SPELL_RECORD_EFFECT_MECHANIC = 0x13C,         // int32[3]
     SPELL_RECORD_EFFECT_COUNT = 3,
 
     // SPELL_EFFECT_* id array (`Effect[3]`) — five arrays before
@@ -5039,6 +5387,8 @@ enum Offsets {
     // sum). AttributesEx2 (+0x24) bit 0x20000000 disables spell mods.
     OFF_SPELL_RECORD_FAMILY_NAME = 0x280,             // u32
     OFF_SPELL_RECORD_FAMILY_FLAGS = 0x284,            // u64
+    OFF_SPELL_RECORD_ATTRIBUTES = 0x18,               // u32 (base Attributes)
+    SPELL_ATTR_PASSIVE = 0x40,                        // bit 6 — always-on aura
     OFF_SPELL_RECORD_ATTRIBUTES_EX2 = 0x24,           // u32
     SPELL_ATTR_EX2_NO_SPELL_MODS = 0x20000000,
 

src/auctionhouse/PostItem.cpp

@@ -0,0 +1,427 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `C_AuctionHouse.PostItem(itemLocation, duration, quantity, numStacks, bid,
+// buyout)` — post `numStacks` auctions of `quantity` each from a single
+// source stack, in one call. A ClassicAPI extension modelled on the retail
+// multi-sell flow; vanilla's `StartAuction` posts exactly one item object.
+//
+// Why this is a tick-driven state machine (not a synchronous loop):
+// vanilla's `CMSG_AUCTION_SELL_ITEM` (opcode 0x256) is
+// `{ auctioneerGuid, itemGuid, bid, buyout, runTime }` — NO count field
+// (WotLK added the server-side count; 1.12 has none, verified from
+// `Script_StartAuction`). So the server posts the *entire* item object a
+// GUID points at. To post a partial `quantity` out of a larger source, the
+// client must first materialize that quantity as its own server-committed
+// item object — i.e. split it into a bag slot (`CMSG_SPLIT_ITEM`) — and both
+// the split and the resulting post are server-authoritative and async (the
+// new stack's GUID doesn't exist client-side until `SMSG_UPDATE_OBJECT`
+// lands). We drive the split→post→split→post sequence off `WorldTick`,
+// keying each transition on observed bag state.
+//
+// Free-slot cost: a partial post needs at most ONE reused general-bag slot
+// (split `quantity` off → post that stack → the post empties the slot →
+// reuse it for the next split). The final stack (once the source is whittled
+// to exactly `quantity`) posts the source object directly, no split. Posting
+// a whole existing stack (`quantity` == the source count) needs zero free
+// slots.
+//
+// Posting reuses the engine's `Script_StartAuction` verbatim (write the
+// target stack's GUID into the sell-slot globals, push bid/buyout/runTime,
+// call it) so all of its validation runs per stack — damaged-item reject,
+// buyout normalization, runTime table check, auctioneer/"AH open" check.
+//
+// Events (retail multi-sell names, fired via Event::Custom):
+//   AUCTION_MULTISELL_START               — job accepted, posting begins
+//   AUCTION_MULTISELL_UPDATE(done, total) — after each stack lands
+//   AUCTION_MULTISELL_FAILURE             — aborted (source changed, no slot,
+//                                           AH closed, or a step timed out)
+//
+// Limitations (v1): source is the single stack at `itemLocation` (not
+// aggregated across bags); temp splits use general-purpose bags only, so
+// family-restricted items (arrows/shards in specialty bags) aren't
+// supported; one job at a time.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "event/Custom.h"
+#include "item/ID.h"
+#include "item/Location.h"
+#include "item/Swap.h"
+#include "tick/WorldTick.h"
+
+#include <cstdint>
+
+namespace AuctionHouse::PostItem {
+
+namespace {
+
+constexpr const char *kEvtStart = "AUCTION_MULTISELL_START";
+constexpr const char *kEvtUpdate = "AUCTION_MULTISELL_UPDATE";
+constexpr const char *kEvtFailure = "AUCTION_MULTISELL_FAILURE";
+const Event::Custom::AutoReserve _r1{kEvtStart};
+const Event::Custom::AutoReserve _r2{kEvtUpdate};
+const Event::Custom::AutoReserve _r3{kEvtFailure};
+
+// Generous per-step abort bound. A split or a post is one server round-trip
+// (~tens of frames); 600 frames (~10s at 60fps) means "something's wrong"
+// (disconnect, server refusal we can't see) rather than normal latency.
+constexpr int kMaxWaitTicks = 600;
+
+enum class Phase { Idle, SplitWait, PostWait };
+
+struct Job {
+    bool active;
+    int srcBag, srcSlot; // source stack (shrinks in place as we split off it)
+    int itemID;          // guards against the source slot changing under us
+    int quantity;
+    int totalStacks;
+    int postedStacks;
+    int bid, buyout, runTime;
+    Phase phase;
+    int workBag, workSlot; // slot currently being split-into / posted-from
+    uint64_t postGuid;     // GUID we posted — detect it leaving bags
+    int waitTicks;
+};
+Job g_job{};
+
+// --- small CGItem / cache readers ---------------------------------------
+
+using GetItemRecord_t = const uint8_t *(__thiscall *)(void *cache, uint32_t itemID,
+                                                      const uint64_t *guid, void *callback,
+                                                      void *userData, int unused);
+const uint8_t *PeekItemRecord(uint32_t itemID) {
+    auto fn = reinterpret_cast<GetItemRecord_t>(Offsets::FUN_DBCACHE_ITEMSTATS_GET_RECORD);
+    auto *cache = reinterpret_cast<void *>(Offsets::VAR_ITEMDB_CACHE);
+    const uint64_t zeroGuid = 0;
+    return fn(cache, itemID, &zeroGuid, nullptr, nullptr, 0);
+}
+
+int CGItemCount(const uint8_t *item) {
+    auto *desc = *reinterpret_cast<const uint8_t *const *>(
+        item + Offsets::OFF_ITEM_DESCRIPTOR);
+    if (desc == nullptr)
+        return 0;
+    return *reinterpret_cast<const int *>(desc + Offsets::OFF_DESCRIPTOR_STACK_COUNT);
+}
+
+uint64_t CGItemGuid(const uint8_t *item) {
+    auto *inst = *reinterpret_cast<const uint8_t *const *>(
+        item + Offsets::OFF_ITEM_INSTANCE_BLOCK);
+    if (inst == nullptr)
+        return 0;
+    return *reinterpret_cast<const uint64_t *>(inst + Offsets::OFF_INSTANCE_BLOCK_GUID);
+}
+
+struct SlotInfo {
+    const uint8_t *item; // null = empty slot
+    int itemID;
+    int count;
+    uint64_t guid;
+};
+
+SlotInfo ReadSlot(void *L, int bag, int slot) {
+    SlotInfo r{nullptr, 0, 0, 0};
+    const uint8_t *item = Item::Location::ResolveBag(L, bag, slot);
+    if (item == nullptr)
+        return r;
+    r.item = item;
+    r.itemID = Item::ID::FromCGItem(item);
+    r.count = CGItemCount(item);
+    r.guid = CGItemGuid(item);
+    return r;
+}
+
+// --- auction-house globals ----------------------------------------------
+
+uint64_t AuctioneerGuid() {
+    const uint32_t lo = *reinterpret_cast<const uint32_t *>(
+        Offsets::VAR_AUCTION_AUCTIONEER_GUID_LO);
+    const uint32_t hi = *reinterpret_cast<const uint32_t *>(
+        Offsets::VAR_AUCTION_AUCTIONEER_GUID_HI);
+    return (static_cast<uint64_t>(hi) << 32) | lo;
+}
+bool AHOpen() { return AuctioneerGuid() != 0; }
+
+void SetSellGuid(uint64_t guid) {
+    *reinterpret_cast<uint32_t *>(Offsets::VAR_AUCTION_SELL_GUID_LO) =
+        static_cast<uint32_t>(guid);
+    *reinterpret_cast<uint32_t *>(Offsets::VAR_AUCTION_SELL_GUID_HI) =
+        static_cast<uint32_t>(guid >> 32);
+}
+
+// Point the sell slot at `guid` and fire the engine's own StartAuction for
+// this bid/buyout/runTime. StartAuction reads its args from L[1..3]; we own
+// the stack at frame-tail, so set top to 0, push the three, call, reset.
+void PostStack(void *L, uint64_t guid) {
+    SetSellGuid(guid);
+    Game::Lua::SetTop(L, 0);
+    Game::Lua::PushNumber(L, static_cast<double>(g_job.bid));
+    Game::Lua::PushNumber(L, static_cast<double>(g_job.buyout));
+    Game::Lua::PushNumber(L, static_cast<double>(g_job.runTime));
+    auto fn = reinterpret_cast<Game::Lua::CFunction>(Offsets::FUN_SCRIPT_START_AUCTION);
+    fn(L);
+    Game::Lua::SetTop(L, 0);
+}
+
+// --- free-slot discovery (general-purpose bags only) --------------------
+
+bool BagIsGeneral(int bag) {
+    if (bag == 0)
+        return true; // backpack is always general
+    if (bag < 1 || bag > 4)
+        return false;
+    const uint8_t *bagItem =
+        Item::Location::ResolveEquipmentSlot(Offsets::INVSLOT_BAG1 + bag - 1);
+    if (bagItem == nullptr)
+        return false; // no bag equipped there
+    const int id = Item::ID::FromCGItem(bagItem);
+    if (id == 0)
+        return false;
+    const uint8_t *rec = PeekItemRecord(static_cast<uint32_t>(id));
+    if (rec == nullptr)
+        return false;
+    return *reinterpret_cast<const uint32_t *>(
+               rec + Offsets::OFF_ITEMSTATS_BAG_FAMILY) == 0;
+}
+
+bool FindFreeGeneralSlot(void *L, int *outBag, int *outSlot) {
+    for (int bag = 0; bag <= 4; ++bag) {
+        if (!BagIsGeneral(bag))
+            continue;
+        const int n = Item::Location::GetBagSlotCount(bag);
+        for (int slot = 1; slot <= n; ++slot) {
+            if (Item::Location::ResolveBag(L, bag, slot) == nullptr) {
+                *outBag = bag;
+                *outSlot = slot;
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+// --- state machine ------------------------------------------------------
+
+void Finish(bool success) {
+    g_job.active = false;
+    if (!success)
+        Event::Custom::Fire(Event::Custom::Lookup(kEvtFailure), "");
+    // success needs no event: the last PostWait already fired
+    // AUCTION_MULTISELL_UPDATE(total, total).
+}
+
+void Tick() {
+    if (!g_job.active)
+        return;
+    void *L = Game::Lua::State();
+    if (L == nullptr)
+        return;
+    const int savedTop = Game::Lua::GetTop(L);
+
+    if (!AHOpen()) { // window closed / walked away mid-job
+        Finish(false);
+        Game::Lua::SetTop(L, savedTop);
+        return;
+    }
+
+    switch (g_job.phase) {
+    case Phase::Idle: {
+        if (g_job.postedStacks >= g_job.totalStacks) {
+            Finish(true);
+            break;
+        }
+        const SlotInfo s = ReadSlot(L, g_job.srcBag, g_job.srcSlot);
+        if (s.item == nullptr || s.itemID != g_job.itemID || s.count < g_job.quantity) {
+            Finish(false); // source moved / consumed / insufficient
+            break;
+        }
+        if (s.count == g_job.quantity) {
+            // Final exact stack — post the source object directly, no split.
+            g_job.workBag = g_job.srcBag;
+            g_job.workSlot = g_job.srcSlot;
+            g_job.postGuid = s.guid;
+            PostStack(L, s.guid);
+            g_job.phase = Phase::PostWait;
+            g_job.waitTicks = 0;
+        } else {
+            int fb = 0, fs = 0;
+            if (!FindFreeGeneralSlot(L, &fb, &fs)) {
+                Finish(false); // no room to materialize the stack
+                break;
+            }
+            if (!Item::Swap::MoveCount(L, g_job.srcBag, g_job.srcSlot, fb, fs,
+                                       g_job.quantity)) {
+                Finish(false);
+                break;
+            }
+            g_job.workBag = fb;
+            g_job.workSlot = fs;
+            g_job.phase = Phase::SplitWait;
+            g_job.waitTicks = 0;
+        }
+        break;
+    }
+    case Phase::SplitWait: {
+        const SlotInfo w = ReadSlot(L, g_job.workBag, g_job.workSlot);
+        if (w.item != nullptr && w.itemID == g_job.itemID && w.count == g_job.quantity) {
+            g_job.postGuid = w.guid;
+            PostStack(L, w.guid);
+            g_job.phase = Phase::PostWait;
+            g_job.waitTicks = 0;
+        } else if (++g_job.waitTicks > kMaxWaitTicks) {
+            Finish(false);
+        }
+        break;
+    }
+    case Phase::PostWait: {
+        const SlotInfo w = ReadSlot(L, g_job.workBag, g_job.workSlot);
+        // Post confirmed once the server pulls the item out of the slot.
+        if (w.item == nullptr || w.guid != g_job.postGuid) {
+            ++g_job.postedStacks;
+            Event::Custom::Fire(Event::Custom::Lookup(kEvtUpdate), "%d%d",
+                                g_job.postedStacks, g_job.totalStacks);
+            g_job.phase = Phase::Idle;
+            g_job.waitTicks = 0;
+        } else if (++g_job.waitTicks > kMaxWaitTicks) {
+            Finish(false);
+        }
+        break;
+    }
+    }
+
+    Game::Lua::SetTop(L, savedTop);
+}
+
+const Tick::WorldTick::AutoSubscribe _tick{&Tick};
+
+// --- Lua entry ----------------------------------------------------------
+
+// Reads `loc.field` as an int. False if missing/non-numeric. Leaves the
+// stack as found. (Same shape as Item::Location's file-static helper.)
+bool ReadIntField(void *L, int locIdx, const char *field, int *out) {
+    Game::Lua::PushString(L, field);
+    Game::Lua::GetTable(L, locIdx);
+    const bool ok = Game::Lua::IsNumber(L, -1);
+    if (ok)
+        *out = static_cast<int>(Game::Lua::ToNumber(L, -1));
+    Game::Lua::SetTop(L, -2);
+    return ok;
+}
+
+// Map the modern `duration` arg to a valid engine runTime (minutes).
+// Accepts the 1/2/3 index form and the raw {120,480,1440} value form.
+// Returns 0 for anything else.
+int MapDuration(int d) {
+    auto *table = reinterpret_cast<const uint32_t *>(Offsets::VAR_AUCTION_DURATION_TABLE);
+    if (d >= 1 && d <= Offsets::AUCTION_DURATION_TABLE_COUNT)
+        return static_cast<int>(table[d - 1]);
+    for (int i = 0; i < Offsets::AUCTION_DURATION_TABLE_COUNT; ++i)
+        if (static_cast<int>(table[i]) == d)
+            return d;
+    return 0;
+}
+
+// Push (false, reason) and return 2 — the immediate-rejection shape.
+int Reject(void *L, const char *reason) {
+    Game::Lua::PushBool(L, false);
+    Game::Lua::PushString(L, reason);
+    return 2;
+}
+
+constexpr int kLuaTable = 5; // LUA_TTABLE (no named constant in Game::Lua)
+
+int __fastcall Script_C_AuctionHouse_PostItem(void *L) {
+    if (Game::Lua::Type(L, 1) != kLuaTable) {
+        Game::Lua::Error(L,
+            "Usage: C_AuctionHouse.PostItem(itemLocation, duration, quantity, numStacks, bid, buyout)");
+        return 0;
+    }
+    if (!Game::Lua::IsNumber(L, 2) || !Game::Lua::IsNumber(L, 3) ||
+        !Game::Lua::IsNumber(L, 4) || !Game::Lua::IsNumber(L, 5)) {
+        Game::Lua::Error(L,
+            "Usage: C_AuctionHouse.PostItem(itemLocation, duration, quantity, numStacks, bid, buyout)");
+        return 0;
+    }
+
+    int bagID = 0, slotIndex = 0;
+    if (!ReadIntField(L, 1, "bagID", &bagID) ||
+        !ReadIntField(L, 1, "slotIndex", &slotIndex))
+        return Reject(L, "itemLocation must be a { bagID, slotIndex } table");
+
+    const int duration = static_cast<int>(Game::Lua::ToNumber(L, 2));
+    const int quantity = static_cast<int>(Game::Lua::ToNumber(L, 3));
+    const int numStacks = static_cast<int>(Game::Lua::ToNumber(L, 4));
+    const int bid = static_cast<int>(Game::Lua::ToNumber(L, 5));
+    const int buyout = Game::Lua::IsNumber(L, 6) ? static_cast<int>(Game::Lua::ToNumber(L, 6)) : 0;
+
+    const int runTime = MapDuration(duration);
+    if (runTime == 0)
+        return Reject(L, "invalid duration (use 1/2/3 or 120/480/1440)");
+    if (quantity < 1 || quantity > 255)
+        return Reject(L, "quantity must be 1..255");
+    if (numStacks < 1)
+        return Reject(L, "numStacks must be >= 1");
+    if (bid < 1)
+        return Reject(L, "bid must be >= 1");
+
+    if (!AHOpen())
+        return Reject(L, "auction house is not open");
+    if (g_job.active)
+        return Reject(L, "a multi-post is already in progress");
+
+    const SlotInfo s = ReadSlot(L, bagID, slotIndex);
+    if (s.item == nullptr)
+        return Reject(L, "source slot is empty");
+
+    const long need = static_cast<long>(quantity) * numStacks;
+    if (static_cast<long>(s.count) < need)
+        return Reject(L, "not enough items for numStacks x quantity");
+
+    // A partial post (source larger than one stack) needs one reusable
+    // general-bag slot to materialize each split. A whole-stack post
+    // (count == quantity, numStacks == 1) needs none.
+    if (s.count > quantity) {
+        int fb = 0, fs = 0;
+        if (!FindFreeGeneralSlot(L, &fb, &fs))
+            return Reject(L, "need at least one free general bag slot to split");
+    }
+
+    g_job = Job{};
+    g_job.active = true;
+    g_job.srcBag = bagID;
+    g_job.srcSlot = slotIndex;
+    g_job.itemID = s.itemID;
+    g_job.quantity = quantity;
+    g_job.totalStacks = numStacks;
+    g_job.postedStacks = 0;
+    g_job.bid = bid;
+    g_job.buyout = buyout;
+    g_job.runTime = runTime;
+    g_job.phase = Phase::Idle;
+
+    Event::Custom::Fire(Event::Custom::Lookup(kEvtStart), "");
+    Game::Lua::PushBool(L, true);
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_AuctionHouse", "PostItem",
+                                     &Script_C_AuctionHouse_PostItem);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace AuctionHouse::PostItem

src/aura/Api.cpp

@@ -29,6 +29,7 @@
 #include "Game.h"
 #include "Offsets.h"
 #include "ui/ColorData.h"
+#include "unit/Identity.h"
 
 #include <cstdint>
 #include <cstring>
@@ -47,6 +48,18 @@ const uint8_t *ResolveUnit(const char *token) {
     return static_cast<const uint8_t *>(fn(token));
 }
 
+// Resolves a token to its GUID for the out-of-range (no live CGUnit) path.
+// Only valid to call AFTER `ResolveUnit(token)` returned null *without raising*:
+// `ResolveUnit` runs the engine's token→GUID resolver first, so reaching a null
+// return means the token was well-formed (the resolver never raised). This runs
+// the same non-raising resolver and returns 0 for a token that maps to no
+// rostered member — which the group-array push paths treat as "no auras".
+uint64_t GuidForOutOfRange(const char *token) {
+    if (token == nullptr)
+        return 0;
+    return Unit::Identity::GuidForToken(token);
+}
+
 // Parses the filter string. Returns Helpful by default; Harmful if
 // the string contains the substring "HARMFUL". Case-sensitive — the
 // modern API documents the filter tokens as upper-case constants
@@ -91,16 +104,25 @@ const char *ArgOptString(void *L, int idx) {
 int PushAuraByIndex(void *L, const char *unitToken, int index,
                     Data::Filter filter, bool playerOnly = false) {
     const uint8_t *unit = ResolveUnit(unitToken);
-    const int slot = Data::FindNthSlot(unit, index, filter, playerOnly);
-    if (slot >= 0) {
-        Data::Push(L, unit, slot);
-        return 1;
+    if (unit != nullptr) {
+        const int slot = Data::FindNthSlot(unit, index, filter, playerOnly);
+        if (slot >= 0) {
+            Data::Push(L, unit, slot);
+            return 1;
+        }
+        // Descriptor exhausted — an aura the engine dropped from the slot array
+        // (rogue stealth, nearby party range fluctuation) may still be live in
+        // the Aura::Source cache. Surface it after the descriptor entries.
+        if (Data::PushNthCacheFallback(L, unit, index, filter, playerOnly))
+            return 1;
+    } else {
+        // No live CGUnit — an out-of-range / cross-map groupmate. The server
+        // still sends their aura spell IDs via SMSG_PARTY_MEMBER_STATS; read
+        // them the same way the built-in UnitBuff/UnitDebuff do.
+        if (Data::PushNthGroupAura(L, GuidForOutOfRange(unitToken), index,
+                                   filter, playerOnly))
+            return 1;
     }
-    // Descriptor exhausted — an aura the engine dropped from the slot array
-    // (rogue stealth, party range fluctuation) may still be live in the
-    // Aura::Source cache. Surface it after the descriptor entries.
-    if (Data::PushNthCacheFallback(L, unit, index, filter, playerOnly))
-        return 1;
     Game::Lua::PushNil(L);
     return 1;
 }
@@ -152,13 +174,21 @@ int __fastcall Script_GetUnitAuraBySpellID(void *L) {
         f = ParseFilter(filterStr);
         fp = &f;
     }
-    const int slot = Data::FindSlotBySpellID(unit, static_cast<uint32_t>(spellID),
-                                             fp, HasPlayerFilter(filterStr));
-    if (slot < 0) {
-        Game::Lua::PushNil(L);
+    const bool playerOnly = HasPlayerFilter(filterStr);
+    if (unit != nullptr) {
+        const int slot = Data::FindSlotBySpellID(
+            unit, static_cast<uint32_t>(spellID), fp, playerOnly);
+        if (slot >= 0) {
+            Data::Push(L, unit, slot);
+            return 1;
+        }
+    } else if (Data::PushGroupAuraBySpellID(L, GuidForOutOfRange(unitToken),
+                                            static_cast<uint32_t>(spellID), fp,
+                                            playerOnly)) {
+        // Out-of-range groupmate — read from the group-member aura array.
         return 1;
     }
-    Data::Push(L, unit, slot);
+    Game::Lua::PushNil(L);
     return 1;
 }
 
@@ -177,13 +207,19 @@ int __fastcall Script_GetAuraDataBySpellName(void *L) {
         f = ParseFilter(filterStr);
         fp = &f;
     }
-    const int slot = Data::FindSlotBySpellName(unit, spellName, fp,
-                                               HasPlayerFilter(filterStr));
-    if (slot < 0) {
-        Game::Lua::PushNil(L);
+    const bool playerOnly = HasPlayerFilter(filterStr);
+    if (unit != nullptr) {
+        const int slot = Data::FindSlotBySpellName(unit, spellName, fp, playerOnly);
+        if (slot >= 0) {
+            Data::Push(L, unit, slot);
+            return 1;
+        }
+    } else if (Data::PushGroupAuraBySpellName(L, GuidForOutOfRange(unitToken),
+                                              spellName, fp, playerOnly)) {
+        // Out-of-range groupmate — read from the group-member aura array.
         return 1;
     }
-    Data::Push(L, unit, slot);
+    Game::Lua::PushNil(L);
     return 1;
 }
 
@@ -234,8 +270,6 @@ int __fastcall Script_GetUnitAuras(void *L) {
 
     Game::Lua::SetTop(L, 0);
     Game::Lua::NewTable(L);
-    if (unit == nullptr)
-        return 1;
 
     // Range tokens are independent of PLAYER: an explicit HELPFUL/HARMFUL
     // selects that range, neither selects both. So `"PLAYER"` alone returns
@@ -246,10 +280,21 @@ int __fastcall Script_GetUnitAuras(void *L) {
     const bool both = !hasHelpful && !hasHarmful;
 
     int nextKey = 1;
-    if (hasHelpful || both)
-        AppendRangeToArray(L, unit, 1, Data::Filter::Helpful, nextKey, playerOnly);
-    if (hasHarmful || both)
-        AppendRangeToArray(L, unit, 1, Data::Filter::Harmful, nextKey, playerOnly);
+    if (unit != nullptr) {
+        if (hasHelpful || both)
+            AppendRangeToArray(L, unit, 1, Data::Filter::Helpful, nextKey, playerOnly);
+        if (hasHarmful || both)
+            AppendRangeToArray(L, unit, 1, Data::Filter::Harmful, nextKey, playerOnly);
+    } else {
+        // No live CGUnit — out-of-range / cross-map groupmate. Enumerate the
+        // group-member aura array (spell IDs the server still transmits), the
+        // same source the built-in UnitBuff/UnitDebuff read out of range.
+        const uint64_t guid = GuidForOutOfRange(unitToken);
+        if (hasHelpful || both)
+            Data::AppendGroupAuras(L, guid, Data::Filter::Helpful, playerOnly, 1, nextKey);
+        if (hasHarmful || both)
+            Data::AppendGroupAuras(L, guid, Data::Filter::Harmful, playerOnly, 1, nextKey);
+    }
     return 1;
 }
 

src/aura/ComboDuration.cpp

@@ -132,30 +132,19 @@ const Override *FindOverride(uint32_t spellId) {
     return nullptr;
 }
 
-// Known values for spells whose duration row DANGLES — a non-zero
-// DurationIndex pointing at a SpellDuration row the client doesn't have.
-// Consulted ONLY when that exact condition holds, so the gate is the bug
-// itself, not a server fingerprint: on a stock client every one of these
-// resolves to a valid row and this table is never reached, and if the
-// broken client data is ever fixed the DBC row takes over automatically.
-//
-// Turtle's reworked Rip is the known case: all six ranks point at
-// SpellDuration row 87, which Turtle added on the SERVER only
-// ({8000, 0, 18000} — live server data shows 10/12/14/16/18s at 1..5 CP,
-// i.e. 8s + 2s per combo point); their client patch never shipped the
-// row (the client table jumps 86 -> 105). Verified the only dangling
-// duration index in the entire client Spell.dbc.
-constexpr Override kDanglingRowKnown[] = {
-    {1079, 8000, 18000}, {9492, 8000, 18000}, {9493, 8000, 18000},
-    {9752, 8000, 18000}, {9894, 8000, 18000}, {9896, 8000, 18000},
-};
+// Resolver chain for dangling-duration-row spells (client DBC missing the
+// row). The KNOWN VALUES themselves are server-custom data and live in
+// their own module (e.g. `src/turtle/ComboDuration.cpp` for Turtle's
+// reworked Rip); this stock module only owns the mechanism and the
+// dangling-condition gate. Chained at static-init by `AutoDanglingResolver`.
+AutoDanglingResolver *g_danglingResolvers = nullptr;
 
-const Override *FindDanglingRowKnown(uint32_t spellId) {
-    for (const auto &k : kDanglingRowKnown) {
-        if (k.spellId == spellId)
-            return &k;
-    }
-    return nullptr;
+bool ResolveDangling(uint32_t spellId, int32_t *baseMs, int32_t *maxMs) {
+    for (AutoDanglingResolver *r = g_danglingResolvers; r != nullptr;
+         r = r->next)
+        if (r->fn(spellId, baseMs, maxMs))
+            return true;
+    return false;
 }
 
 // `C_UnitAuras.RegisterComboDuration(spellID, baseSeconds, maxSeconds)`
@@ -203,6 +192,11 @@ const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
 
 } // namespace
 
+AutoDanglingResolver::AutoDanglingResolver(DanglingResolver f)
+    : fn(f), next(g_danglingResolvers) {
+    g_danglingResolvers = this;
+}
+
 uint32_t TryComboScaledMs(const uint8_t *spellRecord, uint32_t spellId) {
     if (spellRecord == nullptr || spellId == 0)
         return 0;
@@ -227,12 +221,11 @@ uint32_t TryComboScaledMs(const uint8_t *spellRecord, uint32_t spellId) {
             maxMs = *reinterpret_cast<const int32_t *>(row + 0xC);
         } else if (idx != 0) {
             // Dangling duration index — the client data is broken for this
-            // spell. Fall back to the built-in known values (Turtle Rip).
-            const Override *k = FindDanglingRowKnown(spellId);
-            if (k == nullptr)
+            // spell. Defer to a registered resolver (the known values are
+            // server-custom data owned by a platform module, e.g.
+            // src/turtle for Turtle's reworked Rip).
+            if (!ResolveDangling(spellId, &baseMs, &maxMs))
                 return 0;
-            baseMs = k->baseMs;
-            maxMs = k->maxMs;
         } else {
             return 0; // no duration row at all
         }

src/aura/ComboDuration.h

@@ -47,4 +47,22 @@ namespace Aura::ComboDuration {
 // duration path".
 uint32_t TryComboScaledMs(const uint8_t *spellRecord, uint32_t spellId);
 
+// Extension point for finishers whose SpellDuration row DANGLES — a
+// non-zero DurationIndex pointing at a row the client DBC doesn't have.
+// A resolver returns true and fills *baseMs/*maxMs if it knows the spell,
+// false otherwise. Consulted by `TryComboScaledMs` ONLY in that dangling
+// condition (after any Lua-registered override), so the activation gate is
+// the client-data bug itself, not a server fingerprint — the deliberate
+// design choice (a realm-sniffing approach was rejected). Server-custom
+// data (e.g. Turtle's reworked Rip) registers its values here instead of
+// living in this stock module: declare a file-scope
+// `static const Aura::ComboDuration::AutoDanglingResolver`.
+using DanglingResolver = bool (*)(uint32_t spellId, int32_t *baseMs,
+                                  int32_t *maxMs);
+struct AutoDanglingResolver {
+    explicit AutoDanglingResolver(DanglingResolver fn);
+    DanglingResolver fn;
+    AutoDanglingResolver *next;
+};
+
 } // namespace Aura::ComboDuration

src/aura/Data.cpp

@@ -17,6 +17,7 @@
 #include "Offsets.h"
 #include "aura/Source.h"
 #include "dbc/Lookup.h"
+#include "group/MemberStats.h"
 #include "guid/Guid.h"
 #include "unit/Identity.h"
 
@@ -139,6 +140,22 @@ double PlayerBuffExpirationSeconds(const uint8_t *entry) {
     const uint32_t expirationMs = expirationTable[slotCode];
     if (expirationMs == 0)
         return 0.0;
+    // Report "no timer" once the stored expiration has elapsed — this is not a
+    // heuristic, it's exactly what the engine's own GetPlayerBuffTimeLeft does.
+    // Script_GetPlayerBuffTimeLeft (0x004e4930) → FUN_004e4450 reads this same
+    // expiration table and returns:
+    //     if ((int)(now - expiration[slot]) >= 0) return 0;  // elapsed -> 0
+    //     return expiration[slot] - now;                      // else remaining
+    // Permanent auras (paladin auras, passives, racials) carry an infinite
+    // Spell.dbc duration (SpellDuration base -1); the server stores the fixed
+    // cast-time in this slot for them, so it's always "already elapsed" and the
+    // engine shows no countdown. The signed `(int)` compare also absorbs the
+    // ~24.86-day GetTickCount wrap (both operands wrap together).
+    using TickCount_t = uint32_t(__fastcall *)();
+    const uint32_t nowMs = reinterpret_cast<TickCount_t>(
+        static_cast<uintptr_t>(Offsets::FUN_OS_TICKCOUNT_MS))();
+    if (static_cast<int32_t>(nowMs - expirationMs) >= 0)
+        return 0.0; // expiration reached/passed → permanent or no timer
     return static_cast<double>(expirationMs) * 0.001;
 }
 
@@ -419,46 +436,39 @@ static void BuildTable(void *L, uint32_t spellID, int applications,
     // yields nil, so the table doesn't need an explicit entry.
 }
 
-void Push(void *L, const uint8_t *unit, int slot) {
-    const uint32_t spellID = ReadSpellID(unit, slot);
-    const bool isHelpful = slot < Offsets::UNIT_AURA_BUFF_COUNT;
-
-    // Timing fields. Vanilla doesn't broadcast cast time / duration for ANY
-    // unit's auras except the local player's — for everyone else (target,
-    // party, raid, mouseover) `expirationTime` stays 0 unless the
-    // `Aura::Source` cache observed the cast. For the player we read the
-    // engine's `VAR_PLAYER_BUFF_TABLE` (same data `GetPlayerBuffTimeLeft`
-    // returns), which gives a real expiration timestamp.
-    //
-    // `duration` comes from Spell.dbc → SpellDuration.dbc with level scaling
-    // (the *base* value); talent / glyph duration-extension modifiers are
-    // already baked into the expiration timestamp on the caster's side, so
-    // `expirationTime - GetTime()` reflects true remaining time even when the
-    // base `duration` doesn't include the talent boost.
+// Enriches a bare `(guid, spellID)` into a full AuraData table — the shared
+// core behind every push path (descriptor, cache fallback, group-array). No
+// dependence on a live descriptor: the descriptor path passes what it read
+// (stacks, level, is-this-the-player), the others pass their known-or-default
+// values.
+//
+// Timing rules (identical across paths): `duration` is the Spell.dbc →
+// SpellDuration.dbc base scaled by `unitLevel` (0 skips scaling); talent/glyph
+// duration modifiers are baked into the caster-side expiration, so
+// `expirationTime - GetTime()` is the true remaining time even when `duration`
+// omits the boost. `expirationTime` for the local player comes from the engine
+// buff table (gated on `isPlayer`); for everyone else it, the caster, and the
+// applied (caster-modified) duration come from the `Aura::Source` SMSG_SPELL_GO
+// cache when it observed the cast — a miss leaves the modern-truthful defaults
+// (expiration 0, no sourceUnit/GUID).
+static void PushEnriched(void *L, uint64_t guid, uint32_t spellID,
+                         bool isHelpful, int applications, int unitLevel,
+                         bool isPlayer) {
     double duration = 0.0;
     double expirationTime = 0.0;
     uint64_t casterGuid = 0;
-    const uint8_t *player = LocalPlayer();
-    if (spellID != 0) {
-        const int unitLevel = (unit != nullptr) ? PlayerLevel(unit) : 0;
+    if (spellID != 0)
         duration = SpellBaseDurationSeconds(spellID, unitLevel);
-    }
-    if (unit != nullptr && unit == player) {
+    if (isPlayer && spellID != 0) {
         const uint8_t *entry = FindPlayerBuffEntry(spellID);
         if (entry != nullptr)
             expirationTime = PlayerBuffExpirationSeconds(entry);
     }
-    // Caster + non-player expiration from the SMSG_SPELL_GO cache, captured at
-    // cast time (the descriptor has neither). The player-buff table above is
-    // authoritative for the player's own expiration; the cache fills it for
-    // everyone else. Prefer the applied (caster-modified) duration so it stays
-    // consistent with `expirationTime` — otherwise a talented DoT (Improved
-    // Shadow Word: Pain) would show remaining time exceeding the base.
-    if (spellID != 0) {
+    if (spellID != 0 && guid != 0) {
         uint64_t c = 0;
         uint32_t expMs = 0;
         uint32_t durMs = 0;
-        if (Aura::Source::Get(UnitGuid(unit), spellID, &c, &expMs, &durMs)) {
+        if (Aura::Source::Get(guid, spellID, &c, &expMs, &durMs)) {
             if (expirationTime == 0.0 && expMs != 0)
                 expirationTime = static_cast<double>(expMs) * 0.001;
             if (durMs != 0)
@@ -466,9 +476,16 @@ void Push(void *L, const uint8_t *unit, int slot) {
             casterGuid = c;
         }
     }
+    BuildTable(L, spellID, applications, isHelpful, duration, expirationTime,
+               casterGuid);
+}
 
-    BuildTable(L, spellID, ReadStacks(unit, slot), isHelpful, duration,
-               expirationTime, casterGuid);
+void Push(void *L, const uint8_t *unit, int slot) {
+    const uint32_t spellID = ReadSpellID(unit, slot);
+    const bool isHelpful = slot < Offsets::UNIT_AURA_BUFF_COUNT;
+    const int unitLevel = (unit != nullptr) ? PlayerLevel(unit) : 0;
+    PushEnriched(L, UnitGuid(unit), spellID, isHelpful, ReadStacks(unit, slot),
+                 unitLevel, unit != nullptr && unit == LocalPlayer());
 }
 
 namespace {
@@ -479,17 +496,12 @@ namespace {
 // applied (caster-modified) ms when known, else the Spell.dbc base.
 void PushFromCache(void *L, const uint8_t *unit,
                    const Aura::Source::CachedAura &c, bool isHelpful) {
-    double duration = 0.0;
-    if (c.durationMs != 0) {
-        duration = static_cast<double>(c.durationMs) * 0.001;
-    } else {
-        const int unitLevel = (unit != nullptr) ? PlayerLevel(unit) : 0;
-        duration = SpellBaseDurationSeconds(c.spellId, unitLevel);
-    }
-    const double expirationTime =
-        (c.expirationMs != 0) ? static_cast<double>(c.expirationMs) * 0.001 : 0.0;
-    BuildTable(L, c.spellId, 1, isHelpful, duration, expirationTime,
-               c.casterGuid);
+    // `PushEnriched` re-reads the same cache entry `c` came from (by
+    // guid+spellID) to fill caster / expiration / applied duration, so the
+    // result is identical to reading `c`'s fields directly. Stacks aren't in
+    // SMSG_SPELL_GO, so `applications` is 1.
+    const int unitLevel = (unit != nullptr) ? PlayerLevel(unit) : 0;
+    PushEnriched(L, UnitGuid(unit), c.spellId, isHelpful, 1, unitLevel, false);
 }
 
 // Reconciles the `Aura::Source` cache against `unit`'s descriptor: when the
@@ -633,4 +645,280 @@ void AppendCacheFallbacks(void *L, const uint8_t *unit, Filter filter,
     }
 }
 
+// ── Out-of-range groupmate path ────────────────────────────────────────────
+
+namespace {
+
+// Absolute slot range [start, end) for a filter, matching the descriptor
+// convention (helpful 0..31, harmful 32..47).
+void GroupRange(Filter filter, int &start, int &end) {
+    start = (filter == Filter::Harmful) ? Offsets::UNIT_AURA_BUFF_COUNT : 0;
+    end = (filter == Filter::Harmful) ? Offsets::UNIT_AURA_TOTAL
+                                      : Offsets::UNIT_AURA_BUFF_COUNT;
+}
+
+// Spell ID at group-array slot (0..47), 0 if `arr` null / OOB / empty.
+uint32_t GroupSpellID(const uint16_t *arr, int slot) {
+    if (arr == nullptr || slot < 0 || slot >= Offsets::UNIT_AURA_TOTAL)
+        return 0;
+    return arr[slot];
+}
+
+// Whether the group-array slot holds a surfacable aura for this query. Mirrors
+// the engine's per-slot test in Script_UnitBuff/UnitDebuff — a non-zero spell
+// ID with a real Spell.dbc record that passes the visibility predicate (the
+// server only transmits *applied* auras, so there is no flag nibble to check).
+// `playerOnly` additionally requires the `Aura::Source` cache to attribute the
+// cast to the local player (a miss excludes it — we can't confirm the caster
+// from the group array alone).
+bool GroupSlotEligible(uint64_t guid, const uint16_t *arr, int slot,
+                       bool playerOnly) {
+    const uint32_t id = GroupSpellID(arr, slot);
+    if (id == 0 || !IsVisible(SpellRecord(id)))
+        return false;
+    if (playerOnly) {
+        uint64_t c = 0;
+        uint32_t e = 0;
+        uint32_t d = 0;
+        if (!Aura::Source::Get(guid, id, &c, &e, &d) ||
+            c != Unit::Identity::PlayerGuid())
+            return false;
+    }
+    return true;
+}
+
+// The groupmate's level, for Spell.dbc duration scaling (0 = skip). Cheap
+// roster lookup; only hit on the out-of-range path.
+int GroupMemberLevel(uint64_t guid) {
+    return Group::MemberStats::Lookup(guid).level;
+}
+
+// True if the group array exposes ANY visible aura (either kind). When it
+// does, the server's out-of-range aura data is present and authoritative, so
+// we do NOT supplement from the Aura::Source cache — mirroring how the
+// descriptor path treats a populated descriptor (DescriptorHasVisibleAura).
+// Only when the array is entirely empty do we fall back to the cache: the
+// server resends out-of-range stats as deltas only, so a member seen in range
+// and then moved away again leaves an empty party-stats aura array (the array
+// is cleared when they become visible and never re-sent), yet their auras
+// still sit in the cache from when we observed them in range.
+bool GroupArrayHasVisibleAura(const uint16_t *arr) {
+    for (int slot = 0; slot < Offsets::UNIT_AURA_TOTAL; ++slot) {
+        const uint32_t id = GroupSpellID(arr, slot);
+        if (id != 0 && IsVisible(SpellRecord(id)))
+            return true;
+    }
+    return false;
+}
+
+// Whether cache entry `c` may supplement the (empty) group array: a visible
+// aura, not already present in the array, and — when player-filtered — cast by
+// us. See GroupArrayHasVisibleAura for when this path runs.
+bool GroupFallbackEligible(const uint16_t *arr, const Aura::Source::CachedAura &c,
+                           bool playerOnly) {
+    if (!IsVisible(SpellRecord(c.spellId)))
+        return false;
+    for (int slot = 0; slot < Offsets::UNIT_AURA_TOTAL; ++slot)
+        if (GroupSpellID(arr, slot) == c.spellId)
+            return false;
+    if (playerOnly && c.casterGuid != Unit::Identity::PlayerGuid())
+        return false;
+    return true;
+}
+
+// Nth (1-based) cache-fallback aura of `filter`'s kind for an out-of-range
+// member whose group array is empty. Pushes the AuraData table on a hit.
+bool PushNthGroupCacheFallback(void *L, uint64_t guid, const uint16_t *arr,
+                               int oneBasedIndex, Filter filter, bool playerOnly) {
+    Aura::Source::CachedAura buf[kFallbackMax];
+    const int n =
+        Aura::Source::Enumerate(guid, filter == Filter::Harmful, buf, kFallbackMax);
+    int seen = 0;
+    for (int i = 0; i < n; ++i) {
+        if (!GroupFallbackEligible(arr, buf[i], playerOnly))
+            continue;
+        if (++seen == oneBasedIndex) {
+            PushEnriched(L, guid, buf[i].spellId, filter == Filter::Helpful, 1,
+                         GroupMemberLevel(guid), false);
+            return true;
+        }
+    }
+    return false;
+}
+
+// Append every cache-fallback aura of `filter`'s kind into the array table.
+void AppendGroupCacheFallbacks(void *L, uint64_t guid, const uint16_t *arr,
+                               Filter filter, bool playerOnly, int outerIdx,
+                               int &nextKey) {
+    Aura::Source::CachedAura buf[kFallbackMax];
+    const int n =
+        Aura::Source::Enumerate(guid, filter == Filter::Harmful, buf, kFallbackMax);
+    const int level = GroupMemberLevel(guid);
+    for (int i = 0; i < n; ++i) {
+        if (!GroupFallbackEligible(arr, buf[i], playerOnly))
+            continue;
+        Game::Lua::PushNumber(L, static_cast<double>(nextKey++));
+        PushEnriched(L, guid, buf[i].spellId, filter == Filter::Helpful, 1, level,
+                     false);
+        Game::Lua::SetTable(L, outerIdx);
+    }
+}
+
+// Single cache-fallback aura matching `spellID` (when nonzero) or `spellName`
+// (when non-null), of the given kind. Backs the by-ID / by-name group queries.
+bool PushGroupCacheFallbackMatch(void *L, uint64_t guid, const uint16_t *arr,
+                                 bool harmful, uint32_t spellID,
+                                 const char *spellName, bool playerOnly) {
+    Aura::Source::CachedAura buf[kFallbackMax];
+    const int n = Aura::Source::Enumerate(guid, harmful, buf, kFallbackMax);
+    for (int i = 0; i < n; ++i) {
+        if (spellID != 0 && buf[i].spellId != spellID)
+            continue;
+        if (spellName != nullptr) {
+            const char *nm = LocalizedSpellName(SpellRecord(buf[i].spellId));
+            if (nm == nullptr || std::strcmp(nm, spellName) != 0)
+                continue;
+        }
+        if (!GroupFallbackEligible(arr, buf[i], playerOnly))
+            continue;
+        PushEnriched(L, guid, buf[i].spellId, !harmful, 1, GroupMemberLevel(guid),
+                     false);
+        return true;
+    }
+    return false;
+}
+
+} // namespace
+
+bool PushNthGroupAura(void *L, uint64_t guid, int oneBasedIndex, Filter filter,
+                      bool playerOnly) {
+    if (guid == 0 || oneBasedIndex < 1)
+        return false;
+    const uint16_t *arr = Group::MemberStats::AuraArray(guid);
+    if (arr == nullptr)
+        return false;
+    Aura::Source::ObserveGroupAuras(guid, arr);
+    int start, end;
+    GroupRange(filter, start, end);
+    int matches = 0;
+    for (int slot = start; slot < end; ++slot) {
+        if (!GroupSlotEligible(guid, arr, slot, playerOnly))
+            continue;
+        if (++matches == oneBasedIndex) {
+            PushEnriched(L, guid, GroupSpellID(arr, slot),
+                         filter == Filter::Helpful, 1, GroupMemberLevel(guid),
+                         false);
+            return true;
+        }
+    }
+    // Empty array (server delta-resend gap): supplement from the cache.
+    if (!GroupArrayHasVisibleAura(arr))
+        return PushNthGroupCacheFallback(L, guid, arr, oneBasedIndex, filter,
+                                         playerOnly);
+    return false;
+}
+
+bool PushGroupAuraBySpellID(void *L, uint64_t guid, uint32_t spellID,
+                            const Filter *filter, bool playerOnly) {
+    if (guid == 0 || spellID == 0)
+        return false;
+    const uint16_t *arr = Group::MemberStats::AuraArray(guid);
+    if (arr == nullptr)
+        return false;
+    Aura::Source::ObserveGroupAuras(guid, arr);
+    const int start = (filter != nullptr && *filter == Filter::Harmful)
+                          ? Offsets::UNIT_AURA_BUFF_COUNT
+                          : 0;
+    const int end = (filter != nullptr && *filter == Filter::Helpful)
+                        ? Offsets::UNIT_AURA_BUFF_COUNT
+                        : Offsets::UNIT_AURA_TOTAL;
+    for (int slot = start; slot < end; ++slot) {
+        if (GroupSpellID(arr, slot) != spellID)
+            continue;
+        if (!GroupSlotEligible(guid, arr, slot, playerOnly))
+            continue;
+        PushEnriched(L, guid, spellID, slot < Offsets::UNIT_AURA_BUFF_COUNT, 1,
+                     GroupMemberLevel(guid), false);
+        return true;
+    }
+    if (!GroupArrayHasVisibleAura(arr)) {
+        const bool both = (filter == nullptr);
+        if ((both || *filter == Filter::Helpful) &&
+            PushGroupCacheFallbackMatch(L, guid, arr, false, spellID, nullptr,
+                                        playerOnly))
+            return true;
+        if ((both || *filter == Filter::Harmful) &&
+            PushGroupCacheFallbackMatch(L, guid, arr, true, spellID, nullptr,
+                                        playerOnly))
+            return true;
+    }
+    return false;
+}
+
+bool PushGroupAuraBySpellName(void *L, uint64_t guid, const char *spellName,
+                              const Filter *filter, bool playerOnly) {
+    if (guid == 0 || spellName == nullptr || *spellName == '\0')
+        return false;
+    const uint16_t *arr = Group::MemberStats::AuraArray(guid);
+    if (arr == nullptr)
+        return false;
+    Aura::Source::ObserveGroupAuras(guid, arr);
+    const int start = (filter != nullptr && *filter == Filter::Harmful)
+                          ? Offsets::UNIT_AURA_BUFF_COUNT
+                          : 0;
+    const int end = (filter != nullptr && *filter == Filter::Helpful)
+                        ? Offsets::UNIT_AURA_BUFF_COUNT
+                        : Offsets::UNIT_AURA_TOTAL;
+    for (int slot = start; slot < end; ++slot) {
+        const uint32_t id = GroupSpellID(arr, slot);
+        if (id == 0)
+            continue;
+        const char *name = LocalizedSpellName(SpellRecord(id));
+        if (name == nullptr || std::strcmp(name, spellName) != 0)
+            continue;
+        if (!GroupSlotEligible(guid, arr, slot, playerOnly))
+            continue;
+        PushEnriched(L, guid, id, slot < Offsets::UNIT_AURA_BUFF_COUNT, 1,
+                     GroupMemberLevel(guid), false);
+        return true;
+    }
+    if (!GroupArrayHasVisibleAura(arr)) {
+        const bool both = (filter == nullptr);
+        if ((both || *filter == Filter::Helpful) &&
+            PushGroupCacheFallbackMatch(L, guid, arr, false, 0, spellName,
+                                        playerOnly))
+            return true;
+        if ((both || *filter == Filter::Harmful) &&
+            PushGroupCacheFallbackMatch(L, guid, arr, true, 0, spellName,
+                                        playerOnly))
+            return true;
+    }
+    return false;
+}
+
+void AppendGroupAuras(void *L, uint64_t guid, Filter filter, bool playerOnly,
+                      int outerIdx, int &nextKey) {
+    if (guid == 0)
+        return;
+    const uint16_t *arr = Group::MemberStats::AuraArray(guid);
+    if (arr == nullptr)
+        return;
+    Aura::Source::ObserveGroupAuras(guid, arr);
+    int start, end;
+    GroupRange(filter, start, end);
+    const int level = GroupMemberLevel(guid);
+    for (int slot = start; slot < end; ++slot) {
+        if (!GroupSlotEligible(guid, arr, slot, playerOnly))
+            continue;
+        Game::Lua::PushNumber(L, static_cast<double>(nextKey++));
+        PushEnriched(L, guid, GroupSpellID(arr, slot),
+                     filter == Filter::Helpful, 1, level, false);
+        Game::Lua::SetTable(L, outerIdx);
+    }
+    // Empty array (server delta-resend gap): supplement from the cache.
+    if (!GroupArrayHasVisibleAura(arr))
+        AppendGroupCacheFallbacks(L, guid, arr, filter, playerOnly, outerIdx,
+                                  nextKey);
+}
+
 } // namespace Aura::Data

src/aura/Data.h

@@ -132,4 +132,45 @@ bool PushNthCacheFallback(void *L, const uint8_t *unit, int oneBasedIndex,
 void AppendCacheFallbacks(void *L, const uint8_t *unit, Filter filter,
                           bool playerOnly, int outerIdx, int &nextKey);
 
+// ── Out-of-range groupmate path ────────────────────────────────────────────
+//
+// When a party/raid member has no live CGUnit at all (different map, far out
+// of range) the token resolves to a GUID but no object, so there is no
+// descriptor to read. The server still transmits that member's current aura
+// spell IDs via SMSG_PARTY_MEMBER_STATS, which the client keeps in the
+// group-member stats structs (`Group::MemberStats::AuraArray`). These functions
+// enumerate that array — exactly what the built-in `UnitBuff`/`UnitDebuff` do
+// out of range — and build the same AuraData table.
+//
+// Spell IDs only come off the wire: `applications` is 1 (stacks aren't sent)
+// and IDs are u16-truncated (custom IDs > 65535 are wrong). Any caster / real
+// expirationTime we observed for the member via SMSG_SPELL_GO is still merged
+// in from the `Aura::Source` cache. `guid` of 0 (not a rostered member) yields
+// no results. These are only meaningful when the unit has NO descriptor —
+// callers use them in the `unit == nullptr` branch, so there is no descriptor
+// to dedup against.
+
+// Pushes AuraData for the `oneBasedIndex`-th group-array aura on `guid`
+// matching `filter`. On a hit pushes the table and returns true; otherwise
+// pushes nothing and returns false (caller pushes nil).
+bool PushNthGroupAura(void *L, uint64_t guid, int oneBasedIndex, Filter filter,
+                      bool playerOnly = false);
+
+// Pushes AuraData for the group-array aura with `spellID` on `guid`, optionally
+// restricted to one filter range (nullptr = both, helpful first). Returns true
+// on a hit (table pushed), false otherwise (nothing pushed).
+bool PushGroupAuraBySpellID(void *L, uint64_t guid, uint32_t spellID,
+                            const Filter *filter, bool playerOnly = false);
+
+// As `PushGroupAuraBySpellID` but matched by locale-resolved spell name
+// (case-sensitive exact match), mirroring `FindSlotBySpellName`.
+bool PushGroupAuraBySpellName(void *L, uint64_t guid, const char *spellName,
+                              const Filter *filter, bool playerOnly = false);
+
+// Appends every group-array aura on `guid` matching `filter` into the array
+// table at `outerIdx`, continuing from `nextKey` (updated in place). The
+// bulk-enumeration analog of `PushNthGroupAura`, for `GetUnitAuras`.
+void AppendGroupAuras(void *L, uint64_t guid, Filter filter, bool playerOnly,
+                      int outerIdx, int &nextKey);
+
 } // namespace Aura::Data

src/aura/Source.cpp

@@ -20,8 +20,10 @@
 #include "Game.h"
 #include "Offsets.h"
 #include "net/PacketReader.h"
+#include "player/StatSignal.h"
 #include "spell/Lookup.h"
 #include "tick/WorldTick.h"
+#include "totem/Tracker.h"
 #include "unit/Identity.h"
 
 #include <cstdint>
@@ -68,6 +70,49 @@ uint32_t SpellDurationMs(const uint8_t *spellRecord, bool casterIsPlayer) {
     return ms > 0 ? static_cast<uint32_t>(ms) : 0;
 }
 
+// ---- Recent local-player aura casts --------------------------------------
+
+// The aura-application hooks (OnAuraAdded / OnAuraStacksChanged) get no caster,
+// so they compute the UNMODIFIED base duration (`skipMod = 1`). That's correct
+// for other units' auras, but wrong for one the LOCAL PLAYER just cast: it
+// should carry the player-talented duration (Improved Shadow Word: Pain → 24s
+// vs the 18s base). SpellGo normally owns that entry with the talented value,
+// but when it can't attribute the cast to this target — an empty SMSG_SPELL_GO
+// hit list files it under the caster instead, or a slot reshuffle evicts and
+// refills the entry after SpellGo ran — the base value is what's left, so the
+// duration flickers 24 → 18. SpellGo (which knows caster == player) records the
+// spellId here so the application hooks can recover the player-modified
+// duration for it.
+constexpr int kRecentCastCount = 16;
+constexpr uint32_t kRecentCastTtlMs = 1500;
+struct RecentCast {
+    uint32_t spellId;
+    uint32_t tMs; // 0 = empty
+};
+RecentCast g_recentCasts[kRecentCastCount];
+int g_recentCastCursor = 0;
+
+void RememberPlayerCast(uint32_t spellId) {
+    const uint32_t now = NowMs();
+    for (auto &r : g_recentCasts)
+        if (r.spellId == spellId) {
+            r.tMs = now;
+            return;
+        }
+    g_recentCasts[g_recentCastCursor] = {spellId, now};
+    g_recentCastCursor = (g_recentCastCursor + 1) % kRecentCastCount;
+}
+
+bool WasRecentPlayerCast(uint32_t spellId) {
+    if (spellId == 0)
+        return false;
+    const uint32_t now = NowMs();
+    for (const auto &r : g_recentCasts)
+        if (r.spellId == spellId && r.tMs != 0 && now - r.tMs <= kRecentCastTtlMs)
+            return true;
+    return false;
+}
+
 // ---- Cache ---------------------------------------------------------------
 
 // Helpful/harmful classification, recorded from the aura's descriptor slot
@@ -133,6 +178,45 @@ void Store(uint64_t targetGuid, uint32_t spellId, uint64_t casterGuid,
             true};
 }
 
+// ---- Out-of-range group-member aura snapshots ---------------------------
+//
+// Transition state for `ObserveGroupAuras`: the last aura spell-ID set we saw
+// for each out-of-range group member, so we can stamp a duration guess only
+// when an aura genuinely appears (not for auras already present when we first
+// started watching that member). See the header for the rationale.
+
+struct GroupSnapshot {
+    uint64_t guid;
+    uint32_t touchMs;
+    bool used;
+    uint16_t ids[Offsets::UNIT_AURA_TOTAL];
+};
+constexpr int kGroupSnapshots = 44;              // MAX_RAID (40) + slack
+constexpr uint32_t kGroupSnapshotTtlMs = 30000;  // forget members not polled for 30s
+GroupSnapshot g_groupSnaps[kGroupSnapshots];
+
+bool SnapshotHasId(const GroupSnapshot &s, uint16_t id) {
+    for (uint16_t v : s.ids)
+        if (v == id)
+            return true;
+    return false;
+}
+
+// Stamp a base-duration expiration guess for a group aura that just appeared.
+// casterGuid stays 0 (unknown), so `Store`'s guard preserves any real SpellGo
+// timing we already hold. Skips non-aura spells and auras with no finite base
+// duration (nothing meaningful to guess — leave expiration unknown).
+void StampGroupGuess(uint64_t guid, uint16_t spellId, int8_t kind, uint32_t now) {
+    const uint8_t *rec = Spell::Lookup::RecordForID(static_cast<int>(spellId));
+    if (!SpellAppliesAura(rec))
+        return;
+    const uint32_t base = SpellDurationMs(rec, /*casterIsPlayer*/ false);
+    if (base == 0)
+        return;
+    Store(guid, spellId, /*casterGuid*/ 0, now + base, base, /*fromCast*/ false,
+          kind);
+}
+
 // Evict the entry for an aura the engine reports gone. Keyed by (target,
 // spell) like the rest of the cache. Without this, the GetAuraDataByIndex
 // fallback would keep surfacing a dropped aura until its computed expiry —
@@ -154,6 +238,10 @@ void Evict(uint64_t targetGuid, uint32_t spellId) {
 void FlushAll() {
     for (auto &e : g_cache)
         e.used = false;
+    // Reset transition baselines too: post-transition group auras re-sync and
+    // should be treated as first-sight (unknown age), not diffed as new.
+    for (auto &s : g_groupSnaps)
+        s.used = false;
 }
 
 // -1 = no map seen yet (never a valid Map.dbc id), so the first tick just
@@ -189,6 +277,12 @@ void OnWorldTick() {
         if (e.used && e.expirationMs != 0 && now >= e.expirationMs)
             e.used = false;
     }
+    // Forget snapshots for members we haven't polled recently (left the group,
+    // or no longer displayed) so a later re-appearance re-baselines cleanly.
+    for (auto &s : g_groupSnaps) {
+        if (s.used && now - s.touchMs > kGroupSnapshotTtlMs)
+            s.used = false;
+    }
 }
 
 const Tick::WorldTick::AutoSubscribe _tickSub{&OnWorldTick};
@@ -229,6 +323,11 @@ void __fastcall SpellGo_h(uint64_t *itemGUID, uint64_t *casterGUID,
     if (caster == 0 || spellId == 0)
         return;
 
+    // Feed the totem tracker BEFORE the aura gate below — a totem summon
+    // applies no aura, so it would otherwise be dropped. Player casts only.
+    if (caster == Unit::Identity::PlayerGuid())
+        Totem::Tracker::OnPlayerSpellGo(spellId);
+
     const uint8_t *rec = Spell::Lookup::RecordForID(static_cast<int>(spellId));
     if (!SpellAppliesAura(rec))
         return;
@@ -245,6 +344,12 @@ void __fastcall SpellGo_h(uint64_t *itemGUID, uint64_t *casterGUID,
         durationMs = SpellDurationMs(rec, casterIsPlayer);
     const uint32_t expirationMs = durationMs > 0 ? NowMs() + durationMs : 0;
 
+    // Let the application hooks recover the player-talented duration for this
+    // spell if they end up owning the target's entry (empty hit list / refill
+    // race) — see WasRecentPlayerCast.
+    if (casterIsPlayer)
+        RememberPlayerCast(spellId);
+
     if (numTargets == 0) {
         // No explicit hit list (self-cast with caster-implicit target).
         Store(caster, spellId, caster, expirationMs, durationMs, true,
@@ -276,9 +381,15 @@ void StampApplication(void *unit, uint32_t spellId, int8_t kind) {
     const uint64_t unitGuid = Unit::Identity::GuidForObject(unit);
     if (unitGuid == 0)
         return;
-    const uint32_t durationMs = SpellDurationMs(rec, /*casterIsPlayer*/ false);
+    // If the local player just cast this aura, use its player-talented duration
+    // (and attribute the caster) — SpellGo couldn't always land the talented
+    // value on this target's entry. Otherwise base (we lack other casters'
+    // mods). See WasRecentPlayerCast.
+    const bool byPlayer = WasRecentPlayerCast(spellId);
+    const uint32_t durationMs = SpellDurationMs(rec, byPlayer);
+    const uint64_t caster = byPlayer ? Unit::Identity::PlayerGuid() : 0;
     const uint32_t expirationMs = durationMs > 0 ? NowMs() + durationMs : 0;
-    Store(unitGuid, spellId, /*casterGuid*/ 0, expirationMs, durationMs,
+    Store(unitGuid, spellId, caster, expirationMs, durationMs,
           /*fromCast*/ false, kind);
 }
 
@@ -288,6 +399,15 @@ int8_t KindForSlot(int slot) {
     return slot >= Offsets::UNIT_AURA_BUFF_COUNT ? KIND_HARMFUL : KIND_HELPFUL;
 }
 
+// Bump the player-stat-inputs signal when an aura change hits the LOCAL
+// player — buffs/debuffs move GetSpellBonusHealing's flat and Spirit/Armor
+// terms, so its lazy cache must invalidate. Guarded on the player object so
+// other units' aura churn (combat) doesn't needlessly invalidate it.
+void NotifyIfPlayer(void *unit) {
+    if (static_cast<const uint8_t *>(unit) == Unit::Identity::PlayerObject())
+        Player::StatSignal::Notify();
+}
+
 // OnAuraAdded — a new aura occupies a slot (gives the spellId directly).
 using OnAuraAdded_t = void(__fastcall *)(void *unit, void *edx, uint32_t slot,
                                          uint32_t spellId);
@@ -297,6 +417,7 @@ void __fastcall OnAuraAdded_h(void *unit, void *edx, uint32_t slot,
                               uint32_t spellId) {
     g_origOnAuraAdded(unit, edx, slot, spellId);
     StampApplication(unit, spellId, KindForSlot(static_cast<int>(slot)));
+    NotifyIfPlayer(unit);
 }
 
 const Game::HookAutoRegister _hookAuraAdded{
@@ -317,6 +438,7 @@ void __fastcall OnAuraStacksChanged_h(void *unit, void *edx, int slot,
         unit,
         Aura::Data::ReadSpellID(static_cast<const uint8_t *>(unit), slot),
         KindForSlot(slot));
+    NotifyIfPlayer(unit);
 }
 
 const Game::HookAutoRegister _hookAuraStacks{
@@ -346,6 +468,7 @@ void __fastcall OnAuraRemoved_h(void *unit, void *edx, uint32_t slot,
     g_origOnAuraRemoved(unit, edx, slot, spellId);
     (void)slot;
     Evict(Unit::Identity::GuidForObject(unit), spellId);
+    NotifyIfPlayer(unit);
 }
 
 const Game::HookAutoRegister _hookAuraRemoved{
@@ -404,4 +527,55 @@ int Enumerate(uint64_t unitGuid, bool harmful, CachedAura *out, int maxOut) {
     return n;
 }
 
+void ObserveGroupAuras(uint64_t guid, const uint16_t *auraArray) {
+    if (guid == 0 || auraArray == nullptr)
+        return;
+    const int total = Offsets::UNIT_AURA_TOTAL;
+    const int buffCount = Offsets::UNIT_AURA_BUFF_COUNT;
+    const uint32_t now = NowMs();
+
+    GroupSnapshot *snap = nullptr;
+    for (auto &s : g_groupSnaps)
+        if (s.used && s.guid == guid) {
+            snap = &s;
+            break;
+        }
+
+    if (snap == nullptr) {
+        // First sight of this member — record a baseline without stamping;
+        // their current auras have unknown age.
+        GroupSnapshot *dst = nullptr;
+        for (auto &s : g_groupSnaps)
+            if (!s.used) {
+                dst = &s;
+                break;
+            }
+        if (dst == nullptr) { // full — evict the least-recently-polled
+            dst = &g_groupSnaps[0];
+            for (auto &s : g_groupSnaps)
+                if (s.touchMs < dst->touchMs)
+                    dst = &s;
+        }
+        dst->guid = guid;
+        dst->used = true;
+        dst->touchMs = now;
+        for (int i = 0; i < total; ++i)
+            dst->ids[i] = auraArray[i];
+        return;
+    }
+
+    // Stamp a guess for every spell ID present now but absent from the prior
+    // snapshot (a genuine appearance), then refresh the snapshot.
+    for (int slot = 0; slot < total; ++slot) {
+        const uint16_t id = auraArray[slot];
+        if (id == 0 || SnapshotHasId(*snap, id))
+            continue;
+        StampGroupGuess(guid, id, slot < buffCount ? KIND_HELPFUL : KIND_HARMFUL,
+                        now);
+    }
+    for (int i = 0; i < total; ++i)
+        snap->ids[i] = auraArray[i];
+    snap->touchMs = now;
+}
+
 } // namespace Aura::Source

src/aura/Source.h

@@ -74,4 +74,19 @@ void EvictAbsent(uint64_t unitGuid, const uint32_t *presentSpellIds, int count);
 // the aura is still active server-side: the cache survives descriptor clears.
 int Enumerate(uint64_t unitGuid, bool harmful, CachedAura *out, int maxOut);
 
+// Feeds the cache from an out-of-range group member's aura spell-ID array
+// (`Group::MemberStats::AuraArray` — 48 slots, buffs 0..BUFF_COUNT-1, debuffs
+// after). Such a member has no CGUnit and never yields SMSG_SPELL_GO, so the
+// SpellGo path never learns their auras' timing — but SMSG_PARTY_MEMBER_STATS
+// carries the spell IDs and the server sends it promptly when an aura is
+// added/removed. So a spell ID that newly *appears* here did so ~one server
+// tick + latency after the real application: we stamp a best-effort
+// `now + base duration` expiration (base only — no remote caster mods, no
+// caster recorded). Auras already present the first time we see a member have
+// unknown age and are NOT stamped; only genuine absent->present transitions
+// are. Idempotent within a frame; call it before enumerating the array so a
+// just-appeared aura carries its guess on the same poll. The Store guard keeps
+// any real SpellGo timing we already hold, so this never downgrades better data.
+void ObserveGroupAuras(uint64_t guid, const uint16_t *auraArray);
+
 } // namespace Aura::Source

src/baselib/MathLib.cpp

@@ -0,0 +1,82 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// Lua 5.1 math-library additions that 1.12's Lua 5.0 is missing:
+//
+//   - `math.fmod(x, y)` — floating-point remainder of `x / y`.
+//   - `math.modf(x)`    — split into integral + fractional parts.
+//   - `math.huge`       — positive infinity constant.
+//
+// `math.fmod` is a pure rename: Lua 5.0 ships the exact same C function under
+// the name `math.mod`; 5.1 renamed the Lua-facing entry to `math.fmod`. We
+// register it as a direct alias of the engine's `math.mod` C function
+// (`FUN_LUA_MATH_FMOD`) — no wrapper. `math.mod` stays available too, so code
+// written for either name works. `modf` and `huge` are genuinely new in 5.1
+// (not in 1.12's mathlib table), so we implement/define them here.
+
+#include "Game.h"
+#include "Offsets.h"
+
+#include <cmath>
+
+namespace BaseLib::MathLib {
+
+namespace {
+
+// `math.fmod` is 5.0's `math.mod` verbatim — register the engine function
+// pointer directly rather than wrapping it.
+const auto Script_math_fmod =
+    reinterpret_cast<Game::Lua::CFunction>(Offsets::FUN_LUA_MATH_FMOD);
+
+// `math.modf(x)` — returns `(integral, fractional)`, the integral part
+// truncated toward zero and the fractional part carrying `x`'s sign
+// (`modf(3.7) → 3, 0.7`; `modf(-3.7) → -3, -0.7`). Matches C `modf` / Lua 5.1.
+int __fastcall Script_math_modf(void *L) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, "Usage: math.modf(x)");
+        return 0; // unreachable
+    }
+    double integral = 0.0;
+    const double fractional = std::modf(Game::Lua::ToNumber(L, 1), &integral);
+    Game::Lua::PushNumber(L, integral);
+    Game::Lua::PushNumber(L, fractional);
+    return 2;
+}
+
+void RegisterFns() {
+    Game::Lua::RegisterTableFunction("math", "fmod", Script_math_fmod);
+    Game::Lua::RegisterTableFunction("math", "modf", &Script_math_modf);
+
+    // `math.huge` — a numeric constant, not a function. Fetch the (now
+    // guaranteed-present) `math` table and set the field directly.
+    void *L = Game::Lua::State();
+    if (L != nullptr) {
+        Game::Lua::PushString(L, "math");
+        Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX); // [math]
+        if (Game::Lua::Type(L, -1) == 5 /* LUA_TTABLE */) {
+            Game::Lua::SetFieldNumber(L, "huge", HUGE_VAL); // math.huge = inf; [math]
+            Game::Lua::SetTop(L, -2);                        // pop [math]
+        } else {
+            Game::Lua::SetTop(L, -2); // pop whatever GetTable returned
+        }
+    }
+}
+
+// Both states are Lua 5.0 and equally missing this; RegisterTableFunction
+// targets whichever state is active in each registration hook.
+const Game::ModuleAutoRegister _autoreg{&RegisterFns};
+const Game::GlueModuleAutoRegister _autoregGlue{&RegisterFns};
+
+} // namespace
+
+} // namespace BaseLib::MathLib

src/baselib/Mixin.cpp

@@ -0,0 +1,83 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `Mixin(object, ...)` and `CreateFromMixins(...)` — the FrameXML table-mixin
+// primitives. Modern WoW provides these as engine C functions (in TableUtil);
+// we do the same rather than leaving them in the !!!ClassicAPI addon so they
+// exist whenever the DLL is injected, even if the addon is disabled. The
+// composite `CreateAndInitFromMixin` (which calls a Lua `:Init` method) stays
+// Lua-side in the addon, mirroring retail's Mixin.lua.
+//
+// Behaviour matches the canonical Lua implementation exactly:
+//   Mixin(object, ...)      -- shallow-copy every key/value from each table
+//                              argument onto `object`; returns `object`.
+//   CreateFromMixins(...)   -- Mixin({}, ...); returns the new table.
+// Non-table extra arguments are skipped (the Lua form guards nil the same way).
+
+#include "Game.h"
+
+namespace BaseLib::Mixin {
+
+namespace {
+
+// Shallow-copy every pair from the table at `srcIdx` onto the table at
+// `dstIdx` (both absolute, positive stack indices). Stack-balanced.
+void MixinInto(void *L, int dstIdx, int srcIdx) {
+    Game::Lua::PushNil(L);
+    while (Game::Lua::Next(L, srcIdx) != 0) {
+        // stack top: ..., key (-2), value (-1). Copy both so the originals
+        // survive for the next Next() iteration.
+        Game::Lua::PushValue(L, -2); // key copy
+        Game::Lua::PushValue(L, -2); // value copy
+        Game::Lua::SetTable(L, dstIdx); // dst[key] = value; pops the two copies
+        Game::Lua::SetTop(L, -2);       // pop value, leave key for Next()
+    }
+}
+
+int __fastcall Script_Mixin(void *L) {
+    const int top = Game::Lua::GetTop(L);
+    if (top < 1 || Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) {
+        Game::Lua::Error(L, "Usage: Mixin(object, ...)");
+        return 0; // unreachable
+    }
+    for (int i = 2; i <= top; ++i)
+        if (Game::Lua::Type(L, i) == Game::Lua::TYPE_TABLE)
+            MixinInto(L, 1, i);
+    Game::Lua::PushValue(L, 1); // return object
+    return 1;
+}
+
+int __fastcall Script_CreateFromMixins(void *L) {
+    const int top = Game::Lua::GetTop(L);
+    Game::Lua::NewTable(L); // new object at index top + 1
+    const int objIdx = top + 1;
+    for (int i = 1; i <= top; ++i)
+        if (Game::Lua::Type(L, i) == Game::Lua::TYPE_TABLE)
+            MixinInto(L, objIdx, i);
+    Game::Lua::SetTop(L, objIdx); // the new table is the sole result
+    return 1;
+}
+
+void RegisterFns() {
+    Game::Lua::RegisterGlobalFunction("Mixin", &Script_Mixin);
+    Game::Lua::RegisterGlobalFunction("CreateFromMixins", &Script_CreateFromMixins);
+}
+
+// Pure table helpers — register on both the in-game and glue states so they're
+// always present (matching the "always available" intent).
+const Game::ModuleAutoRegister _autoreg{&RegisterFns};
+const Game::GlueModuleAutoRegister _autoregGlue{&RegisterFns};
+
+} // namespace
+
+} // namespace BaseLib::Mixin

src/baselib/Select.cpp

@@ -0,0 +1,87 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `select(index, ...)` — the Lua 5.1 base-library vararg helper, missing
+// from 1.12's Lua 5.0 (it predates the function). Two forms:
+//   - `select('#', ...)`  → the number of extra arguments.
+//   - `select(n, ...)`    → all arguments from position `n` onward.
+//     `n` may be negative to index from the end (`-1` = the last arg).
+//
+// Ported from Lua 5.1's `luaB_select` (lbaselib.c). The numeric form needs
+// no pushes at all: the varargs are already sitting on the stack at
+// positions `2..top`, so returning `top - n` hands back exactly the slice
+// from `n+1` onward — the same trick the reference implementation uses.
+// The `'#'` form pushes the count and returns 1.
+//
+// Registered on BOTH Lua states (in-game + glue): it's a language-level
+// helper, state-agnostic, and both states are 5.0 and equally missing it.
+
+#include "Game.h"
+
+namespace BaseLib::Select {
+
+namespace {
+
+int __fastcall Script_select(void *L) {
+    const int n = Game::Lua::GetTop(L);
+    if (n < 1) {
+        Game::Lua::Error(L, "bad argument #1 to 'select' (number expected, got no value)");
+        return 0; // unreachable
+    }
+
+    // `select('#', ...)` — count form. Only inspect the string when the
+    // arg *is* a string: calling lua_tostring on a number would convert
+    // the stack value in place (Lua 5.0/5.1 semantics), corrupting arg 1.
+    if (Game::Lua::Type(L, 1) == Game::Lua::TYPE_STRING) {
+        const char *s = Game::Lua::ToString(L, 1);
+        if (s != nullptr && s[0] == '#') {
+            Game::Lua::PushNumber(L, static_cast<double>(n - 1));
+            return 1;
+        }
+        // A non-'#' string falls through: lua_isnumber accepts numeric
+        // strings (e.g. "2"), matching the reference's luaL_checkint
+        // coercion; a non-numeric string errors below.
+    }
+
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, "bad argument #1 to 'select' (number expected)");
+        return 0; // unreachable
+    }
+    int i = static_cast<int>(Game::Lua::ToNumber(L, 1));
+    if (i < 0)
+        i = n + i; // negative indexes count back from the last argument
+    else if (i > n)
+        i = n;
+    if (i < 1) {
+        Game::Lua::Error(L, "bad argument #1 to 'select' (index out of range)");
+        return 0; // unreachable
+    }
+    // The varargs from position i+1..n are already on the stack; returning
+    // their count hands exactly that slice back to the caller.
+    return n - i;
+}
+
+void RegisterInGame() {
+    Game::Lua::RegisterGlobalFunction("select", &Script_select);
+}
+
+void RegisterGlue() {
+    Game::Lua::RegisterGlueFunction("select", &Script_select);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterInGame};
+const Game::GlueModuleAutoRegister _autoregGlue{&RegisterGlue};
+
+} // namespace
+
+} // namespace BaseLib::Select

src/baselib/StringLib.cpp

@@ -0,0 +1,282 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// String helpers that 1.12's Lua 5.0 is missing:
+//
+//   - `string.match(s, pattern [, init])` — first-match extraction (5.1).
+//   - `string.gmatch(s, pattern)`         — match iterator (5.1).
+//   - `strsplit(sep, str [, pieces])`     — WoW global; split on any char.
+//   - `strjoin(delimiter, ...)`           — WoW global; join varargs.
+//   - `strtrim(str [, chars])`            — WoW global; trim a char set.
+//   - `strreplace(str, find, replace)`    — plain-text replace (see below).
+//   - `string.reverse(s)` / `strrev(s)`   — 5.1 string function, missing in 5.0.
+//
+// The two pattern `string.*` ones reuse machinery 5.0 already ships:
+//   - `match` is `find` returning captures / the whole match instead of the
+//     start/end indices — so we call the engine's `str_find` and transform.
+//   - `gmatch` is exactly 5.0's `string.gfind` (renamed in 5.1); we register
+//     it as a direct alias of the engine's `gfind` C function.
+// `strsplit` is a hand-rolled port of 3.3.5's `strsplit` (see below).
+//
+// NOTE: only the `string.foo(s, ...)` call form works — NOT the
+// `("x"):foo(...)` method sugar. WoW's Lua VM strips type-metatables for
+// every value except tables/userdata (both `lua_setmetatable` and the VM's
+// `luaT_gettmbyobj` hard-return "no metamethod" for strings), so strings have
+// no `__index`, and there's no client-side way to add one short of hooking a
+// hot VM-core function. This is the long-standing vanilla constraint.
+
+#include "Game.h"
+#include "Offsets.h"
+
+#include <cstddef>
+#include <cstring>
+#include <string>
+
+namespace BaseLib::StringLib {
+
+namespace {
+
+// `string.match(s, pattern [, init])`. Calls the engine `str_find` and
+// reshapes its result: no match → nil; match with captures → the captures;
+// match with no captures → the whole matched substring.
+int __fastcall Script_string_match(void *L) {
+    // Normalize to exactly (s, pattern, init): pad missing args with nil so
+    // str_find defaults `init` to 1, and drop any stray 4th value so it can't
+    // be misread as find's `plain` flag (match has no plain form).
+    Game::Lua::SetTop(L, 3);
+    constexpr int kBase = 3;
+
+    auto strFind = reinterpret_cast<Game::Lua::CFunction>(Offsets::FUN_LUA_STR_FIND);
+    const int nres = strFind(L); // pushes start,end,caps.. above kBase, or a nil
+
+    if (nres <= 1) {
+        // No match. str_find pushed the nil (return 1); guard the degenerate
+        // nres==0 case by pushing our own nil so the shape holds.
+        if (nres < 1)
+            Game::Lua::PushNil(L);
+        return 1;
+    }
+
+    if (nres == 2) {
+        // No captures → the whole matched substring s[start..end] (1-based,
+        // inclusive). An empty match has end == start-1 → an empty string.
+        const int start = static_cast<int>(Game::Lua::ToNumber(L, kBase + 1));
+        const int end = static_cast<int>(Game::Lua::ToNumber(L, kBase + 2));
+        // str_find already coerced arg 1 to a string, so this is safe.
+        const char *s = Game::Lua::ToString(L, 1);
+        Game::Lua::SetTop(L, kBase); // drop start, end
+        const size_t len = (end >= start) ? static_cast<size_t>(end - start + 1) : 0;
+        Game::Lua::PushLString(L, s + start - 1, static_cast<unsigned int>(len));
+        return 1;
+    }
+
+    // Captures present → drop start & end, hand back only the captures.
+    Game::Lua::Remove(L, kBase + 1); // remove start; end → kBase+1, caps → kBase+2..
+    Game::Lua::Remove(L, kBase + 1); // remove end;   caps → kBase+1..
+    return nres - 2;
+}
+
+// `string.gmatch` is 5.0's `string.gfind` verbatim — register the engine
+// function pointer directly rather than wrapping it.
+const auto Script_string_gmatch =
+    reinterpret_cast<Game::Lua::CFunction>(Offsets::FUN_LUA_STR_GFIND);
+
+// `strsplit(sep, str [, pieces])` — the WoW global (also aliased as
+// `string.split`), split `str` on ANY character in `sep` and return the
+// pieces as multiple values. `pieces > 0` caps the result count, with the
+// unsplit remainder as the final piece; `0` / omitted = unlimited. Ported
+// from 3.3.5's `strsplit` (FUN_00816a60) with one deliberate change: we do
+// NOT `lua_settop(L, 0)` up front. Popping the args would leave the source
+// string unreferenced, so a GC step triggered by a `pushlstring` could free
+// the very buffer we're still scanning. Keeping the args on the stack keeps
+// the source GC-rooted; Lua returns the top N values (our pieces) regardless
+// of the args sitting below them. Each push is guarded by `lua_checkstack`
+// (this pushes an unbounded number of results), erroring like 3.3.5 on
+// genuine stack exhaustion.
+int __fastcall Script_strsplit(void *L) {
+    const char *sep = Game::Lua::ToString(L, 1);
+    const char *str = Game::Lua::ToString(L, 2);
+    if (sep == nullptr || str == nullptr) {
+        Game::Lua::Error(L, "Usage: strsplit(\"separators\", str [, pieces])");
+        return 0; // unreachable
+    }
+    const int pieces =
+        Game::Lua::IsNumber(L, 3) ? static_cast<int>(Game::Lua::ToNumber(L, 3)) : 0;
+
+    const char *segStart = str;
+    int count = 0;
+    // Only scan for separators while unlimited (pieces == 0) or the cap
+    // hasn't been reached (pieces > 1). pieces == 1 (or <= 0 but non-zero)
+    // yields the whole string as a single piece — matches 3.3.5.
+    if (pieces == 0 || pieces > 1) {
+        for (const char *p = str; *p != '\0'; ++p) {
+            bool isSep = false;
+            for (const char *s = sep; *s != '\0'; ++s) {
+                if (*p == *s) {
+                    isSep = true;
+                    break;
+                }
+            }
+            if (!isSep)
+                continue;
+            ++count;
+            if (Game::Lua::CheckStack(L, count) == 0) {
+                Game::Lua::Error(L, "strsplit(): Stack overflow");
+                return 0; // unreachable
+            }
+            Game::Lua::PushLString(L, segStart,
+                                   static_cast<unsigned int>(p - segStart));
+            segStart = p + 1;
+            if (count == pieces - 1)
+                break; // cap hit; remainder becomes the final piece
+        }
+    }
+    if (Game::Lua::CheckStack(L, count + 1) == 0) {
+        Game::Lua::Error(L, "strsplit(): Stack overflow");
+        return 0; // unreachable
+    }
+    Game::Lua::PushString(L, segStart); // final piece (remainder to end)
+    return count + 1;
+}
+
+// `strjoin(delimiter, ...)` — the inverse of `strsplit`: concatenate the
+// vararg pieces with `delimiter` between each. Standard WoW global (FrameXML
+// defines it in Lua; there's no C original to mirror). A nil / non-coercible
+// piece is treated as an empty string rather than erroring, so the delimiter
+// placement stays predictable. `strjoin(",")` with no pieces returns "".
+int __fastcall Script_strjoin(void *L) {
+    const char *delim = Game::Lua::ToString(L, 1);
+    if (delim == nullptr) {
+        Game::Lua::Error(L, "Usage: strjoin(delimiter, ...)");
+        return 0; // unreachable
+    }
+    const unsigned delimLen = Game::Lua::StrLen(L, 1);
+    const int top = Game::Lua::GetTop(L);
+
+    std::string out; // no Error() past this point — a longjmp would leak it
+    for (int i = 2; i <= top; ++i) {
+        if (i > 2)
+            out.append(delim, delimLen);
+        const char *piece = Game::Lua::ToString(L, i);
+        if (piece != nullptr)
+            out.append(piece, Game::Lua::StrLen(L, i));
+    }
+    Game::Lua::PushLString(L, out.data(), static_cast<unsigned int>(out.size()));
+    return 1;
+}
+
+// `strtrim(str [, chars])` — remove any of the characters in `chars` from
+// both ends of `str` (default: whitespace). `chars` is a literal set of
+// characters, not a pattern. Standard WoW global. Two-ended scan — no
+// allocation, embedded NULs preserved (bounds come from the Lua length).
+int __fastcall Script_strtrim(void *L) {
+    const char *str = Game::Lua::ToString(L, 1);
+    if (str == nullptr) {
+        Game::Lua::Error(L, "Usage: strtrim(str [, chars])");
+        return 0; // unreachable
+    }
+    const unsigned len = Game::Lua::StrLen(L, 1);
+    const char *chars = Game::Lua::IsString(L, 2) ? Game::Lua::ToString(L, 2)
+                                                  : " \t\n\v\f\r";
+
+    bool trim[256] = {false};
+    for (const char *c = chars; *c != '\0'; ++c)
+        trim[static_cast<unsigned char>(*c)] = true;
+
+    unsigned start = 0, end = len;
+    while (start < end && trim[static_cast<unsigned char>(str[start])])
+        ++start;
+    while (end > start && trim[static_cast<unsigned char>(str[end - 1])])
+        --end;
+    Game::Lua::PushLString(L, str + start, end - start);
+    return 1;
+}
+
+// `strreplace(str, find, replace)` — replace every occurrence of the literal
+// substring `find` with `replace`; returns `(result, count)`. NOT a stock WoW
+// global and NOT pattern-based (that's `gsub`) — a plain-text replace that
+// needs no magic-character escaping. Empty `find` returns `str` unchanged
+// (count 0) rather than looping forever.
+int __fastcall Script_strreplace(void *L) {
+    const char *str = Game::Lua::ToString(L, 1);
+    const char *find = Game::Lua::ToString(L, 2);
+    const char *repl = Game::Lua::ToString(L, 3);
+    if (str == nullptr || find == nullptr || repl == nullptr) {
+        Game::Lua::Error(L, "Usage: strreplace(str, find, replace)");
+        return 0; // unreachable
+    }
+    const unsigned strLen = Game::Lua::StrLen(L, 1);
+    const unsigned findLen = Game::Lua::StrLen(L, 2);
+    const unsigned replLen = Game::Lua::StrLen(L, 3);
+
+    if (findLen == 0) { // nothing to match — return input unchanged
+        Game::Lua::PushLString(L, str, strLen);
+        Game::Lua::PushNumber(L, 0.0);
+        return 2;
+    }
+
+    std::string out; // no Error() past this point
+    int count = 0;
+    unsigned i = 0;
+    while (i < strLen) {
+        if (i + findLen <= strLen && std::memcmp(str + i, find, findLen) == 0) {
+            out.append(repl, replLen);
+            i += findLen;
+            ++count;
+        } else {
+            out.push_back(str[i]);
+            ++i;
+        }
+    }
+    Game::Lua::PushLString(L, out.data(), static_cast<unsigned int>(out.size()));
+    Game::Lua::PushNumber(L, static_cast<double>(count));
+    return 2;
+}
+
+// `string.reverse(s)` / `strrev(s)` — return `s` with its bytes reversed.
+// Lua 5.1 added `string.reverse`; 5.0's strlib lacks it. Byte-wise (not
+// UTF-8 aware), matching stock Lua; embedded NULs preserved (bounds from the
+// Lua length).
+int __fastcall Script_string_reverse(void *L) {
+    const char *s = Game::Lua::ToString(L, 1);
+    if (s == nullptr) {
+        Game::Lua::Error(L, "Usage: string.reverse(s)");
+        return 0; // unreachable
+    }
+    const unsigned len = Game::Lua::StrLen(L, 1);
+    std::string out(len, '\0'); // no Error() past this point
+    for (unsigned i = 0; i < len; ++i)
+        out[i] = s[len - 1 - i];
+    Game::Lua::PushLString(L, out.data(), len);
+    return 1;
+}
+
+void RegisterFns() {
+    Game::Lua::RegisterTableFunction("string", "match", &Script_string_match);
+    Game::Lua::RegisterTableFunction("string", "gmatch", Script_string_gmatch);
+    Game::Lua::RegisterTableFunction("string", "reverse", &Script_string_reverse);
+    Game::Lua::RegisterGlobalFunction("strsplit", &Script_strsplit);
+    Game::Lua::RegisterGlobalFunction("strjoin", &Script_strjoin);
+    Game::Lua::RegisterGlobalFunction("strtrim", &Script_strtrim);
+    Game::Lua::RegisterGlobalFunction("strreplace", &Script_strreplace);
+    Game::Lua::RegisterGlobalFunction("strrev", &Script_string_reverse);
+}
+
+// Both states are Lua 5.0 and equally missing these; RegisterTableFunction
+// targets whichever state is active in each registration hook.
+const Game::ModuleAutoRegister _autoreg{&RegisterFns};
+const Game::GlueModuleAutoRegister _autoregGlue{&RegisterFns};
+
+} // namespace
+
+} // namespace BaseLib::StringLib

src/chatbubble/Info.cpp

@@ -0,0 +1,82 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `C_ChatBubbles.GetAllChatBubbles([includeForbidden])` — returns an
+// array of the currently-active chat-bubble Frame objects, matching
+// modern WoW's 7.2.5 signature. Addons use it to recolor / translate /
+// reposition speech bubbles by reading the bubble's FontString region.
+//
+// Vanilla 1.12 chat bubbles are `CGChatBubbleFrame`s — full
+// `CSimpleFrame`s created purely in C++ (never via `CreateFrame`), so
+// they have no name and no Lua wrapper until something pushes them. This
+// is exactly the default-nameplate case: we push each via the shared
+// `UI::FrameObject::Push`, which delegates to the engine's own
+// `FrameScript_Object::ScriptRegister` to lazily build the canonical
+// wrapper. The returned frames respond to real frame methods — the
+// FontString holding the spoken text (bubble + 0x31c, created with the
+// bubble as its parent) shows up in `bubble:GetRegions()`, so the modern
+// "iterate GetRegions, find the FontString, read GetText()" idiom works
+// unchanged. This is the pre-7.2.5 "walk WorldFrame children" pattern the
+// wiki describes, but handed the exact set instead of the whole world.
+//
+// The engine keeps active bubbles on an intrusive Storm `TSList` whose
+// head is `VAR_CHAT_BUBBLE_LIST_HEAD` (`0x00B6F038`); each node's forward
+// link sits at `+0x318` and the list terminator carries the low-bit
+// sentinel. We mirror the engine's own walk in the per-frame update
+// `FUN_004b1060` / teardown `FUN_004b0f80` verbatim. Bubbles whose owner
+// unit has despawned are pruned on the engine's next update tick, so a
+// just-orphaned bubble can linger one frame — harmless, and addons that
+// care filter on `bubble:IsShown()` (a real method here) anyway.
+//
+// `includeForbidden` is accepted and ignored: vanilla has no forbidden
+// frames, so every bubble is returned regardless.
+
+#include "Game.h"
+#include "ui/FrameObject.h"
+
+#include <cstdint>
+
+namespace ChatBubble::Info {
+
+namespace {
+
+// Storm TSList of live CGChatBubbleFrames. Head pointer, per-node
+// forward link, and the end-of-list low-bit sentinel — see the engine
+// walks at 0x004b1060 / 0x004b0f80.
+constexpr uintptr_t kListHead = 0x00B6F038;
+constexpr int kOffNextLink = 0x318;
+
+} // namespace
+
+static int __fastcall Script_GetAllChatBubbles(void *L) {
+    Game::Lua::NewTable(L);
+
+    uintptr_t node = *reinterpret_cast<const uintptr_t *>(kListHead);
+    int nextIndex = 1;
+    while (node != 0 && (node & 1) == 0) {
+        Game::Lua::PushNumber(L, static_cast<double>(nextIndex++));
+        UI::FrameObject::Push(L, reinterpret_cast<void *>(node));
+        Game::Lua::SetTable(L, -3);
+        node = *reinterpret_cast<const uintptr_t *>(node + kOffNextLink);
+    }
+    return 1;
+}
+
+static void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_ChatBubbles", "GetAllChatBubbles",
+                                     &Script_GetAllChatBubbles);
+}
+
+static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace ChatBubble::Info

src/clipboard/Copy.cpp

@@ -0,0 +1,170 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `length = CopyToClipboard(text [, removeMarkup])` — copy `text` to the
+// Windows clipboard and return the number of bytes copied. Vanilla has no
+// clipboard access at all (Blizzard never exposed one), so this is a pure
+// ClassicAPI addition backed by the Win32 clipboard API.
+//
+//   - `text`         the string to copy (numbers are coerced, like Lua does).
+//   - `removeMarkup` optional; when truthy, strip WoW UI escape sequences
+//                    (|cAARRGGBB..|r color, |H..|h..|h hyperlinks keeping the
+//                    visible text, |T..|t textures, |n newline, || → |) before
+//                    copying, so the clipboard gets plain text.
+//   - returns        byte length of the copied (possibly stripped) string —
+//                    consistent with Lua's `#s`. 0 on an empty string or if
+//                    the clipboard couldn't be opened.
+//
+// WoW's in-memory strings are UTF-8 here (same assumption the credential and
+// TTS modules make), so we convert to UTF-16 and set CF_UNICODETEXT; Windows
+// synthesizes CF_TEXT for legacy consumers.
+
+#include "Game.h"
+
+#include <string>
+
+#include <windows.h>
+
+namespace Clipboard::Copy {
+
+namespace {
+
+// Strip WoW UI escape sequences, leaving readable text. See header comment for
+// the set handled; unknown `|x` sequences are left verbatim so real text that
+// merely contains a pipe survives.
+std::string StripMarkup(const char *s, unsigned len) {
+    std::string out;
+    out.reserve(len);
+    unsigned i = 0;
+    while (i < len) {
+        const char c = s[i];
+        if (c != '|') {
+            out.push_back(c);
+            ++i;
+            continue;
+        }
+        const char n = (i + 1 < len) ? s[i + 1] : '\0';
+        switch (n) {
+        case '|': // escaped pipe
+            out.push_back('|');
+            i += 2;
+            break;
+        case 'n': // newline token
+            out.push_back('\n');
+            i += 2;
+            break;
+        case 'r': // color reset
+            i += 2;
+            break;
+        case 'c': // color open: |c + up to 8 hex digits
+            i += 2;
+            for (int k = 0; k < 8 && i < len; ++k) {
+                const char h = s[i];
+                const bool isHex = (h >= '0' && h <= '9') || (h >= 'a' && h <= 'f') ||
+                                   (h >= 'A' && h <= 'F');
+                if (!isHex)
+                    break;
+                ++i;
+            }
+            break;
+        case 'h': // hyperlink boundary (text separator or closer) — drop
+            i += 2;
+            break;
+        case 'H': // hyperlink data opener — skip through to the next |h
+            i += 2;
+            while (i < len && !(s[i] == '|' && i + 1 < len && s[i + 1] == 'h'))
+                ++i;
+            break; // the |h is dropped by the 'h' case on the next iteration
+        case 't': // stray texture closer — drop
+            i += 2;
+            break;
+        case 'T': // texture opener — skip through to the next |t
+            i += 2;
+            while (i < len && !(s[i] == '|' && i + 1 < len && s[i + 1] == 't'))
+                ++i;
+            break; // the |t is dropped by the 't' case on the next iteration
+        default: // unknown sequence — keep the pipe literally
+            out.push_back('|');
+            ++i;
+            break;
+        }
+    }
+    return out;
+}
+
+// Place a UTF-8 byte range on the clipboard as CF_UNICODETEXT. Returns true on
+// success. Does not free the allocation on success — ownership passes to the
+// clipboard.
+bool SetClipboardUtf8(const char *data, int byteLen) {
+    if (!OpenClipboard(nullptr))
+        return false;
+
+    bool ok = false;
+    if (EmptyClipboard()) {
+        // Empty string still writes a valid (empty) clipboard entry.
+        const int wlen =
+            byteLen > 0 ? MultiByteToWideChar(CP_UTF8, 0, data, byteLen, nullptr, 0) : 0;
+        HGLOBAL h = GlobalAlloc(GMEM_MOVEABLE, (static_cast<SIZE_T>(wlen) + 1) * sizeof(wchar_t));
+        if (h != nullptr) {
+            auto *dst = static_cast<wchar_t *>(GlobalLock(h));
+            if (dst != nullptr) {
+                if (wlen > 0)
+                    MultiByteToWideChar(CP_UTF8, 0, data, byteLen, dst, wlen);
+                dst[wlen] = L'\0';
+                GlobalUnlock(h);
+                if (SetClipboardData(CF_UNICODETEXT, h) != nullptr)
+                    ok = true; // clipboard owns h now
+            }
+            if (!ok)
+                GlobalFree(h);
+        }
+    }
+
+    CloseClipboard();
+    return ok;
+}
+
+int __fastcall Script_CopyToClipboard(void *L) {
+    if (!Game::Lua::IsString(L, 1) && !Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, "Usage: CopyToClipboard(text [, removeMarkup])");
+        return 0; // unreachable
+    }
+
+    const char *text = Game::Lua::ToString(L, 1);
+    const unsigned len = Game::Lua::StrLen(L, 1);
+    const bool removeMarkup = Game::Lua::ToBoolean(L, 2) != 0;
+
+    int copiedLen;
+    if (removeMarkup) {
+        const std::string stripped = StripMarkup(text, len);
+        copiedLen = static_cast<int>(stripped.size());
+        SetClipboardUtf8(stripped.data(), copiedLen);
+    } else {
+        copiedLen = static_cast<int>(len);
+        SetClipboardUtf8(text, copiedLen);
+    }
+
+    Game::Lua::PushNumber(L, static_cast<double>(copiedLen));
+    return 1;
+}
+
+void RegisterFns() {
+    Game::Lua::RegisterGlobalFunction("CopyToClipboard", &Script_CopyToClipboard);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterFns};
+const Game::GlueModuleAutoRegister _autoregGlue{&RegisterFns};
+
+} // namespace
+
+} // namespace Clipboard::Copy

src/color/Util.cpp

@@ -0,0 +1,292 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `C_ColorUtil` — the modern color-space + text-color-code helpers, backported
+// to 1.12. Every one is pure math / string formatting (no engine state), so
+// this is a plain reimplementation rather than a hook.
+//
+// Conventions verified in-game against a retail-family client that ships
+// C_ColorUtil natively:
+//   - HSV/HSL hue is in DEGREES, [0, 360); saturation / value / lightness are
+//     [0, 1]. Achromatic (gray) inputs yield hue = -1 (a sentinel, not 0).
+//   - GenerateTextColorCode(color) returns the BARE 8-hex string "AARRGGBB"
+//     (e.g. red -> "ffff0000"), alpha forced to ff (the arg type is colorRGB,
+//     no alpha channel).
+//   - WrapTextInColorCode(text, code) returns "|c" .. code .. text .. "|r".
+//   - WrapTextInColor(text, color) = WrapTextInColorCode(text,
+//     GenerateTextColorCode(color)) -> "|cffff0000Hi|r".
+//
+// The color arg is a table read by raw r/g/b fields (ColorMixin-shaped); an
+// optional a field is honored (default 1.0) though retail's colorRGB type
+// omits it — for the documented no-alpha case both give ff.
+
+#include "Game.h"
+
+#include <cmath>
+#include <cstdio>
+#include <string>
+
+namespace Color::Util {
+
+namespace {
+
+double Clamp01(double v) { return v < 0.0 ? 0.0 : (v > 1.0 ? 1.0 : v); }
+
+int ToByte(double v) {
+    const double c = Clamp01(v);
+    return static_cast<int>(c * 255.0 + 0.5); // round to nearest
+}
+
+double Max3(double a, double b, double c) {
+    double m = a > b ? a : b;
+    return m > c ? m : c;
+}
+double Min3(double a, double b, double c) {
+    double m = a < b ? a : b;
+    return m < c ? m : c;
+}
+double MinLuma(double l) { return l < 1.0 - l ? l : 1.0 - l; }
+
+// --- Pure conversions --------------------------------------------------
+
+void RgbToHsv(double r, double g, double b, double &h, double &s, double &v) {
+    const double mx = Max3(r, g, b), mn = Min3(r, g, b), d = mx - mn;
+    v = mx;
+    s = (mx <= 0.0) ? 0.0 : d / mx;
+    if (d <= 0.0) { // achromatic
+        h = -1.0;
+        return;
+    }
+    if (mx == r)
+        h = 60.0 * std::fmod((g - b) / d, 6.0);
+    else if (mx == g)
+        h = 60.0 * ((b - r) / d + 2.0);
+    else
+        h = 60.0 * ((r - g) / d + 4.0);
+    if (h < 0.0)
+        h += 360.0;
+}
+
+void HsvToRgb(double h, double s, double v, double &r, double &g, double &b) {
+    if (s <= 0.0 || h < 0.0) { // achromatic (incl. the -1 sentinel)
+        r = g = b = v;
+        return;
+    }
+    h = std::fmod(h, 360.0);
+    if (h < 0.0)
+        h += 360.0;
+    const double hh = h / 60.0;
+    const int i = static_cast<int>(std::floor(hh));
+    const double f = hh - i;
+    const double p = v * (1.0 - s);
+    const double q = v * (1.0 - s * f);
+    const double t = v * (1.0 - s * (1.0 - f));
+    switch (i % 6) {
+    case 0: r = v; g = t; b = p; break;
+    case 1: r = q; g = v; b = p; break;
+    case 2: r = p; g = v; b = t; break;
+    case 3: r = p; g = q; b = v; break;
+    case 4: r = t; g = p; b = v; break;
+    default: r = v; g = p; b = q; break;
+    }
+}
+
+void HsvToHsl(double h, double sv, double v, double &ho, double &sl, double &l) {
+    ho = h; // hue (incl. -1) passes through unchanged
+    l = v * (1.0 - sv / 2.0);
+    sl = (l <= 0.0 || l >= 1.0) ? 0.0 : (v - l) / MinLuma(l);
+}
+
+void HslToHsv(double h, double sl, double l, double &ho, double &sv, double &v) {
+    ho = h;
+    v = l + sl * MinLuma(l);
+    sv = (v <= 0.0) ? 0.0 : 2.0 * (1.0 - l / v);
+}
+
+void HslToRgb(double h, double s, double l, double &r, double &g, double &b) {
+    if (s <= 0.0 || h < 0.0) { // achromatic
+        r = g = b = l;
+        return;
+    }
+    h = std::fmod(h, 360.0);
+    if (h < 0.0)
+        h += 360.0;
+    const double c = (1.0 - std::fabs(2.0 * l - 1.0)) * s;
+    const double hh = h / 60.0;
+    const double x = c * (1.0 - std::fabs(std::fmod(hh, 2.0) - 1.0));
+    const double m = l - c / 2.0;
+    double r1, g1, b1;
+    switch (static_cast<int>(std::floor(hh)) % 6) {
+    case 0: r1 = c; g1 = x; b1 = 0.0; break;
+    case 1: r1 = x; g1 = c; b1 = 0.0; break;
+    case 2: r1 = 0.0; g1 = c; b1 = x; break;
+    case 3: r1 = 0.0; g1 = x; b1 = c; break;
+    case 4: r1 = x; g1 = 0.0; b1 = c; break;
+    default: r1 = c; g1 = 0.0; b1 = x; break;
+    }
+    r = r1 + m;
+    g = g1 + m;
+    b = b1 + m;
+}
+
+// --- Lua glue ----------------------------------------------------------
+
+// Read arg `n` as a number, or raise the usage error.
+double Arg(void *L, int n, const char *usage) {
+    if (!Game::Lua::IsNumber(L, n)) {
+        Game::Lua::Error(L, "%s", usage);
+        return 0.0; // unreachable
+    }
+    return Game::Lua::ToNumber(L, n);
+}
+
+// Read a numeric field from the color table at (absolute, positive) index
+// `idx`. Raw access — ColorMixin stores r/g/b/a as direct keys.
+double ColorField(void *L, int idx, const char *key, double dflt) {
+    Game::Lua::PushString(L, key);
+    Game::Lua::RawGet(L, idx);
+    const double v = Game::Lua::IsNumber(L, -1) ? Game::Lua::ToNumber(L, -1) : dflt;
+    Game::Lua::SetTop(L, -2); // pop the value
+    return v;
+}
+
+// "AARRGGBB" from a color table at `idx`, alpha default ff.
+std::string HexFromColor(void *L, int idx) {
+    const int a = ToByte(ColorField(L, idx, "a", 1.0));
+    const int r = ToByte(ColorField(L, idx, "r", 0.0));
+    const int g = ToByte(ColorField(L, idx, "g", 0.0));
+    const int b = ToByte(ColorField(L, idx, "b", 0.0));
+    char buf[9];
+    std::snprintf(buf, sizeof(buf), "%02x%02x%02x%02x", a, r, g, b);
+    return std::string(buf, 8);
+}
+
+int __fastcall Script_ConvertRGBToHSV(void *L) {
+    const double r = Arg(L, 1, "Usage: C_ColorUtil.ConvertRGBToHSV(r, g, b)");
+    const double g = Arg(L, 2, "Usage: C_ColorUtil.ConvertRGBToHSV(r, g, b)");
+    const double b = Arg(L, 3, "Usage: C_ColorUtil.ConvertRGBToHSV(r, g, b)");
+    double h, s, v;
+    RgbToHsv(r, g, b, h, s, v);
+    Game::Lua::PushNumber(L, h);
+    Game::Lua::PushNumber(L, s);
+    Game::Lua::PushNumber(L, v);
+    return 3;
+}
+
+int __fastcall Script_ConvertHSVToRGB(void *L) {
+    const double h = Arg(L, 1, "Usage: C_ColorUtil.ConvertHSVToRGB(h, s, v)");
+    const double s = Arg(L, 2, "Usage: C_ColorUtil.ConvertHSVToRGB(h, s, v)");
+    const double v = Arg(L, 3, "Usage: C_ColorUtil.ConvertHSVToRGB(h, s, v)");
+    double r, g, b;
+    HsvToRgb(h, s, v, r, g, b);
+    Game::Lua::PushNumber(L, r);
+    Game::Lua::PushNumber(L, g);
+    Game::Lua::PushNumber(L, b);
+    return 3;
+}
+
+int __fastcall Script_ConvertHSVToHSL(void *L) {
+    const double h = Arg(L, 1, "Usage: C_ColorUtil.ConvertHSVToHSL(h, s, v)");
+    const double s = Arg(L, 2, "Usage: C_ColorUtil.ConvertHSVToHSL(h, s, v)");
+    const double v = Arg(L, 3, "Usage: C_ColorUtil.ConvertHSVToHSL(h, s, v)");
+    double ho, sl, l;
+    HsvToHsl(h, s, v, ho, sl, l);
+    Game::Lua::PushNumber(L, ho);
+    Game::Lua::PushNumber(L, sl);
+    Game::Lua::PushNumber(L, l);
+    return 3;
+}
+
+int __fastcall Script_ConvertHSLToHSV(void *L) {
+    const double h = Arg(L, 1, "Usage: C_ColorUtil.ConvertHSLToHSV(h, s, l)");
+    const double s = Arg(L, 2, "Usage: C_ColorUtil.ConvertHSLToHSV(h, s, l)");
+    const double l = Arg(L, 3, "Usage: C_ColorUtil.ConvertHSLToHSV(h, s, l)");
+    double ho, sv, v;
+    HslToHsv(h, s, l, ho, sv, v);
+    Game::Lua::PushNumber(L, ho);
+    Game::Lua::PushNumber(L, sv);
+    Game::Lua::PushNumber(L, v);
+    return 3;
+}
+
+int __fastcall Script_ConvertHSLToRGB(void *L) {
+    const double h = Arg(L, 1, "Usage: C_ColorUtil.ConvertHSLToRGB(h, s, l)");
+    const double s = Arg(L, 2, "Usage: C_ColorUtil.ConvertHSLToRGB(h, s, l)");
+    const double l = Arg(L, 3, "Usage: C_ColorUtil.ConvertHSLToRGB(h, s, l)");
+    double r, g, b;
+    HslToRgb(h, s, l, r, g, b);
+    Game::Lua::PushNumber(L, r);
+    Game::Lua::PushNumber(L, g);
+    Game::Lua::PushNumber(L, b);
+    return 3;
+}
+
+int __fastcall Script_GenerateTextColorCode(void *L) {
+    if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) {
+        Game::Lua::Error(L, "Usage: C_ColorUtil.GenerateTextColorCode(color)");
+        return 0; // unreachable
+    }
+    const std::string hex = HexFromColor(L, 1);
+    Game::Lua::PushString(L, hex.c_str());
+    return 1;
+}
+
+int __fastcall Script_WrapTextInColor(void *L) {
+    const char *text = Game::Lua::ToString(L, 1);
+    if (text == nullptr || Game::Lua::Type(L, 2) != Game::Lua::TYPE_TABLE) {
+        Game::Lua::Error(L, "Usage: C_ColorUtil.WrapTextInColor(text, color)");
+        return 0; // unreachable
+    }
+    std::string out = "|c" + HexFromColor(L, 2) + text + "|r";
+    Game::Lua::PushString(L, out.c_str());
+    return 1;
+}
+
+int __fastcall Script_WrapTextInColorCode(void *L) {
+    const char *text = Game::Lua::ToString(L, 1);
+    const char *code = Game::Lua::ToString(L, 2);
+    if (text == nullptr || code == nullptr) {
+        Game::Lua::Error(L, "Usage: C_ColorUtil.WrapTextInColorCode(text, colorCode)");
+        return 0; // unreachable
+    }
+    std::string out = std::string("|c") + code + text + "|r";
+    Game::Lua::PushString(L, out.c_str());
+    return 1;
+}
+
+void RegisterFns() {
+    Game::Lua::RegisterTableFunction("C_ColorUtil", "ConvertRGBToHSV",
+                                     &Script_ConvertRGBToHSV);
+    Game::Lua::RegisterTableFunction("C_ColorUtil", "ConvertHSVToRGB",
+                                     &Script_ConvertHSVToRGB);
+    Game::Lua::RegisterTableFunction("C_ColorUtil", "ConvertHSVToHSL",
+                                     &Script_ConvertHSVToHSL);
+    Game::Lua::RegisterTableFunction("C_ColorUtil", "ConvertHSLToHSV",
+                                     &Script_ConvertHSLToHSV);
+    Game::Lua::RegisterTableFunction("C_ColorUtil", "ConvertHSLToRGB",
+                                     &Script_ConvertHSLToRGB);
+    Game::Lua::RegisterTableFunction("C_ColorUtil", "GenerateTextColorCode",
+                                     &Script_GenerateTextColorCode);
+    Game::Lua::RegisterTableFunction("C_ColorUtil", "WrapTextInColor",
+                                     &Script_WrapTextInColor);
+    Game::Lua::RegisterTableFunction("C_ColorUtil", "WrapTextInColorCode",
+                                     &Script_WrapTextInColorCode);
+}
+
+// Pure helpers — useful on both the in-game and glue states.
+const Game::ModuleAutoRegister _autoreg{&RegisterFns};
+const Game::GlueModuleAutoRegister _autoregGlue{&RegisterFns};
+
+} // namespace
+
+} // namespace Color::Util

src/container/FreeSlots.cpp

@@ -13,6 +13,7 @@
 
 #include "Game.h"
 #include "Offsets.h"
+#include "item/BagFamily.h"
 #include "item/ID.h"
 #include "item/Location.h"
 
@@ -73,15 +74,14 @@ BagInfo ResolveBagInfo(int bagID) {
 
     const int slots = static_cast<int>(*reinterpret_cast<const uint32_t *>(
         record + Offsets::OFF_ITEMSTATS_CONTAINER_SLOTS));
-    // Convert 1.12's raw BagFamily ID to the modern bitmask. See
-    // `Offsets::OFF_ITEMSTATS_BAG_FAMILY` for the encoding-shift story
-    // and `Item::Info::BagFamilyIdToBitmask` for the canonical helper —
-    // we inline the one-liner here to avoid a header dance for a
-    // single-instruction conversion.
-    const uint32_t rawFamily = *reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_BAG_FAMILY);
+    // BagFamily bitmask: the item's field if populated, else derived from
+    // the container subclass — Turtle leaves bags' m_bagFamily at 0, so a
+    // Soul Bag would otherwise report family 0 and get miscounted as a
+    // general-purpose bag by CalculateTotalNumberOfFreeBagSlots. Shared
+    // with C_Item.GetItemFamily so a bag and its contents agree. See
+    // `Item::BagFamily`.
     const int family =
-        (rawFamily == 0) ? 0 : static_cast<int>(1u << (rawFamily - 1));
+        static_cast<int>(Item::BagFamily::BitmaskForRecord(record));
     return {slots, family};
 }
 
@@ -106,14 +106,13 @@ int CountFreeSlotsInBag(void *L, int bagID, int slotCount) {
 // `(0, 0)` — matching 3.3.5's behavior of always pushing two values
 // rather than nil/nothing.
 //
-// `bagType` is the `BagFamily` bitmask in modern encoding (raw 1.12
-// ID converted via `1 << (ID-1)`). Empirically on Turtle WoW, only
-// Light Quiver actually carries a non-zero family for bags themselves
-// — Soul Pouch, Enchanting Bag, etc. all return 0 because the
-// vanilla-era server data doesn't populate the field. **Individual
-// items** (arrows, bullets, shards, herbs) reliably return their
-// family, so addons that auto-route loot work correctly via
-// `C_Item.GetItemFamily(itemID)` even though `bagType` is sparse.
+// `bagType` is the `BagFamily` bitmask in modern encoding. Bags leave the
+// raw family field empty in Turtle's data (Soul/Herb/quiver/ammo pouch/…
+// all read 0), so it's derived from the bag's class + subclass via
+// `Item::BagFamily`: a Soul Bag reports `0x4`, a quiver `0x1`, an ammo
+// pouch `0x2` — matching what `C_Item.GetItemFamily` reports for both the
+// bag and the items it holds. See that helper for the Turtle custom-family
+// caveat (Meat/Fish/Leather/Mining, IDs 10–13).
 int __fastcall Script_C_Container_GetContainerNumFreeSlots(void *L) {
     if (!Game::Lua::IsNumber(L, 1)) {
         Game::Lua::Error(L,
@@ -139,12 +138,12 @@ int __fastcall Script_C_Container_GetContainerNumFreeSlots(void *L) {
 //       free, family = C_Container.GetContainerNumFreeSlots(bag)
 //       if family == 0 then total = total + free end
 //
-// Takes no arguments. Caveat inherited from `GetContainerNumFreeSlots`:
-// vanilla-era server data leaves most bags' BagFamily at 0, so specialty
-// bags that retail *would* exclude (Soul Pouch, Enchanting Bag, …) get
-// counted here — the client just doesn't carry the family bit for them. The
-// result stays consistent with what `GetContainerNumFreeSlots` reports for
-// those same bags.
+// Takes no arguments. Specialty bags are correctly excluded: their family
+// comes from `Item::BagFamily` (container-subclass fallback), so a Soul
+// Bag / Herb Bag / Meat Bag reports a non-zero family and its slots are
+// left out of the general-purpose total — matching retail's FrameXML
+// behavior. (An earlier version miscounted them because Turtle leaves the
+// raw family field at 0 for bags.)
 int __fastcall Script_C_Container_CalculateTotalNumberOfFreeBagSlots(void *L) {
     int total = 0;
     for (int bagID = 0; bagID <= 4; bagID++) {

src/container/ItemInfo.cpp

@@ -0,0 +1,194 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `C_Container.GetContainerItemInfo(containerIndex, slotIndex)` — the modern
+// structured-table accessor (namespaced + table-returning since Patch
+// 10.0.2). Vanilla's global `GetContainerItemInfo` returns a flat 5-tuple
+// (`texture, itemCount, locked, quality, readable` — verified by decoding
+// `Script_GetContainerItemInfo` at `0x004F9670`); backported addons expect
+// the `ContainerItemInfo` table with the wider modern field set. We assemble
+// that table from the same sources the engine reads plus the extra fields it
+// never surfaced in 1.12.
+//
+// Field sources:
+//   iconFileID  — ItemStats displayInfoID → ItemDisplayInfo.dbc icon path.
+//                 (1.12 has no fileID system; we return the icon *path*
+//                 string, same convention as `GetItemIcon`.)
+//   stackCount  — CGItem descriptor `+OFF_DESCRIPTOR_STACK_COUNT` (the
+//                 engine's `itemCount` return).
+//   isLocked    — CGItem `+OFF_ITEM_CLIENT_LOCK & 1` (the `locked` return).
+//   quality     — ItemStats `+OFF_ITEMSTATS_QUALITY`; nil when uncached
+//                 (modern contract: `Enum.ItemQuality or nil`).
+//   isReadable  — static page text OR the per-instance readable-text id,
+//                 mirroring the engine's `readable` branch at `0x004F97BD`.
+//   hasLoot     — ItemStats LOOTABLE flag (best-effort static approximation:
+//                 vanilla can't track post-loot dynamic emptiness client-side).
+//   hyperlink   — engine link builder via `Item::Link::FromCGItem` (enchant /
+//                 random-suffix decorated, same as `GetContainerItemLink`).
+//   isFiltered  — always false (vanilla has no bag search-filter system).
+//   hasNoValue  — ItemStats sellPrice == 0.
+//   itemID      — instance block itemID (`Item::ID::FromCGItem`).
+//   isBound     — CGItem descriptor SOULBOUND flag (`C_Item.IsBound`'s bit).
+//   itemName    — instance-decorated display name, base ItemStats name on miss.
+//
+// Returns nil for an empty slot or an invalid bag/slot index (modern
+// contract). Cache-derived fields (icon / quality / hasLoot / hasNoValue /
+// name) are omitted/nil when the item's static data isn't cached yet — the
+// live per-instance fields (count / locked / bound / itemID / link) are always
+// present. Passive: does not warm the item cache.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "dbc/Lookup.h"
+#include "item/ID.h"
+#include "item/Link.h"
+#include "item/Location.h"
+#include "item/StatAccum.h"
+
+#include <cstdint>
+#include <cstdio>
+
+namespace Container::ItemInfo {
+
+namespace {
+
+bool BuildIconPath(uint32_t displayInfoID, char *out, size_t outSize) {
+    out[0] = '\0';
+    const char *iconName = DBC::StringField(
+        Offsets::VAR_ITEMDISPLAYINFO_RECORDS, Offsets::VAR_ITEMDISPLAYINFO_COUNT,
+        displayInfoID, Offsets::OFF_ITEMDISPLAYINFO_ICON);
+    if (iconName == nullptr || iconName[0] == '\0')
+        return false;
+    std::snprintf(out, outSize, "Interface\\Icons\\%s", iconName);
+    return true;
+}
+
+// Mirrors the engine's `readable` decision (0x004F97BD..0x004F97CF): a slot
+// is readable when its static page text is set OR the per-instance
+// readable-text id is non-zero (letters / server-authored notes).
+bool ItemReadable(const uint8_t *item, const uint8_t *record) {
+    if (record != nullptr &&
+        *reinterpret_cast<const uint32_t *>(record + Offsets::OFF_ITEMSTATS_PAGE_TEXT) != 0)
+        return true;
+    const uint8_t *descriptor = *reinterpret_cast<const uint8_t *const *>(
+        item + Offsets::OFF_ITEM_DESCRIPTOR);
+    return descriptor != nullptr &&
+           *reinterpret_cast<const uint32_t *>(
+               descriptor + Offsets::OFF_DESCRIPTOR_READABLE_TEXT_ID) != 0;
+}
+
+int __fastcall Script_C_Container_GetContainerItemInfo(void *L) {
+    if (!Game::Lua::IsNumber(L, 1) || !Game::Lua::IsNumber(L, 2)) {
+        Game::Lua::Error(L,
+            "Usage: C_Container.GetContainerItemInfo(containerIndex, slotIndex)");
+        return 0;
+    }
+    const int bagID = static_cast<int>(Game::Lua::ToNumber(L, 1));
+    const int slotIndex = static_cast<int>(Game::Lua::ToNumber(L, 2));
+
+    const uint8_t *item = Item::Location::ResolveBag(L, bagID, slotIndex);
+    if (item == nullptr) {
+        Game::Lua::PushNil(L); // empty slot / bad index → nil (modern contract)
+        return 1;
+    }
+
+    // --- Gather everything into locals BEFORE touching the Lua stack. The
+    // engine link/name builders and cache/DBC reads below are pure C; keeping
+    // them off the half-built table avoids any stack interleaving. ---
+    const int itemID = Item::ID::FromCGItem(item);
+    const uint8_t *record = (itemID > 0)
+        ? Item::StatAccum::FetchRecord(static_cast<uint32_t>(itemID))
+        : nullptr;
+
+    // Live per-instance descriptor fields.
+    const uint8_t *descriptor = *reinterpret_cast<const uint8_t *const *>(
+        item + Offsets::OFF_ITEM_DESCRIPTOR);
+    int stackCount = 0;
+    bool isBound = false;
+    if (descriptor != nullptr) {
+        stackCount = *reinterpret_cast<const int *>(
+            descriptor + Offsets::OFF_DESCRIPTOR_STACK_COUNT);
+        isBound = (*reinterpret_cast<const uint32_t *>(
+                       descriptor + Offsets::OFF_DESCRIPTOR_FLAGS) &
+                   Offsets::ITEM_FLAG_SOULBOUND) != 0;
+    }
+    const bool isLocked = (*reinterpret_cast<const uint32_t *>(
+                               item + Offsets::OFF_ITEM_CLIENT_LOCK) &
+                           Offsets::ITEM_CLIENT_LOCK_BIT) != 0;
+    const bool isReadable = ItemReadable(item, record);
+
+    // Static template fields (cache-dependent).
+    bool haveIcon = false;
+    char iconPath[260];
+    bool haveQuality = false;
+    uint32_t quality = 0;
+    bool hasLoot = false;
+    bool hasNoValue = false;
+    if (record != nullptr) {
+        const uint32_t displayInfoID = *reinterpret_cast<const uint32_t *>(
+            record + Offsets::OFF_ITEMSTATS_DISPLAY_INFO_ID);
+        haveIcon = BuildIconPath(displayInfoID, iconPath, sizeof(iconPath));
+        quality = *reinterpret_cast<const uint32_t *>(
+            record + Offsets::OFF_ITEMSTATS_QUALITY);
+        haveQuality = true;
+        const uint32_t flags = *reinterpret_cast<const uint32_t *>(
+            record + Offsets::OFF_ITEMSTATS_FLAGS);
+        hasLoot = (flags & Offsets::ITEM_FLAG_LOOTABLE) != 0;
+        hasNoValue = *reinterpret_cast<const uint32_t *>(
+                         record + Offsets::OFF_ITEMSTATS_SELL_PRICE) == 0;
+    }
+
+    const char *hyperlink = Item::Link::FromCGItem(item);
+
+    char nameBuf[256];
+    const char *itemName = nullptr;
+    if (Item::Link::NameFromCGItem(item, nameBuf, sizeof(nameBuf))) {
+        itemName = nameBuf;
+    } else if (record != nullptr) {
+        const char *baseName = *reinterpret_cast<const char *const *>(
+            record + Offsets::OFF_ITEMSTATS_NAME);
+        if (baseName != nullptr && baseName[0] != '\0')
+            itemName = baseName;
+    }
+
+    // --- Build the ContainerItemInfo table (only stack-safe SetField* now). ---
+    Game::Lua::NewTable(L);
+    if (haveIcon)
+        Game::Lua::SetFieldString(L, "iconFileID", iconPath);
+    Game::Lua::SetFieldNumber(L, "stackCount", static_cast<double>(stackCount));
+    Game::Lua::SetFieldBool(L, "isLocked", isLocked);
+    if (haveQuality)
+        Game::Lua::SetFieldNumber(L, "quality", static_cast<double>(quality));
+    Game::Lua::SetFieldBool(L, "isReadable", isReadable);
+    Game::Lua::SetFieldBool(L, "hasLoot", hasLoot);
+    if (hyperlink != nullptr && hyperlink[0] != '\0')
+        Game::Lua::SetFieldString(L, "hyperlink", hyperlink);
+    Game::Lua::SetFieldBool(L, "isFiltered", false);
+    Game::Lua::SetFieldBool(L, "hasNoValue", hasNoValue);
+    Game::Lua::SetFieldNumber(L, "itemID", static_cast<double>(itemID));
+    Game::Lua::SetFieldBool(L, "isBound", isBound);
+    if (itemName != nullptr)
+        Game::Lua::SetFieldString(L, "itemName", itemName);
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_Container", "GetContainerItemInfo",
+                                     &Script_C_Container_GetContainerItemInfo);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace Container::ItemInfo

src/coroutine/Library.cpp

@@ -107,11 +107,19 @@ static int AuxResume(void *L, void *co, int nargs) {
                                      : "cannot resume non-suspended coroutine");
         return -1;
     }
+    if (Game::Lua::CheckStack(co, nargs) == 0) {
+        Game::Lua::PushString(L, "too many arguments to resume coroutine");
+        return -1;
+    }
     Game::Lua::XMove(L, co, nargs);
     const int s = Game::Lua::Resume(co, nargs);
     const bool yielded = LuaCI(co) > LuaBaseCI(co);
     if (s == LUA_OK || yielded) {
         const int nres = Game::Lua::GetTop(co);
+        if (Game::Lua::CheckStack(L, nres) == 0) {
+            Game::Lua::PushString(L, "too many results to resume coroutine");
+            return -1;
+        }
         Game::Lua::XMove(co, L, nres);
         return nres;
     }

src/equipmentset/Data.cpp

@@ -88,12 +88,27 @@ void Persist() {
 } // namespace
 
 void EnsureLoaded() {
-    if (g_loaded)
-        return;
-    g_path = Storage::ResolveFilePath();
-    if (g_path.empty())
-        return; // session globals not yet populated; retry on next call
+    // Re-resolve the per-character path on every call rather than latching
+    // once. The injected DLL persists across a logout→character-select→login
+    // (no process restart), so a permanent `g_loaded` latch would leave the
+    // previous character's file path and cached sets in place — the next
+    // character would then read, and save into, character A's data. Detecting
+    // a path change here makes the cache self-heal on any character/account
+    // switch. Every mutation Persist()s immediately, so dropping the old
+    // in-memory sets never loses unsaved work.
+    std::string path = Storage::ResolveFilePath();
+    if (path.empty())
+        return; // session globals not yet populated; keep current, retry later
+    if (g_loaded && path == g_path)
+        return; // already loaded for this character
+
+    g_path = std::move(path);
+    g_sets.clear();
     Storage::Load(g_path, &g_sets);
+    // Per-session "ignore this slot on next save" state belongs to the
+    // character it was set on — clear it when switching characters.
+    for (int i = 0; i < SLOT_COUNT; ++i)
+        g_ignoredForSave[i] = false;
     g_loaded = true;
 }
 

src/equipmentset/Storage.h

@@ -22,9 +22,11 @@ namespace EquipmentSet::Storage {
 // Resolves the per-character file path. Returns an empty string until
 // the engine has populated all three session globals (account, realm,
 // character). Path format: `WTF\Account\<acct>\<realm>\<char>\
-// ClassicAPI_EquipmentSets.txt`. Once the engine has the player in
-// world the values are stable for the rest of the session, so callers
-// can cache after the first non-empty return.
+// ClassicAPI_EquipmentSets.txt`. The values are stable only while the
+// current character is in world — they change on a logout→login to a
+// different character (the DLL is NOT reloaded across that transition),
+// so callers must re-resolve and compare rather than caching the first
+// non-empty return permanently. See `Data::EnsureLoaded`.
 std::string ResolveFilePath();
 
 // Reads the file at `path` and overwrites `outSets` with the parsed

src/equipmentset/Tooltip.cpp

@@ -40,11 +40,12 @@
 // `C_EquipmentSet.GetItemIDs` + `C_EquipmentSet.GetItemLocations`
 // themselves.
 //
-// Tooltip filling is done by calling back through Lua (`self:AddLine`
-// etc.) rather than hitting the engine's tooltip-line internals
-// directly. The Lua dispatch goes through the engine's own frame-
-// method registry, so any addon-installed hook on AddLine (DBM,
-// pfUI's tooltip skin, etc.) still runs.
+// Tooltip lines are built with the engine's own primitives — the
+// per-tooltip clear (FUN_GAMETOOLTIP_CLEAR) and the raw add-line
+// (FUN_GAMETOOLTIP_ADD_LINE), the same native path SetTotem and
+// SetHyperlinkCompareItem use; no Lua method dispatch. It shows itself
+// at the end (Script_Show), matching retail: PaperDollFrame.lua sets the
+// anchor then calls SetEquipmentSet with no trailing :Show().
 
 #include "Game.h"
 #include "Offsets.h"
@@ -58,57 +59,41 @@ namespace EquipmentSet::Tooltip {
 
 namespace {
 
-// Calls `self:Method()` with no Lua args. Stack at entry must have
-// the tooltip at index 1 (the standard `frame:method()` self slot).
-// Leaves the stack unchanged.
-void CallSelfNoArgs(void *L, const char *methodName) {
-    Game::Lua::PushValue(L, 1);
-    Game::Lua::PushString(L, methodName);
-    Game::Lua::GetTable(L, -2); // method = self[methodName]
-    Game::Lua::Insert(L, -2);   // [method, self]
-    Game::Lua::Call(L, 1, 0);
+using AddLine_t = void(__thiscall *)(void *self, const char *left, const char *right,
+                                     const void *leftColor, const void *rightColor, int wrap);
+using ClearTooltip_t = void(__fastcall *)(void *self);
+using ShowScript_t = int(__fastcall *)(void *L); // engine's Script_Show
+
+// Packs r,g,b (0..1) into the 0xAARRGGBB value FUN_GAMETOOLTIP_ADD_LINE's
+// color arg wants — its little-endian bytes are the {b,g,r,a} the engine's
+// line-color setter reads. Alpha is always opaque.
+uint32_t Pack(double r, double g, double b) {
+    auto ch = [](double v) {
+        const int i = static_cast<int>(v * 255.0 + 0.5);
+        return static_cast<uint32_t>(i < 0 ? 0 : (i > 255 ? 255 : i));
+    };
+    return 0xFF000000u | (ch(r) << 16) | (ch(g) << 8) | ch(b);
 }
 
-// Calls `self:AddLine(text, r, g, b)`. Same self-on-stack precondition.
-void AddLine(void *L, const char *text, double r, double g, double b) {
-    Game::Lua::PushValue(L, 1);
-    Game::Lua::PushString(L, "AddLine");
-    Game::Lua::GetTable(L, -2);
-    Game::Lua::Insert(L, -2);
-    Game::Lua::PushString(L, text);
-    Game::Lua::PushNumber(L, r);
-    Game::Lua::PushNumber(L, g);
-    Game::Lua::PushNumber(L, b);
-    Game::Lua::Call(L, 5, 0);
+// Left-aligned colored line via the engine's raw add-line. The packed
+// color is a local so its address stays valid across the call.
+void AddColoredLine(void *self, const char *text, double r, double g, double b) {
+    const uint32_t color = Pack(r, g, b);
+    reinterpret_cast<AddLine_t>(Offsets::FUN_GAMETOOLTIP_ADD_LINE)(
+        self, text, nullptr, &color, nullptr, 0);
 }
 
-// Calls `self:SetText(text, r, g, b)`. Same precondition. Used for
-// the header line — `SetText` is the standard vanilla entry for
-// "first line of a fresh tooltip" and handles internal redraw state
-// `AddLine` skips when it's the first content after a clear.
-void SetText(void *L, const char *text, double r, double g, double b) {
-    Game::Lua::PushValue(L, 1);
-    Game::Lua::PushString(L, "SetText");
-    Game::Lua::GetTable(L, -2);
-    Game::Lua::Insert(L, -2);
-    Game::Lua::PushString(L, text);
-    Game::Lua::PushNumber(L, r);
-    Game::Lua::PushNumber(L, g);
-    Game::Lua::PushNumber(L, b);
-    Game::Lua::Call(L, 5, 0); // self + text + r + g + b
-}
-
-// Format-and-add one localized count line. Calls
-// `Game::Lua::PushLocalizedFormatInt` to resolve the format string
-// (Blizzard's FrameXML globals like `ITEMS_EQUIPPED` first, with the
-// C `fallback` for stripped-down servers), then dispatches `AddLine`.
-void AddLocalizedLineInt(void *L, const char *globalName, const char *fallback, int n,
-                         double r, double g, double b) {
+// Adds one localized "N unit" line: `string.format(_G[globalName] or
+// fallback, n)` (the project's GlobalString localize-or-fallback helper,
+// with the C `fallback` for servers stripped of the standard strings),
+// then the native colored add-line.
+void AddLocalizedLineInt(void *L, void *self, const char *globalName,
+                         const char *fallback, int n, double r, double g, double b) {
     const int savedTop = Game::Lua::GetTop(L);
     Game::Lua::PushLocalizedFormatInt(L, globalName, fallback, n);
     const char *text = Game::Lua::ToString(L, -1);
     if (text != nullptr)
-        AddLine(L, text, r, g, b);
+        AddColoredLine(self, text, r, g, b);
     Game::Lua::SetTop(L, savedTop);
 }
 
@@ -185,39 +170,36 @@ int __fastcall Script_GameTooltipSetEquipmentSet(void *L) {
     if (s == nullptr)
         return 0;
 
+    void *self = Game::Lua::ResolveObject(L, 1);
+    if (self == nullptr)
+        return 0;
+
     const Tally t = TallySet(*s);
     const int totalSlots = t.equipped + t.inInventory + t.missing;
 
-    // Trim the Lua stack to just the tooltip self-arg so our internal
-    // method-call sequences don't accumulate the original args past
-    // their useful lifetime. `setName` was a `const char *` lifted out
-    // by ToString — Lua's strings are pinned by reference count, so
-    // dropping the string from the stack doesn't invalidate the
-    // pointer for the lifetime of this call.
-    Game::Lua::SetTop(L, 1);
-
-    // Header — set name, white. Doubles as the "ClearLines" boundary;
-    // SetText replaces line 1 and clears subsequent lines in vanilla.
-    SetText(L, s->name.c_str(), 1.0, 1.0, 1.0);
+    // Header — set name, white. Clear first so it lands as line 0
+    // (the clear resets the line count the add-line body indexes from).
+    reinterpret_cast<ClearTooltip_t>(Offsets::FUN_GAMETOOLTIP_CLEAR)(self);
+    AddColoredLine(self, s->name.c_str(), 1.0, 1.0, 1.0);
 
     // Body lines — try Blizzard's localized FORMAT_* globals first.
     // Same key names retail FrameXML uses (`ITEMS_VARIABLE_QUANTITY`,
     // `ITEMS_EQUIPPED`, ...); addons that need their own wording can
     // override by reassigning `_G[name]` at runtime. The fallbacks
     // only fire on servers stripped of the standard GlobalStrings.
-    AddLocalizedLineInt(L, "ITEMS_VARIABLE_QUANTITY", "%d items",
+    AddLocalizedLineInt(L, self, "ITEMS_VARIABLE_QUANTITY", "%d items",
                         totalSlots, 1.0, 1.0, 1.0);
 
     if (t.equipped > 0) {
-        AddLocalizedLineInt(L, "ITEMS_EQUIPPED", "%d equipped",
+        AddLocalizedLineInt(L, self, "ITEMS_EQUIPPED", "%d equipped",
                             t.equipped, 0.0, 1.0, 0.0); // green
     }
     if (t.inInventory > 0) {
-        AddLocalizedLineInt(L, "ITEMS_IN_INVENTORY", "%d in inventory",
+        AddLocalizedLineInt(L, self, "ITEMS_IN_INVENTORY", "%d in inventory",
                             t.inInventory, 1.0, 1.0, 1.0);
     }
     if (t.ignored > 0) {
-        AddLocalizedLineInt(L, "ITEM_SLOTS_IGNORED", "%d slots ignored",
+        AddLocalizedLineInt(L, self, "ITEM_SLOTS_IGNORED", "%d slots ignored",
                             t.ignored, 0.5, 0.5, 0.5); // gray
     }
     // Missing slots: list each by name using the itemID we stored at
@@ -255,18 +237,20 @@ int __fastcall Script_GameTooltipSetEquipmentSet(void *L) {
         Game::Lua::Call(L, 2, 1);
         const char *line = Game::Lua::ToString(L, -1);
         if (line != nullptr)
-            AddLine(L, line, 1.0, 0.0, 0.0); // red
+            AddColoredLine(self, line, 1.0, 0.0, 0.0); // red
         Game::Lua::SetTop(L, savedTop);
     }
     if (unnamedMissing > 0) {
         // Pre-itemID-format files or items the cache has no record of.
         // No Blizzard format global maps cleanly here; addons can
         // override with `_G.CLASSICAPI_EQUIPMENTSET_MISSING`.
-        AddLocalizedLineInt(L, "CLASSICAPI_EQUIPMENTSET_MISSING",
+        AddLocalizedLineInt(L, self, "CLASSICAPI_EQUIPMENTSET_MISSING",
                             "%d missing", unnamedMissing, 1.0, 0.0, 0.0);
     }
 
-    CallSelfNoArgs(L, "Show");
+    // Show ourselves — self is still at Lua stack index 1 (Script_Show
+    // reads it there). Retail's SetEquipmentSet shows internally too.
+    reinterpret_cast<ShowScript_t>(Offsets::FUN_SCRIPT_FRAME_SHOW)(L);
     return 0;
 }
 

src/event/Custom.cpp

@@ -28,7 +28,17 @@ namespace {
 // any engine code runs. `RetryClaims` (triggered by the
 // `Frame::RegisterEvent` hook) walks this list and claims a NULL slot
 // for each unclaimed entry.
-constexpr int MAX_RESERVED = 32;
+//
+// MUST stay comfortably above the total number of `AutoReserve` instances
+// across the codebase (file-scope + the lazily-registered TTS ones) — the
+// constructor SILENTLY drops any reservation past the cap, and which ones
+// overflow depends on unspecified cross-TU static-init order, so exceeding
+// it makes an arbitrary subset of custom events quietly stop firing (their
+// `Lookup` returns -1 and `Fire` no-ops). We hit exactly that at 32: ~40
+// reservations meant a shifting handful (e.g. ITEM_DATA_LOAD_RESULT /
+// GET_ITEM_INFO_RECEIVED) never claimed a slot. Grep `AutoReserve` before
+// bumping the reservation count near this ceiling.
+constexpr int MAX_RESERVED = 64;
 struct ReservedName {
     const char *name;
     int slot;  // -1 until claimed
@@ -36,6 +46,22 @@ struct ReservedName {
 ReservedName g_reserved[MAX_RESERVED];
 int g_reservedCount = 0;
 bool g_writesEnabled = false;
+// One-shot latch so a genuinely full event table (no NULL slot left to
+// claim) is logged once per session instead of silently dropping the
+// event — the failure mode that would otherwise rot unnoticed. Re-armed on
+// `/reload` (the table is rebuilt fresh). In practice this never triggers:
+// SuperWoW/nampower clamp the FrameXML table to 700 and the engine leaves
+// ~200 NULL gaps in the low range, dwarfing our ~46 reservations. The log is
+// purely a backstop if some future install somehow drains the gap pool.
+bool g_warnedTableFull = false;
+
+// One grow attempt per in-game table build. Reset in `PrepareForReload`
+// (the table is rebuilt fresh on every /reload + logout). See `Grow`.
+bool g_growLatched = false;
+// Debug: force a grow on the next table build regardless of headroom, so
+// the (otherwise dormant) grow path can actually be exercised in-game.
+// Armed by `_classicapi_ForceEventGrow`, consumed by the next `Grow`.
+bool g_forceGrowNext = false;
 
 // Engine's SStrDup at `FUN_STORM_SSTRDUP` — uses `SMemAlloc` internally
 // and is exactly what the engine itself does when filling event table
@@ -51,14 +77,38 @@ char *SStrDup(const char *s) {
     return fn(s, __FILE__, __LINE__);
 }
 
-// Walk the engine's event table from the END looking for a NULL-name
+// Storm allocator/free — the same pair the engine uses for the event-table
+// buffer (see RebuildEventTable), so its reload teardown `SMemFree`s our
+// grown buffer exactly as its own. Both `__stdcall`, 4 args (`ret 0x10`).
+// SMemAlloc flag bit 8 zero-fills (matching SetEventCount's fresh entries).
+void *SMemAlloc(unsigned size) {
+    using SMemAlloc_t = void *(__stdcall *)(unsigned size, const char *file,
+                                            int line, int flags);
+    auto fn = reinterpret_cast<SMemAlloc_t>(Offsets::FUN_STORM_SMEMALLOC);
+    return fn(size, __FILE__, __LINE__, 8 /* zero-fill */);
+}
+void SMemFree(void *ptr) {
+    using SMemFree_t = int(__stdcall *)(void *ptr, const char *file, int line,
+                                        int flags);
+    auto fn = reinterpret_cast<SMemFree_t>(Offsets::FUN_STORM_SMEMFREE);
+    fn(ptr, __FILE__, __LINE__, 0);
+}
+
+// Walk the engine's event table from the LOW end looking for a NULL-name
 // slot. The bulk-init at `0x0051AB30` leaves ~200 NULL gaps scattered
 // through the 548-slot input names array (it only writes ~350 of the
-// slots explicitly; the rest stay zero-initialized from .data). UP
-// and DOWN walks both find these gaps — we go DOWN for convention with
-// VanillaMinimapTracking and so the dump in `_classicapi_DumpAllEvents`
-// shows our events grouped at the tail, visually distinct from engine
-// events.
+// slots explicitly; the rest stay zero-initialized from .data) — a big
+// contiguous hole around 42..106 alone dwarfs our reservation count.
+//
+// We go LOW (ascending) deliberately: SuperWoW and nampower own the HIGH
+// range (fixed event IDs 549..655, and they destructively clamp the table
+// to 700), and other claim-based DLLs (VanillaMinimapTracking) also walk
+// from the tail — so the top is the contested end. Claiming from the low
+// engine gaps keeps us entirely out of their way and independent of their
+// clamp / hook order. The engine's ~200 low NULL gaps dwarf our ~46
+// reservations, so a free slot is essentially always available; the
+// skip-occupied invariant keeps this safe against future engine additions
+// regardless of direction.
 int TryClaim(const char *eventName) {
     if (!g_writesEnabled)
         return -1;
@@ -66,7 +116,7 @@ int TryClaim(const char *eventName) {
     const int count = *reinterpret_cast<int *>(Offsets::VAR_EVENT_TABLE_COUNT);
     if (base == nullptr || count <= 0)
         return -1;
-    for (int i = count - 1; i >= 0; --i) {
+    for (int i = 0; i < count; ++i) {
         auto **namePtr = reinterpret_cast<const char **>(
             base + i * Offsets::EVENT_ENTRY_STRIDE +
             Offsets::OFF_EVENT_ENTRY_NAME);
@@ -78,9 +128,119 @@ int TryClaim(const char *eventName) {
             return i;
         }
     }
+    // Writes are enabled and the table is valid, but every slot is taken —
+    // real capacity exhaustion despite `Grow`. Warn once so it's diagnosable.
+    if (!g_warnedTableFull) {
+        g_warnedTableFull = true;
+        Debug::Log::Printf(
+            "[event] table full (%d slots, no NULL left) — cannot claim '%s'"
+            " and any further custom events; even Grow couldn't make room.",
+            count, eventName ? eventName : "?");
+    }
     return -1;
 }
 
+// On-demand event-table grow. Correctly TIMED: called once per in-game
+// table build from `RetryClaims` (the `frame:RegisterEvent` hook), on the
+// FIRST such call — which is AFTER `RebuildEventTable` has built the fresh
+// table (frames can only register once it exists) but BEFORE any frame has
+// joined a chain (it's the first registration, and we run before the
+// original registers it). So every chain is still an empty self-sentinel,
+// and the buffer can be moved safely.
+//
+// (This is what the removed `EnsureCapacity` got wrong: it ran from
+// `LoadScriptFunctions_h`, BEFORE `RebuildEventTable`, so it saw the stale
+// previous/glue table and always aborted — it never actually grew. The
+// realloc logic itself was fine; only the timing was broken.)
+//
+// Grows only when the engine's low NULL gaps are fewer than our
+// reservations — which never happens in practice (~200 gaps vs ~46
+// reservations), so this is a dormant durability valve. `g_forceGrowNext`
+// (debug) forces it so the path can be exercised. It grows by reallocating
+// the entry buffer with the engine's own Storm allocator and swapping the
+// `{cap@0, count@4, base@8}` globals at `0x00CEEF60` — bypassing
+// SetEventCount's destructive `= 700` clamp. All consumers (RegisterEvent,
+// the dispatcher, SuperWoW, nampower) read the base pointer fresh, so the
+// swap is picked up everywhere; the engine's reload teardown `SMemFree`s
+// our buffer and frees the (shared) name strings via its per-entry helper,
+// exactly as its own.
+void Grow() {
+    if (g_growLatched || !g_writesEnabled)
+        return;
+    g_growLatched = true; // one attempt per build, whether or not it grows
+
+    const int count = *reinterpret_cast<int *>(Offsets::VAR_EVENT_TABLE_COUNT);
+    auto *base = *reinterpret_cast<uint8_t **>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
+    if (base == nullptr || count <= 0 || g_reservedCount <= 0)
+        return;
+
+    int nulls = 0;
+    for (int i = 0; i < count; ++i)
+        if (*reinterpret_cast<const char *const *>(
+                base + i * Offsets::EVENT_ENTRY_STRIDE +
+                Offsets::OFF_EVENT_ENTRY_NAME) == nullptr)
+            ++nulls;
+
+    const bool force = g_forceGrowNext;
+    g_forceGrowNext = false;
+    if (nulls >= g_reservedCount && !force)
+        return; // plenty of room — the common (only) real case
+
+    // Growing moves the buffer, invalidating every entry's self-referential
+    // list anchor, so it's safe ONLY while all chains are empty. We run
+    // before the first registration, so that holds — but VERIFY it (a live
+    // chain means someone registered earlier via a path we didn't intercept;
+    // moving the buffer would corrupt their subscription). Abort if so and
+    // fall back to claim-NULL.
+    for (int i = 0; i < count; ++i) {
+        const uint32_t head = *reinterpret_cast<const uint32_t *>(
+            base + i * Offsets::EVENT_ENTRY_STRIDE + Offsets::OFF_EVENT_ENTRY_HEAD);
+        if (head != 0 && (head & 1) == 0) { // populated chain (not 0 / sentinel)
+            Debug::Log::Printf(
+                "[event] grow aborted — chain live at slot %d (not first-reg)", i);
+            return;
+        }
+    }
+
+    constexpr int kMargin = 16;
+    const int deficit = (nulls < g_reservedCount) ? (g_reservedCount - nulls) : 0;
+    const int newCount = count + deficit + kMargin;
+    auto *newBuf = static_cast<uint8_t *>(
+        SMemAlloc(static_cast<unsigned>(newCount) * Offsets::EVENT_ENTRY_STRIDE));
+    if (newBuf == nullptr)
+        return; // alloc failed — keep the old table; claiming still works
+
+    // Rebuild each entry at its NEW address, mirroring SetEventCount's own
+    // per-entry init: copy the name pointer (shared string, not duplicated);
+    // the `+0x04` field stays 0 (zero-filled, matching the engine); re-init
+    // the anchor as an empty self-sentinel at the new location. Old entries
+    // past the copy and all new entries are already zero-filled + get fresh
+    // anchors. Safe because every chain is empty.
+    for (int i = 0; i < newCount; ++i) {
+        auto *e = reinterpret_cast<uint32_t *>(
+            newBuf + i * Offsets::EVENT_ENTRY_STRIDE);
+        if (i < count) // copy name; new slots stay null
+            e[0] = *reinterpret_cast<const uint32_t *>(
+                base + i * Offsets::EVENT_ENTRY_STRIDE);
+        const uint32_t anchor = static_cast<uint32_t>(
+            reinterpret_cast<uintptr_t>(&e[2])); // entry+0x08
+        e[2] = anchor;      // self-referential list anchor
+        e[3] = anchor | 1;  // empty-chain sentinel head (+0x0C)
+    }
+
+    // Publish base BEFORE count so the globals never advertise more entries
+    // than the buffer holds. Then free the OLD buffer only — the name
+    // strings live on in newBuf and are freed by the reload teardown.
+    *reinterpret_cast<uint8_t **>(Offsets::VAR_EVENT_TABLE_BASE_PTR) = newBuf;
+    *reinterpret_cast<int *>(Offsets::VAR_EVENT_TABLE_CAP) = newCount;
+    *reinterpret_cast<int *>(Offsets::VAR_EVENT_TABLE_COUNT) = newCount;
+    SMemFree(base);
+
+    Debug::Log::Printf("[event] grew table %d -> %d (%d NULL, %d reserved%s)",
+                       count, newCount, nulls, g_reservedCount,
+                       force ? ", FORCED" : "");
+}
+
 } // namespace
 
 AutoReserve::AutoReserve(const char *name) {
@@ -123,6 +283,11 @@ int LookupByName(const char *name) {
 }
 
 void RetryClaims() {
+    // Grow the table first if the low gap pool is short (dormant valve).
+    // Runs at most once per table build; on the first call every chain is
+    // still empty (this is the first registration), which is the only safe
+    // time to move the buffer.
+    Grow();
     for (int i = 0; i < g_reservedCount; ++i) {
         if (g_reserved[i].slot < 0)
             g_reserved[i].slot = TryClaim(g_reserved[i].name);
@@ -135,6 +300,8 @@ void PrepareForReload() {
     for (int i = 0; i < g_reservedCount; ++i)
         g_reserved[i].slot = -1;
     g_writesEnabled = false;
+    g_warnedTableFull = false;  // fresh table after the rebuild — re-arm
+    g_growLatched = false;      // re-arm the one-shot grow for the new table
 }
 
 // Diagnostic Lua functions — registered via the auto-register pattern
@@ -180,10 +347,24 @@ int __fastcall Script_DumpAllEvents(void *) {
     return 0;
 }
 
+// `_classicapi_ForceEventGrow()` — arms a one-shot forced table grow for
+// the NEXT in-game table build, so the (otherwise dormant) grow path can be
+// exercised: call it, then `/reload`. The grow fires at the first
+// `RegisterEvent` after the rebuild (chains still empty) and logs
+// `[event] grew table N -> M (..., FORCED)`. Diagnostic only.
+int __fastcall Script_ForceEventGrow(void *) {
+    g_forceGrowNext = true;
+    Debug::Log::Printf(
+        "[event] force-grow armed — /reload to trigger it on the next build");
+    return 0;
+}
+
 void RegisterDiagnostics() {
     Game::Lua::RegisterGlobalFunction("_classicapi_DumpSlot", &Script_DumpSlot);
     Game::Lua::RegisterGlobalFunction("_classicapi_DumpAllEvents",
                                       &Script_DumpAllEvents);
+    Game::Lua::RegisterGlobalFunction("_classicapi_ForceEventGrow",
+                                      &Script_ForceEventGrow);
 }
 
 const Game::ModuleAutoRegister _autoreg{&RegisterDiagnostics};

src/event/Custom.h

@@ -37,8 +37,9 @@ namespace Event::Custom {
 // DLL operate on the table independently of the others.
 //
 // The name pointer must outlive the engine (a string literal does).
-// Same name reserved twice is deduped; reserving more than 32 names
-// total silently drops the overflow.
+// Same name reserved twice is deduped; reserving more than `MAX_RESERVED`
+// names total (see Custom.cpp) silently drops the overflow — keep that cap
+// above the codebase-wide `AutoReserve` count.
 struct AutoReserve {
     explicit AutoReserve(const char *name);
 };

src/event/EnteringWorld.cpp

@@ -0,0 +1,109 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `PLAYER_ENTERING_WORLD(isInitialLogin, isReloadingUi)` — the 8.0.1 payload,
+// backported. Vanilla fires PEW with no args; backported addons expect the
+// two booleans to distinguish a fresh login from a `/reload` from an
+// instance/zone transition.
+//
+// Delivery: PEW is a no-arg event, so the engine broadcasts it through
+// `FUN_FIRE_EVENT_NO_ARGS` (the `__fastcall(int)` dispatcher), NOT the
+// variadic `FUN_FIRE_EVENT`. We intercept that dispatcher (via the shared
+// `Event::SignalHook`) and, for the PEW event id, suppress the no-arg fire
+// and instead re-broadcast through the variadic `FUN_FIRE_EVENT` with a
+// two-boolean payload. Both fire paths read the same frame chain off the
+// event's table slot, so the frames registered for PEW receive the args
+// exactly once. Booleans use the `%d`/`%s`+nullptr trick (`1` / `nil`), so
+// `if isInitialLogin then …` reads naturally.
+//
+// Flags, from signals we already produce — no PEW-specific engine hook:
+//   - isInitialLogin: our GlueModuleAutoRegister runs on every glue-screen
+//     boot (initial launch + each logout return), so a set latch means "the
+//     next enter-world is a fresh login". The first PEW consumes it.
+//   - isReloadingUi: our ModuleAutoRegister runs whenever the in-game Lua
+//     state is (re)built — login OR `/reload`, but NOT a zone transition. So
+//     "script re-init happened and it wasn't the fresh login" == a reload.
+//   - Instance/zone transition rebuilds neither, so both latches are clear →
+//     both false, matching retail.
+
+#include "Game.h"
+#include "event/Custom.h"
+#include "event/SignalHook.h"
+
+namespace Event::EnteringWorld {
+
+namespace {
+
+// Set on glue-screen boot; a pending latch means the next enter-world is a
+// fresh character login (from the login/char-select screen).
+bool g_atGlue = false;
+// Set when the in-game Lua state is (re)built (login or /reload).
+bool g_scriptReloaded = false;
+// Cached PLAYER_ENTERING_WORLD event-table slot; -1 = unresolved. Reset per
+// in-game init (the table is rebuilt, though engine slots are stable) and
+// re-resolved lazily at fire time.
+int g_pewId = -1;
+
+int PewId() {
+    if (g_pewId < 0)
+        g_pewId = Event::Custom::LookupByName("PLAYER_ENTERING_WORLD");
+    return g_pewId;
+}
+
+// Shared-hook interceptor. For PEW, re-broadcast with the payload and
+// suppress the engine's no-arg fire; everything else passes through.
+bool Intercept(int eventID) {
+    const int pew = PewId();
+    if (pew < 0 || eventID != pew)
+        return false;
+
+    const bool isInitialLogin = g_atGlue;
+    g_atGlue = false;
+    const bool isReloadingUi = !isInitialLogin && g_scriptReloaded;
+    g_scriptReloaded = false;
+
+    // Re-fire through the variadic dispatcher with the two booleans. true → 1
+    // (%d), false → nil (%s + nullptr, which the dispatcher's pushstring
+    // tail-jumps to pushnil).
+    auto *const kNil = static_cast<const char *>(nullptr);
+    if (isInitialLogin && isReloadingUi)
+        Event::Custom::Fire(pew, "%d%d", 1, 1);
+    else if (isInitialLogin)
+        Event::Custom::Fire(pew, "%d%s", 1, kNil);
+    else if (isReloadingUi)
+        Event::Custom::Fire(pew, "%s%d", kNil, 1);
+    else
+        Event::Custom::Fire(pew, "%s%s", kNil, kNil);
+    return true; // handled — suppress the original no-arg PEW fire
+}
+
+const Event::SignalHook::AutoSubscribe _intercept{&Intercept};
+
+// In-game Lua (re)init: login or /reload rebuilt the script state (never a
+// zone transition). Also re-arm the PEW slot lookup — the event table was
+// rebuilt.
+void OnInGameInit() {
+    g_scriptReloaded = true;
+    g_pewId = -1;
+}
+
+// Glue-screen boot: we're at the login/char-select screen, so the next
+// enter-world will be a fresh login.
+void OnGlueInit() { g_atGlue = true; }
+
+const Game::ModuleAutoRegister _inGame{&OnInGameInit};
+const Game::GlueModuleAutoRegister _glue{&OnGlueInit};
+
+} // namespace
+
+} // namespace Event::EnteringWorld

src/event/Registered.cpp

@@ -0,0 +1,98 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `GetFramesRegisteredForEvent(event)` → the Frame objects currently
+// subscribed to `event`, returned as multiple return values (matching
+// modern WoW's vararg signature — not a table). Empty result set returns
+// nothing.
+//
+// The engine already keeps exactly this list: every `frame:RegisterEvent`
+// appends the frame to a subscriber chain hanging off the matching event
+// table entry. We find the entry by name (same table `Event::Custom`
+// walks), then walk the chain the same way `Frame::RegisterEvent`
+// (`FUN_00702140`) does — node next at `+0x04`, subscriber frame at
+// `+0x08`, with a low-bit-set / null value marking the end sentinel — and
+// push each frame via the shared `UI::FrameObject::Push` so callers get
+// the canonical wrapper table (real frame methods, `:GetName()`, etc.).
+//
+// Event names resolve through `Event::Custom::LookupByName`, so this also
+// works for our `AutoReserve`-claimed custom events, not just engine ones.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "event/Custom.h"
+#include "ui/FrameObject.h"
+
+#include <cstdint>
+
+namespace Event::Registered {
+
+namespace {
+
+int __fastcall Script_GetFramesRegisteredForEvent(void *L) {
+    if (!Game::Lua::IsString(L, 1))
+        return 0;
+    const char *event = Game::Lua::ToString(L, 1);
+    if (event == nullptr)
+        return 0;
+
+    const int slot = Event::Custom::LookupByName(event);
+    if (slot < 0)
+        return 0;
+
+    auto *base = *reinterpret_cast<uint8_t **>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
+    if (base == nullptr)
+        return 0;
+
+    const uint8_t *entry = base + slot * Offsets::EVENT_ENTRY_STRIDE;
+    const uintptr_t head = *reinterpret_cast<const uintptr_t *>(
+        entry + Offsets::OFF_EVENT_ENTRY_HEAD);
+
+    // First pass: count subscribers so we can reserve stack up front — an
+    // event with many registered frames would otherwise risk overflowing
+    // the default Lua stack slack as we push.
+    int count = 0;
+    for (uintptr_t node = head; (node & 1) == 0 && node != 0;
+         node = *reinterpret_cast<const uintptr_t *>(
+             node + Offsets::OFF_EVENT_NODE_NEXT)) {
+        if (*reinterpret_cast<void *const *>(node + Offsets::OFF_EVENT_NODE_FRAME))
+            ++count;
+    }
+    if (count == 0)
+        return 0;
+    Game::Lua::CheckStack(L, count);
+
+    int pushed = 0;
+    for (uintptr_t node = head; (node & 1) == 0 && node != 0;
+         node = *reinterpret_cast<const uintptr_t *>(
+             node + Offsets::OFF_EVENT_NODE_NEXT)) {
+        void *frame = *reinterpret_cast<void *const *>(
+            node + Offsets::OFF_EVENT_NODE_FRAME);
+        if (frame != nullptr) {
+            UI::FrameObject::Push(L, frame);
+            ++pushed;
+        }
+    }
+    return pushed;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterGlobalFunction("GetFramesRegisteredForEvent",
+                                      &Script_GetFramesRegisteredForEvent);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace Event::Registered

src/event/SignalHook.cpp

@@ -0,0 +1,49 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#include "SignalHook.h"
+
+#include "Game.h"
+#include "Offsets.h"
+
+namespace Event::SignalHook {
+
+namespace {
+
+// Chained at static-init time by each `AutoSubscribe` constructor, before
+// `DllMain`. Zero-initialized (namespace static) ahead of any dynamic init,
+// so the head is valid when subscribers link in.
+AutoSubscribe *g_head = nullptr;
+
+// `FUN_FIRE_EVENT_NO_ARGS` is `__fastcall(int eventID)`; we mirror loot's
+// long-standing shape with a dummy EDX so the trampoline call matches the
+// register layout, and forward `0` for it (unused by the callee).
+using FireNoArgs_t = void(__fastcall *)(int eventID, int edx);
+FireNoArgs_t g_orig = nullptr;
+
+void __fastcall Hook(int eventID, int /*edx*/) {
+    for (AutoSubscribe *s = g_head; s != nullptr; s = s->next)
+        if (s->fn(eventID))
+            return; // a subscriber handled it — suppress the original fire
+    g_orig(eventID, 0);
+}
+
+const Game::HookAutoRegister _hook{
+    Offsets::FUN_FIRE_EVENT_NO_ARGS, reinterpret_cast<void *>(&Hook),
+    reinterpret_cast<void **>(&g_orig)};
+
+} // namespace
+
+AutoSubscribe::AutoSubscribe(Interceptor f) : fn(f), next(g_head) { g_head = this; }
+
+} // namespace Event::SignalHook

src/event/SignalHook.h

@@ -0,0 +1,47 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+// Shared interceptor for the engine's no-arg event dispatcher
+// `FUN_FIRE_EVENT_NO_ARGS` (`0x00703E50`) — the `__fastcall(int eventID)`
+// path every no-arg event broadcast goes through (PLAYER_ENTERING_WORLD,
+// LOOT_OPENED/CLOSED, zone changes, …), as opposed to the variadic
+// `FUN_FIRE_EVENT` used by events that carry a printf-style payload.
+//
+// MinHook allows only ONE hook per target address, and more than one feature
+// needs to intercept this dispatcher (loot silent-scan suppression, the
+// PLAYER_ENTERING_WORLD payload). So — exactly like `Tick::WorldTick` for the
+// per-frame tick — this module owns the single hook and fans out to
+// subscribers. Declare a file-scope `static const
+// Event::SignalHook::AutoSubscribe` in your module.
+//
+// An interceptor returns `true` when it has fully handled `eventID` and the
+// engine's original no-arg fire must be SUPPRESSED — either because it
+// swallowed the event (loot) or re-fired it a different way (the PEW payload
+// re-broadcasts through the variadic `FUN_FIRE_EVENT` with args). Returning
+// `false` lets the event fall through to the next subscriber and ultimately
+// the original. The FIRST subscriber to return `true` wins and the original
+// is skipped, so subscribers must claim disjoint event ids.
+
+namespace Event::SignalHook {
+
+using Interceptor = bool (*)(int eventID);
+
+struct AutoSubscribe {
+    explicit AutoSubscribe(Interceptor fn);
+    Interceptor fn;
+    AutoSubscribe *next;
+};
+
+} // namespace Event::SignalHook

src/friendlist/Who.cpp

@@ -282,7 +282,25 @@ void RegisterLuaFunctions() {
                                      &Script_C_FriendList_IsWhoQueryPending);
 }
 
+// Clear transient /who state on every in-game Lua (re)build — login OR
+// /reload. The DLL survives a logout→character-select→login, so a query
+// whose SMSG_WHO response never crossed that boundary would otherwise leave
+// g_inFlight stuck (IsWhoQueryPending() wrongly true for the next character)
+// and our VAR_WHO_TO_UI_FLAG override forced on (routing the next
+// character's unrelated /who to the WhoList). ResetIfStuck only heals this
+// lazily on a *subsequent* send; a fresh-init reset makes every character
+// start clean. RestoreFlagIfOwned puts the engine flag back to the value we
+// snapshotted before overriding. ModuleAutoRegister fires per login and per
+// /reload, before any addon runs, so this always precedes a new burst.
+void ResetState() {
+    g_inFlight = 0;
+    RestoreFlagIfOwned();
+    g_haveSent = false;
+    g_lastSendTick = 0;
+}
+
 const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+const Game::ModuleAutoRegister _resetOnInit{&ResetState};
 
 } // namespace
 

src/gameobject/ClosestPosition.cpp

@@ -0,0 +1,64 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `ClosestGameObjectPosition(gameObjectID)` → `xPos, yPos, distance` — the
+// world position of the nearest game object with the given
+// game-object-template ID, and its distance from the player in yards.
+// Returns nothing when none is found (the `MayReturnNothing` contract).
+//
+// The game-object analog of `ClosestUnitPosition`; same shared scan
+// (Object::ClosestByEntry), just filtering on the GameObject GUID type
+// (`0xF110`) and `TYPEMASK_GAMEOBJECT`. Same retail-vs-vanilla caveat:
+// this returns the nearest CURRENTLY-VISIBLE object of that entry rather
+// than reading retail's static starting-zone database (which vanilla
+// doesn't have).
+
+#include "Game.h"
+#include "Offsets.h"
+#include "guid/Guid.h"
+#include "object/ClosestByEntry.h"
+
+#include <cmath>
+#include <cstdint>
+
+namespace GameObject::ClosestPosition {
+
+namespace {
+
+int __fastcall Script_ClosestGameObjectPosition(void *L) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, "Usage: ClosestGameObjectPosition(gameObjectID)");
+        return 0;
+    }
+    const auto entry = static_cast<uint32_t>(Game::Lua::ToNumber(L, 1));
+    const Object::ClosestByEntry::Result r = Object::ClosestByEntry::Find(
+        Offsets::TYPEMASK_GAMEOBJECT, Guid::Type::GameObject, entry);
+    if (!r.found)
+        return 0;
+
+    Game::Lua::PushNumber(L, static_cast<double>(r.x));
+    Game::Lua::PushNumber(L, static_cast<double>(r.y));
+    Game::Lua::PushNumber(L, std::sqrt(static_cast<double>(r.distSq)));
+    return 3;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterGlobalFunction("ClosestGameObjectPosition",
+                                      &Script_ClosestGameObjectPosition);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace GameObject::ClosestPosition

src/group/MemberStats.cpp

@@ -0,0 +1,112 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#include "group/MemberStats.h"
+
+#include "Offsets.h"
+
+namespace Group::MemberStats {
+
+namespace {
+
+// Both roster lookups are `__fastcall(u64 *guid) -> block*` (NULL on miss).
+using Lookup_t = const uint8_t *(__fastcall *)(uint64_t *guid);
+
+uint16_t U16(const uint8_t *p, int off) {
+    return *reinterpret_cast<const uint16_t *>(p + off);
+}
+
+} // namespace
+
+Stats Lookup(uint64_t guid) {
+    Stats s;
+    if (guid == 0)
+        return s;
+
+    // Party stats block — the full record.
+    auto statsFn = reinterpret_cast<Lookup_t>(
+        static_cast<uintptr_t>(Offsets::FUN_GROUP_MEMBER_STATS_LOOKUP));
+    if (const uint8_t *e = statsFn(&guid)) {
+        s.valid = true;
+        s.full = true;
+        s.powerType = e[Offsets::OFF_GROUP_MEMBER_STATS_POWER_TYPE];
+        s.health = U16(e, Offsets::OFF_GROUP_MEMBER_STATS_HEALTH);
+        s.maxHealth = U16(e, Offsets::OFF_GROUP_MEMBER_STATS_MAX_HEALTH);
+        s.power = U16(e, Offsets::OFF_GROUP_MEMBER_STATS_POWER);
+        s.maxPower = U16(e, Offsets::OFF_GROUP_MEMBER_STATS_MAX_POWER);
+        s.level = U16(e, Offsets::OFF_GROUP_MEMBER_STATS_LEVEL);
+        s.areaId = U16(e, Offsets::OFF_GROUP_MEMBER_AREA_ID);
+        s.online = (e[Offsets::OFF_GROUP_MEMBER_STATUS_FLAGS] &
+                    Offsets::GROUP_MEMBER_STATUS_ONLINE) != 0;
+        // The party stats block carries no dead / subgroup / rank fields; those
+        // are raid-only (dead comes from UnitIsDead on the live unit otherwise).
+        return s;
+    }
+
+    // Raid slot — same struct GetRaidRosterInfo reads.
+    auto slotFn = reinterpret_cast<Lookup_t>(
+        static_cast<uintptr_t>(Offsets::FUN_GROUP_MEMBER_SLOT_LOOKUP));
+    if (const uint8_t *e = slotFn(&guid)) {
+        s.valid = true;
+        s.full = false;
+        s.powerType = e[Offsets::OFF_RAID_SLOT_POWER_TYPE];
+        s.health = U16(e, Offsets::OFF_RAID_SLOT_HEALTH);
+        s.maxHealth = U16(e, Offsets::OFF_RAID_SLOT_MAX_HEALTH);
+        s.power = U16(e, Offsets::OFF_RAID_SLOT_POWER);
+        s.maxPower = U16(e, Offsets::OFF_RAID_SLOT_MAX_POWER);
+        s.level = U16(e, Offsets::OFF_RAID_SLOT_LEVEL);
+        s.areaId = U16(e, Offsets::OFF_RAID_SLOT_AREA_ID);
+        const uint32_t flags =
+            *reinterpret_cast<const uint32_t *>(e + Offsets::OFF_RAID_SLOT_FLAGS);
+        s.online = (flags & Offsets::RAID_SLOT_FLAG_ONLINE) != 0;
+        s.dead = (flags & Offsets::RAID_SLOT_FLAG_DEAD) != 0;
+        s.subgroup = static_cast<int>(*reinterpret_cast<const uint32_t *>(
+                         e + Offsets::OFF_RAID_SLOT_SUBGROUP)) + 1;
+        s.rank = static_cast<int>(
+            *reinterpret_cast<const uint32_t *>(e + Offsets::OFF_RAID_SLOT_RANK));
+        return s;
+    }
+
+    return s;
+}
+
+const uint16_t *AuraArray(uint64_t guid) {
+    if (guid == 0)
+        return nullptr;
+
+    // Party stats block first — auras at +0x1a, but only for an online member
+    // (the engine's Script_UnitBuff bails on the party path when the online bit
+    // is clear).
+    auto statsFn = reinterpret_cast<Lookup_t>(
+        static_cast<uintptr_t>(Offsets::FUN_GROUP_MEMBER_STATS_LOOKUP));
+    if (const uint8_t *e = statsFn(&guid)) {
+        if ((e[Offsets::OFF_GROUP_MEMBER_STATUS_FLAGS] &
+             Offsets::GROUP_MEMBER_STATUS_ONLINE) == 0)
+            return nullptr;
+        return reinterpret_cast<const uint16_t *>(
+            e + Offsets::OFF_GROUP_MEMBER_STATS_AURAS);
+    }
+
+    // Raid slot — auras at +0x64, no online gate (mirrors the engine's raid
+    // branch, which reads the array unconditionally).
+    auto slotFn = reinterpret_cast<Lookup_t>(
+        static_cast<uintptr_t>(Offsets::FUN_GROUP_MEMBER_SLOT_LOOKUP));
+    if (const uint8_t *e = slotFn(&guid)) {
+        return reinterpret_cast<const uint16_t *>(
+            e + Offsets::OFF_RAID_SLOT_AURAS);
+    }
+
+    return nullptr;
+}
+
+} // namespace Group::MemberStats

src/group/MemberStats.h

@@ -0,0 +1,67 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <cstdint>
+
+namespace Group::MemberStats {
+
+// Cached stats for a party/raid member, read from the group roster
+// (fed by SMSG_PARTY_MEMBER_STATS). This is the ONLY source for a member with
+// no live CGUnit — a groupmate on a different map or otherwise out of range —
+// and is exactly what the engine's UnitHealth / UnitMana fall back to. Any
+// module that reads unit fields off the descriptor should consult this when
+// the descriptor is unavailable so it doesn't report 0 for out-of-range
+// groupmates.
+//
+// `full` distinguishes the two backing structures: the party stats block and
+// the raid slot. Both carry health / power / level / area / online; `dead`,
+// `subgroup`, and `rank` come only from the raid slot (0 / false on the party
+// path). Power values are RAW (divide by the power divisor for display);
+// health is the roster u16, matching what UnitHealth returns out of range.
+struct Stats {
+    bool valid = false;
+    bool full = false;       // true = party stats block; false = raid slot
+    int powerType = 0;
+    uint32_t health = 0;
+    uint32_t maxHealth = 0;
+    uint32_t power = 0;      // raw (pre-divisor)
+    uint32_t maxPower = 0;   // raw (pre-divisor)
+    int level = 0;
+    int areaId = 0;          // AreaTable.dbc ID
+    bool online = false;
+    bool dead = false;       // raid slot only
+    int subgroup = 0;        // raid slot only, 1-based (0 = party path)
+    int rank = 0;            // raid slot only
+};
+
+// Look up a member by GUID. Tries the party stats block, then the raid slot,
+// mirroring the engine's UnitHealth/UnitMana out-of-range fallback. Returns an
+// invalid `Stats` (`valid == false`) when the GUID isn't a rostered member.
+// Pure — no Lua, no throw; safe from any context.
+Stats Lookup(uint64_t guid);
+
+// Pointer to an out-of-range groupmate's 48-slot aura spell-ID array (buffs
+// 0..31, debuffs 32..47), or nullptr if `guid` isn't a rostered member — or is
+// an *offline* party member (the engine surfaces no auras for those). Mirrors
+// the engine's own out-of-range fallback in Script_UnitBuff/Script_UnitDebuff
+// exactly: the party stats block at +OFF_GROUP_MEMBER_STATS_AURAS gated on the
+// online flag, else the raid slot at +OFF_RAID_SLOT_AURAS. Spell IDs only —
+// SMSG_PARTY_MEMBER_STATS carries no caster/duration/stacks, and truncates IDs
+// to u16 (custom IDs > 65535 are wrong; same as the built-in UnitBuff). The
+// pointer is into live engine memory — read it immediately, don't cache it.
+// Pure — no Lua, no throw; safe from any context.
+const uint16_t *AuraArray(uint64_t guid);
+
+} // namespace Group::MemberStats

src/item/BagFamily.cpp

@@ -0,0 +1,80 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#include "item/BagFamily.h"
+
+#include "Offsets.h"
+
+namespace Item::BagFamily {
+
+namespace {
+
+// Chained at static-init by each `AutoResolver` constructor, before
+// `DllMain`. Zero-initialized (namespace static) ahead of any dynamic
+// init, so the head is valid when resolvers link in.
+AutoResolver *g_resolvers = nullptr;
+
+// Stock vanilla bags/quivers that shipped with an empty `m_bagFamily`
+// field, recovered from (class, subclass). Correspondence cross-referenced
+// by name between ItemSubClass.dbc and ItemBagFamily.dbc. Everything else
+// in stock vanilla either carries the field directly or has no family, so
+// it isn't listed — server-custom bags come in through the resolver chain.
+uint32_t StockSubclassToId(uint32_t itemClass, uint32_t subclass) {
+    if (itemClass == kItemClassContainer) {
+        switch (subclass) {
+        case 1:  return 3;   // Soul Bag        → Soul Shards
+        case 2:  return 6;   // Herb Bag        → Herbs
+        case 3:  return 7;   // Enchanting Bag  → Enchanting Supplies
+        case 4:  return 8;   // Engineering Bag → Engineering Supplies
+        default: return 0;
+        }
+    }
+    if (itemClass == kItemClassQuiver) {
+        switch (subclass) {
+        case 2:  return 1;   // Quiver     → Arrows
+        case 3:  return 2;   // Ammo Pouch → Bullets
+        default: return 0;
+        }
+    }
+    return 0;
+}
+
+} // namespace
+
+AutoResolver::AutoResolver(Resolver f) : fn(f), next(g_resolvers) {
+    g_resolvers = this;
+}
+
+uint32_t SubclassToId(uint32_t itemClass, uint32_t subclass) {
+    if (const uint32_t id = StockSubclassToId(itemClass, subclass))
+        return id;
+    for (AutoResolver *r = g_resolvers; r != nullptr; r = r->next)
+        if (const uint32_t id = r->fn(itemClass, subclass))
+            return id;
+    return 0;
+}
+
+uint32_t BitmaskForRecord(const uint8_t *record) {
+    uint32_t rawId = *reinterpret_cast<const uint32_t *>(
+        record + Offsets::OFF_ITEMSTATS_BAG_FAMILY);
+    if (rawId == 0) {
+        const uint32_t cls = *reinterpret_cast<const uint32_t *>(
+            record + Offsets::OFF_ITEMSTATS_CLASS);
+        const uint32_t sub = *reinterpret_cast<const uint32_t *>(
+            record + Offsets::OFF_ITEMSTATS_SUBCLASS);
+        rawId = SubclassToId(cls, sub);
+    }
+    return IdToBitmask(rawId);
+}
+
+} // namespace Item::BagFamily

src/item/BagFamily.h

@@ -0,0 +1,72 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <cstdint>
+
+// Shared BagFamily derivation for a cached `ItemStats_C` record. Used by
+// `C_Item.GetItemFamily` and `C_Container.GetContainerNumFreeSlots` /
+// `CalculateTotalNumberOfFreeBagSlots` so the family a bag reports matches
+// the family the items it holds report.
+//
+// This module knows only STOCK vanilla data. Server-custom container
+// families (e.g. Turtle's cooking/gathering bags) plug in through the
+// `AutoResolver` extension point below, so non-stock hardcoded data lives
+// in its own module (see `src/turtle/`) rather than here.
+namespace Item::BagFamily {
+
+// Item.dbc `m_class` values. Containers hold the profession/soul bags;
+// Quivers hold arrows (subclass 2) and bullets/ammo pouches (subclass 3).
+// See ItemClass.dbc.
+constexpr uint32_t kItemClassContainer = 1;
+constexpr uint32_t kItemClassQuiver = 11;
+
+// Convert 1.12's raw 1-based `ItemBagFamily.dbc` ID to the modern bitmask
+// encoding (`1 << (id - 1)`); `0` stays `0`. Vanilla stores the raw ID
+// (`arrow=1, bullet=2, soul shard=3, herb=6, …`); Wrath+ flipped the same
+// field to the bitmask form, which is what backported addons expect.
+inline uint32_t IdToBitmask(uint32_t rawId) {
+    return (rawId == 0) ? 0 : (1u << (rawId - 1));
+}
+
+// (class, subclass) → `ItemBagFamily.dbc` raw ID, for bags/quivers whose
+// `m_bagFamily` field shipped empty. Covers the stock vanilla profession
+// bags (Container class: Soul/Herb/Enchanting/Engineering) and quivers
+// (Quiver class: Quiver→arrows, Ammo Pouch→bullets); for anything else it
+// consults the registered custom resolvers (see `AutoResolver`) before
+// giving up with `0`. Keyed on class because subclass numbers repeat
+// across classes (Container subclass 2 = Herb Bag, Quiver subclass 2 =
+// Quiver). Returns a raw family ID, not a bitmask.
+uint32_t SubclassToId(uint32_t itemClass, uint32_t subclass);
+
+// BagFamily bitmask for a cached `ItemStats_C` record: the item's
+// `m_bagFamily` field if populated, otherwise — for a container whose
+// field is empty — derived from the container subclass. Pass a non-null
+// record.
+uint32_t BitmaskForRecord(const uint8_t *record);
+
+// Extension point for server-custom bag families. A resolver maps a
+// (class, subclass) pair to an `ItemBagFamily.dbc` raw ID, or returns `0`
+// if it doesn't recognize it. Consulted by `SubclassToId` only after the
+// stock table misses. Declare a file-scope
+// `static const Item::BagFamily::AutoResolver` in a platform module to
+// register one at static-init time.
+using Resolver = uint32_t (*)(uint32_t itemClass, uint32_t subclass);
+struct AutoResolver {
+    explicit AutoResolver(Resolver fn);
+    Resolver fn;
+    AutoResolver *next;
+};
+
+} // namespace Item::BagFamily

src/item/Count.cpp

@@ -11,6 +11,8 @@
 // You should have received a copy of the GNU General Public License along with
 // ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
 
+#include "item/Count.h"
+
 #include "Game.h"
 #include "Offsets.h"
 #include "item/Arg.h"
@@ -251,6 +253,15 @@ int __fastcall Script_C_Item_GetItemCount(void *L) {
 
 } // namespace
 
+int InInventory(void *L, int itemID) {
+    if (itemID <= 0)
+        return 0;
+    int total = CountEquipped(itemID, /*includeUses*/ false);
+    for (int bag = 0; bag <= 4; bag++)
+        total += CountInBag(L, bag, itemID, /*includeUses*/ false);
+    return total;
+}
+
 static void RegisterLuaFunctions() {
     Game::Lua::RegisterTableFunction("C_Item", "GetItemCount",
                                      &Script_C_Item_GetItemCount);

src/item/Count.h

@@ -0,0 +1,25 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+namespace Item::Count {
+
+// Total plain stack count of `itemID` across the player's equipped slots
+// and bags 0..4 (no bank, no charge multiplier) — the "carried on me"
+// count. Needs the Lua state `L`: the bag walk uses the engine's slot
+// packer, which reads and clears the Lua stack, so the caller must have
+// already consumed any stack arguments it still needs before calling.
+int InInventory(void *L, int itemID);
+
+} // namespace Item::Count

src/item/Info.cpp

@@ -15,8 +15,10 @@
 #include "Offsets.h"
 #include "dbc/Lookup.h"
 #include "item/Arg.h"
+#include "item/BagFamily.h"
 #include "item/Data.h"
 #include "item/ID.h"
+#include "item/Link.h"
 #include "item/Location.h"
 
 #include <cstdint>
@@ -191,17 +193,6 @@ static int __fastcall Script_C_Item_GetItemIconByID(void *L) {
     return PushIconForItemID(L, Item::Arg::ResolveItemID(L, 1));
 }
 
-// Convert 1.12's raw `BagFamily` ID to the modern bitmask encoding.
-// Vanilla stores `arrow=1, bullet=2, soul shard=3, herb=6, ...`; Wrath
-// flipped to `1 << (ID-1)` (`arrow=0x1, bullet=0x2, soul shard=0x4,
-// herb=0x20, ...`) and addons backported from Wrath+ expect the
-// bitmask. We always surface the modern shape so callers don't have to
-// branch on client version. See `Offsets::OFF_ITEMSTATS_BAG_FAMILY`
-// for the empirical verification.
-uint32_t BagFamilyIdToBitmask(uint32_t rawId) {
-    return (rawId == 0) ? 0 : (1u << (rawId - 1));
-}
-
 // `C_Item.GetItemFamily(item)` — returns the BagFamily bitmask for an
 // item (modern encoding: `1 << (ID-1)`), or `nil` if the item isn't
 // in the cache. Used by auto-routing addons that decide which
@@ -226,10 +217,14 @@ uint32_t BagFamilyIdToBitmask(uint32_t rawId) {
 // but has family 0 (general-purpose)". Both are safe to treat as "no
 // preference" but keeping them distinct helps debugging.
 //
-// 1.12 vanilla server data sparsely populates the field for **bags**
-// themselves (only quivers seem to carry it on Turtle WoW). Individual
-// loot items do carry the field reliably (arrows, bullets, shards,
-// herbs all return their proper raw IDs).
+// 1.12 vanilla server data leaves the `m_bagFamily` field empty on the
+// **bags/quivers** themselves — Soul/Herb/Enchanting/Engineering bags AND
+// quivers/ammo pouches all read 0. Individual loot items do carry the
+// field reliably (arrows, bullets, shards, herbs return their proper raw
+// IDs). For a bag whose field is empty we recover the family from its
+// class + subclass (the same signal the "Soul Bag" tooltip line uses), so
+// a Felcloth Bag reports the Soul Shard family (0x4), a quiver 0x1, an
+// ammo pouch 0x2 — see `Item::BagFamily`.
 static int __fastcall Script_C_Item_GetItemFamily(void *L) {
     const int itemID = Item::Arg::ResolveItemID(L, 1);
     if (itemID <= 0)
@@ -239,13 +234,96 @@ static int __fastcall Script_C_Item_GetItemFamily(void *L) {
         Item::Data::WarmCache(static_cast<uint32_t>(itemID));
         return 0;
     }
-    const uint32_t rawId = *reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_BAG_FAMILY);
-    Game::Lua::PushNumber(L, static_cast<double>(BagFamilyIdToBitmask(rawId)));
+    // Family field if populated, else derived from the container subclass
+    // (Turtle leaves bags' m_bagFamily at 0 — see Item::BagFamily).
+    Game::Lua::PushNumber(
+        L, static_cast<double>(Item::BagFamily::BitmaskForRecord(record)));
     return 1;
 }
 
+// `C_Item.GetItemInfo(itemInfo)` — the full modern info tuple, sourced
+// entirely from the cached `ItemStats_C` record (+ the class/subclass/invtype
+// DBC name lookups this file already does for `GetItemInfoInstant`). Accepts
+// a numeric itemID, an `"item:NNN"` string, or a full chat link — same parser
+// as `GetItemInfoInstant`.
+//
+// Returns (18 values):
+//   itemName, itemLink, itemQuality, itemLevel, itemMinLevel, itemType,
+//   itemSubType, itemStackCount, itemEquipLoc, itemTexture, sellPrice,
+//   classID, subclassID, bindType, expansionID, setID, isCraftingReagent,
+//   itemDescription
+//
+// `expansionID` is always 0 (vanilla) and `isCraftingReagent` always false
+// (no such flag in 1.12's item data); `setID` is nil when the item has no
+// set. On a cache miss it warms the cache and returns nothing (nil) —
+// the value lands on a retry after `GET_ITEM_INFO_RECEIVED`,
+// matching the modern async contract.
+static int __fastcall Script_C_Item_GetItemInfo(void *L) {
+    const int itemID = Item::Arg::ResolveItemID(L, 1);
+    if (itemID <= 0)
+        return 0;
+
+    const uint8_t *record = FetchItemRecord(static_cast<uint32_t>(itemID));
+    if (record == nullptr) {
+        Item::Data::WarmCache(static_cast<uint32_t>(itemID));
+        return 0; // nil this call; GET_ITEM_INFO_RECEIVED fires when ready
+    }
+
+    auto u32 = [record](int off) {
+        return *reinterpret_cast<const uint32_t *>(record + off);
+    };
+    const uint32_t quality = u32(Offsets::OFF_ITEMSTATS_QUALITY);
+    const uint32_t itemLevel = u32(Offsets::OFF_ITEMSTATS_ITEM_LEVEL);
+    const uint32_t reqLevel = u32(Offsets::OFF_ITEMSTATS_REQUIRED_LEVEL);
+    const uint32_t classID = u32(Offsets::OFF_ITEMSTATS_CLASS);
+    const uint32_t subClassID = u32(Offsets::OFF_ITEMSTATS_SUBCLASS);
+    const uint32_t stackCount = u32(Offsets::OFF_ITEMSTATS_STACKABLE);
+    const uint32_t invType = u32(Offsets::OFF_ITEMSTATS_INVENTORY_TYPE);
+    const uint32_t displayInfoID = u32(Offsets::OFF_ITEMSTATS_DISPLAY_INFO_ID);
+    const uint32_t sellPrice = u32(Offsets::OFF_ITEMSTATS_SELL_PRICE);
+    const uint32_t bindType = u32(Offsets::OFF_ITEMSTATS_BONDING);
+    const uint32_t setID = u32(Offsets::OFF_ITEMSTATS_ITEM_SET);
+    const char *name = *reinterpret_cast<const char *const *>(
+        record + Offsets::OFF_ITEMSTATS_NAME);
+    const char *description = *reinterpret_cast<const char *const *>(
+        record + Offsets::OFF_ITEMSTATS_DESCRIPTION);
+
+    char iconPath[260];
+    if (!BuildIconPath(displayInfoID, iconPath, sizeof(iconPath)))
+        iconPath[0] = 0;
+    char link[256];
+    const bool haveLink = Item::Link::BasicFromItemID(static_cast<uint32_t>(itemID),
+                                                      link, sizeof(link));
+
+    Game::Lua::PushString(L, PushedOrEmpty(name));                    // 1  itemName
+    if (haveLink)
+        Game::Lua::PushString(L, link);                              // 2  itemLink
+    else
+        Game::Lua::PushNil(L);
+    Game::Lua::PushNumber(L, static_cast<double>(quality));           // 3  itemQuality
+    Game::Lua::PushNumber(L, static_cast<double>(itemLevel));         // 4  itemLevel
+    Game::Lua::PushNumber(L, static_cast<double>(reqLevel));          // 5  itemMinLevel
+    Game::Lua::PushString(L, LookupItemClassName(classID));           // 6  itemType
+    Game::Lua::PushString(L, LookupItemSubClassName(classID, subClassID)); // 7 itemSubType
+    Game::Lua::PushNumber(L, static_cast<double>(stackCount));        // 8  itemStackCount
+    Game::Lua::PushString(L, LookupInvType(invType));                 // 9  itemEquipLoc
+    Game::Lua::PushString(L, iconPath);                               // 10 itemTexture
+    Game::Lua::PushNumber(L, static_cast<double>(sellPrice));         // 11 sellPrice
+    Game::Lua::PushNumber(L, static_cast<double>(classID));           // 12 classID
+    Game::Lua::PushNumber(L, static_cast<double>(subClassID));        // 13 subclassID
+    Game::Lua::PushNumber(L, static_cast<double>(bindType));          // 14 bindType
+    Game::Lua::PushNumber(L, 0.0);                                    // 15 expansionID (classic)
+    if (setID != 0)
+        Game::Lua::PushNumber(L, static_cast<double>(setID));        // 16 setID
+    else
+        Game::Lua::PushNil(L);
+    Game::Lua::PushBool(L, false);                                   // 17 isCraftingReagent
+    Game::Lua::PushString(L, PushedOrEmpty(description));            // 18 itemDescription
+    return 18;
+}
+
 static void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_Item", "GetItemInfo", &Script_C_Item_GetItemInfo);
     Game::Lua::RegisterTableFunction("C_Item", "GetItemInfoInstant", &Script_GetItemInfoInstant);
     Game::Lua::RegisterGlobalFunction("GetItemIcon", &Script_GetItemIcon);
     Game::Lua::RegisterTableFunction("C_Item", "GetItemIcon", &Script_C_Item_GetItemIcon);

src/item/NewItems.cpp

@@ -41,7 +41,16 @@
 // enough for the initial bag population to finish), takes a single scan as the
 // baseline, and then goes idle — items already owned at login are therefore
 // never flagged. It re-arms on player-GUID change (relog / character switch).
-// Bank and equipment are out of scope, matching retail.
+//
+// The "already owned" baseline spans **everything the player owns** — bags,
+// worn equipment (paperdoll + equipped bags), AND the bank (main + bank bags)
+// — even though only *bag* items are ever flagged new. That's what stops a
+// move INTO a bag from any of those (unequip, or a pull from the bank) from
+// looking like a fresh loot: the item's GUID was already in the owned set, so
+// the bag diff treats it as a move. The bank is reachable without the bank
+// window open because its GUIDs are read straight from the invMgr array (the
+// same gate-bypass `C_Item.GetItemCount` uses; the array is server-populated
+// at login).
 //
 // Bag enumeration is pure C++: it replicates what `PackBagSlot` does
 // internally (see Offsets.h). The backpack is indexed straight off the
@@ -67,17 +76,19 @@ namespace {
 constexpr const char *kEvtNewItems = "BAG_NEW_ITEMS_UPDATED";
 const Event::Custom::AutoReserve _r{kEvtNewItems};
 
-// Bags cap at backpack (16) + four equipped bags; even the largest Turtle
-// bags stay well under this. Overflow silently drops — a flagged-new item
-// past the cap just won't glow, never a crash.
-constexpr int kMaxItems = 256;
+// Sized for the whole owned universe the baseline tracks — backpack + four
+// bags + 19 worn slots + 4 equipped bags + main bank (24) + six bank bags.
+// A full inventory-and-bank can push ~300, so 512 leaves generous headroom.
+// Overflow silently drops (AddUnique bails at the cap) — a dropped GUID just
+// can't be flagged/recognized, never a crash.
+constexpr int kMaxItems = 512;
 
 // Delay after the player is first resolvable before the baseline is taken,
 // giving the initial bag population time to finish. Wall-clock (via the
 // engine ms counter) so it's independent of frame rate.
 constexpr uint32_t kSettleMs = 1500;
 
-uint64_t g_seen[kMaxItems]; // all bag-resident GUIDs at the last scan
+uint64_t g_seen[kMaxItems]; // all owned GUIDs (bags + equipment + bank) at the last scan
 int g_seenCount = 0;
 uint64_t g_new[kMaxItems]; // subset currently flagged "new"
 int g_newCount = 0;
@@ -167,6 +178,81 @@ int ScanBags(const uint8_t *player, uint64_t *out) {
     return count;
 }
 
+// Appends GUIDs from an invMgr's GUID array (the flat `+OFF_INVMGR_GUID_ARRAY`
+// list `GetItemBySlot` indexes) over linear slots [first, last]. Reading the
+// array directly is how we reach BANK slots without the bank window open —
+// `GetItemBySlot` gates slots 39..68 on a live banker GUID, but the array
+// itself is server-populated at login (same bypass `C_Item.GetItemCount`
+// uses). We only need the GUID here, not the resolved object.
+void AppendGuidArray(const uint8_t *invMgr, int first, int last, uint64_t *out,
+                     int *count) {
+    if (invMgr == nullptr)
+        return;
+    auto *arr = *reinterpret_cast<const uint64_t *const *>(
+        invMgr + Offsets::OFF_INVMGR_GUID_ARRAY);
+    if (arr == nullptr)
+        return;
+    for (int slot = first; slot <= last; ++slot)
+        if (arr[slot] != 0)
+            AddUnique(out, count, arr[slot]);
+}
+
+using ResolveByGuid_t = void *(__fastcall *)(int type, const char *debugName,
+                                             uint32_t guidLo, uint32_t guidHi,
+                                             int priority);
+const uint8_t *ResolveByGuid(int type, uint64_t guid) {
+    if (guid == 0)
+        return nullptr;
+    auto fn = reinterpret_cast<ResolveByGuid_t>(Offsets::FUN_OBJECT_RESOLVE_BY_GUID);
+    return static_cast<const uint8_t *>(
+        fn(type, "ItemMgr", static_cast<uint32_t>(guid),
+           static_cast<uint32_t>(guid >> 32), 0x172));
+}
+
+// Appends every item the player owns that ISN'T in bags 0..4 — worn
+// equipment (paperdoll 1..19 + the four equipped-bag containers 20..23),
+// the main bank (24 slots), and each bank bag's contents. Used only to widen
+// the "already owned" baseline so a move INTO a bag from any of these
+// (unequip, or a pull from the bank) reads as a move, not a fresh loot. We
+// never *flag* these as new — this only feeds the seen-set. Pure C++ (no Lua
+// stack) — safe off the frame tick.
+void AppendNonBagOwned(uint64_t *out, int *count) {
+    // Worn equipment + equipped bags: GetItemBySlot works for these (no
+    // banker gate), so go through the normal per-slot resolver.
+    for (int slot = Offsets::EQUIPMENT_SLOT_FIRST; slot <= Offsets::INVSLOT_BAG1 + 3;
+         ++slot) {
+        const uint64_t guid = ItemGUID(Item::Location::ResolveEquipmentSlot(slot));
+        if (guid != 0)
+            AddUnique(out, count, guid);
+    }
+
+    const uint8_t *playerInvMgr = Unit::Identity::PlayerInventoryManager();
+    if (playerInvMgr == nullptr)
+        return;
+    // Main bank slots 39..62 live in the player invMgr's own GUID array.
+    AppendGuidArray(playerInvMgr, Offsets::INVMGR_BANK_MAIN_FIRST_SLOT,
+                    Offsets::INVMGR_BANK_MAIN_LAST_SLOT, out, count);
+    // Bank bags (containers at player slots 63..68) each carry their own
+    // invMgr; resolve the container, then walk its GUID array.
+    auto *playerArr = *reinterpret_cast<const uint64_t *const *>(
+        playerInvMgr + Offsets::OFF_INVMGR_GUID_ARRAY);
+    if (playerArr == nullptr)
+        return;
+    for (int slot = Offsets::INVMGR_BANK_BAG_FIRST_SLOT;
+         slot <= Offsets::INVMGR_BANK_BAG_LAST_SLOT; ++slot) {
+        const uint8_t *bag = ResolveByGuid(Offsets::OBJ_TYPE_CONTAINER, playerArr[slot]);
+        if (bag == nullptr)
+            continue;
+        auto *bagInvMgr =
+            static_cast<const uint8_t *>(Item::Location::ContainerInventory(bag));
+        if (bagInvMgr == nullptr)
+            continue;
+        const int bagSlots = static_cast<int>(*reinterpret_cast<const uint32_t *>(bagInvMgr));
+        if (bagSlots > 0)
+            AppendGuidArray(bagInvMgr, 0, bagSlots - 1, out, count);
+    }
+}
+
 void FireChanged() {
     Event::Custom::Fire(Event::Custom::Lookup(kEvtNewItems), "");
 }
@@ -204,9 +290,11 @@ void OnTick() {
     if (player == nullptr)
         return; // not resolvable yet — retry next tick
 
-    // Everything currently in the bags becomes the baseline; nothing owned at
-    // login is "new". Any change up to this point is intentionally absorbed.
+    // Everything currently owned — bags AND worn equipment — becomes the
+    // baseline; nothing owned at login is "new". Including equipment means a
+    // later unequip (paperdoll → bag) is recognized as a move, not a loot.
     g_seenCount = ScanBags(player, g_seen);
+    AppendNonBagOwned(g_seen, &g_seenCount);
     g_newCount = 0;
     g_seeded = true;
 }
@@ -224,25 +312,25 @@ void OnBagChanged() {
     if (player == nullptr)
         return;
 
-    uint64_t current[kMaxItems];
-    const int currentCount = ScanBags(player, current);
+    uint64_t currentBags[kMaxItems];
+    const int bagCount = ScanBags(player, currentBags);
 
     bool changed = false;
-    // Drop flags for items no longer in the bags (used, sold, banked).
+    // Drop flags for items no longer in the bags (used, sold, equipped, banked).
     for (int i = 0; i < g_newCount;) {
-        if (!Contains(current, currentCount, g_new[i])) {
+        if (!Contains(currentBags, bagCount, g_new[i])) {
             g_new[i] = g_new[--g_newCount];
             changed = true;
         } else {
             ++i;
         }
     }
-    // Flag anything not present at the previous scan.
-    for (int i = 0; i < currentCount; ++i) {
-        if (!Contains(g_seen, g_seenCount, current[i]))
-            changed |= AddUnique(g_new, &g_newCount, current[i]);
+    for (int i = 0; i < bagCount; ++i) {
+        if (!Contains(g_seen, g_seenCount, currentBags[i]))
+            changed |= AddUnique(g_new, &g_newCount, currentBags[i]);
     }
-    CopyToSeen(current, currentCount);
+    CopyToSeen(currentBags, bagCount);
+    AppendNonBagOwned(g_seen, &g_seenCount);
 
     if (changed)
         FireChanged();

src/item/StatAccum.cpp

@@ -279,6 +279,15 @@ void AddByKey(Accum *acc, const char *key, long delta) {
         }
 }
 
+long Value(const Accum *acc, const char *key) {
+    if (acc == nullptr || key == nullptr)
+        return 0;
+    for (int i = 0; i < kCount; ++i)
+        if (std::strcmp(acc[i].key, key) == 0)
+            return acc[i].value;
+    return 0;
+}
+
 const uint8_t *FetchRecord(uint32_t itemID) {
     auto fn = reinterpret_cast<GetItemRecord_t>(Offsets::FUN_DBCACHE_ITEMSTATS_GET_RECORD);
     auto *cache = reinterpret_cast<void *>(Offsets::VAR_ITEMDB_CACHE);
@@ -306,6 +315,34 @@ double ComputeDPS(const uint8_t *record) {
     return avgTotal / (static_cast<double>(delayMs) / 1000.0);
 }
 
+void ApplyEnchant(Accum *acc, uint32_t enchantID, long sign) {
+    if (enchantID == 0)
+        return;
+    const uint8_t *en = DBC::Record(Offsets::VAR_SPELLITEMENCHANT_RECORDS,
+                                    Offsets::VAR_SPELLITEMENCHANT_COUNT, enchantID);
+    if (en == nullptr)
+        return;
+    auto type = reinterpret_cast<const int32_t *>(en + Offsets::OFF_SPELLITEMENCHANT_TYPE);
+    auto amount = reinterpret_cast<const int32_t *>(en + Offsets::OFF_SPELLITEMENCHANT_AMOUNT);
+    auto arg = reinterpret_cast<const int32_t *>(en + Offsets::OFF_SPELLITEMENCHANT_ARG);
+    for (int i = 0; i < 3; ++i) { // SpellItemEnchantment has 3 effect slots
+        switch (type[i]) {
+        case 3: // equip spell — stat/resist value lives in the spell
+            AddSpellStatAuras(acc, arg[i], sign);
+            break;
+        case 4: // resistance — arg = school index (0 = armor)
+            AddByKey(acc, ResistKey(arg[i]), sign * static_cast<long>(amount[i]));
+            break;
+        case 5: // direct stat — arg = ItemModType, amount = value
+            AddByKey(acc, StatKeyForItemModType(static_cast<uint32_t>(arg[i])),
+                     sign * static_cast<long>(amount[i]));
+            break;
+        default: // 1 proc / 2 weapon-damage / 6 totem / 7 use spell
+            break;
+        }
+    }
+}
+
 void ApplyRandomSuffix(Accum *acc, int suffixID, long sign) {
     if (suffixID <= 0)
         return;
@@ -316,34 +353,8 @@ void ApplyRandomSuffix(Accum *acc, int suffixID, long sign) {
         return;
     auto enchants = reinterpret_cast<const uint32_t *>(
         rp + Offsets::OFF_ITEMRANDOMPROP_ENCHANT);
-    for (int s = 0; s < Offsets::ITEMRANDOMPROP_ENCHANT_SLOT_COUNT; ++s) {
-        const uint32_t enchantID = enchants[s];
-        if (enchantID == 0)
-            continue;
-        const uint8_t *en = DBC::Record(Offsets::VAR_SPELLITEMENCHANT_RECORDS,
-                                        Offsets::VAR_SPELLITEMENCHANT_COUNT, enchantID);
-        if (en == nullptr)
-            continue;
-        auto type = reinterpret_cast<const int32_t *>(en + Offsets::OFF_SPELLITEMENCHANT_TYPE);
-        auto amount = reinterpret_cast<const int32_t *>(en + Offsets::OFF_SPELLITEMENCHANT_AMOUNT);
-        auto arg = reinterpret_cast<const int32_t *>(en + Offsets::OFF_SPELLITEMENCHANT_ARG);
-        for (int i = 0; i < 3; ++i) { // SpellItemEnchantment has 3 effect slots
-            switch (type[i]) {
-            case 3: // equip spell — stat/resist value lives in the spell
-                AddSpellStatAuras(acc, arg[i], sign);
-                break;
-            case 4: // resistance — arg = school index (0 = armor)
-                AddByKey(acc, ResistKey(arg[i]), sign * static_cast<long>(amount[i]));
-                break;
-            case 5: // direct stat — arg = ItemModType, amount = value
-                AddByKey(acc, StatKeyForItemModType(static_cast<uint32_t>(arg[i])),
-                         sign * static_cast<long>(amount[i]));
-                break;
-            default: // 1 proc / 2 weapon-damage / 6 totem / 7 use spell
-                break;
-            }
-        }
-    }
+    for (int s = 0; s < Offsets::ITEMRANDOMPROP_ENCHANT_SLOT_COUNT; ++s)
+        ApplyEnchant(acc, enchants[s], sign);
 }
 
 void AccumulateRecord(Accum *acc, const uint8_t *record, long sign) {

src/item/StatAccum.h

@@ -51,6 +51,9 @@ void Init(Accum *acc);
 // a zero delta). Linear scan — the table is small and fixed.
 void AddByKey(Accum *acc, const char *key, long delta);
 
+// Read the accumulated value for `key` (0 for an unknown key). Linear scan.
+long Value(const Accum *acc, const char *key);
+
 // Passive cache peek for an item's `ItemStats_C` record. Does NOT warm
 // the cache (returns nullptr for an uncached item) — see the item-cache
 // race note in CLAUDE.md.
@@ -66,6 +69,13 @@ void AccumulateRecord(Accum *acc, const uint8_t *record, long sign);
 // suffixID <= 0.
 void ApplyRandomSuffix(Accum *acc, int suffixID, long sign);
 
+// Fold a single SpellItemEnchantment record (by enchant ID) into `acc`,
+// scaled by `sign`. Handles equip-spell (type 3), resistance (4), and
+// direct-stat (5) enchant effects. Shared by `ApplyRandomSuffix` (a suffix's
+// enchant slots) and callers reading an item's *applied* permanent/temporary
+// enchants off its CGItem descriptor. No-op for enchantID 0.
+void ApplyEnchant(Accum *acc, uint32_t enchantID, long sign);
+
 // Weapon DPS = average damage / swing time, or 0 for non-weapons.
 double ComputeDPS(const uint8_t *record);
 

src/item/TypeInfo.cpp

@@ -13,6 +13,7 @@
 
 #include "Game.h"
 #include "Offsets.h"
+#include "dbc/Lookup.h"
 
 #include <cstdint>
 
@@ -25,6 +26,18 @@ int LocaleIndex() {
         static_cast<uintptr_t>(Offsets::VAR_LOCALE_INDEX));
 }
 
+// Localized ItemClass.dbc name for a class ID (records indexed by ID, the
+// standard DBC shape — same lookup `Script_GetItemInfo` uses). Returns ""
+// for an unknown class. Obsolete slots keep the client's literal string
+// (classID 3 → "Jewelry(OBSOLETE)", 8 → "Generic(OBSOLETE)", …) — that's
+// the real vanilla data; Enum.ItemClass supplies the modern key names.
+const char *ClassName(uint32_t classID) {
+    const char *s = DBC::LocalizedField(Offsets::VAR_ITEMCLASS_RECORDS,
+                                        Offsets::VAR_ITEMCLASS_COUNT, classID,
+                                        Offsets::OFF_ITEMCLASS_NAMES);
+    return (s != nullptr && s[0] != '\0') ? s : "";
+}
+
 // Linear-scan ItemSubClass.dbc for the (classID, subClassID) compound-key
 // row — same scan Item::GetData uses. Returns the record or nullptr.
 const uint8_t *FindSubClass(uint32_t classID, uint32_t subClassID) {
@@ -72,8 +85,27 @@ const char *InvTypeKey(int invType) {
     return (s != nullptr && s[0] != '\0') ? s : "";
 }
 
+// `GetItemClassInfo(classID)` → `className` (localized). `nil` for an
+// unknown class. Backport of the modern global (also exposed as
+// `C_Item.GetItemClassInfo`).
+int __fastcall Script_GetItemClassInfo(void *L) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, "Usage: GetItemClassInfo(classID)");
+        return 0;
+    }
+    const char *name = ClassName(static_cast<uint32_t>(Game::Lua::ToNumber(L, 1)));
+    if (name[0] == '\0') {
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+    Game::Lua::PushString(L, name);
+    return 1;
+}
+
 // `C_Item.GetItemSubClassInfo(classID, subClassID)` →
-// `subClassName, subClassUsesInvType`.
+// `subClassName, subClassUsesInvType`. Also exposed as the global
+// `GetItemSubClassInfo(classID, subClassID)` → `name, isArmorType`, the
+// same two values (the second is true for the armor material subclasses).
 //
 // `subClassName` is the localized ItemSubClass.dbc name (verbose form, e.g.
 // "One-Handed Swords"; falls back to the short form for subclasses that
@@ -184,7 +216,57 @@ constexpr Game::Lua::EnumIntegerEntry kInventoryTypeEntries[] = {
     {"IndexEquipablespellWeaponType", 34},
 };
 
+// `Enum.ItemClass` — the modern item-class enum. Values 0..15 are the
+// classes vanilla items actually report (the numeric IDs match retail; the
+// obsolete slots 3/8/10/14 keep their modern key names — Gem /
+// ItemEnhancement / CurrencyTokenObsolete / PermanentObsolete — even
+// though ItemClass.dbc labels them "…(OBSOLETE)"). 16..19 are post-vanilla
+// and never appear in 1.12 item data, included so backport code that
+// references those keys resolves (comparisons just never match).
+constexpr Game::Lua::EnumIntegerEntry kItemClassEntries[] = {
+    {"Consumable", 0},
+    {"Container", 1},
+    {"Weapon", 2},
+    {"Gem", 3},
+    {"Armor", 4},
+    {"Reagent", 5},
+    {"Projectile", 6},
+    {"Tradegoods", 7},
+    {"ItemEnhancement", 8},
+    {"Recipe", 9},
+    {"CurrencyTokenObsolete", 10},
+    {"Quiver", 11},
+    {"Questitem", 12},
+    {"Key", 13},
+    {"PermanentObsolete", 14},
+    {"Miscellaneous", 15},
+    {"Glyph", 16},
+    {"Battlepet", 17},
+    {"WoWToken", 18},
+    {"Profession", 19},
+};
+
+// `Enum.ItemQuality` — the numeric `quality` reported by `GetItemInfo` /
+// `C_Item.GetItemQuality`. Values 0..6 are all vanilla ever uses; the
+// post-vanilla Heirloom (7) and WoWToken (8) tiers are omitted (no such
+// items exist on 1.12).
+constexpr Game::Lua::EnumIntegerEntry kItemQualityEntries[] = {
+    {"Poor", 0},
+    {"Common", 1},
+    {"Uncommon", 2},
+    {"Rare", 3},
+    {"Epic", 4},
+    {"Legendary", 5},
+    {"Artifact", 6},
+};
+
 void RegisterLuaFunctions() {
+    Game::Lua::RegisterGlobalFunction("GetItemClassInfo",
+                                      &Script_GetItemClassInfo);
+    Game::Lua::RegisterGlobalFunction("GetItemSubClassInfo",
+                                      &Script_GetItemSubClassInfo);
+    Game::Lua::RegisterTableFunction("C_Item", "GetItemClassInfo",
+                                     &Script_GetItemClassInfo);
     Game::Lua::RegisterTableFunction("C_Item", "GetItemSubClassInfo",
                                      &Script_GetItemSubClassInfo);
     Game::Lua::RegisterTableFunction("C_Item", "GetItemInventorySlotKey",
@@ -194,6 +276,12 @@ void RegisterLuaFunctions() {
     Game::Lua::RegisterIntegerEnum(
         "Enum", "InventoryType", kInventoryTypeEntries,
         sizeof(kInventoryTypeEntries) / sizeof(kInventoryTypeEntries[0]));
+    Game::Lua::RegisterIntegerEnum(
+        "Enum", "ItemClass", kItemClassEntries,
+        sizeof(kItemClassEntries) / sizeof(kItemClassEntries[0]));
+    Game::Lua::RegisterIntegerEnum(
+        "Enum", "ItemQuality", kItemQualityEntries,
+        sizeof(kItemQualityEntries) / sizeof(kItemQualityEntries[0]));
 }
 
 const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};

src/loot/History.cpp

@@ -92,18 +92,7 @@ int MapRollType(int packetType) {
 // have gone). Guaranteed loaded at hook time: the roll handler's wrapper
 // gates on this same lookup succeeding. Returns nullptr if not cached.
 const uint8_t *LookupPlayerRecord(uint64_t guid) {
-    if (guid == 0)
-        return nullptr;
-    using Lookup_t = const uint8_t *(__thiscall *)(void *cache, uint32_t lo,
-                                                   uint32_t hi, void *cookie,
-                                                   void *cb, void *ud, char flag);
-    auto fn = reinterpret_cast<Lookup_t>(
-        static_cast<uintptr_t>(Offsets::FUN_PLAYER_INFO_LOOKUP));
-    uint32_t cookie[2] = {0, 0};
-    return fn(reinterpret_cast<void *>(
-                  static_cast<uintptr_t>(Offsets::VAR_PLAYER_NAME_CACHE)),
-              static_cast<uint32_t>(guid), static_cast<uint32_t>(guid >> 32),
-              cookie, nullptr, nullptr, 0);
+    return Unit::Identity::PlayerInfoRecord(guid);
 }
 
 const char *NameFromRecord(const uint8_t *rec) {

src/loot/Scan.cpp

@@ -27,6 +27,7 @@
 #include "../Game.h"
 #include "../Offsets.h"
 #include "../event/Custom.h"
+#include "../event/SignalHook.h"
 #include "../guid/Guid.h"
 #include "../tick/WorldTick.h"
 
@@ -115,9 +116,6 @@ using LootSlotLinkBuilder_t = const char *(__fastcall *)(uint32_t userFacingSlot
 using LootController_t = void(__fastcall *)(int lootStructPtr,
                                              int coin,
                                              int unk);
-using FireEventNoArgs_t = void(__fastcall *)(int eventID,
-                                              int /*edx unused*/);
-
 struct C3Vector {
     float x, y, z;
 };
@@ -256,7 +254,6 @@ void StartLoot(uint64_t guid) {
 // === Hooks ===
 
 LootController_t s_lootController_o = nullptr;
-FireEventNoArgs_t s_fireEventNoArgs_o = nullptr;
 
 // `LOOT_OPENED` / `LOOT_CLOSED` get suppressed only while a scan is
 // actively interleaving open/close cycles, signaled by
@@ -265,12 +262,14 @@ FireEventNoArgs_t s_fireEventNoArgs_o = nullptr;
 // `SendCloseLoot` that follows, then dropped before
 // `TryStartNext`-initiated CMSG_LOOTs go out. Every other engine
 // event fire — and normal play's loot events — pass through.
-void __fastcall FireEventNoArgs_h(int eventID, int /*unusedEdx*/) {
-    if (s_scan.suppressEvents &&
-        (eventID == EVENT_LOOT_OPENED || eventID == EVENT_LOOT_CLOSED)) {
-        return;
-    }
-    s_fireEventNoArgs_o(eventID, 0);
+//
+// Runs as an interceptor on the shared no-arg event hook
+// (`Event::SignalHook`) rather than owning the hook directly, so it can
+// coexist with other features that intercept the same dispatcher (e.g. the
+// PLAYER_ENTERING_WORLD payload). Return true to swallow.
+bool SuppressLootEvents(int eventID) {
+    return s_scan.suppressEvents &&
+           (eventID == EVENT_LOOT_OPENED || eventID == EVENT_LOOT_CLOSED);
 }
 
 // Intercepts the engine's loot-window state controller. Two paths:
@@ -336,10 +335,7 @@ const Game::HookAutoRegister _hookController{
     reinterpret_cast<void *>(&LootController_h),
     reinterpret_cast<void **>(&s_lootController_o)};
 
-const Game::HookAutoRegister _hookFireEvent{
-    Offsets::FUN_FIRE_EVENT_NO_ARGS,
-    reinterpret_cast<void *>(&FireEventNoArgs_h),
-    reinterpret_cast<void **>(&s_fireEventNoArgs_o)};
+const Event::SignalHook::AutoSubscribe _lootIntercept{&SuppressLootEvents};
 
 // === Tick (timeout only) ===
 

src/nameplate/Events.cpp

@@ -30,17 +30,23 @@
 //   (dispatcher leaves `_G.arg<N>` alone when no codes are parsed),
 //   restore.
 // - `NAME_PLATE_UNIT_ADDED` / `_REMOVED` — `arg1` is the
-//   `"nameplateN"` unit token (formatted from the plate's index in
-//   `g_orderedGUIDs` at fire time). The token resolves to the unit
-//   via the `nameplateN`-aware token resolver in `unit/TokenExtensions.cpp`
-//   — addons can pass it straight to `UnitName`, `UnitGUID`, etc.,
-//   or to `GetNamePlateForUnit` for the frame.
+//   `"nameplateN"` unit token (`N` = the plate's assigned slot). The token
+//   resolves to the unit via the `nameplateN`-aware token resolver in
+//   `unit/TokenExtensions.cpp` — addons can pass it straight to `UnitName`,
+//   `UnitGUID`, etc., or to `GetNamePlateForUnit` for the frame.
+//
+// Slot assignment (retail-exact): a plate keeps its slot for its whole
+// lifetime, so surviving plates are NEVER renumbered when another is removed
+// — a removal frees the slot and the next new plate reuses the lowest free
+// one. `g_slots` is therefore a sparse array (freed middle slots read back as
+// the empty GUID 0 until reused), not a compacting list.
 
 #include "Game.h"
 #include "Offsets.h"
 #include "event/Custom.h"
 #include "nameplate/Walk.h"
 #include "tick/WorldTick.h"
+#include "unit/TokenObserver.h"
 
 #include <algorithm>
 #include <cstdint>
@@ -84,13 +90,27 @@ std::unordered_map<uint64_t, const void *> g_currentTickPlates;
 // then tops out as pool reuse covers all subsequent shows.
 std::unordered_set<const void *> g_seenPlates;
 
-// Ordered list of currently-visible nameplate GUIDs, in
-// creation-order. Append on UNIT_ADDED, erase on UNIT_REMOVED. Backs
-// the `nameplateN` unit-token resolver in `unit/TokenExtensions.cpp`. Order
-// matches modern WoW semantics: stable for the lifetime of each
-// plate, gaps when middle plates vanish (until the next REMOVED
-// shifts later entries down).
-std::vector<uint64_t> g_orderedGUIDs;
+// Nameplate token slots: slot `i` (0-based) holds the GUID assigned to
+// `nameplate(i+1)`, or 0 when free. Retail-exact slot assignment — a plate
+// keeps its slot for its whole lifetime (survivors are never renumbered),
+// UNIT_REMOVED frees the slot (sets 0), and a new plate reuses the lowest
+// free slot. Sparse: freed middle slots stay as gaps until reused. Backs the
+// `nameplateN` unit-token resolver in `unit/TokenExtensions.cpp`.
+std::vector<uint64_t> g_slots;
+
+// Assign `guid` the lowest free slot, reusing a vacated one when present and
+// growing the array only when every slot is occupied. Returns the 0-based
+// slot. Never shifts an existing entry.
+int AssignSlot(uint64_t guid) {
+    for (size_t i = 0; i < g_slots.size(); ++i) {
+        if (g_slots[i] == 0) {
+            g_slots[i] = guid;
+            return static_cast<int>(i);
+        }
+    }
+    g_slots.push_back(guid);
+    return static_cast<int>(g_slots.size() - 1);
+}
 
 // Fire `eventName` with a pre-formatted string as `arg1`. The engine
 // dispatcher's `%s` format code pushes the C string into `_G.arg1`
@@ -114,6 +134,32 @@ const char *FormatNamePlateToken(char *buf, size_t bufSize, int oneBasedIndex) {
     return buf;
 }
 
+// Descriptor-field observer callback — makes unit events (UNIT_HEALTH,
+// UNIT_AURA, …) fire with the `"nameplateN"` token, so a nameplated unit is a
+// first-class unit-event source exactly like a party member. Registered per
+// nameplate GUID via `Unit::TokenObserver` on UNIT_ADDED, unregistered on
+// UNIT_REMOVED. We reverse-look-up the changed GUID's slot at fire time
+// (cheap; the array is small) so the token reflects its current assignment.
+// The event id is the field index (`fieldOffset >> 2`); the engine fires every
+// unit event as "%s" + token, so we match. A GUID no longer in any slot
+// (removal raced this field change) simply drops the fire.
+int __fastcall NamePlateFieldCb(uint32_t fieldOffset, uint32_t /*size*/,
+                                uint32_t guidLo, uint32_t guidHi,
+                                const uint32_t * /*oldValue*/, void * /*userArg*/) {
+    const uint64_t guid =
+        (static_cast<uint64_t>(guidHi) << 32) | static_cast<uint64_t>(guidLo);
+    auto it = std::find(g_slots.begin(), g_slots.end(), guid);
+    if (it == g_slots.end())
+        return 1;
+    const int oneBased = static_cast<int>(it - g_slots.begin()) + 1;
+    char tokenBuf[24];
+    FormatNamePlateToken(tokenBuf, sizeof tokenBuf, oneBased);
+    using Fire_t = void(__cdecl *)(int eventId, const char *fmt, ...);
+    reinterpret_cast<Fire_t>(static_cast<uintptr_t>(Offsets::FUN_FIRE_EVENT))(
+        static_cast<int>(fieldOffset >> 2), "%s", tokenBuf);
+    return 1;
+}
+
 // Fire `eventName` with the nameplate `Frame` set as `_G.arg1`.
 // `FUN_FIRE_EVENT`'s format-string parser only handles primitive
 // types, but it only mutates `_G.arg<N>` for codes it actually
@@ -178,38 +224,42 @@ void OnWorldTick() {
 
     // Fire CREATED (with the Frame as arg1) for never-before-seen
     // frame pointers; ADDED (with `"nameplateN"` token as arg1) for
-    // GUIDs not in last tick's snapshot. New entries are appended to
-    // the ordered list *before* firing so the token resolves to the
-    // newly-added plate during the event handler.
+    // GUIDs not in last tick's snapshot. The slot is assigned *before*
+    // firing so the token resolves to the newly-added plate during the
+    // event handler.
     for (const auto &kv : g_currentTickPlates) {
         if (g_seenPlates.insert(kv.second).second)
             FireWithFrame(kEventCreated, const_cast<void *>(kv.second));
         if (g_lastTickPlates.find(kv.first) == g_lastTickPlates.end()) {
-            g_orderedGUIDs.push_back(kv.first);
+            const int slot = AssignSlot(kv.first);
+            // Watch this unit's fields so UNIT_HEALTH/UNIT_AURA/… fire with
+            // its "nameplateN" token (the engine only watches its own
+            // target/party/raid tokens, not nameplates).
+            Unit::TokenObserver::Register(kv.first, &NamePlateFieldCb);
             char tokenBuf[24];
             FireWithString(kEventUnitAdded,
-                FormatNamePlateToken(tokenBuf, sizeof tokenBuf,
-                                     static_cast<int>(g_orderedGUIDs.size())));
+                FormatNamePlateToken(tokenBuf, sizeof tokenBuf, slot + 1));
         }
     }
 
-    // Fire REMOVED for GUIDs in last tick's snapshot but not current.
-    // We compute the token from the position *before* erasing so the
-    // event payload reflects the slot the unit just vacated; the
-    // handler can still resolve the token to the unit via
-    // `g_orderedGUIDs[slot]` during dispatch. Later plates shift down
-    // when we erase — matches modern semantics.
+    // Fire REMOVED for GUIDs in last tick's snapshot but not current. The
+    // slot is *freed* (set 0), not erased, so surviving plates keep their
+    // index (retail-exact — no shift); the next ADD reuses it. Token is
+    // computed before freeing so the payload names the slot just vacated.
+    // Trailing empties are trimmed so the array tracks the high-water mark.
     for (const auto &kv : g_lastTickPlates) {
         if (g_currentTickPlates.find(kv.first) == g_currentTickPlates.end()) {
-            auto it = std::find(g_orderedGUIDs.begin(), g_orderedGUIDs.end(),
-                                kv.first);
-            if (it == g_orderedGUIDs.end())
+            auto it = std::find(g_slots.begin(), g_slots.end(), kv.first);
+            if (it == g_slots.end())
                 continue;
-            const int oneBased = static_cast<int>(it - g_orderedGUIDs.begin()) + 1;
+            const int oneBased = static_cast<int>(it - g_slots.begin()) + 1;
             char tokenBuf[24];
             FireWithString(kEventUnitRemoved,
                 FormatNamePlateToken(tokenBuf, sizeof tokenBuf, oneBased));
-            g_orderedGUIDs.erase(it);
+            Unit::TokenObserver::Unregister(kv.first, &NamePlateFieldCb);
+            *it = 0; // free the slot (no shift of survivors)
+            while (!g_slots.empty() && g_slots.back() == 0)
+                g_slots.pop_back();
         }
     }
 
@@ -230,24 +280,35 @@ static const Tick::WorldTick::AutoSubscribe _tickSub{&OnWorldTick};
 // suppress every refire, and the freshly-built wrapper would lack
 // the addon's `.nameplate` field.
 //
-// `g_orderedGUIDs` is also cleared so the post-reload token indices
-// start at `nameplate1` again, matching the order plates re-fire in.
+// `g_slots` is also cleared so post-reload token slots start fresh.
 void PrepareForReload() {
     g_seenPlates.clear();
     g_lastTickPlates.clear();
-    g_orderedGUIDs.clear();
+    // Objects survive a /reload, so their observer nodes do too. The first
+    // post-reload tick re-fires ADDED and re-registers, which would stack a
+    // second observer per field (the registrar never dedups) → double events.
+    // Tear ours down here so re-registration starts clean (skip free slots).
+    for (uint64_t guid : g_slots)
+        if (guid != 0)
+            Unit::TokenObserver::Unregister(guid, &NamePlateFieldCb);
+    g_slots.clear();
 }
 
 // Exposed via `nameplate/Walk.h` so the `nameplateN` token resolver
 // in `unit/TokenExtensions.cpp` can map an index to a GUID without seeing
-// the internal vector.
+// the internal array. Returns 0 for an out-of-range OR currently-free slot.
 uint64_t GetGUIDByIndex(int oneBased) {
     if (oneBased <= 0)
         return 0;
     const size_t idx = static_cast<size_t>(oneBased - 1);
-    if (idx >= g_orderedGUIDs.size())
+    if (idx >= g_slots.size())
         return 0;
-    return g_orderedGUIDs[idx];
+    return g_slots[idx]; // 0 when the slot is free
 }
 
+// Number of slots (1-based max index). Because the slot array is SPARSE,
+// callers that iterate all plates must scan `1..GetSlotCount()` and skip the
+// slots where `GetGUIDByIndex` returns 0 — they can't stop at the first gap.
+int GetSlotCount() { return static_cast<int>(g_slots.size()); }
+
 } // namespace NamePlate::Events

src/nameplate/Info.cpp

@@ -56,6 +56,7 @@
 #include "Offsets.h"
 #include "guid/Guid.h"
 #include "nameplate/Walk.h"
+#include "ui/FrameObject.h"
 
 #include <cstdint>
 
@@ -66,9 +67,6 @@ namespace {
 using NamePlate::Walk::ForEachNamePlatedUnit;
 using NamePlate::Walk::kOffUnitNamePlate;
 
-using LuaRawGetI_t = void(__fastcall *)(void *L, int idx, int n);
-using ScriptRegister_t = void(__fastcall *)(void *this_, void *edx_unused,
-                                              const char *name);
 using TokenToGUID_t = uint64_t(__fastcall *)(const char *token);
 using ResolveByGUID_t = void *(__fastcall *)(int type, const char *debugName,
                                               uint32_t guidLo, uint32_t guidHi,
@@ -115,70 +113,13 @@ static int __fastcall Script_GetNamePlateGUIDs(void *L) {
 // frame-push path. Internal callers (Script_GetNamePlates etc.) call
 // it through the unqualified name (they live in the same namespace).
 //
-// Delegate wrapper construction to the engine's own
-// `FrameScript_Object::ScriptRegister`. First call for a never-seen
-// nameplate builds a `{[0] = lightuserdata}` table with the
-// framescript metatable, `luaL_ref`s it into the registry, and
-// writes the refkey to `nameplate + 0x08` (`OFF_COBJECT_LUA_REGISTRY_REF`).
-// Subsequent calls find a populated refkey and just rawgeti.
-//
-// Why delegate instead of building our own wrapper:
-//
-// - **Single source of truth.** Every code path that pushes this
-//   frame — ours via this function, addons' `CreateFrame("Type",
-//   "name", plate)` extracting the parent, the engine's own internal
-//   pushers — funnels through `rawgeti(REGISTRY, plate+0x08)` and
-//   gets the same Lua table. Earlier "build our own wrapper +
-//   `luaL_ref` it" approach kept a side cache, but pfUI's
-//   `CreateFrame("Button", "name", parent)` inside `NAME_PLATE_CREATED`
-//   ends up causing the engine to register the parent itself —
-//   the engine's wrapper diverges from ours, and later
-//   `GetNamePlateForUnit` calls return the engine's bare wrapper
-//   instead of our decorated one. Addon fields on the wrapper
-//   (`plate.nameplate = styledButton`) disappear from the API's
-//   perspective even though they still exist on the orphaned
-//   table.
-//
-// - **Refcount-pinning is benign here.** `ScriptRegister`
-//   unconditionally increments `nameplate + 0x04`, which normally
-//   keeps the engine from GC-ing the CObject. Nameplates are
-//   pool-managed and never destroyed during a session, so pinning
-//   doesn't actually leak anything. We call `ScriptRegister` at
-//   most once per nameplate pointer (gated by `refKey <= 0`), so
-//   the refcount tops out at one increment per pool slot.
-//
-// Defensive fallback: if the registry slot exists but isn't a table
-// any more (some other code freed it), we re-register. This shouldn't
-// happen in practice — engines only unref on frame destruction —
-// but a stale type check keeps callers from ever seeing a non-table.
+// Thin wrapper over the shared `UI::FrameObject::Push` — nameplates and
+// chat bubbles are both engine-created-in-C++ `CSimpleFrame`s that need
+// the same lazy `ScriptRegister` → `rawgeti` push so addons get the
+// engine's canonical wrapper (see that helper for the pfUI-divergence
+// rationale that motivated delegating to the engine).
 void PushNamePlateFrame(void *L, void *nameplate) {
-    auto rawgeti = reinterpret_cast<LuaRawGetI_t>(
-        Offsets::FUN_FRAMESCRIPT_PUSH_OBJECT);
-    auto scriptRegister = reinterpret_cast<ScriptRegister_t>(
-        static_cast<uintptr_t>(Offsets::FUN_FRAMESCRIPT_OBJECT_SCRIPT_REGISTER));
-
-    int refKey = *reinterpret_cast<const int *>(
-        static_cast<uint8_t *>(nameplate) + Offsets::OFF_COBJECT_LUA_REGISTRY_REF);
-    if (refKey <= 0) {
-        scriptRegister(nameplate, nullptr, nullptr);
-        refKey = *reinterpret_cast<const int *>(
-            static_cast<uint8_t *>(nameplate) + Offsets::OFF_COBJECT_LUA_REGISTRY_REF);
-    }
-
-    rawgeti(L, Game::Lua::REGISTRY_INDEX, refKey);
-    if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_TABLE)
-        return;
-    Game::Lua::SetTop(L, -2);
-
-    // Slot got freed somewhere — re-register to rebuild a fresh
-    // wrapper and slot. Zero the refcount so `ScriptRegister`
-    // re-enters its build branch.
-    *reinterpret_cast<int *>(
-        static_cast<uint8_t *>(nameplate) + Offsets::OFF_COBJECT_LUA_REFCOUNT) = 0;
-    scriptRegister(nameplate, nullptr, nullptr);
-    refKey = *reinterpret_cast<const int *>(
-        static_cast<uint8_t *>(nameplate) + Offsets::OFF_COBJECT_LUA_REGISTRY_REF);
-    rawgeti(L, Game::Lua::REGISTRY_INDEX, refKey);
+    UI::FrameObject::Push(L, nameplate);
 }
 
 // GUID → nameplate Frame pushed on stack. Pushes nil if the GUID

src/nameplate/Walk.h

@@ -37,12 +37,18 @@ void PushNamePlateFrame(void *L, void *nameplate);
 namespace NamePlate::Events {
 
 // Returns the GUID currently bound to `nameplateN` (1-based, matching
-// the modern Lua token form). `0` means no nameplate at that index.
-// Backed by the per-tick UNIT_ADDED / UNIT_REMOVED diff in
-// `Events.cpp` — order is creation-order (append on ADDED, erase on
-// REMOVED), stable within a frame.
+// the modern Lua token form). `0` means the slot is out of range OR
+// currently free. Backed by the retail-exact slot assignment in
+// `Events.cpp`: a plate keeps its slot for its lifetime and freed slots
+// are reused, so the slot array is SPARSE (gaps read back as 0).
 uint64_t GetGUIDByIndex(int oneBased);
 
+// Highest slot index in use (1-based). Callers that iterate every plate
+// must loop `1..GetSlotCount()` and skip indices where `GetGUIDByIndex`
+// returns 0 — they must NOT stop at the first gap, since the array is
+// sparse.
+int GetSlotCount();
+
 // Clears the per-tick diff state (seen pointers, last tick's
 // snapshot, ordered GUID list) so the post-`/reload` tick refires
 // CREATED + UNIT_ADDED for every currently-visible plate. Called

src/object/ClosestByEntry.cpp

@@ -0,0 +1,105 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#include "object/ClosestByEntry.h"
+
+#include "Game.h"
+#include "Offsets.h"
+#include "unit/Position.h"
+
+#include <cstdint>
+
+namespace Object::ClosestByEntry {
+
+namespace {
+
+// `ClntObjMgrEnumVisibleObjects(cb, ctx)` — walks the visible-object
+// table; the callback's dummy EDX slot absorbs the second __fastcall
+// register so the trailing `uint64_t guid` lands where the engine puts it.
+// Return non-zero to keep iterating.
+using EnumCallback_t = int(__fastcall *)(void *ctx, void *unusedEdx,
+                                         uint64_t guid);
+using EnumVisibleObjects_t = int(__fastcall *)(EnumCallback_t cb, void *ctx);
+
+// `ClntObjMgrObjectPtr(typeMask, dbg, guidLo, guidHi, dbgCode)` — resolves
+// a GUID to its live `CGObject_C *`, filtered by typeMask; NULL if none.
+using ObjectPtr_t = void *(__fastcall *)(uint32_t typeMask, const char *dbg,
+                                         uint32_t guidLo, uint32_t guidHi,
+                                         int dbgCode);
+
+struct ScanCtx {
+    uint32_t typeMask;
+    Guid::Type guidType;
+    uint32_t wantEntry;
+    float px, py, pz; // player position
+    Result r;
+};
+
+int __fastcall ScanCallback(ScanCtx *ctx, void * /*unusedEdx*/, uint64_t guid) {
+    // Type + entry checks are pure GUID bit-reads, so we skip the (costly)
+    // object resolve for everything that can't match.
+    if (Guid::Classify(guid) != ctx->guidType)
+        return 1;
+    const uint32_t entry = static_cast<uint32_t>((guid >> 24) & 0xFFFFFFu);
+    if (entry != ctx->wantEntry)
+        return 1;
+
+    auto ObjectPtr =
+        reinterpret_cast<ObjectPtr_t>(Offsets::FUN_CLNT_OBJ_MGR_OBJECT_PTR);
+    void *obj = ObjectPtr(ctx->typeMask, nullptr, static_cast<uint32_t>(guid),
+                          static_cast<uint32_t>(guid >> 32), 0);
+    if (obj == nullptr)
+        return 1;
+
+    float pos[3];
+    if (!Unit::Position::Read(obj, pos))
+        return 1;
+
+    const float dx = pos[0] - ctx->px;
+    const float dy = pos[1] - ctx->py;
+    const float dz = pos[2] - ctx->pz;
+    const float distSq = dx * dx + dy * dy + dz * dz;
+    if (!ctx->r.found || distSq < ctx->r.distSq) {
+        ctx->r.found = true;
+        ctx->r.x = pos[0];
+        ctx->r.y = pos[1];
+        ctx->r.distSq = distSq;
+    }
+    return 1;
+}
+
+} // namespace
+
+Result Find(uint32_t typeMask, Guid::Type guidType, uint32_t entry) {
+    const Result none{false, 0.0f, 0.0f, 0.0f};
+    if (entry == 0)
+        return none;
+
+    // The enumerator derefs the object manager unconditionally; it's NULL
+    // during glue / character-select. Bail rather than crash.
+    if (*reinterpret_cast<void *volatile *>(Offsets::VAR_LOCAL_PLAYER_PTR) ==
+        nullptr)
+        return none;
+
+    float ppos[3];
+    if (!Unit::Position::Read(Unit::Position::ResolveToken("player"), ppos))
+        return none;
+
+    ScanCtx ctx{typeMask, guidType, entry, ppos[0], ppos[1], ppos[2], none};
+    auto Enum = reinterpret_cast<EnumVisibleObjects_t>(
+        Offsets::FUN_CLNT_OBJ_MGR_ENUM_VISIBLE_OBJECTS);
+    Enum(reinterpret_cast<EnumCallback_t>(&ScanCallback), &ctx);
+    return ctx.r;
+}
+
+} // namespace Object::ClosestByEntry

src/object/ClosestByEntry.h

@@ -0,0 +1,41 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include "guid/Guid.h"
+
+#include <cstdint>
+
+// Shared "nearest visible object of a given template entry" scan, backing
+// both `ClosestUnitPosition` (creatures) and `ClosestGameObjectPosition`
+// (game objects). Vanilla packs the template entry into GUID bits 24-47
+// for the world-object types, so the only per-caller differences are the
+// GUID type prefix and the object-manager type mask.
+namespace Object::ClosestByEntry {
+
+struct Result {
+    bool found;
+    float x, y;   // world position of the nearest match
+    float distSq; // squared center-to-center distance from the player
+};
+
+// Nearest CURRENTLY-VISIBLE object whose GUID is of `guidType` (Creature /
+// GameObject / …) and encodes template `entry` (GUID bits 24-47),
+// relative to the local player. `typeMask` is the `ClntObjMgrObjectPtr`
+// filter used to resolve the GUID (`TYPEMASK_UNIT` / `TYPEMASK_GAMEOBJECT`).
+// Returns `{found=false}` for entry 0, pre-world, on a player-position
+// miss, or when nothing matches.
+Result Find(uint32_t typeMask, Guid::Type guidType, uint32_t entry);
+
+} // namespace Object::ClosestByEntry

src/player/Equipment.cpp

@@ -52,6 +52,7 @@
 #include "Offsets.h"
 #include "equipmentset/Locations.h"
 #include "event/Custom.h"
+#include "player/StatSignal.h"
 #include "unit/Identity.h"
 
 #include <cstdint>
@@ -112,6 +113,9 @@ int __fastcall EquipSlotChanged_cb(uint32_t fieldOffset, uint32_t /*size*/,
         Event::Custom::FireIdSuccess(Event::Custom::Lookup(kEvtEquipmentChanged),
                                      slot0 + 1,
                                      SlotHasItem(guidLo, guidHi, slot0));
+        // Gear swap changes item +healing and Spirit/Armor — invalidate the
+        // GetSpellBonusHealing cache.
+        Player::StatSignal::Notify();
     }
     return 1;
 }

src/player/Facing.cpp

@@ -0,0 +1,55 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `GetPlayerFacing()` → facing angle of the player in radians (0 =
+// north/+Y in WoW's world convention, increasing counter-clockwise), or
+// nothing when there's no player (glue / loading). Vanilla 1.12 doesn't
+// ship it (only character-create/select facing exist), but it's the
+// missing half that makes our backported `TargetDirectionEnemy/Friend`
+// usable — a caller passes `GetPlayerFacing()` to target what's in front.
+//
+// The orientation is a field in the player's CGUnit movement block
+// (`OFF_UNIT_FACING` = +0x9C4), sitting just past the {x,y,z} position at
+// +0x9B8. The `GetPosition` virtual only copies x/y/z into a caller buffer,
+// so the facing is read off the object directly.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "unit/Position.h"
+
+#include <cstdint>
+
+namespace Player::Facing {
+
+namespace {
+
+int __fastcall Script_GetPlayerFacing(void *L) {
+    void *player = Unit::Position::ResolveToken("player");
+    if (player == nullptr)
+        return 0;
+
+    const float facing = *reinterpret_cast<const float *>(
+        static_cast<const uint8_t *>(player) + Offsets::OFF_UNIT_FACING);
+    Game::Lua::PushNumber(L, static_cast<double>(facing));
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterGlobalFunction("GetPlayerFacing", &Script_GetPlayerFacing);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace Player::Facing

src/player/Info.cpp

@@ -39,6 +39,7 @@
 #include "Offsets.h"
 #include "dbc/Lookup.h"
 #include "guid/Guid.h"
+#include "unit/Identity.h"
 
 #include <cstdint>
 #include <cstring>
@@ -47,20 +48,8 @@ namespace Player::Info {
 
 namespace {
 
-// `FUN_0055F080` — `__thiscall(this=cache, guidLo, guidHi, &cookie,
-// callback, userData, retryFlag) → entryData* or NULL`.
-using LookupOrFetch_t = const uint8_t *(__thiscall *)(
-    void *cache,
-    uint32_t guidLo,
-    uint32_t guidHi,
-    uint64_t *cookie,
-    void *callback,
-    void *userData,
-    int retryFlag);
-
-// Thin shim: parses a GUID string and splits to hi/lo dwords for the
-// engine's `__thiscall` cache lookup, which takes them as separate
-// args. Shared parser lives in `Guid::Parse`.
+// Thin shim: parses a GUID string and splits to hi/lo dwords. Shared parser
+// lives in `Guid::Parse`.
 bool ParseGUID(const char *str, uint32_t &outHi, uint32_t &outLo) {
     uint64_t value = 0;
     if (!Guid::Parse(str, &value))
@@ -82,14 +71,8 @@ int __fastcall Script_GetPlayerInfoByGUID(void *L) {
     if (hi == 0 && lo == 0)
         return 0;
 
-    auto fn = reinterpret_cast<LookupOrFetch_t>(Offsets::FUN_PLAYER_INFO_LOOKUP);
-    auto *cache = reinterpret_cast<void *>(
-        static_cast<uintptr_t>(Offsets::VAR_PLAYER_NAME_CACHE));
-
-    uint64_t cookie = 0;
-    const uint8_t *entry = fn(cache, lo, hi, &cookie,
-                              nullptr /*callback*/, nullptr /*userData*/,
-                              0 /*retryFlag*/);
+    const uint8_t *entry = Unit::Identity::PlayerInfoRecord(
+        (static_cast<uint64_t>(hi) << 32) | lo);
 
     const char *name = nullptr;
     const char *realm = nullptr;

src/player/StatSignal.cpp

@@ -0,0 +1,28 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#include "player/StatSignal.h"
+
+namespace Player::StatSignal {
+
+namespace {
+// Starts at 1 so a consumer whose cached epoch is default-0 always computes on
+// its first query.
+uint32_t g_epoch = 1;
+} // namespace
+
+void Notify() { ++g_epoch; }
+
+uint32_t Epoch() { return g_epoch; }
+
+} // namespace Player::StatSignal

src/player/StatSignal.h

@@ -0,0 +1,38 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <cstdint>
+
+// A pull-based "the local player's stat inputs changed" signal. `Notify()` is
+// called from the aura and equipment hooks whenever the player gains/loses an
+// aura or swaps gear — the state that feeds derived stats like
+// `GetSpellBonusHealing` (flat +healing, plus the Spirit/Armor talent
+// conversions that scale with those descriptor fields).
+//
+// Unlike Tick::WorldTick (push / per-frame callback), this is a monotonic
+// epoch that consumers POLL: a lazy cache recomputes only when `Epoch()`
+// differs from the value it last computed at, so a per-frame query is O(1)
+// between real changes and never does work on idle frames.
+namespace Player::StatSignal {
+
+// Bump the epoch — called from the aura / equipment hooks on a
+// player-affecting change.
+void Notify();
+
+// Current epoch; increments on each `Notify()`. A consumer caches the value it
+// last recomputed at and recomputes only when this differs.
+uint32_t Epoch();
+
+} // namespace Player::StatSignal

src/quest/Log.cpp

@@ -76,6 +76,87 @@ static int __fastcall Script_GetQuestIDForLogIndex(void *L) {
     return 1;
 }
 
+// `C_QuestLog.GetLogIndexForQuestID(questID)` — the inverse of
+// `GetQuestIDForLogIndex`: the 1-based quest-log index of `questID`, or nil
+// if the quest isn't in the log. The index spans the full entry array
+// (headers included), matching `GetQuestIDForLogIndex` /
+// `GetQuestLogTitle`. Walks `VAR_QUEST_LOG_ENTRIES`, skipping header rows via
+// the `+8` header-pointer gate, and returns the first matching entry's index.
+static int __fastcall Script_GetLogIndexForQuestID(void *L) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, "Usage: GetLogIndexForQuestID(questID)");
+        return 0;
+    }
+    const int target = static_cast<int>(Game::Lua::ToNumber(L, 1));
+    if (target <= 0)
+        return 0; // nil — no such quest
+
+    const int total = *reinterpret_cast<const int *>(
+        static_cast<uintptr_t>(Offsets::VAR_QUEST_LOG_ENTRY_COUNT));
+    auto *base = reinterpret_cast<const uint8_t *>(
+        static_cast<uintptr_t>(Offsets::VAR_QUEST_LOG_ENTRIES));
+    for (int i = 0; i < total; ++i) {
+        auto *entry = base + i * Offsets::OFF_QUEST_LOG_ENTRY_STRIDE;
+        if (*reinterpret_cast<const void *const *>(
+                entry + Offsets::OFF_QUEST_LOG_ENTRY_HEADER_PTR) != nullptr)
+            continue; // header row
+        const int questID = *reinterpret_cast<const int *>(
+            entry + Offsets::OFF_QUEST_LOG_ENTRY_QUEST_ID);
+        if (questID == target) {
+            Game::Lua::PushNumber(L, static_cast<double>(i + 1)); // 1-based
+            return 1;
+        }
+    }
+    return 0; // nil — quest not in the log
+}
+
+// `C_QuestLog.GetHeaderIndexForQuest(questID)` — the 1-based log index of the
+// collapsible category header (zone / "Dungeon" / class sort, …) the quest
+// sits under, or nil if the quest isn't in the log or has no header above it.
+// The log is laid out header-then-its-quests, so we locate the quest's entry
+// and walk backwards to the nearest preceding header row (`+8` non-NULL).
+static int __fastcall Script_GetHeaderIndexForQuest(void *L) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, "Usage: GetHeaderIndexForQuest(questID)");
+        return 0;
+    }
+    const int target = static_cast<int>(Game::Lua::ToNumber(L, 1));
+    if (target <= 0)
+        return 0; // nil — no such quest
+
+    const int total = *reinterpret_cast<const int *>(
+        static_cast<uintptr_t>(Offsets::VAR_QUEST_LOG_ENTRY_COUNT));
+    auto *base = reinterpret_cast<const uint8_t *>(
+        static_cast<uintptr_t>(Offsets::VAR_QUEST_LOG_ENTRIES));
+
+    // Locate the quest's entry.
+    int questIndex = -1;
+    for (int i = 0; i < total; ++i) {
+        auto *entry = base + i * Offsets::OFF_QUEST_LOG_ENTRY_STRIDE;
+        if (*reinterpret_cast<const void *const *>(
+                entry + Offsets::OFF_QUEST_LOG_ENTRY_HEADER_PTR) != nullptr)
+            continue; // header row
+        if (*reinterpret_cast<const int *>(
+                entry + Offsets::OFF_QUEST_LOG_ENTRY_QUEST_ID) == target) {
+            questIndex = i;
+            break;
+        }
+    }
+    if (questIndex < 0)
+        return 0; // quest not in the log
+
+    // Walk back to the nearest preceding header.
+    for (int i = questIndex - 1; i >= 0; --i) {
+        auto *entry = base + i * Offsets::OFF_QUEST_LOG_ENTRY_STRIDE;
+        if (*reinterpret_cast<const void *const *>(
+                entry + Offsets::OFF_QUEST_LOG_ENTRY_HEADER_PTR) != nullptr) {
+            Game::Lua::PushNumber(L, static_cast<double>(i + 1)); // 1-based
+            return 1;
+        }
+    }
+    return 0; // nil — quest sits above any header (shouldn't normally happen)
+}
+
 // `C_QuestLog.IsOnQuest(questID)` — true iff `questID` is currently
 // in the player's quest log (incomplete OR ready-to-turn-in; the log
 // holds both). Walks `VAR_QUEST_LOG_ENTRIES` and matches against each
@@ -148,6 +229,10 @@ static int __fastcall Script_IsUnitOnQuest(void *L) {
 static void RegisterLuaFunctions() {
     Game::Lua::RegisterTableFunction("C_QuestLog", "GetQuestIDForLogIndex",
                                      &Script_GetQuestIDForLogIndex);
+    Game::Lua::RegisterTableFunction("C_QuestLog", "GetLogIndexForQuestID",
+                                     &Script_GetLogIndexForQuestID);
+    Game::Lua::RegisterTableFunction("C_QuestLog", "GetHeaderIndexForQuest",
+                                     &Script_GetHeaderIndexForQuest);
     Game::Lua::RegisterTableFunction("C_QuestLog", "IsOnQuest",
                                      &Script_IsOnQuest);
     Game::Lua::RegisterTableFunction("C_QuestLog", "IsUnitOnQuest",

src/spell/BonusDamage.cpp

@@ -0,0 +1,295 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `GetSpellBonusDamage(school)` / `GetSpellBonusHealing()` — the local
+// player's flat spell-damage (per school) and healing bonus.
+//
+// **Spell damage is a direct field read.** The value lives in the CGPlayer
+// sub-struct at `[player + OFF_CGPLAYER_INFO]` (the +0xE68 blob), NOT the
+// broadcast UpdateField descriptor at `+0x110` — the descriptor copy of
+// this field is never sent to the client and reads zero (which sent an
+// earlier version of this module down a "derive it from gear" path). The
+// +0xE68 copy is the client's fully-computed value: `MOD_DAMAGE_DONE_POS[7]`
+// at `+0xFD4`, `MOD_DAMAGE_DONE_NEG[7]` at `+0xFF0`, one int32 per school;
+// net = POS − NEG. Because it's the finished value, gear + enchants + buffs
+// + talents + set bonuses are all already baked in.
+//
+// This mirrors nampower's `Script_GetSpellPower` (same base + offsets),
+// cross-verified in-game: a geared mage reads 613 generic across the magic
+// schools with Fire at 647 (a +34 fire-specific piece on top of the 613).
+//
+// **Healing has no such field** — vanilla 1.12 never had `MOD_HEALING_DONE`
+// (TBC addition; `PLAYER_FIELD_BYTES` follows `_PCT` directly), and nothing
+// client-side computes a healing total (verified in-game: toggling a pure
+// +44-healing item moved NO field in the +0xE68 struct). So
+// `GetSpellBonusHealing` is DERIVED in two parts, both read from `Spell.dbc`:
+//
+//   1. Flat healing — Σ `SPELL_AURA_MOD_HEALING_DONE` (aura 135) off gear
+//      equip-effects, item enchants, random suffixes, and active buffs.
+//   2. Talent/buff stat→healing — the server's own `SpellBaseHealingBonusDone`
+//      sums `SPELL_AURA_MOD_SPELL_HEALING_OF_STAT_PERCENT` (aura 175) ×
+//      total Spirit / 100 over the unit's aura-175 auras. We mirror it: read
+//      total Spirit from `UNIT_FIELD_STAT4` (descriptor +0x250), then sum
+//      aura-175 percents over PASSIVE known spells (talents — Spiritual
+//      Guidance, `Spell.dbc` ranks 14901/15028..15031 = 5/10/15/20/25%) plus
+//      active buffs. Generic (any aura-175 talent/buff, incl. Turtle customs)
+//      and robust — it reads the percent directly, no client-vs-server value
+//      delta.
+//
+// An earlier attempt derived (2) as (spell_damage_field − derived_gear_damage)
+// — the part of the damage field gear doesn't explain. That was FRAGILE: the
+// field reflects values AFTER SpellMods, but our gear sum used raw DBC values.
+// Inner Fire (10951) is +60 in the DBC but +78 live (Improved Inner Fire, a
+// +15%/rank SpellMod), so an 18-point gap leaked into healing when that pure
+// +damage buff was gained. Reading aura 175 directly (above) sidesteps it.
+//
+// Residual: assumes talent ranks supersede (only the learned rank is known —
+// otherwise summed) and misses set-bonus healing granted via a set spell.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "dbc/Lookup.h"
+#include "item/ID.h"
+#include "item/Location.h"
+#include "item/StatAccum.h"
+#include "player/StatSignal.h"
+#include "spell/HealingAura.h"
+#include "tick/WorldTick.h"
+#include "unit/Identity.h"
+
+#include <cstdint>
+
+namespace Spell::BonusDamage {
+
+namespace {
+
+// ---------------------------------------------------------------------------
+// Spell damage — direct read from the CGPlayer +0xE68 sub-struct.
+// ---------------------------------------------------------------------------
+
+const uint8_t *PlayerFields() {
+    const uint8_t *player = Unit::Identity::PlayerObject();
+    if (player == nullptr)
+        return nullptr;
+    return *reinterpret_cast<const uint8_t *const *>(
+        player + Offsets::OFF_CGPLAYER_INFO);
+}
+
+// Net spell damage for a 0-based school (0=physical .. 6=arcane). POS is the
+// full per-school value (generic "+spell damage" is already folded into every
+// magic school by the server), NEG the signed-magnitude negative accumulator.
+long SpellDamageForSchool(int school0) {
+    const uint8_t *pf = PlayerFields();
+    if (pf == nullptr)
+        return 0;
+    const int32_t pos = *reinterpret_cast<const int32_t *>(
+        pf + Offsets::OFF_PLAYER_FIELD_MOD_DAMAGE_DONE_POS + school0 * 4);
+    const int32_t neg = *reinterpret_cast<const int32_t *>(
+        pf + Offsets::OFF_PLAYER_FIELD_MOD_DAMAGE_DONE_NEG + school0 * 4);
+    return static_cast<long>(pos) - static_cast<long>(neg);
+}
+
+// ---------------------------------------------------------------------------
+// Healing — derived (no client field exists in vanilla).
+//
+// Item flat +healing goes through the shared Item::StatAccum engine (base
+// record + on-equip spells + random suffix + applied enchants) — exactly the
+// ITEM_MOD_SPELL_HEALING_DONE_SHORT (aura 135) value GetItemStats reports, so
+// the item spell/suffix/enchant walk isn't re-implemented here. Buff / talent
+// healing (flat + Spirit/Armor conversions) is decoded from Spell.dbc below.
+// ---------------------------------------------------------------------------
+
+// Flat +healing contributed by one equipped item, via Item::StatAccum.
+long ItemFlatHealing(const uint8_t *cgItem) {
+    if (cgItem == nullptr)
+        return 0;
+    Item::StatAccum::Accum acc[Item::StatAccum::kCount];
+    Item::StatAccum::Init(acc);
+
+    const int itemID = Item::ID::FromCGItem(cgItem);
+    if (itemID > 0)
+        Item::StatAccum::AccumulateRecord(
+            acc, Item::StatAccum::FetchRecord(static_cast<uint32_t>(itemID)), +1);
+
+    auto *desc = *reinterpret_cast<const uint8_t *const *>(
+        cgItem + Offsets::OFF_ITEM_DESCRIPTOR);
+    if (desc != nullptr) {
+        // Random suffix ("… of Restoration") + applied permanent (slot 0) and
+        // temporary (slot 1) enchants (Healing Power, Mana Oil, …).
+        Item::StatAccum::ApplyRandomSuffix(
+            acc, *reinterpret_cast<const int32_t *>(
+                     desc + Offsets::OFF_DESCRIPTOR_RANDOM_PROPERTY), +1);
+        for (int slot = 0; slot <= 1; ++slot)
+            Item::StatAccum::ApplyEnchant(
+                acc, *reinterpret_cast<const uint32_t *>(
+                         desc + Offsets::OFF_DESCRIPTOR_ENCHANTMENT_ID +
+                         slot * Offsets::DESCRIPTOR_ENCHANTMENT_SLOT_STRIDE), +1);
+    }
+    return Item::StatAccum::Value(acc, "ITEM_MOD_SPELL_HEALING_DONE_SHORT");
+}
+
+// --- Buff / talent healing auras (flat + Spirit/Armor conversions) ---
+// One decoder for every healing aura a buff or passive talent can carry,
+// mirroring the server's SpellBaseHealingBonusDone. Stock vanilla auras are
+// handled inline:
+//   135  MOD_HEALING_DONE                   → flat  += amount
+//   175  MOD_SPELL_HEALING_OF_STAT_PERCENT  → += Spirit × amount / 100  (Spiritual Guidance)
+// Any other aura index is deferred to `Spell::HealingAura::Resolve`, the
+// extension point where server-custom healing auras live (e.g. Turtle's
+// Ironclad, aura 199 = × Armor — see src/turtle/HealingAura.cpp). Amounts/
+// percents are read straight from Spell.dbc — generic and robust (no
+// client-vs-server value delta). `requirePassive` gates the bitmap walk to
+// always-on talents, so a *known but not-currently-cast* buff (Divine
+// Spirit) isn't counted as on; active buffs pass `requirePassive == false`.
+constexpr int kAuraModHealingDone = 135;
+constexpr int kAuraModHealingOfStatPercent = 175;  // × Spirit
+
+void AddSpellHealingAuras(long &total, int spellID, int32_t spirit,
+                          int32_t armor, bool requirePassive) {
+    if (spellID <= 0)
+        return;
+    const uint8_t *sp = DBC::Record(Offsets::VAR_SPELL_RECORDS,
+                                    Offsets::VAR_SPELL_RECORD_COUNT,
+                                    static_cast<uint32_t>(spellID));
+    if (sp == nullptr)
+        return;
+    if (requirePassive &&
+        !(*reinterpret_cast<const uint32_t *>(sp + Offsets::OFF_SPELL_RECORD_ATTRIBUTES) &
+          Offsets::SPELL_ATTR_PASSIVE))
+        return;
+    auto aura = reinterpret_cast<const int32_t *>(
+        sp + Offsets::OFF_SPELL_RECORD_EFFECT_APPLY_AURA_NAME);
+    auto base = reinterpret_cast<const int32_t *>(
+        sp + Offsets::OFF_SPELL_RECORD_EFFECT_BASE_POINTS);
+    auto dice = reinterpret_cast<const int32_t *>(
+        sp + Offsets::OFF_SPELL_RECORD_EFFECT_BASE_DICE);
+    for (int i = 0; i < Offsets::SPELL_RECORD_EFFECT_COUNT; ++i) {
+        const long amount = static_cast<long>(base[i]) + static_cast<long>(dice[i]);
+        if (aura[i] == kAuraModHealingDone)
+            total += amount;
+        else if (aura[i] == kAuraModHealingOfStatPercent)
+            total += static_cast<long>(spirit) * amount / 100;
+        else
+            total += Spell::HealingAura::Resolve(aura[i], amount, spirit, armor);
+    }
+}
+
+long ComputeHealing() {
+    long total = 0;
+
+    // Items — flat +healing via the shared StatAccum engine.
+    for (int slot = 1; slot <= 19; ++slot)
+        total += ItemFlatHealing(Item::Location::ResolveEquipmentSlot(slot));
+
+    // Player Spirit / Armor for the aura-175 / aura-199 conversions.
+    const uint8_t *desc = Unit::Identity::PlayerDescriptor();
+    const int32_t spirit = desc ? *reinterpret_cast<const int32_t *>(
+        desc + Offsets::OFF_UNIT_FIELD_STAT_SPIRIT) : 0;
+    const int32_t armor = desc ? *reinterpret_cast<const int32_t *>(
+        desc + Offsets::OFF_UNIT_FIELD_RESISTANCE_ARMOR) : 0;
+
+    // Active buffs — flat healing + Spirit/Armor conversions, one pass.
+    auto *table = reinterpret_cast<const uint8_t *>(
+        static_cast<uintptr_t>(Offsets::VAR_PLAYER_BUFF_TABLE));
+    for (int i = 0; i < Offsets::PLAYER_BUFF_TABLE_COUNT; ++i) {
+        const uint8_t *entry = table + i * Offsets::PLAYER_BUFF_ENTRY_STRIDE;
+        if (*reinterpret_cast<const int32_t *>(
+                entry + Offsets::OFF_PLAYER_BUFF_SLOT_CODE) < 0)
+            continue;
+        AddSpellHealingAuras(total, *reinterpret_cast<const int32_t *>(
+                                        entry + Offsets::OFF_PLAYER_BUFF_SPELL_ID),
+                             spirit, armor, /*requirePassive=*/false);
+    }
+
+    // Passive talents — Spirit/Armor conversions (Spiritual Guidance, Ironclad)
+    // and any passive flat healing, via the known-spell bitmap (bounded by
+    // spellCount). The passive gate assumes ranks supersede (only the learned
+    // rank is known), so no per-rank dedup is needed.
+    auto *bitmap = *reinterpret_cast<const uint32_t *const *>(
+        static_cast<uintptr_t>(Offsets::VAR_PLAYER_SPELL_BITMAP));
+    const int spellCount = *reinterpret_cast<const int *>(
+        static_cast<uintptr_t>(Offsets::VAR_SPELL_RECORD_COUNT));
+    if (bitmap != nullptr && spellCount > 0) {
+        for (int id = 1; id <= spellCount; ++id)
+            if (bitmap[id >> 5] & (1u << (id & 31)))
+                AddSpellHealingAuras(total, id, spirit, armor, /*requirePassive=*/true);
+    }
+
+    return total;
+}
+
+// Event-driven cache for the derived healing sum. The walk (StatAccum over 19
+// items + the buff table + the known-spell bitmap) is expensive, so we
+// recompute it ONLY when the player's stat inputs change — Player::StatSignal
+// is bumped from the aura and equipment hooks, so a per-frame
+// GetSpellBonusHealing poll is O(1) between real gear/buff changes.
+//
+// Every input to the sum is now event-driven: the aura, equipment, and
+// spell-learn/unlearn hooks all bump Player::StatSignal (buffs, gear, and
+// talent respecs respectively). This coarse world-tick recompute (at most once
+// per kFallbackTicks frames, ~4s) is a pure backstop against a missed signal —
+// e.g. a player aura the object-pointer guard in aura/Source didn't match —
+// bounding staleness rather than being the primary mechanism.
+constexpr int kFallbackTicks = 256;
+uint32_t g_cachedEpoch = 0;     // 0 = never computed (epoch starts at 1)
+int g_ticksSinceCompute = 0;
+long g_cachedHealing = 0;
+
+void OnTick() { ++g_ticksSinceCompute; }
+const Tick::WorldTick::AutoSubscribe _tick{&OnTick};
+
+long CurrentHealing() {
+    const uint32_t epoch = Player::StatSignal::Epoch();
+    if (epoch != g_cachedEpoch || g_ticksSinceCompute >= kFallbackTicks) {
+        g_cachedHealing = ComputeHealing();
+        g_cachedEpoch = epoch;
+        g_ticksSinceCompute = 0;
+    }
+    return g_cachedHealing;
+}
+
+// ---------------------------------------------------------------------------
+// Lua bindings.
+// ---------------------------------------------------------------------------
+
+// `GetSpellBonusDamage(school)` → number. `school` is 1-based (1=Physical
+// through 7=Arcane). Raises the usage error for a missing / out-of-range
+// school, matching 3.3.5's Script_GetSpellBonusDamage (0x0060E310).
+int __fastcall Script_GetSpellBonusDamage(void *L) {
+    const int school =
+        Game::Lua::IsNumber(L, 1) ? static_cast<int>(Game::Lua::ToNumber(L, 1)) : 0;
+    const unsigned idx = static_cast<unsigned>(school - 1);
+    if (idx >= static_cast<unsigned>(Offsets::SPELL_SCHOOL_COUNT)) {
+        Game::Lua::Error(L, "Usage: GetSpellBonusDamage(school)");
+        return 0;
+    }
+    Game::Lua::PushNumber(L, static_cast<double>(SpellDamageForSchool(static_cast<int>(idx))));
+    return 1;
+}
+
+// `GetSpellBonusHealing()` → number. The player's flat healing bonus (derived).
+int __fastcall Script_GetSpellBonusHealing(void *L) {
+    Game::Lua::PushNumber(L, static_cast<double>(CurrentHealing()));
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterGlobalFunction("GetSpellBonusDamage", &Script_GetSpellBonusDamage);
+    Game::Lua::RegisterGlobalFunction("GetSpellBonusHealing", &Script_GetSpellBonusHealing);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace Spell::BonusDamage

src/spell/Cast.cpp

@@ -91,6 +91,7 @@ using GetDuration_t = int(__fastcall *)(const uint8_t *spellRecord, int unit, in
 constexpr int OFF_NAME = 0x1E0;            // localized name[9]
 constexpr int OFF_ICON_ID = 0x1D4;         // -> SpellIcon.dbc
 constexpr int OFF_ATTRIBUTES = 0x18;       // u32 Attributes flags
+constexpr int OFF_ATTRIBUTES_EX2 = 0x24;   // u32 AttributesEx2 flags
 constexpr int OFF_SUBRECORD_VALUE = 0x04;  // SpellIcon path field
 
 // SPELL_ATTR_TRADESPELL — set on profession recipe casts (enchant,
@@ -99,6 +100,12 @@ constexpr int OFF_SUBRECORD_VALUE = 0x04;  // SpellIcon path field
 // there, +0x18 here — the bit value is the same across builds).
 constexpr uint32_t SPELL_ATTR_TRADESPELL = 0x20;
 
+// SPELL_ATTR_RANGED — every ranged ability carries it; the server adds a
+// flat +500ms "aim time" to these (SpellEntry::GetCastTime). Auto-repeat
+// shots (Auto Shot / Shoot, AttributesEx2 bit 0x20) are the one exclusion.
+constexpr uint32_t SPELL_ATTR_RANGED = 0x2;
+constexpr uint32_t SPELL_ATTR_EX2_AUTOREPEAT = 0x20;
+
 struct TrackedSpell {
     int spellID; // 0 = not casting / channeling
     int startMs;
@@ -163,8 +170,30 @@ void *Resolve(const char *token) {
 // matches the engine's cast bar exactly — including talents like a Mage's
 // faster casts. Unit arg 0 = local player; flag 0 clamps negatives to 0.
 int CastTimeMs(int spellID) {
-    return static_cast<int>(
+    int ms = static_cast<int>(
         reinterpret_cast<GetCastTime_t>(Offsets::FUN_GET_CAST_TIME)(spellID, 0, 0));
+    // FUN_006e3340 (also the spell tooltip's cast-time source) does NOT add the
+    // flat +500ms "aim time" the server applies to ranged, non-autorepeat
+    // spells — SpellEntry::GetCastTime does `castTime += 500` for
+    // SPELL_ATTR_RANGED. So our zero-latency prediction runs ~500ms short of
+    // the server for Volley / Aimed Shot / Multi-Shot; the confirming
+    // SMSG_SPELL_START then snaps the bar out ~1 RTT later. Mirror the server
+    // here so the prediction is right from frame 1 (only for spells that
+    // already have a cast time — instant ranged abilities that the server
+    // gives a 500ms aim time still surface through the packet path). The
+    // cast-time reconcile in HandleSpellStart remains the backstop.
+    if (ms > 0) {
+        const uint8_t *rec = Spell::Lookup::RecordForID(spellID);
+        if (rec != nullptr) {
+            const uint32_t attr =
+                *reinterpret_cast<const uint32_t *>(rec + OFF_ATTRIBUTES);
+            const uint32_t attrEx2 =
+                *reinterpret_cast<const uint32_t *>(rec + OFF_ATTRIBUTES_EX2);
+            if ((attr & SPELL_ATTR_RANGED) && !(attrEx2 & SPELL_ATTR_EX2_AUTOREPEAT))
+                ms += 500;
+        }
+    }
+    return ms;
 }
 
 // Effective channel duration (ms) for the local player, 0 if none. Uses
@@ -407,13 +436,26 @@ void HandleSpellStart(uint64_t caster, int spellID, uint32_t castTime) {
         // Spell_C_CastSpell at `spellID == VAR_CURRENT_CAST_SPELL`, so the
         // client path (FUN_CAST_START_SET hook) never fires for them — this
         // server packet is the only signal. Dedup against a fresh client stamp
-        // (same spell, started within ~latency) so a normal cast's confirming
-        // packet doesn't restart its bar; otherwise it's a chained recast the
+        // (same spell, started within ~latency): a normal cast's confirming
+        // packet mustn't RESTART its bar; otherwise it's a chained recast the
         // client bailed on — take it, and flag it so the VAR==0 poll (which
         // never saw it) won't clear it.
         if (g_cast.spellID == spellID && now < g_cast.endMs &&
-            now - g_cast.startMs < kCastStartDedupMs)
+            now - g_cast.startMs < kCastStartDedupMs) {
+            // Confirming packet. Keep startMs (no visual restart), but SNAP the
+            // end time to the server's authoritative castTime. The client stamp
+            // came from FUN_006e3340, which folds in the caster's cast-speed /
+            // ranged-haste multiplier (descriptor +0x22c) — right for spells the
+            // server also hastes (Aimed/Multi-Shot), WRONG for ones it doesn't.
+            // Volley is the case that surfaced this: not channeled, not sped by
+            // Quick Shots server-side, so the hasted prediction ended the bar
+            // early and the player was "still casting after the bar finished."
+            // The server's castTime is reality; reconcile to it (preserving any
+            // pushback already accumulated). A no-op when client and server agree.
+            g_cast.endMs =
+                g_cast.startMs + static_cast<int>(castTime) + g_cast.delayMs;
             return;
+        }
         g_cast = TrackedSpell{spellID, now, now + static_cast<int>(castTime), 0};
         g_castFromServer = true;
         g_channel.spellID = 0; // a cast supersedes any channel

src/spell/EffectMechanic.cpp

@@ -0,0 +1,76 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `C_Spell.GetSpellEffectMechanics(spellID)` -> { m1, m2, m3 }
+//
+// Returns a spell's three per-effect mechanic ids (Spell.dbc
+// `EffectMechanic[3]`) as a 1-based array table, or nil for an invalid /
+// out-of-range spell ID. Each entry is a standard WoW SpellMechanic id
+// (0 = that effect carries no mechanic); the numbering matches
+// C_Spell.GetSpellMechanicByID (1 = Charm, 7 = Root, 12 = Stun,
+// 15 = Bleed, 17 = Polymorph, ...).
+//
+// Complements GetSpellMechanicByID, which reads only the SPELL-level
+// `Mechanic` field (+0x14). Vanilla frequently stores the meaningful
+// mechanic on an *effect* rather than the spell — periodic damage such
+// as bleeds is the common case — so effect-mechanic-aware callers (e.g.
+// bleed classification for immunity tracking) need this array too:
+//
+//   local em = C_Spell.GetSpellEffectMechanics(spellID)
+//   if em then for i = 1, 3 do if em[i] == 15 then --[[ bleed ]] end end end
+//
+// Reads Spell.dbc directly, so it covers every spell the client knows —
+// not just the player's spellbook — with no caching or network round-trip
+// (Spell.dbc is resident from boot).
+
+#include "Game.h"
+#include "Offsets.h"
+#include "spell/Arg.h"
+#include "spell/Lookup.h"
+
+#include <cstdint>
+
+namespace Spell::EffectMechanic {
+
+namespace {
+
+int __fastcall Script_GetSpellEffectMechanics(void *L) {
+    const int spellID = Spell::Arg::ResolveSpellID(L, 1);
+    const uint8_t *record = Spell::Lookup::RecordForID(spellID);
+    if (record == nullptr)
+        return 0; // nil for invalid / out-of-range spell IDs
+
+    auto *mechanics = reinterpret_cast<const uint32_t *>(
+        record + Offsets::OFF_SPELL_RECORD_EFFECT_MECHANIC);
+
+    // Fixed 1-based array of all three effects (0 = effect has no mechanic),
+    // matching the raw EffectMechanic[3] layout so callers can index by slot.
+    Game::Lua::NewTable(L);
+    for (int i = 0; i < Offsets::SPELL_RECORD_EFFECT_COUNT; ++i) {
+        Game::Lua::PushNumber(L, static_cast<double>(i + 1));        // key
+        Game::Lua::PushNumber(L, static_cast<double>(mechanics[i])); // value
+        Game::Lua::SetTable(L, -3);
+    }
+    return 1;
+}
+
+} // namespace
+
+static void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_Spell", "GetSpellEffectMechanics",
+                                     &Script_GetSpellEffectMechanics);
+}
+
+static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace Spell::EffectMechanic

src/spell/HealingAura.cpp

@@ -0,0 +1,37 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#include "spell/HealingAura.h"
+
+namespace Spell::HealingAura {
+
+namespace {
+
+// Chained at static-init by each `AutoResolver` constructor, before
+// `DllMain`. Zero-initialized ahead of any dynamic init.
+AutoResolver *g_resolvers = nullptr;
+
+} // namespace
+
+AutoResolver::AutoResolver(Resolver f) : fn(f), next(g_resolvers) {
+    g_resolvers = this;
+}
+
+long Resolve(int auraIndex, long amount, int32_t spirit, int32_t armor) {
+    for (AutoResolver *r = g_resolvers; r != nullptr; r = r->next)
+        if (const long v = r->fn(auraIndex, amount, spirit, armor))
+            return v;
+    return 0;
+}
+
+} // namespace Spell::HealingAura

src/spell/HealingAura.h

@@ -0,0 +1,45 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <cstdint>
+
+// Extension point for non-stock healing-aura semantics feeding
+// `GetSpellBonusHealing`. The stock vanilla healing auras — 135
+// (MOD_HEALING_DONE, flat) and 175 (MOD_SPELL_HEALING_OF_STAT_PERCENT,
+// ×Spirit) — are decoded inline in `spell/BonusDamage.cpp`. Server-custom
+// aura effects (e.g. Turtle's Ironclad, aura 199 = ×Armor) register a
+// resolver here so their meaning lives outside the stock decoder.
+namespace Spell::HealingAura {
+
+// Flat healing contribution for a single Spell.dbc aura effect: the aura
+// index plus its computed amount (base + dice), and the player's Spirit /
+// Armor for stat-scaled auras. Returns 0 for aura indices no resolver
+// recognizes. Consulted by the stock decoder for any effect that isn't a
+// stock healing aura.
+long Resolve(int auraIndex, long amount, int32_t spirit, int32_t armor);
+
+// A resolver maps one aura effect to its flat healing contribution, or
+// returns 0 if it doesn't recognize the aura index. Declare a file-scope
+// `static const Spell::HealingAura::AutoResolver` in a platform module to
+// register one at static-init time.
+using Resolver = long (*)(int auraIndex, long amount, int32_t spirit,
+                          int32_t armor);
+struct AutoResolver {
+    explicit AutoResolver(Resolver fn);
+    Resolver fn;
+    AutoResolver *next;
+};
+
+} // namespace Spell::HealingAura

src/spell/Info.cpp

@@ -13,6 +13,7 @@
 
 #include "Game.h"
 #include "Offsets.h"
+#include "player/StatSignal.h"
 #include "spell/Arg.h"
 #include "spell/Lookup.h"
 
@@ -442,34 +443,46 @@ static int __fastcall Script_C_IsSpellPassive(void *L) {
 //     arrays and not in the talent tree).
 //   - Same shape modern WoW (5.4.8+) uses for the same function — see
 //     `[0x011C25D8]` in 5.4.8's `Wow.exe`.
+// Shared read of the engine's known-spell bitmap (the same bit the helper
+// at `0x0060C740` consults): true iff the local player knows `spellID`.
+// Bounds-checked; false for out-of-range IDs or before the bitmap exists.
+static bool PlayerKnowsSpell(int spellID) {
+    if (spellID < 1)
+        return false;
+    const int spellCount = *reinterpret_cast<const int *>(
+        static_cast<uintptr_t>(Offsets::VAR_SPELL_RECORD_COUNT));
+    if (spellID > spellCount)
+        return false;
+    auto *bitmap = *reinterpret_cast<const uint32_t *const *>(
+        static_cast<uintptr_t>(Offsets::VAR_PLAYER_SPELL_BITMAP));
+    if (bitmap == nullptr)
+        return false;
+    const uint32_t mask = 1u << (spellID & 31);
+    return (bitmap[spellID >> 5] & mask) != 0;
+}
+
 static int __fastcall Script_IsPlayerSpell(void *L) {
     if (!Game::Lua::IsNumber(L, 1)) {
         Game::Lua::Error(L, "Usage: IsPlayerSpell(spellID)");
         return 0;
     }
     const int spellID = static_cast<int>(Game::Lua::ToNumber(L, 1));
-    if (spellID < 1) {
-        Game::Lua::PushBool(L, 0);
-        return 1;
-    }
+    Game::Lua::PushBoolean(L, PlayerKnowsSpell(spellID));
+    return 1;
+}
 
-    const int spellCount = *reinterpret_cast<const int *>(
-        static_cast<uintptr_t>(Offsets::VAR_SPELL_RECORD_COUNT));
-    if (spellID > spellCount) {
-        Game::Lua::PushBoolean(L, 0);
-        return 1;
-    }
+// `CanDualWield()` — true if the local player can equip a weapon in the off
+// hand. The server tracks this as a plain bool (`Player::m_canDualWield`)
+// flipped on only by `SPELL_EFFECT_DUAL_WIELD` (effect 40); no class has it
+// innately. Verified against the client Spell.dbc: exactly ONE spell carries
+// that effect — 674 "Dual Wield", the trained warrior/rogue/hunter passive —
+// and it lands in the known-spell bitmap like any learned spell. So there's
+// no separate client-visible capability flag to read; `IsPlayerSpell(674)`
+// is the exact equivalent of the server's `CanDualWield()`.
+static constexpr int kDualWieldSpellID = 674;
 
-    auto *bitmap = *reinterpret_cast<const uint32_t *const *>(
-        static_cast<uintptr_t>(Offsets::VAR_PLAYER_SPELL_BITMAP));
-    if (bitmap == nullptr) {
-        Game::Lua::PushBoolean(L, 0);
-        return 1;
-    }
-
-    const uint32_t mask = 1u << (spellID & 31);
-    const bool isKnown = (bitmap[spellID >> 5] & mask) != 0;
-    Game::Lua::PushBoolean(L, isKnown);
+static int __fastcall Script_CanDualWield(void *L) {
+    Game::Lua::PushBoolean(L, PlayerKnowsSpell(kDualWieldSpellID));
     return 1;
 }
 
@@ -586,6 +599,35 @@ static int __fastcall Script_C_Spell_IsSpellHelpful(void *L) {
     return 1;
 }
 
+// --- Known-spell-bitmap change signal ------------------------------------
+// Learning/unlearning a spell rewrites the bitmap GetSpellBonusHealing scans
+// for talent conversions (Spiritual Guidance / Ironclad). Co-hook the engine's
+// learn + unlearn writers and bump Player::StatSignal, so a talent respec
+// invalidates the healing cache immediately — the same event-driven path as
+// aura/equipment changes, no polling. Both fire only at login and on
+// learn/unlearn (never per-frame), so they're safe co-hook targets.
+using LearnSpell_t = void(__fastcall *)(uint32_t spellID, int notify,
+                                        uint32_t replacedSpellID);
+static LearnSpell_t g_origLearnSpell = nullptr;
+static void __fastcall LearnSpell_h(uint32_t spellID, int notify,
+                                    uint32_t replacedSpellID) {
+    g_origLearnSpell(spellID, notify, replacedSpellID);
+    Player::StatSignal::Notify();
+}
+static const Game::HookAutoRegister _hookLearnSpell{
+    Offsets::FUN_LEARN_SPELL, reinterpret_cast<void *>(&LearnSpell_h),
+    reinterpret_cast<void **>(&g_origLearnSpell)};
+
+using UnlearnSpell_t = void(__fastcall *)(uint32_t spellID, int param2);
+static UnlearnSpell_t g_origUnlearnSpell = nullptr;
+static void __fastcall UnlearnSpell_h(uint32_t spellID, int param2) {
+    g_origUnlearnSpell(spellID, param2);
+    Player::StatSignal::Notify();
+}
+static const Game::HookAutoRegister _hookUnlearnSpell{
+    Offsets::FUN_UNLEARN_SPELL, reinterpret_cast<void *>(&UnlearnSpell_h),
+    reinterpret_cast<void **>(&g_origUnlearnSpell)};
+
 static void RegisterLuaFunctions() {
     Game::Lua::RegisterGlobalFunction("GetSpellInfo", &Script_GetSpellInfo);
     Game::Lua::RegisterGlobalFunction("GetSpellLink", &Script_GetSpellLink);
@@ -593,6 +635,7 @@ static void RegisterLuaFunctions() {
                                       &Script_FindSpellBookSlotByID);
     Game::Lua::RegisterGlobalFunction("IsPassiveSpell", &Script_IsPassiveSpell);
     Game::Lua::RegisterGlobalFunction("IsPlayerSpell", &Script_IsPlayerSpell);
+    Game::Lua::RegisterGlobalFunction("CanDualWield", &Script_CanDualWield);
     Game::Lua::RegisterGlobalFunction("IsSpellKnown", &Script_IsSpellKnown);
     Game::Lua::RegisterGlobalFunction("IsHarmfulSpell", &Script_IsHarmfulSpell);
     Game::Lua::RegisterGlobalFunction("IsHelpfulSpell", &Script_IsHelpfulSpell);

src/spell/Tooltip.cpp

@@ -55,6 +55,71 @@ static int __fastcall Script_GameTooltipSetSpellByID(void *L) {
     return 0;
 }
 
+// `GameTooltip:AddSpellByID(spellID)` — APPENDS a spell's tooltip to the
+// current one instead of clearing+rebuilding (the `SetSpellByID` behavior).
+// The natural pair to `SetSpellByID`; lets callers compose tooltips like
+// `AddLine(talentName) + AddSpellByID(rankSpellID)`.
+//
+// `BuildSpellTooltip`'s last arg (`param_7`) gates the clear: `0` calls the
+// per-tooltip Clear (`FUN_00530050`) first — that's `SetSpellByID`; non-zero
+// SKIPS the clear and appends. The append path is the engine's talent
+// "next rank" preview, so it (a) emits a `"\nNext rank:"` header line
+// instead of the spell name, and (b) does NOT stash the displayed spellID at
+// `+0x39C` (so `GetSpell` keeps reflecting the base tooltip — correct for an
+// append). We fix (a) by overwriting that header line — which lands at index
+// `numLines`-before-the-build (0-based) — with the real spell name via the
+// line pool's left-text FontString. Verified against `FUN_0052E610`.
+void AppendByID(void *L, int spellID) {
+    if (spellID <= 0)
+        return;
+    void *tooltipObj = Game::Lua::ResolveObject(L, 1);
+    if (tooltipObj == nullptr)
+        return;
+    auto *tt = static_cast<uint8_t *>(tooltipObj);
+
+    const int before = *reinterpret_cast<const int *>(
+        tt + Offsets::OFF_GAMETOOLTIP_NUM_LINES);
+
+    auto BuildSpellTooltip =
+        reinterpret_cast<BuildSpellTooltip_t>(Offsets::FUN_GAMETOOLTIP_BUILD_SPELL_TOOLTIP);
+    BuildSpellTooltip(tooltipObj, spellID, 0, 0, 0, 0, 0, /*param_7 (append)=*/1);
+
+    const int after = *reinterpret_cast<const int *>(
+        tt + Offsets::OFF_GAMETOOLTIP_NUM_LINES);
+    if (after <= before)
+        return; // nothing appended (bad spellID / missing Spell.dbc record)
+
+    const uint8_t *record = Spell::Lookup::RecordForID(spellID);
+    if (record == nullptr)
+        return;
+    const int locale = *reinterpret_cast<const int *>(Offsets::VAR_LOCALE_INDEX);
+    const char *name = *reinterpret_cast<const char *const *>(
+        record + OFF_SPELL_NAME + locale * 4);
+    if (name == nullptr || name[0] == '\0')
+        return;
+
+    // Left-text FontString array: descriptor at +0x324, data ptr at +0x8.
+    auto **textLeft = *reinterpret_cast<void ***>(
+        tt + Offsets::OFF_GAMETOOLTIP_TEXTLEFT_DESC + 8);
+    if (textLeft == nullptr)
+        return;
+    void *fs = textLeft[before];
+    if (fs == nullptr)
+        return;
+    using SetText_t = void(__thiscall *)(void *fs, const char *text, int flag);
+    reinterpret_cast<SetText_t>(Offsets::FUN_FONTSTRING_SET_TEXT)(fs, name, 0);
+}
+
+static int __fastcall Script_GameTooltipAddSpellByID(void *L) {
+    if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE ||
+        !Game::Lua::IsNumber(L, 2)) {
+        Game::Lua::Error(L, "Usage: GameTooltip:AddSpellByID(spellID)");
+        return 0;
+    }
+    AppendByID(L, static_cast<int>(Game::Lua::ToNumber(L, 2)));
+    return 0;
+}
+
 // `GameTooltip:GetSpell()` → (name, rank, spellID) for whichever spell
 // the tooltip is currently displaying, or nothing if it isn't showing
 // a spell. BuildSpellTooltip writes the spellID to `tooltip+0x39C`;
@@ -126,6 +191,7 @@ static int __fastcall Script_GameTooltipHasSpell(void *L) {
 
 static const Game::Lua::FrameMethodEntry g_methods[] = {
     {"SetSpellByID", &Script_GameTooltipSetSpellByID},
+    {"AddSpellByID", &Script_GameTooltipAddSpellByID},
     {"GetSpell", &Script_GameTooltipGetSpell},
     {"HasSpell", &Script_GameTooltipHasSpell},
 };

src/spell/Tooltip.h

@@ -26,4 +26,13 @@ namespace Spell::Tooltip {
 // so we render the rank-1 spell tooltip instead).
 void ShowByID(void *L, int spellID);
 
+// Like `ShowByID` but APPENDS the spell's tooltip to the current one
+// (no clear), and overwrites the engine's talent "next rank" header with
+// the real spell name. Backs `GameTooltip:AddSpellByID`. Silent no-op if
+// `spellID <= 0`, stack[1] isn't a frame object, or the build added no
+// lines. Does not stash the displayed spellID (so `GetSpell` still
+// reflects the base tooltip). Useful for cross-class talent tooltips
+// (`AddLine(talentName) + AppendByID(rankSpellID)`).
+void AppendByID(void *L, int spellID);
+
 } // namespace Spell::Tooltip

src/table/Count.cpp

@@ -0,0 +1,77 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#include "Game.h"
+
+#include <cmath>
+#include <vector>
+
+namespace Table::Count {
+
+// `numTableNodes, numArrayNodes, maxArrayIndex = table.count(tbl)` — a modern
+// WoW diagnostic (added retail 11.2.5) reporting how a table is populated.
+// These are COUNTS of live entries, not the table's allocated capacity:
+//
+//   numTableNodes  total number of key/value pairs.
+//   numArrayNodes  count of pairs whose key is an integer in [1..numTableNodes]
+//                  (the "looks like a contiguous array part" heuristic).
+//   maxArrayIndex  the largest positive integral key (>= 1), or 0 if none.
+//                  Verified against retail: negative/zero integral keys do
+//                  NOT count ({[-3]=x} -> 1, 0, 0).
+//
+// Pure iteration — no Lua-internal struct layout needed. Note we only ever
+// read a key via ToNumber, never ToString: lua_tostring on a NUMERIC key
+// rewrites it to a string in place and corrupts lua_next's traversal.
+static int __fastcall Script_table_count(void *L) {
+    if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) {
+        Game::Lua::Error(L, "Usage: table.count(table)");
+        return 0;
+    }
+
+    std::vector<double> integralKeys;
+    int total = 0;
+    double maxKey = 0.0; // largest positive integral key seen; 0 = none
+
+    Game::Lua::PushNil(L);
+    while (Game::Lua::Next(L, 1) != 0) {
+        ++total;
+        // key at -2, value at -1.
+        if (Game::Lua::Type(L, -2) == Game::Lua::TYPE_NUMBER) {
+            const double k = Game::Lua::ToNumber(L, -2);
+            if (k == std::floor(k)) { // integral key
+                integralKeys.push_back(k);
+                if (k >= 1.0 && k > maxKey) // only positive keys count
+                    maxKey = k;
+            }
+        }
+        Game::Lua::SetTop(L, -2); // pop value, keep key for the next Next()
+    }
+
+    int numArray = 0;
+    for (double k : integralKeys)
+        if (k >= 1.0 && k <= static_cast<double>(total))
+            ++numArray;
+
+    Game::Lua::PushNumber(L, static_cast<double>(total));
+    Game::Lua::PushNumber(L, static_cast<double>(numArray));
+    Game::Lua::PushNumber(L, maxKey);
+    return 3;
+}
+
+static void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("table", "count", &Script_table_count);
+}
+
+static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace Table::Count

src/talent/Info.cpp

@@ -18,7 +18,12 @@
 
 namespace Talent::Info {
 
-// `GetTalentSpellID(tabIndex, talentIndex[, rank])` — returns the
+// Cross-class talent record resolver — defined below (before
+// `GetTalentIDByIndex`), shared by both talent getters' optional classID arg.
+static const uint8_t *ResolveTalentRecordForClass(int classID, int tabIndex,
+                                                   int talentIndex);
+
+// `GetTalentSpellID(tabIndex, talentIndex[, rank[, classID]])` — returns the
 // spellID for the given talent at the requested rank, or `nil` if the
 // talent isn't allocated (or any arg is out of range).
 //
@@ -34,13 +39,22 @@ namespace Talent::Info {
 // points in this talent), falls back to rank 1 so the function still
 // produces the talent's canonical spellID for unallocated talents.
 //
+// `classID` is optional (4th arg; pass `rank` as nil to use the default).
+// When a number, resolves against `Talent.dbc` / `TalentTab.dbc` for that
+// class instead of the player's runtime tree — same cross-class path as
+// `GetTalentIDByIndex`. There's no "currentRank" for a class you aren't, so a
+// cross-class query with no explicit `rank` defaults to rank 1 (the talent's
+// canonical spellID). Ordering matches the player-class path exactly (see
+// `ResolveTalentRecordForClass`).
+//
 // Returns `nil` when:
-//   - tab/talentIndex/rank are non-numeric or out of range
+//   - tab/talentIndex/rank/classID are non-numeric-when-required or out of range
 //   - the explicit `rank` exceeds the talent's allocated max (e.g. rank
 //     5 on a 1-rank talent — the SpellRank slot is zero)
 static int __fastcall Script_GetTalentSpellID(void *L) {
     if (!Game::Lua::IsNumber(L, 1) || !Game::Lua::IsNumber(L, 2)) {
-        Game::Lua::Error(L, "Usage: GetTalentSpellID(tabIndex, talentIndex[, rank])");
+        Game::Lua::Error(L,
+            "Usage: GetTalentSpellID(tabIndex, talentIndex[, rank[, classID]])");
         return 0;
     }
     const int tabIndex = static_cast<int>(Game::Lua::ToNumber(L, 1));
@@ -48,6 +62,29 @@ static int __fastcall Script_GetTalentSpellID(void *L) {
     if (tabIndex < 1 || talentIndex < 1)
         return 0;
 
+    // Explicit classID → cross-class DBC path. `rank` (arg 3) is still honored
+    // when given; without it we can't ask the engine for a currentRank on a
+    // class the player isn't, so default to rank 1.
+    if (Game::Lua::IsNumber(L, 4)) {
+        const int classID = static_cast<int>(Game::Lua::ToNumber(L, 4));
+        int rank = 1;
+        if (Game::Lua::IsNumber(L, 3)) {
+            rank = static_cast<int>(Game::Lua::ToNumber(L, 3));
+            if (rank < 1 || rank > Offsets::TALENT_MAX_RANKS)
+                return 0;
+        }
+        const uint8_t *rec =
+            ResolveTalentRecordForClass(classID, tabIndex, talentIndex);
+        if (rec == nullptr)
+            return 0;
+        const uint32_t spellID = *reinterpret_cast<const uint32_t *>(
+            rec + Offsets::OFF_TALENT_SPELL_RANK + (rank - 1) * sizeof(uint32_t));
+        if (spellID == 0)
+            return 0; // rank slot not populated (rank > maxRank for this talent)
+        Game::Lua::PushNumber(L, static_cast<double>(spellID));
+        return 1;
+    }
+
     // Pre-validate tab/idx so we don't trigger `lua_error` from the
     // engine's `Script_GetTalentInfo` on out-of-range input. The engine
     // bails to its error path (lua_error) on bad tab, bad talent index,
@@ -109,8 +146,74 @@ static int __fastcall Script_GetTalentSpellID(void *L) {
     return 1;
 }
 
-// `GetTalentIDByIndex(tabIndex, talentIndex)` — returns the Talent.dbc
-// primary key (the row's ID at `TalentEntry+0x00`) for the talent at
+// Cross-class talent resolution via the DBC flat arrays — mirrors the engine's
+// tree builder `FUN_004f2c00` but filtered to an arbitrary class instead of the
+// local player's. Used by `GetTalentSpellID` / `GetTalentIDByIndex`'s optional
+// `classID` arg so an addon can inspect any class's tree, not just the one it's
+// running on.
+
+// TalentTab.dbc rowID of the `tabIndex`-th (1-based) tab belonging to `classID`,
+// or 0. Tabs are taken in DBC row order and filtered by `classMask` (mask 0 =
+// all classes). Race isn't part of "which class owns a tab" — vanilla tabs are
+// never race-restricted — so we apply only the class half of `FUN_004f2e50`.
+static uint32_t NthClassTalentTabID(int classID, int tabIndex) {
+    const uint32_t classBit = 1u << ((classID - 1) & 0x1F);
+    auto *base = *reinterpret_cast<const uint8_t *const *>(
+        static_cast<uintptr_t>(Offsets::VAR_TALENTTAB_DBC_FLAT_RECORDS));
+    const int count = *reinterpret_cast<const int *>(
+        static_cast<uintptr_t>(Offsets::VAR_TALENTTAB_DBC_FLAT_COUNT));
+    if (base == nullptr)
+        return 0;
+    int match = 0;
+    for (int i = 0; i < count; ++i) {
+        const uint8_t *rec = base + i * Offsets::TALENTTAB_ENTRY_STRIDE;
+        const uint32_t classMask = *reinterpret_cast<const uint32_t *>(
+            rec + Offsets::OFF_TALENTTAB_CLASS_MASK);
+        if (classMask != 0 && (classMask & classBit) == 0)
+            continue;
+        if (++match == tabIndex)
+            return *reinterpret_cast<const uint32_t *>(
+                rec + Offsets::OFF_TALENTTAB_ID);
+    }
+    return 0;
+}
+
+// Talent.dbc record for the `talentIndex`-th (1-based) talent whose TabID is
+// `tabID`, in DBC row order — the same order the builder assigns within a tab.
+// Returns null if there aren't that many.
+static const uint8_t *NthTabTalentRecord(uint32_t tabID, int talentIndex) {
+    auto *base = *reinterpret_cast<const uint8_t *const *>(
+        static_cast<uintptr_t>(Offsets::VAR_TALENT_DBC_FLAT_RECORDS));
+    const int count = *reinterpret_cast<const int *>(
+        static_cast<uintptr_t>(Offsets::VAR_TALENT_DBC_FLAT_COUNT));
+    if (base == nullptr)
+        return nullptr;
+    int match = 0;
+    for (int i = 0; i < count; ++i) {
+        const uint8_t *rec = base + i * Offsets::TALENT_ENTRY_STRIDE;
+        if (*reinterpret_cast<const uint32_t *>(rec + Offsets::OFF_TALENT_DBC_TAB_ID) != tabID)
+            continue;
+        if (++match == talentIndex)
+            return rec;
+    }
+    return nullptr;
+}
+
+// The Talent.dbc record for (classID, tabIndex, talentIndex), or null on any
+// out-of-range input. `classID` is 1-based (1..31; vanilla uses 1..11 with 6/10
+// unused).
+static const uint8_t *ResolveTalentRecordForClass(int classID, int tabIndex,
+                                                   int talentIndex) {
+    if (classID < 1 || classID > 31 || tabIndex < 1 || talentIndex < 1)
+        return nullptr;
+    const uint32_t tabID = NthClassTalentTabID(classID, tabIndex);
+    if (tabID == 0)
+        return nullptr;
+    return NthTabTalentRecord(tabID, talentIndex);
+}
+
+// `GetTalentIDByIndex(tabIndex, talentIndex[, classID])` — returns the
+// Talent.dbc primary key (the row's ID at `TalentEntry+0x00`) for the talent at
 // the given (tab, idx). 1.12's `GetTalentInfo` returns
 // `(name, icon, tier, column, currentRank, maxRank, ...)` but NOT the
 // talentID, so addons that want a stable identifier (for SavedVariables
@@ -118,14 +221,22 @@ static int __fastcall Script_GetTalentSpellID(void *L) {
 // encode `(class, tab, tier, column)` and hope the talent tree doesn't
 // shift.
 //
-// Reads from the same per-tab talent arrays at `[VAR_TALENT_TAB_INFO_ARRAY]`
-// that #36 `GetTalentSpellID` walks. talentID at `+0x00` of the
-// `TalentEntry` was verified empirically during the GetTalentSpellID
-// debug pass: `entryFirstDword=174` matched Inner Focus's Talent.dbc
-// row ID (and `166` for the first Discipline talent).
+// Without `classID` (or when it's nil) it reads the player's own tree from the
+// per-tab talent arrays at `[VAR_TALENT_TAB_INFO_ARRAY]` (same source #36
+// `GetTalentSpellID` walks). talentID at `+0x00` of the `TalentEntry` was
+// verified empirically during the GetTalentSpellID debug pass:
+// `entryFirstDword=174` matched Inner Focus's Talent.dbc row ID (and `166` for
+// the first Discipline talent).
+//
+// With an explicit `classID` it resolves against the Talent.dbc / TalentTab.dbc
+// flat arrays instead, so it works for any class — not just the one the addon
+// is running on. The (tab, idx) ordering matches the player-class path exactly:
+// both come from the engine builder's DBC-row-order walk (see
+// `ResolveTalentRecordForClass` and the flat-array note in Offsets.h).
 static int __fastcall Script_GetTalentIDByIndex(void *L) {
     if (!Game::Lua::IsNumber(L, 1) || !Game::Lua::IsNumber(L, 2)) {
-        Game::Lua::Error(L, "Usage: GetTalentIDByIndex(tabIndex, talentIndex)");
+        Game::Lua::Error(L,
+            "Usage: GetTalentIDByIndex(tabIndex, talentIndex[, classID])");
         return 0;
     }
     const int tabIndex = static_cast<int>(Game::Lua::ToNumber(L, 1));
@@ -133,6 +244,21 @@ static int __fastcall Script_GetTalentIDByIndex(void *L) {
     if (tabIndex < 1 || talentIndex < 1)
         return 0;
 
+    // Explicit classID → cross-class DBC path. Omitted/nil → player's own class
+    // via the engine's runtime tab-info arrays (below).
+    if (Game::Lua::IsNumber(L, 3)) {
+        const int classID = static_cast<int>(Game::Lua::ToNumber(L, 3));
+        const uint8_t *rec =
+            ResolveTalentRecordForClass(classID, tabIndex, talentIndex);
+        if (rec == nullptr)
+            return 0;
+        const uint32_t talentID = *reinterpret_cast<const uint32_t *>(rec);
+        if (talentID == 0)
+            return 0;
+        Game::Lua::PushNumber(L, static_cast<double>(talentID));
+        return 1;
+    }
+
     const int tabCount = *reinterpret_cast<const int *>(
         static_cast<uintptr_t>(Offsets::VAR_TALENT_TAB_COUNT));
     if (tabIndex > tabCount)

src/target/Nearest.cpp

@@ -0,0 +1,328 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// Backports the post-vanilla TargetScript selection functions that 1.12.1
+// doesn't ship, built on the engine's own tab-targeting internals:
+//
+//   TargetNearest()                  — cycle nearest attackable/assistable unit
+//   TargetNearestEnemyPlayer([rev])  — cycle nearest hostile player (PvP)
+//   TargetNearestFriendPlayer([rev]) — cycle nearest friendly player
+//   TargetDirectionEnemy(facing[,cone])  — nearest hostile in a facing cone
+//   TargetDirectionFriend(facing[,cone]) — nearest friendly in a facing cone
+//
+// Vanilla already ships `TargetNearestEnemy/Friend/PartyMember/RaidMember`;
+// they run through `FUN_00493f60(reverse, mode)` — enumerate visible units,
+// keep those `FUN_00493e40(player, cand, mode)` accepts, sort by distance,
+// cycle, and commit via `FUN_00493540(guidLo, guidHi)`. We reuse the two
+// load-bearing pieces of that machinery directly:
+//
+//   * `FUN_00493e40` (Offsets::FUN_TARGET_CANDIDATE_VALID) — the exact
+//     per-mode validity predicate (mode 1 = enemy: attackable + alive +
+//     not-critter; mode 2 = friend: assistable + alive). Calling it gives
+//     us the engine's real reaction/hostility semantics with zero
+//     reimplementation.
+//   * `FUN_00493540` (Offsets::FUN_SET_SELECTION_BY_GUID) — the canonical
+//     setter the native cycle commits through (CMSG_SET_SELECTION + client
+//     target + event 0xC3), which also maintains the current-selection
+//     globals we read back for cycle continuity.
+//
+// So the only genuinely new logic here is (a) an extra player-GUID filter
+// for the `*Player` variants and (b) the cone geometry for the direction
+// variants — everything reaction-related defers to the engine.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "guid/Guid.h"
+#include "unit/Position.h"
+
+#include <cmath>
+#include <cstdint>
+
+namespace Target::Nearest {
+
+namespace {
+
+// Candidate class each function selects from.
+enum class Filter { Enemy, Friend, EnemyPlayer, FriendPlayer, Any };
+constexpr int kFilterCount = 5;
+
+// Default cone (full width, radians) when `coneAngle` is omitted — 90°, so
+// 45° to either side of the facing. The engine's own default constant
+// wasn't cleanly recoverable from the 3.3.5 reference binary; this is a
+// deliberate, documented choice that matches the "roughly in front of me"
+// intent of a direction-target keybind.
+constexpr float kDefaultConeAngle = 1.5707963f; // pi/2
+
+// Re-cycle window: repeated presses within this many ms advance through the
+// frozen candidate snapshot (no ping-pong as distances shift); a longer gap
+// rebuilds and re-targets the nearest. Mirrors the ~1s reset the native
+// cycle uses.
+constexpr uint32_t kCycleWindowMs = 1000;
+
+constexpr int kMaxCandidates = 64;
+
+// Engine entry points ─────────────────────────────────────────────────
+using Predicate_t = int(__fastcall *)(void *player, void *cand, int mode);
+using SetTargetByGuid_t = void(__fastcall *)(const uint64_t *guid);
+using EnumCallback_t = int(__fastcall *)(void *ctx, void *unusedEdx, uint64_t guid);
+using EnumVisibleObjects_t = int(__fastcall *)(EnumCallback_t cb, void *ctx);
+using ObjectPtr_t = void *(__fastcall *)(uint32_t typeMask, const char *dbg,
+                                         uint32_t guidLo, uint32_t guidHi,
+                                         int dbgCode);
+using TickMs_t = uint32_t(__fastcall *)();
+
+bool PassesFilter(void *player, void *cand, uint64_t guid, Filter f) {
+    auto valid = reinterpret_cast<Predicate_t>(Offsets::FUN_TARGET_CANDIDATE_VALID);
+    switch (f) {
+    case Filter::Enemy:        return valid(player, cand, 1) != 0;
+    case Filter::Friend:       return valid(player, cand, 2) != 0;
+    case Filter::EnemyPlayer:  return Guid::IsPlayer(guid) && valid(player, cand, 1) != 0;
+    case Filter::FriendPlayer: return Guid::IsPlayer(guid) && valid(player, cand, 2) != 0;
+    case Filter::Any:          return valid(player, cand, 1) != 0 ||
+                                      valid(player, cand, 2) != 0;
+    }
+    return false;
+}
+
+struct Candidate {
+    uint64_t guid;
+    float x, y;   // world XY (for the direction cone)
+    float distSq; // 3D squared distance from the player (for nearest)
+};
+
+struct CollectCtx {
+    void *player;
+    Filter filter;
+    float px, py, pz;
+    Candidate list[kMaxCandidates];
+    int count;
+};
+
+int __fastcall CollectCb(CollectCtx *ctx, void * /*edx*/, uint64_t guid) {
+    if (ctx->count >= kMaxCandidates)
+        return 1;
+    // Players and creatures both resolve under TYPEMASK_UNIT (CGPlayer
+    // derives from CGUnit); non-unit objects resolve to null and drop out.
+    auto ObjectPtr =
+        reinterpret_cast<ObjectPtr_t>(Offsets::FUN_CLNT_OBJ_MGR_OBJECT_PTR);
+    void *cand = ObjectPtr(Offsets::TYPEMASK_UNIT, nullptr,
+                           static_cast<uint32_t>(guid),
+                           static_cast<uint32_t>(guid >> 32), 0);
+    if (cand == nullptr || cand == ctx->player)
+        return 1;
+    if (!PassesFilter(ctx->player, cand, guid, ctx->filter))
+        return 1;
+
+    float pos[3];
+    if (!Unit::Position::Read(cand, pos))
+        return 1;
+    const float dx = pos[0] - ctx->px;
+    const float dy = pos[1] - ctx->py;
+    const float dz = pos[2] - ctx->pz;
+    Candidate &c = ctx->list[ctx->count++];
+    c.guid = guid;
+    c.x = pos[0];
+    c.y = pos[1];
+    c.distSq = dx * dx + dy * dy + dz * dz;
+    return 1;
+}
+
+// Enumerate visible units matching `f` into `out`. Returns false (empty)
+// pre-world or on a player-position miss.
+bool Collect(Filter f, CollectCtx *out) {
+    out->count = 0;
+    // The enumerator derefs the object manager unconditionally; null on the
+    // glue / character-select screen.
+    if (*reinterpret_cast<void *volatile *>(Offsets::VAR_LOCAL_PLAYER_PTR) ==
+        nullptr)
+        return false;
+    void *player = Unit::Position::ResolveToken("player");
+    float ppos[3];
+    if (!Unit::Position::Read(player, ppos))
+        return false;
+
+    out->player = player;
+    out->filter = f;
+    out->px = ppos[0];
+    out->py = ppos[1];
+    out->pz = ppos[2];
+    auto Enum = reinterpret_cast<EnumVisibleObjects_t>(
+        Offsets::FUN_CLNT_OBJ_MGR_ENUM_VISIBLE_OBJECTS);
+    Enum(reinterpret_cast<EnumCallback_t>(&CollectCb), out);
+    return true;
+}
+
+// Commit the selection through the engine's `Script_TargetUnit` helper
+// rather than the tab-cycle's raw `FUN_00493540`: this one first checks the
+// GUID resolves to a live unit and bails otherwise, so a stale GUID left in
+// a cycle snapshot (unit despawned / went out of range between presses)
+// gets rejected instead of committed. Committing a dead GUID would leave
+// `"target"` pointing at freed unit data and crash the next handler that
+// reads it. `FUN_TARGET_BY_GUID` still routes through `FUN_00493540`
+// internally, so the current-selection globals we read back are maintained.
+void SetTarget(uint64_t guid) {
+    reinterpret_cast<SetTargetByGuid_t>(Offsets::FUN_TARGET_BY_GUID)(&guid);
+}
+
+uint64_t CurrentSelection() {
+    const uint32_t lo = *reinterpret_cast<volatile uint32_t *>(
+        Offsets::VAR_CURRENT_SELECTION_GUID_LO);
+    const uint32_t hi = *reinterpret_cast<volatile uint32_t *>(
+        Offsets::VAR_CURRENT_SELECTION_GUID_HI);
+    return (static_cast<uint64_t>(hi) << 32) | lo;
+}
+
+uint32_t NowMs() {
+    return reinterpret_cast<TickMs_t>(Offsets::FUN_OS_TICKCOUNT_MS)();
+}
+
+// Ascending insertion sort by 3D distance (candidate counts are tiny).
+void SortByDistance(Candidate *a, int n) {
+    for (int i = 1; i < n; ++i) {
+        Candidate key = a[i];
+        int j = i - 1;
+        while (j >= 0 && a[j].distSq > key.distSq) {
+            a[j + 1] = a[j];
+            --j;
+        }
+        a[j + 1] = key;
+    }
+}
+
+// Per-filter tab-cycle state. A frozen snapshot of GUIDs (sorted nearest→
+// farthest) plus a cursor; presses within `kCycleWindowMs` that haven't had
+// the target changed out from under them advance the cursor over the frozen
+// list, so the order stays stable through a cycle burst.
+struct CycleState {
+    bool valid = false;
+    uint64_t snapshot[kMaxCandidates];
+    int count = 0;
+    int index = 0;
+    uint32_t lastPressMs = 0;
+    uint64_t lastSetGuid = 0;
+};
+CycleState g_cycle[kFilterCount];
+
+void DoCycle(void *L, Filter f) {
+    const bool reverse = Game::Lua::ToBoolean(L, 1) != 0;
+    CycleState &st = g_cycle[static_cast<int>(f)];
+    const uint32_t now = NowMs();
+
+    const bool cont = st.valid && st.count > 0 &&
+                      (now - st.lastPressMs) <= kCycleWindowMs &&
+                      CurrentSelection() == st.lastSetGuid;
+
+    if (cont) {
+        st.index = reverse ? (st.index + st.count - 1) % st.count
+                           : (st.index + 1) % st.count;
+    } else {
+        CollectCtx c;
+        if (!Collect(f, &c) || c.count == 0) {
+            st.valid = false;
+            return;
+        }
+        SortByDistance(c.list, c.count);
+        st.count = c.count;
+        for (int i = 0; i < c.count; ++i)
+            st.snapshot[i] = c.list[i].guid;
+        st.index = 0;
+        st.valid = true;
+    }
+
+    const uint64_t guid = st.snapshot[st.index];
+    SetTarget(guid);
+    st.lastSetGuid = guid;
+    st.lastPressMs = now;
+}
+
+void DoDirection(void *L, bool hostile, const char *usage) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, usage);
+        return;
+    }
+    const float facing = static_cast<float>(Game::Lua::ToNumber(L, 1));
+    float cone = Game::Lua::IsNumber(L, 2)
+                     ? static_cast<float>(Game::Lua::ToNumber(L, 2))
+                     : kDefaultConeAngle;
+    if (cone <= 0.0f)
+        cone = kDefaultConeAngle;
+    const float cosHalf = std::cos(cone * 0.5f);
+    const float dirX = std::cos(facing);
+    const float dirY = std::sin(facing);
+
+    CollectCtx c;
+    if (!Collect(hostile ? Filter::Enemy : Filter::Friend, &c) || c.count == 0)
+        return;
+
+    int best = -1;
+    float bestDistSq = 0.0f;
+    for (int i = 0; i < c.count; ++i) {
+        const float vx = c.list[i].x - c.px;
+        const float vy = c.list[i].y - c.py;
+        const float horizSq = vx * vx + vy * vy;
+        if (horizSq <= 0.0001f)
+            continue;
+        // cos(angle between facing and the horizontal vector to the unit).
+        const float cosAngle = (dirX * vx + dirY * vy) / std::sqrt(horizSq);
+        if (cosAngle < cosHalf)
+            continue; // outside the cone
+        if (best < 0 || c.list[i].distSq < bestDistSq) {
+            best = i;
+            bestDistSq = c.list[i].distSq;
+        }
+    }
+    if (best >= 0)
+        SetTarget(c.list[best].guid);
+}
+
+// Lua entry points ─────────────────────────────────────────────────────
+int __fastcall Script_TargetNearest(void *L) {
+    DoCycle(L, Filter::Any);
+    return 0;
+}
+int __fastcall Script_TargetNearestEnemyPlayer(void *L) {
+    DoCycle(L, Filter::EnemyPlayer);
+    return 0;
+}
+int __fastcall Script_TargetNearestFriendPlayer(void *L) {
+    DoCycle(L, Filter::FriendPlayer);
+    return 0;
+}
+int __fastcall Script_TargetDirectionEnemy(void *L) {
+    DoDirection(L, /*hostile*/ true,
+                "Usage: TargetDirectionEnemy(facing [, coneAngle])");
+    return 0;
+}
+int __fastcall Script_TargetDirectionFriend(void *L) {
+    DoDirection(L, /*hostile*/ false,
+                "Usage: TargetDirectionFriend(facing [, coneAngle])");
+    return 0;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterGlobalFunction("TargetNearest", &Script_TargetNearest);
+    Game::Lua::RegisterGlobalFunction("TargetNearestEnemyPlayer",
+                                      &Script_TargetNearestEnemyPlayer);
+    Game::Lua::RegisterGlobalFunction("TargetNearestFriendPlayer",
+                                      &Script_TargetNearestFriendPlayer);
+    Game::Lua::RegisterGlobalFunction("TargetDirectionEnemy",
+                                      &Script_TargetDirectionEnemy);
+    Game::Lua::RegisterGlobalFunction("TargetDirectionFriend",
+                                      &Script_TargetDirectionFriend);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace Target::Nearest

src/taxi/Map.cpp

@@ -366,6 +366,80 @@ int __fastcall Script_GetAllTaxiNodes(void *L) {
     return 1;
 }
 
+// Direct-edge test — mirrors FUN_004dbad0: a 256x256 [from][to] matrix of
+// TaxiPath IDs (0 = no direct flight path). IDs outside 1..256 are never direct.
+bool DirectEdge(int from, int to) {
+    if (from <= 0 || from > Offsets::TAXI_ADJACENCY_DIM ||
+        to <= 0 || to > Offsets::TAXI_ADJACENCY_DIM)
+        return false;
+    const int *adj = reinterpret_cast<const int *>(Offsets::VAR_TAXI_ADJACENCY);
+    return adj[from * Offsets::TAXI_ADJACENCY_DIM + to] != 0;
+}
+
+// `C_TaxiMap.GetTaxiRoute(slotIndex)` — the TaxiNodes.dbc ID chain the client
+// would fly to the taxi-map slot `slotIndex` (1..NumTaxiNodes), in flight
+// order { currentNodeID, ..., destNodeID }. This mirrors TakeTaxiNode's own
+// decision (FUN_004dc8d0): a direct hop when a TaxiPath edge exists, otherwise
+// the client's precomputed multi-hop route array. It is the exact node list
+// TakeTaxiNode would hand the server, so an addon can identify every hop
+// without matching flight-map coordinates back to nodes. Returns nothing when
+// no taxi map is open, the slot is out of range, it is the current node, or no
+// route exists.
+int __fastcall Script_GetTaxiRoute(void *L) {
+    if (!Game::Lua::IsNumber(L, 1))
+        return 0;
+    const int slot1 = static_cast<int>(Game::Lua::ToNumber(L, 1));
+    const int count =
+        *reinterpret_cast<const int *>(Offsets::VAR_TAXI_NODE_COUNT);
+    if (count <= 0 || slot1 < 1 || slot1 > count)
+        return 0;
+
+    const auto *arrayBase =
+        reinterpret_cast<const uint8_t *>(Offsets::VAR_TAXI_NODE_ARRAY);
+    const uint8_t *slotRec =
+        arrayBase + (slot1 - 1) * Offsets::TAXI_NODE_STRIDE;
+
+    const uint8_t *curRec = *reinterpret_cast<const uint8_t *const *>(
+        Offsets::VAR_TAXI_CURRENT_REC);
+    const uint8_t *dstRec = *reinterpret_cast<const uint8_t *const *>(
+        slotRec + Offsets::OFF_TAXI_SLOT_RECORD);
+    if (curRec == nullptr || dstRec == nullptr)
+        return 0;
+    const int currentID = IntField(curRec, 0);
+    const int destID = IntField(dstRec, 0);
+    if (currentID == 0 || destID == 0 || currentID == destID)
+        return 0;
+
+    // Collect the chain exactly as FUN_004dc8d0 (TakeTaxiNode) would send it.
+    int ids[64];
+    int n = 0;
+    if (DirectEdge(currentID, destID)) {
+        ids[n++] = currentID;
+        ids[n++] = destID;
+    } else if (*(slotRec + Offsets::OFF_TAXI_SLOT_MULTIHOP) != 0) {
+        const int *route = *reinterpret_cast<const int *const *>(
+            slotRec + Offsets::OFF_TAXI_SLOT_ROUTE);
+        const int rc = *reinterpret_cast<const int *>(
+            slotRec + Offsets::OFF_TAXI_SLOT_ROUTE_COUNT);
+        if (route == nullptr || rc < 2)
+            return 0;
+        const int cap = rc < 64 ? rc : 64;
+        for (int i = 0; i < cap; ++i)
+            ids[n++] = route[i];
+    } else {
+        return 0; // reachable node with no computed route (shouldn't happen)
+    }
+
+    Game::Lua::SetTop(L, 0);
+    Game::Lua::NewTable(L);
+    for (int i = 0; i < n; ++i) {
+        Game::Lua::PushNumber(L, static_cast<double>(i + 1));
+        Game::Lua::PushNumber(L, static_cast<double>(ids[i]));
+        Game::Lua::SetTable(L, -3);
+    }
+    return 1;
+}
+
 void RegisterLuaFunctions() {
     static const Game::Lua::EnumIntegerEntry kFaction[] = {
         {"Neutral", FACTION_NEUTRAL},
@@ -385,6 +459,8 @@ void RegisterLuaFunctions() {
                                      &Script_GetTaxiNodesForMap);
     Game::Lua::RegisterTableFunction("C_TaxiMap", "GetAllTaxiNodes",
                                      &Script_GetAllTaxiNodes);
+    Game::Lua::RegisterTableFunction("C_TaxiMap", "GetTaxiRoute",
+                                     &Script_GetTaxiRoute);
 }
 
 const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};

src/taxi/Paths.cpp

@@ -0,0 +1,139 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `C_TaxiMap.GetTaxiPaths()` and `C_TaxiMap.GetTaxiPathWaypoints(pathID)` —
+// direct readers for `TaxiPath.dbc` (the directed flight-path edge list with
+// costs) and `TaxiPathNode.dbc` (each path's world-coordinate waypoint
+// polyline). Vanilla exposes neither; addons can't read DBCs at all, so this
+// hands them the raw taxi graph + geometry.
+//
+// Together they let an addon build the taxi routing graph (nodes + weighted
+// directed edges) and measure real flight distances (sum the 3D chords of a
+// path's waypoints). Uses for a flight-path database, a map overlay, or a
+// travel-time estimator — see the sibling `C_TaxiMap.GetTaxiNodesForMap` for
+// the node table these edges connect.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "dbc/Lookup.h"
+
+#include <algorithm>
+#include <cstdint>
+#include <vector>
+
+namespace Taxi::Paths {
+
+namespace {
+
+int IntField(const uint8_t *rec, int off) {
+    return *reinterpret_cast<const int *>(rec + off);
+}
+float FloatField(const uint8_t *rec, int off) {
+    return *reinterpret_cast<const float *>(rec + off);
+}
+
+// `C_TaxiMap.GetTaxiPaths()` — every row of TaxiPath.dbc as
+// { pathID, fromNodeID, toNodeID, cost }. Directed: A->B and B->A are two
+// separate entries.
+int __fastcall Script_GetTaxiPaths(void *L) {
+    Game::Lua::SetTop(L, 0);
+    Game::Lua::NewTable(L);
+
+    const int count = *reinterpret_cast<const int *>(Offsets::VAR_TAXIPATH_COUNT);
+    int outIdx = 0;
+    for (int id = 1; id <= count; ++id) {
+        const uint8_t *rec = DBC::Record(Offsets::VAR_TAXIPATH_RECORDS,
+                                         Offsets::VAR_TAXIPATH_COUNT,
+                                         static_cast<uint32_t>(id));
+        if (rec == nullptr)
+            continue;
+
+        outIdx += 1;
+        Game::Lua::PushNumber(L, static_cast<double>(outIdx));
+        Game::Lua::NewTable(L);
+        Game::Lua::SetFieldNumber(L, "pathID", id);
+        Game::Lua::SetFieldNumber(L, "fromNodeID", IntField(rec, Offsets::OFF_TAXIPATH_FROM));
+        Game::Lua::SetFieldNumber(L, "toNodeID", IntField(rec, Offsets::OFF_TAXIPATH_TO));
+        Game::Lua::SetFieldNumber(L, "cost", IntField(rec, Offsets::OFF_TAXIPATH_COST));
+        Game::Lua::SetTable(L, -3);
+    }
+    return 1;
+}
+
+// `C_TaxiMap.GetTaxiPathWaypoints(pathID)` — the path's waypoints as
+// { x, y, z, mapID }, ordered by node index (flight order). Returns nothing
+// for a missing / unknown pathID or an empty path.
+int __fastcall Script_GetTaxiPathWaypoints(void *L) {
+    if (!Game::Lua::IsNumber(L, 1))
+        return 0;
+    const int wantPath = static_cast<int>(Game::Lua::ToNumber(L, 1));
+    if (wantPath <= 0)
+        return 0;
+
+    struct Waypoint {
+        int index;
+        float x, y, z;
+        int mapID;
+    };
+    std::vector<Waypoint> pts;
+    const int count = *reinterpret_cast<const int *>(Offsets::VAR_TAXIPATHNODE_COUNT);
+    for (int id = 1; id <= count; ++id) {
+        const uint8_t *rec = DBC::Record(Offsets::VAR_TAXIPATHNODE_RECORDS,
+                                         Offsets::VAR_TAXIPATHNODE_COUNT,
+                                         static_cast<uint32_t>(id));
+        if (rec == nullptr)
+            continue;
+        if (IntField(rec, Offsets::OFF_TAXIPATHNODE_PATH_ID) != wantPath)
+            continue;
+        pts.push_back({IntField(rec, Offsets::OFF_TAXIPATHNODE_INDEX),
+                       FloatField(rec, Offsets::OFF_TAXIPATHNODE_X),
+                       FloatField(rec, Offsets::OFF_TAXIPATHNODE_Y),
+                       FloatField(rec, Offsets::OFF_TAXIPATHNODE_Z),
+                       IntField(rec, Offsets::OFF_TAXIPATHNODE_MAP)});
+    }
+    if (pts.empty())
+        return 0;
+
+    // DBC rows for a path are stored in index order, but sort to guarantee a
+    // dense 1-based (ipairs-safe) array in flight order regardless.
+    std::sort(pts.begin(), pts.end(),
+              [](const Waypoint &a, const Waypoint &b) { return a.index < b.index; });
+
+    Game::Lua::SetTop(L, 0);
+    Game::Lua::NewTable(L);
+    int outIdx = 0;
+    for (const Waypoint &p : pts) {
+        outIdx += 1;
+        Game::Lua::PushNumber(L, static_cast<double>(outIdx));
+        Game::Lua::NewTable(L);
+        Game::Lua::SetFieldNumber(L, "x", p.x);
+        Game::Lua::SetFieldNumber(L, "y", p.y);
+        Game::Lua::SetFieldNumber(L, "z", p.z);
+        Game::Lua::SetFieldNumber(L, "mapID", p.mapID);
+        Game::Lua::SetTable(L, -3);
+    }
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_TaxiMap", "GetTaxiPaths",
+                                     &Script_GetTaxiPaths);
+    Game::Lua::RegisterTableFunction("C_TaxiMap", "GetTaxiPathWaypoints",
+                                     &Script_GetTaxiPathWaypoints);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace Taxi::Paths

src/tooltip/CompareItem.cpp

@@ -62,7 +62,7 @@
 #include "item/Location.h"
 #include "item/StatAccum.h"
 #include "item/TooltipItem.h"
-#include "tooltip/SetItemEvent.h"
+#include "tooltip/SetEvents.h"
 #include "ui/ColorData.h"
 
 #include <cstdint>
@@ -598,7 +598,7 @@ int __fastcall Script_SetHyperlinkCompareItem(void *L) {
     // this internal build so a handler doesn't run mid-way through the
     // line-shift below (it fires for the *hovered* item's real Set* instead).
     {
-        Tooltip::SetItemEvent::Suppressor noEvent;
+        Tooltip::SetEvents::Suppressor noEvent;
         reinterpret_cast<BuildItemTooltip_t>(Offsets::FUN_GAMETOOLTIP_BUILD_ITEM)(
             self, static_cast<uint32_t>(equippedID), &equippedGUID, &equippedGUID, 0, 0, 0, 0, 0, 0);
     }

src/tooltip/SetEvents.cpp

@@ -0,0 +1,241 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `GameTooltip:HookScript("OnTooltipSet{Item,Spell,Unit,GameObject}", fn)` —
+// backport of the modern tooltip scripts that fire whenever a tooltip's item /
+// spell / unit / gameobject is set, so addons can annotate tooltips by hooking
+// one script instead of wrapping every Set* method. Fully native — real frame
+// scripts, settable via the standard SetScript / GetScript / HookScript.
+//
+// 1.12 already has the machinery for tooltip scripts, just not these ones:
+//
+//   - The CGGameTooltip vtable resolver FUN_GAMETOOLTIP_SCRIPT_RESOLVER maps a
+//     script name to its handler slot on the tooltip (OnTooltipCleared etc.,
+//     each an 8-byte {handler, context} pair). SetScript/GetScript/HookScript
+//     all go through it. We co-hook it: for our OnTooltipSet* names (which the
+//     engine doesn't know) we hand back a pointer to a C-side per-tooltip cell
+//     — the tooltip object (alloc size 0x460) has no free 8-byte slot, and the
+//     resolver's only contract is "return the address the script lives at", so
+//     external storage works exactly like an in-object slot.
+//
+//   - Each object type has a single builder funnel that every Set*/mouseover
+//     path converges on (item FUN_GAMETOOLTIP_BUILD_ITEM, spell _BUILD_SPELL,
+//     unit _BUILD_UNIT, gameobject _BUILD_GAMEOBJECT). We co-hook each and,
+//     after the build, fire the matching handler via FUN_FRAME_INVOKE_SCRIPT
+//     (the same no-arg runner the clear uses for OnTooltipCleared) with the
+//     tooltip as `self`.
+//
+// Suppressed during our own Tooltip::Compare equipped-item build (see
+// Suppressor), and guarded against a handler that re-enters a builder.
+
+#include "SetEvents.h"
+
+#include "Game.h"
+#include "Offsets.h"
+
+#include <cstdint>
+
+namespace Tooltip::SetEvents {
+
+namespace {
+
+// One entry per script kind. Order is arbitrary but the cell slot array and
+// the builder hooks index by it.
+enum ScriptKind { SK_ITEM = 0, SK_SPELL, SK_UNIT, SK_GAMEOBJECT, SK_COUNT };
+
+// Script names, matched case-insensitively against the resolver's input.
+constexpr const char *kNamesLower[SK_COUNT] = {
+    "ontooltipsetitem",
+    "ontooltipsetspell",
+    "ontooltipsetunit",
+    "ontooltipsetgameobject",
+};
+
+// Per-tooltip storage: one 8-byte {handler, context} slot per script kind.
+// Tooltips are few and permanent (GameTooltip, ItemRefTooltip,
+// ShoppingTooltip1/2, AtlasLootTooltip, WorldMapTooltip, plus the odd addon
+// tooltip), so a small fixed table with a linear scan is plenty and gives each
+// cell a stable address to hand out.
+struct Cell {
+    void *tooltip;
+    uint32_t slot[SK_COUNT][2]; // [kind] = {handler, exec context}
+};
+constexpr int kMaxTooltips = 32;
+Cell g_cells[kMaxTooltips];
+int g_cellCount = 0;
+
+uint32_t *SlotFor(void *tooltip, int kind, bool create) {
+    for (int i = 0; i < g_cellCount; ++i)
+        if (g_cells[i].tooltip == tooltip)
+            return g_cells[i].slot[kind];
+    if (!create || g_cellCount >= kMaxTooltips)
+        return nullptr;
+    Cell &c = g_cells[g_cellCount++];
+    c.tooltip = tooltip;
+    for (auto &s : c.slot) {
+        s[0] = 0;
+        s[1] = 0;
+    }
+    return c.slot[kind];
+}
+
+bool EqualsIgnoreCase(const char *s, const char *literal) {
+    if (s == nullptr)
+        return false;
+    for (;; ++s, ++literal) {
+        unsigned char a = static_cast<unsigned char>(*s);
+        const unsigned char b = static_cast<unsigned char>(*literal);
+        if (a >= 'A' && a <= 'Z')
+            a = static_cast<unsigned char>(a + 32);
+        if (a != b)
+            return false;
+        if (b == 0)
+            return true;
+    }
+}
+
+// --- Suppression / recursion state -------------------------------------
+int g_suppress = 0; // > 0 while our own compare build runs
+int g_firing = 0;   // recursion guard around any handler fire
+
+// The engine's real script invoker: binds the global `this` = frame and runs
+// the handler under its own protected lua_pcall. We call it directly rather
+// than the FUN_00702690 wrapper, whose exec-context mutation is unsafe from the
+// deep nested Lua->C->Lua stack our co-hook fires within — see Offsets.h.
+using InvokeScript_t = void(__fastcall *)(uint32_t handler, void *frame);
+
+// Fire the handler (if any) for `kind` on `self`.
+//
+// We fire from inside a builder, which is itself mid-execution of the engine's
+// Script_Set* (and, in the wild, nested under addon Set* wrappers + several
+// other DLLs' hooks). The invoker pushes onto the Lua stack and does NOT
+// restore the top to where the outer, still-running C code left it — harmless
+// from the engine's top-level dispatch, but from here it shifts the stack and
+// the outer code (and other DLLs' hooks) then index garbage → deref → crash.
+// Snapshot and restore the stack top around the fire so the outer code sees
+// exactly the stack it left.
+void FireScript(void *self, int kind) {
+    if (g_suppress > 0 || g_firing > 0)
+        return;
+    uint32_t *slot = SlotFor(self, kind, /*create*/ false);
+    if (slot == nullptr || slot[0] == 0)
+        return;
+    void *L = Game::Lua::State();
+    const int savedTop = (L != nullptr) ? Game::Lua::GetTop(L) : 0;
+    ++g_firing;
+    reinterpret_cast<InvokeScript_t>(Offsets::FUN_FRAME_INVOKE_SCRIPT)(slot[0], self);
+    --g_firing;
+    if (L != nullptr)
+        Game::Lua::SetTop(L, savedTop);
+}
+
+// --- Resolver co-hook (CGGameTooltip vtable script-name → slot) ---------
+using Resolver_t = int(__fastcall *)(void *self, void *edx, const char *name);
+Resolver_t g_resolverOriginal = nullptr;
+
+int __fastcall Resolver_h(void *self, void *edx, const char *name) {
+    const int engineSlot = g_resolverOriginal(self, edx, name);
+    if (engineSlot != 0) // a base-frame or existing tooltip script — leave it
+        return engineSlot;
+    for (int k = 0; k < SK_COUNT; ++k)
+        if (EqualsIgnoreCase(name, kNamesLower[k]))
+            return reinterpret_cast<int>(SlotFor(self, k, /*create*/ true));
+    return 0;
+}
+
+// --- Builder co-hooks --------------------------------------------------
+// Each builder is a __thiscall funnel modelled as __fastcall(self /*ecx*/,
+// edx /*unused reg placeholder*/, ...real stack args...). The declared stack
+// arg count MUST match the callee's RET N or the caller's stack is corrupted.
+// Builders whose callers use the return value (spell, unit) are declared to
+// return it so the co-hook forwards it.
+
+// Item — FUN_GAMETOOLTIP_BUILD_ITEM, 9 stack args, return unused.
+using BuildItem_t = void(__fastcall *)(void *self, void *edx, uint32_t itemID,
+                                       const void *guid, const void *guid2, int a4,
+                                       int a5, int a6, int headerFlag, int a8, int a9);
+BuildItem_t g_buildItemOriginal = nullptr;
+
+void __fastcall BuildItem_h(void *self, void *edx, uint32_t itemID, const void *guid,
+                            const void *guid2, int a4, int a5, int a6, int headerFlag,
+                            int a8, int a9) {
+    g_buildItemOriginal(self, edx, itemID, guid, guid2, a4, a5, a6, headerFlag, a8, a9);
+    FireScript(self, SK_ITEM);
+}
+
+// Spell — FUN_GAMETOOLTIP_BUILD_SPELL_TOOLTIP, 7 stack args, returns an int.
+using BuildSpell_t = int(__fastcall *)(void *self, void *edx, int spellID, int a2,
+                                       int a3, int isPet, int a5, int a6, int a7);
+BuildSpell_t g_buildSpellOriginal = nullptr;
+
+int __fastcall BuildSpell_h(void *self, void *edx, int spellID, int a2, int a3,
+                            int isPet, int a5, int a6, int a7) {
+    const int ret = g_buildSpellOriginal(self, edx, spellID, a2, a3, isPet, a5, a6, a7);
+    FireScript(self, SK_SPELL);
+    return ret;
+}
+
+// Unit — FUN_GAMETOOLTIP_BUILD_UNIT, 1 stack arg (guid), returns an int the
+// caller (Script_GameTooltip_SetUnit) tests.
+using BuildUnit_t = int(__fastcall *)(void *self, void *edx, const void *guid);
+BuildUnit_t g_buildUnitOriginal = nullptr;
+
+int __fastcall BuildUnit_h(void *self, void *edx, const void *guid) {
+    const int ret = g_buildUnitOriginal(self, edx, guid);
+    FireScript(self, SK_UNIT);
+    return ret;
+}
+
+// GameObject — FUN_GAMETOOLTIP_BUILD_GAMEOBJECT, 1 stack arg (guid), void.
+using BuildGO_t = void(__fastcall *)(void *self, void *edx, const void *guid);
+BuildGO_t g_buildGOOriginal = nullptr;
+
+void __fastcall BuildGO_h(void *self, void *edx, const void *guid) {
+    g_buildGOOriginal(self, edx, guid);
+    FireScript(self, SK_GAMEOBJECT);
+}
+
+static const Game::HookAutoRegister _resolverHook{
+    Offsets::FUN_GAMETOOLTIP_SCRIPT_RESOLVER,
+    reinterpret_cast<void *>(&Resolver_h),
+    reinterpret_cast<void **>(&g_resolverOriginal)};
+
+static const Game::HookAutoRegister _buildItemHook{
+    Offsets::FUN_GAMETOOLTIP_BUILD_ITEM,
+    reinterpret_cast<void *>(&BuildItem_h),
+    reinterpret_cast<void **>(&g_buildItemOriginal)};
+
+static const Game::HookAutoRegister _buildSpellHook{
+    Offsets::FUN_GAMETOOLTIP_BUILD_SPELL_TOOLTIP,
+    reinterpret_cast<void *>(&BuildSpell_h),
+    reinterpret_cast<void **>(&g_buildSpellOriginal)};
+
+static const Game::HookAutoRegister _buildUnitHook{
+    Offsets::FUN_GAMETOOLTIP_BUILD_UNIT,
+    reinterpret_cast<void *>(&BuildUnit_h),
+    reinterpret_cast<void **>(&g_buildUnitOriginal)};
+
+static const Game::HookAutoRegister _buildGOHook{
+    Offsets::FUN_GAMETOOLTIP_BUILD_GAMEOBJECT,
+    reinterpret_cast<void *>(&BuildGO_h),
+    reinterpret_cast<void **>(&g_buildGOOriginal)};
+
+} // namespace
+
+Suppressor::Suppressor() { ++g_suppress; }
+Suppressor::~Suppressor() {
+    if (g_suppress > 0)
+        --g_suppress;
+}
+
+} // namespace Tooltip::SetEvents

src/tooltip/SetEvents.h

@@ -13,12 +13,14 @@
 
 #pragma once
 
-namespace Tooltip::SetItemEvent {
+namespace Tooltip::SetEvents {
 
-// RAII guard that suppresses OnTooltipSetItem firing for the duration of an
-// engine item-build we invoke *internally* (Tooltip::Compare building the
-// equipped item into a shopping tooltip). Without it, a handler would run in
-// the middle of our line-shift / delta rendering and see a half-built tooltip.
+// RAII guard that suppresses tooltip set-event firing (OnTooltipSetItem etc.)
+// for the duration of an engine build we invoke *internally* — currently
+// Tooltip::Compare building the equipped item into a shopping tooltip. Without
+// it, a handler would run in the middle of our line-shift / delta rendering and
+// see a half-built tooltip. Only the item builder runs during that internal
+// build, so in practice this gates OnTooltipSetItem; it's global for safety.
 // Nestable (ref-counted).
 struct Suppressor {
     Suppressor();
@@ -27,4 +29,4 @@ struct Suppressor {
     Suppressor &operator=(const Suppressor &) = delete;
 };
 
-} // namespace Tooltip::SetItemEvent
+} // namespace Tooltip::SetEvents

src/tooltip/SetItemEvent.cpp

@@ -1,168 +0,0 @@
-// This file is part of ClassicAPI.
-//
-// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
-// of the GNU General Public License as published by the Free Software Foundation, either
-// version 3 of the License, or (at your option) any later version.
-//
-// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
-// PURPOSE. See the GNU General Public License for more details.
-//
-// You should have received a copy of the GNU General Public License along with
-// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
-
-// `GameTooltip:HookScript("OnTooltipSetItem", fn)` — backport of the modern
-// tooltip script that fires whenever a tooltip's item is set, so addons can
-// annotate item tooltips by hooking one script instead of wrapping every
-// Set* method (the pattern AtlasLoot resorts to in vanilla, rebuilding the
-// tooltip and clobbering its item linkage). Fully native — a real frame
-// script, settable via the standard SetScript / GetScript / HookScript.
-//
-// 1.12 already has the machinery for tooltip scripts, just not this one:
-//
-//   - The CGGameTooltip vtable resolver FUN_GAMETOOLTIP_SCRIPT_RESOLVER maps a
-//     script name to its handler slot on the tooltip (OnTooltipCleared etc.,
-//     each an 8-byte {handler, context} pair). SetScript/GetScript/HookScript
-//     all go through it. We co-hook it: for "OnTooltipSetItem" (a name the
-//     engine doesn't know) we hand back a pointer to a C-side per-tooltip cell
-//     — the tooltip object (alloc size 0x460) has no free 8-byte slot, and the
-//     resolver's only contract is "return the address the script lives at", so
-//     external storage works exactly like an in-object slot.
-//
-//   - Every item setter (SetHyperlink item:, SetBagItem, SetInventoryItem,
-//     SetMerchantItem, SetAuctionItem, …) funnels through the shared item
-//     builder FUN_GAMETOOLTIP_BUILD_ITEM. We co-hook it and, after the build,
-//     fire the handler via FUN_FRAME_RUN_SCRIPT (the same no-arg runner the
-//     clear uses for OnTooltipCleared) with the tooltip as `self`.
-//
-// Suppressed during our own Tooltip::Compare equipped-item build (see
-// Suppressor), and guarded against a handler that re-enters the builder.
-
-#include "SetItemEvent.h"
-
-#include "Game.h"
-#include "Offsets.h"
-
-#include <cstdint>
-
-namespace Tooltip::SetItemEvent {
-
-namespace {
-
-// Per-tooltip 8-byte handler slot {handler, context}. Tooltips are few and
-// permanent (GameTooltip, ItemRefTooltip, ShoppingTooltip1/2, AtlasLootTooltip,
-// WorldMapTooltip, plus the odd addon tooltip), so a small fixed table with a
-// linear scan is plenty and gives each cell a stable address to hand out.
-struct Cell {
-    void *tooltip;
-    uint32_t slot[2]; // [0] = handler, [1] = exec context (written by SetScript)
-};
-constexpr int kMaxTooltips = 32;
-Cell g_cells[kMaxTooltips];
-int g_cellCount = 0;
-
-uint32_t *CellFor(void *tooltip, bool create) {
-    for (int i = 0; i < g_cellCount; ++i)
-        if (g_cells[i].tooltip == tooltip)
-            return g_cells[i].slot;
-    if (!create || g_cellCount >= kMaxTooltips)
-        return nullptr;
-    Cell &c = g_cells[g_cellCount++];
-    c.tooltip = tooltip;
-    c.slot[0] = 0;
-    c.slot[1] = 0;
-    return c.slot;
-}
-
-bool EqualsIgnoreCase(const char *s, const char *literal) {
-    if (s == nullptr)
-        return false;
-    for (;; ++s, ++literal) {
-        unsigned char a = static_cast<unsigned char>(*s);
-        const unsigned char b = static_cast<unsigned char>(*literal);
-        if (a >= 'A' && a <= 'Z')
-            a = static_cast<unsigned char>(a + 32);
-        if (a != b)
-            return false;
-        if (b == 0)
-            return true;
-    }
-}
-
-constexpr char kScriptNameLower[] = "ontooltipsetitem"; // matched case-insensitively
-
-// --- Suppression / recursion state -------------------------------------
-int g_suppress = 0; // > 0 while our own compare build runs
-int g_firing = 0;   // recursion guard around the handler fire
-
-// --- Resolver co-hook (CGGameTooltip vtable script-name → slot) ---------
-using Resolver_t = int(__fastcall *)(void *self, void *edx, const char *name);
-Resolver_t g_resolverOriginal = nullptr;
-
-int __fastcall Resolver_h(void *self, void *edx, const char *name) {
-    const int engineSlot = g_resolverOriginal(self, edx, name);
-    if (engineSlot != 0) // a base-frame or existing tooltip script — leave it
-        return engineSlot;
-    if (EqualsIgnoreCase(name, kScriptNameLower))
-        return reinterpret_cast<int>(CellFor(self, /*create*/ true));
-    return 0;
-}
-
-// --- Item-builder co-hook (fires the handler after the item is set) -----
-using Build_t = void(__fastcall *)(void *self, void *edx, uint32_t itemID, const void *guid,
-                                   const void *guid2, int a4, int a5, int a6, int headerFlag,
-                                   int a8, int a9);
-Build_t g_buildOriginal = nullptr;
-
-// The engine's real script invoker: binds the global `this` = frame and runs
-// the handler under its own protected lua_pcall. We call it directly rather
-// than the FUN_00702690 wrapper, whose exec-context mutation is unsafe from the
-// deep nested Lua->C->Lua stack our co-hook fires within — see Offsets.h.
-using InvokeScript_t = void(__fastcall *)(uint32_t handler, void *frame);
-
-void __fastcall Build_h(void *self, void *edx, uint32_t itemID, const void *guid,
-                        const void *guid2, int a4, int a5, int a6, int headerFlag, int a8,
-                        int a9) {
-    g_buildOriginal(self, edx, itemID, guid, guid2, a4, a5, a6, headerFlag, a8, a9);
-    if (g_suppress > 0 || g_firing > 0)
-        return;
-    uint32_t *slot = CellFor(self, /*create*/ false);
-    if (slot == nullptr || slot[0] == 0)
-        return;
-
-    // We fire from inside the item builder, which is itself mid-execution of
-    // the engine's Script_Set* (and, in the wild, nested under addon Set*
-    // wrappers + several other DLLs' hooks). The invoker pushes onto the Lua
-    // stack and does NOT restore the top to where the outer, still-running C
-    // code left it — harmless from the engine's top-level dispatch, but from
-    // here it shifts the stack and the outer code (and other DLLs' hooks) then
-    // index garbage → deref → crash. Snapshot and restore the stack top around
-    // the fire so the outer code sees exactly the stack it left.
-    void *L = Game::Lua::State();
-    const int savedTop = (L != nullptr) ? Game::Lua::GetTop(L) : 0;
-    ++g_firing;
-    reinterpret_cast<InvokeScript_t>(Offsets::FUN_FRAME_INVOKE_SCRIPT)(slot[0], self);
-    --g_firing;
-    if (L != nullptr)
-        Game::Lua::SetTop(L, savedTop);
-}
-
-static const Game::HookAutoRegister _resolverHook{
-    Offsets::FUN_GAMETOOLTIP_SCRIPT_RESOLVER,
-    reinterpret_cast<void *>(&Resolver_h),
-    reinterpret_cast<void **>(&g_resolverOriginal)};
-
-static const Game::HookAutoRegister _buildHook{
-    Offsets::FUN_GAMETOOLTIP_BUILD_ITEM,
-    reinterpret_cast<void *>(&Build_h),
-    reinterpret_cast<void **>(&g_buildOriginal)};
-
-} // namespace
-
-Suppressor::Suppressor() { ++g_suppress; }
-Suppressor::~Suppressor() {
-    if (g_suppress > 0)
-        --g_suppress;
-}
-
-} // namespace Tooltip::SetItemEvent

src/totem/Tracker.cpp

@@ -0,0 +1,657 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `GetTotemInfo(slot)` — the four-element totem bar, backported. Vanilla
+// 1.12 tracks nothing about the shaman's totems client-side (the totem
+// bar, PLAYER_TOTEM_UPDATE, and GetTotemInfo are all TBC additions), so
+// this is a self-tracking subsystem — but a fully DATA-DRIVEN one:
+//
+//   * SLOT is read straight from the totem summon spell's `Spell.dbc`
+//     effect: 87/88/89/90 = SUMMON_TOTEM_SLOT1..4 = Fire/Earth/Water/Air,
+//     so `slot = effect - 86`. No hardcoded spell table; Turtle custom
+//     totems self-classify.
+//   * CREATURE ENTRY is the effect's `EffectMiscValue` (the summoned
+//     totem's creature-template ID) — used to detect the totem's death.
+//   * DURATION is the summon spell's `SpellDuration.dbc` value (via the
+//     engine's own duration helper, so player duration mods apply).
+//
+// Detection: the player's totem cast fires SMSG_SPELL_GO, which
+// `Aura::Source` already co-hooks; it calls `OnPlayerSpellGo` here (before
+// its aura gate, since a summon applies no aura). We stamp the slot with
+// start time + duration.
+//
+// Death / removal: on WorldTick we scan the object manager for a
+// player-owned creature of the slot's entry. A "seen once, then gone"
+// latch clears the slot early (totem killed, Totemic Recall, or manually
+// destroyed) — the owner check (CreatedBy == player) means another
+// shaman's same-entry totem can't keep ours alive, and the seen-latch
+// tolerates the ~1-tick spawn lag before the totem appears. Duration is
+// the backstop for the normal case. A recast into the same slot simply
+// re-stamps it.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "event/Custom.h"
+#include "event/SignalHook.h"
+#include "guid/Guid.h"
+#include "item/Count.h"
+#include "spell/Lookup.h"
+#include "tick/WorldTick.h"
+#include "ui/ColorData.h"
+#include "unit/Identity.h"
+
+#include <cstdint>
+
+namespace Totem::Tracker {
+
+namespace {
+
+// Spell.dbc record field offsets (see spell/Info.cpp for the shared set).
+constexpr int OFF_EFFECT = 0xF4;      // int32[3] — SPELL_EFFECT_*
+constexpr int OFF_TOTEM_TOOL = 0xA0;  // int32[2] — Totem (required tool item IDs)
+constexpr int OFF_MISC_VALUE = 0x1A8; // int32[3] — EffectMiscValue
+constexpr int OFF_ICON_ID = 0x1D4;    // int32 — SpellIconID
+constexpr int OFF_NAME = 0x1E0;       // char*[9] locale array
+
+// SUMMON_TOTEM_SLOT1..4 spell effects (verified against Spell.dbc: Searing
+// 87/Fire, Stoneskin 88/Earth, Healing Stream 89/Water, Windfury 90/Air).
+constexpr int kEffectSummonTotemSlot1 = 87;
+constexpr int kEffectSummonTotemSlot4 = 90;
+constexpr int kSlots = 4;
+
+
+// Re-scan the object manager for totem existence at most this often.
+constexpr uint32_t kScanIntervalMs = 250;
+
+struct Slot {
+    bool active;
+    bool seen;          // the totem creature has been observed in the world
+    uint32_t spellID;
+    uint32_t entry;     // summoned creature-template ID (for death detection)
+    uint32_t startMs;   // FUN_OS_TICKCOUNT_MS (shares GetTime's epoch × 1000)
+    uint32_t durationMs;
+};
+
+Slot g_slots[kSlots] = {};
+uint32_t g_lastScanMs = 0;
+
+// Per-slot totem tool item ID (Fire/Earth/Water/Air), read from the totem
+// spell's `Totem[0]` field — the required TOOL the spell lists (Earth
+// Totem, Fire Totem, …), NOT a consumed reagent, and NOT hardcoded. Filled
+// from the player's spellbook on SPELLS_CHANGED and refreshed at cast; 0 =
+// not yet resolved. `g_spellsChangedId` caches the event id.
+uint32_t g_toolItem[kSlots] = {};
+int g_spellsChangedId = -1;
+
+uint32_t NowMs() {
+    using TickCount_t = uint32_t(__fastcall *)();
+    return reinterpret_cast<TickCount_t>(
+        static_cast<uintptr_t>(Offsets::FUN_OS_TICKCOUNT_MS))();
+}
+
+// The totem tool item a spell requires (`Totem[0]`), or 0.
+uint32_t TotemToolItem(const uint8_t *rec) {
+    const int32_t t = *reinterpret_cast<const int32_t *>(rec + OFF_TOTEM_TOOL);
+    return t > 0 ? static_cast<uint32_t>(t) : 0;
+}
+
+// Fill any still-unknown slot tool items by scanning the player's spellbook
+// for totem summons and reading each one's required tool. Tools are fixed
+// per element, so once a slot is resolved it never changes and the scan
+// early-outs. Walks the flat learned-spell array `VAR_PLAYER_SPELLBOOK`
+// (the same list `GetSpellName` reads) — the `IsPlayerSpell` bitmap
+// doesn't reliably carry totems. Driven by SPELLS_CHANGED (when the
+// spellbook is populated), so no polling.
+void ScanTools() {
+    bool anyUnknown = false;
+    for (int s = 0; s < kSlots; ++s)
+        if (g_toolItem[s] == 0) {
+            anyUnknown = true;
+            break;
+        }
+    if (!anyUnknown)
+        return;
+
+    auto *book = reinterpret_cast<const int32_t *>(
+        static_cast<uintptr_t>(Offsets::VAR_PLAYER_SPELLBOOK));
+    for (int slot = 0; slot < Offsets::SPELLBOOK_MAX_SLOTS; ++slot) {
+        const int spellID = book[slot];
+        if (spellID <= 0)
+            continue;
+        const uint8_t *rec = Spell::Lookup::RecordForID(spellID);
+        if (rec == nullptr)
+            continue;
+        const auto *eff = reinterpret_cast<const int32_t *>(rec + OFF_EFFECT);
+        for (int i = 0; i < Offsets::SPELL_RECORD_EFFECT_COUNT; ++i) {
+            const int e = eff[i];
+            if (e < kEffectSummonTotemSlot1 || e > kEffectSummonTotemSlot4)
+                continue;
+            const int s = e - kEffectSummonTotemSlot1;
+            if (g_toolItem[s] == 0)
+                g_toolItem[s] = TotemToolItem(rec);
+            break;
+        }
+    }
+}
+
+// Re-resolve tool items whenever the player's spells (re)load.
+// SPELLS_CHANGED is a no-arg event through the same dispatcher
+// Event::SignalHook owns, so we observe it there (never suppress — return
+// false). By the time it fires the spellbook is populated, so the scan
+// sees the totems.
+bool OnSignal(int eventID) {
+    if (g_spellsChangedId < 0)
+        g_spellsChangedId = Event::Custom::LookupByName("SPELLS_CHANGED");
+    if (eventID == g_spellsChangedId)
+        ScanTools();
+    return false;
+}
+
+const Event::SignalHook::AutoSubscribe _spellsChanged{&OnSignal};
+
+uint32_t SpellDurationMs(const uint8_t *rec) {
+    using GetDuration_t = int(__fastcall *)(const uint8_t *rec, int unit,
+                                            char skipMod);
+    const int ms = reinterpret_cast<GetDuration_t>(
+        static_cast<uintptr_t>(Offsets::FUN_GET_SPELL_DURATION))(rec, 0, 0);
+    return ms > 0 ? static_cast<uint32_t>(ms) : 0;
+}
+
+// ---- object-manager existence scan (player-owned creature by entry) ------
+
+using EnumCallback_t = int(__fastcall *)(void *ctx, void *unusedEdx,
+                                         uint64_t guid);
+using EnumVisibleObjects_t = int(__fastcall *)(EnumCallback_t cb, void *ctx);
+using ObjectPtr_t = void *(__fastcall *)(uint32_t typeMask, const char *dbg,
+                                         uint32_t guidLo, uint32_t guidHi,
+                                         int dbgCode);
+
+struct ScanCtx {
+    uint64_t playerGuid;
+    uint32_t entries[kSlots]; // 0 = slot not being checked
+    bool present[kSlots];
+};
+
+int __fastcall ScanCallback(ScanCtx *ctx, void * /*unusedEdx*/, uint64_t guid) {
+    if (!Guid::IsCreature(guid))
+        return 1;
+    const uint32_t entry = static_cast<uint32_t>((guid >> 24) & 0xFFFFFFu);
+    if (entry == 0)
+        return 1;
+    int match = -1;
+    for (int s = 0; s < kSlots; ++s) {
+        if (ctx->entries[s] == entry) {
+            match = s;
+            break;
+        }
+    }
+    if (match < 0)
+        return 1;
+
+    // Confirm it's OUR totem: resolve + check CreatedBy == player.
+    auto ObjectPtr =
+        reinterpret_cast<ObjectPtr_t>(Offsets::FUN_CLNT_OBJ_MGR_OBJECT_PTR);
+    void *obj = ObjectPtr(Offsets::TYPEMASK_UNIT, nullptr,
+                          static_cast<uint32_t>(guid),
+                          static_cast<uint32_t>(guid >> 32), 0);
+    if (obj == nullptr)
+        return 1;
+    auto *desc = *reinterpret_cast<const uint8_t *const *>(
+        static_cast<const uint8_t *>(obj) + Offsets::OFF_UNIT_DESCRIPTOR);
+    if (desc == nullptr)
+        return 1;
+    const uint64_t createdBy = *reinterpret_cast<const uint64_t *>(
+        desc + Offsets::OFF_UNIT_FIELD_CREATEDBY);
+    if (createdBy == ctx->playerGuid)
+        ctx->present[match] = true;
+    return 1; // keep scanning — other slots may match other creatures
+}
+
+// On-demand lookup of the live GUID of the player's totem creature of a
+// given entry (for TargetTotem). Returns 0 when none is visible.
+struct FindGuidCtx {
+    uint64_t playerGuid;
+    uint32_t entry;
+    uint64_t found;
+};
+
+int __fastcall FindGuidCallback(FindGuidCtx *ctx, void * /*unusedEdx*/,
+                                uint64_t guid) {
+    if (!Guid::IsCreature(guid))
+        return 1;
+    if (static_cast<uint32_t>((guid >> 24) & 0xFFFFFFu) != ctx->entry)
+        return 1;
+    auto ObjectPtr =
+        reinterpret_cast<ObjectPtr_t>(Offsets::FUN_CLNT_OBJ_MGR_OBJECT_PTR);
+    void *obj = ObjectPtr(Offsets::TYPEMASK_UNIT, nullptr,
+                          static_cast<uint32_t>(guid),
+                          static_cast<uint32_t>(guid >> 32), 0);
+    if (obj == nullptr)
+        return 1;
+    auto *desc = *reinterpret_cast<const uint8_t *const *>(
+        static_cast<const uint8_t *>(obj) + Offsets::OFF_UNIT_DESCRIPTOR);
+    if (desc == nullptr)
+        return 1;
+    if (*reinterpret_cast<const uint64_t *>(
+            desc + Offsets::OFF_UNIT_FIELD_CREATEDBY) == ctx->playerGuid) {
+        ctx->found = guid;
+        return 0; // stop
+    }
+    return 1;
+}
+
+uint64_t FindTotemGuid(uint32_t entry) {
+    if (entry == 0)
+        return 0;
+    if (*reinterpret_cast<void *volatile *>(Offsets::VAR_LOCAL_PLAYER_PTR) ==
+        nullptr)
+        return 0;
+    const uint64_t player = Unit::Identity::PlayerGuid();
+    if (player == 0)
+        return 0;
+    FindGuidCtx ctx{player, entry, 0};
+    auto Enum = reinterpret_cast<EnumVisibleObjects_t>(
+        Offsets::FUN_CLNT_OBJ_MGR_ENUM_VISIBLE_OBJECTS);
+    Enum(reinterpret_cast<EnumCallback_t>(&FindGuidCallback), &ctx);
+    return ctx.found;
+}
+
+// PLAYER_TOTEM_UPDATE(totemSlot 1-4) — a TBC event absent from vanilla's
+// table, reserved as a custom event and fired when a slot's state changes
+// (totem dropped, expired, killed, or recalled). Changes are recorded in a
+// dirty mask by the cast path and the clear paths, then flushed from OnTick
+// (WorldTick context — safe to run Lua handlers, unlike mid-packet).
+constexpr const char *kPlayerTotemUpdate = "PLAYER_TOTEM_UPDATE";
+const Event::Custom::AutoReserve _totemUpdate{kPlayerTotemUpdate};
+int g_totemUpdateId = -1;
+uint8_t g_dirtyMask = 0;
+
+void MarkDirty(int slotIdx) {
+    g_dirtyMask |= static_cast<uint8_t>(1u << slotIdx);
+}
+
+void FireDirty() {
+    if (g_dirtyMask == 0)
+        return;
+    if (g_totemUpdateId < 0)
+        g_totemUpdateId = Event::Custom::LookupByName(kPlayerTotemUpdate);
+    if (g_totemUpdateId < 0)
+        return; // slot not claimed yet — keep dirty, retry next tick
+    for (int s = 0; s < kSlots; ++s)
+        if (g_dirtyMask & (1u << s))
+            Event::Custom::Fire(g_totemUpdateId, "%d", s + 1);
+    g_dirtyMask = 0;
+}
+
+void OnTick() {
+    const uint32_t now = NowMs();
+
+    // Duration backstop — always cheap, runs every tick.
+    bool anyActive = false;
+    for (int s = 0; s < kSlots; ++s) {
+        Slot &t = g_slots[s];
+        if (!t.active)
+            continue;
+        if (t.durationMs != 0 && now - t.startMs >= t.durationMs) {
+            t.active = false;
+            MarkDirty(s);
+            continue;
+        }
+        anyActive = true;
+    }
+
+    // Death / removal scan — throttled, and only while a slot is up. The
+    // object-manager enumerator derefs the manager unconditionally, so it's
+    // gated on the local player existing.
+    if (anyActive && now - g_lastScanMs >= kScanIntervalMs &&
+        *reinterpret_cast<void *volatile *>(Offsets::VAR_LOCAL_PLAYER_PTR) !=
+            nullptr) {
+        const uint64_t player = Unit::Identity::PlayerGuid();
+        if (player != 0) {
+            g_lastScanMs = now;
+            ScanCtx ctx{};
+            ctx.playerGuid = player;
+            for (int s = 0; s < kSlots; ++s)
+                ctx.entries[s] = g_slots[s].active ? g_slots[s].entry : 0;
+
+            auto Enum = reinterpret_cast<EnumVisibleObjects_t>(
+                Offsets::FUN_CLNT_OBJ_MGR_ENUM_VISIBLE_OBJECTS);
+            Enum(reinterpret_cast<EnumCallback_t>(&ScanCallback), &ctx);
+
+            for (int s = 0; s < kSlots; ++s) {
+                Slot &t = g_slots[s];
+                if (!t.active)
+                    continue;
+                if (ctx.present[s])
+                    t.seen = true;
+                else if (t.seen) {
+                    t.active = false; // was up, now gone → died / recalled
+                    MarkDirty(s);
+                }
+            }
+        }
+    }
+
+    FireDirty();
+}
+
+const Tick::WorldTick::AutoSubscribe _tick{&OnTick};
+
+// SpellIcon.dbc path for an icon ID (records indexed by ID; path at +4).
+const char *IconPath(int iconID) {
+    if (iconID <= 0)
+        return nullptr;
+    const int count = *reinterpret_cast<const int *>(
+        static_cast<uintptr_t>(Offsets::VAR_SPELL_ICON_COUNT));
+    if (iconID > count)
+        return nullptr;
+    auto *const *records = *reinterpret_cast<const uint8_t *const *const *>(
+        static_cast<uintptr_t>(Offsets::VAR_SPELL_ICON_RECORDS));
+    if (records == nullptr || records[iconID] == nullptr)
+        return nullptr;
+    return *reinterpret_cast<const char *const *>(records[iconID] + 4);
+}
+
+// Pushes the empty tail (no active totem) after `haveTotem` has been
+// pushed by the caller. Returns the total count including that first value.
+int PushEmptyTail(void *L) {
+    Game::Lua::PushString(L, "");    // totemName
+    Game::Lua::PushNumber(L, 0.0);   // startTime
+    Game::Lua::PushNumber(L, 0.0);   // duration
+    Game::Lua::PushNil(L);           // icon
+    Game::Lua::PushNumber(L, 1.0);   // modRate
+    Game::Lua::PushNumber(L, 0.0);   // spellID
+    return 7;
+}
+
+// `GetTotemInfo(slot)` → `haveTotem, totemName, startTime, duration, icon,
+// modRate, spellID`. Slots: 1 Fire, 2 Earth, 3 Water, 4 Air. `haveTotem`
+// is TOOL presence (the documented meaning) — whether the player carries
+// the slot's totem tool item (Earth/Fire/Water/Air Totem) — NOT whether a
+// totem is summoned; the active totem is signaled by a non-empty
+// `totemName` / non-zero `startTime`.
+int __fastcall Script_GetTotemInfo(void *L) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, "Usage: GetTotemInfo(slot)");
+        return 0;
+    }
+    const int slot = static_cast<int>(Game::Lua::ToNumber(L, 1));
+    if (slot < 1 || slot > kSlots) {
+        Game::Lua::PushBool(L, false);
+        return PushEmptyTail(L);
+    }
+
+    // Tool presence — independent of the summoned state. The tool item
+    // (resolved from the totem spell's Totem[0] on SPELLS_CHANGED, not
+    // hardcoded) is checked against the bag. The bag walk reads the Lua
+    // stack, so it runs before we push any return values (`slot` captured).
+    const uint32_t tool = g_toolItem[slot - 1];
+    const bool haveTotem =
+        tool != 0 && Item::Count::InInventory(L, static_cast<int>(tool)) > 0;
+
+    const Slot &t = g_slots[slot - 1];
+    if (!t.active) {
+        Game::Lua::PushBool(L, haveTotem);
+        return PushEmptyTail(L);
+    }
+
+    const uint8_t *rec = Spell::Lookup::RecordForID(static_cast<int>(t.spellID));
+    const char *name = "";
+    const char *icon = nullptr;
+    if (rec != nullptr) {
+        const int locale =
+            *reinterpret_cast<const int *>(static_cast<uintptr_t>(
+                Offsets::VAR_LOCALE_INDEX));
+        const char *n = *reinterpret_cast<const char *const *>(
+            rec + OFF_NAME + locale * 4);
+        if (n != nullptr)
+            name = n;
+        icon = IconPath(*reinterpret_cast<const int *>(rec + OFF_ICON_ID));
+    }
+
+    Game::Lua::PushBool(L, haveTotem);
+    Game::Lua::PushString(L, name);
+    Game::Lua::PushNumber(L, static_cast<double>(t.startMs) * 0.001);
+    Game::Lua::PushNumber(L, static_cast<double>(t.durationMs) / 1000.0);
+    if (icon != nullptr)
+        Game::Lua::PushString(L, icon);
+    else
+        Game::Lua::PushNil(L);
+    Game::Lua::PushNumber(L, 1.0); // modRate — no per-totem haste in 1.12
+    Game::Lua::PushNumber(L, static_cast<double>(t.spellID));
+    return 7;
+}
+
+// `GetTotemTimeLeft(slot)` → seconds until the slot's totem is auto-
+// destroyed, or `0` when no totem is active in that slot. Slots: 1 Fire,
+// 2 Earth, 3 Water, 4 Air.
+int __fastcall Script_GetTotemTimeLeft(void *L) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, "Usage: GetTotemTimeLeft(slot)");
+        return 0;
+    }
+    const int slot = static_cast<int>(Game::Lua::ToNumber(L, 1));
+    double seconds = 0.0;
+    if (slot >= 1 && slot <= kSlots) {
+        const Slot &t = g_slots[slot - 1];
+        if (t.active && t.durationMs != 0) {
+            const uint32_t now = NowMs();
+            const uint32_t end = t.startMs + t.durationMs;
+            if (now < end)
+                seconds = static_cast<double>(end - now) / 1000.0;
+        }
+    }
+    Game::Lua::PushNumber(L, seconds);
+    return 1;
+}
+
+// `GetTotemDuration(slot)` → the total duration (seconds) of the slot's
+// active totem, or `0` when none. This is the totem's full lifetime from
+// cast (the 4th value of GetTotemInfo); see GetTotemTimeLeft for the
+// remaining time.
+int __fastcall Script_GetTotemDuration(void *L) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, "Usage: GetTotemDuration(slot)");
+        return 0;
+    }
+    const int slot = static_cast<int>(Game::Lua::ToNumber(L, 1));
+    double seconds = 0.0;
+    if (slot >= 1 && slot <= kSlots) {
+        const Slot &t = g_slots[slot - 1];
+        if (t.active)
+            seconds = static_cast<double>(t.durationMs) / 1000.0;
+    }
+    Game::Lua::PushNumber(L, seconds);
+    return 1;
+}
+
+// `TargetTotem(slot)` — target the player's totem in the given slot
+// (1 Fire, 2 Earth, 3 Water, 4 Air). No-op when the slot has no active
+// totem or the totem creature isn't currently visible. Finds the totem
+// creature's live GUID and sets the target via the same engine path
+// `TargetUnit` uses.
+int __fastcall Script_TargetTotem(void *L) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, "Usage: TargetTotem(slot)");
+        return 0;
+    }
+    const int slot = static_cast<int>(Game::Lua::ToNumber(L, 1));
+    if (slot < 1 || slot > kSlots)
+        return 0;
+    const Slot &t = g_slots[slot - 1];
+    if (!t.active || t.entry == 0)
+        return 0;
+    uint64_t guid = FindTotemGuid(t.entry);
+    if (guid == 0)
+        return 0;
+    using TargetByGuid_t = void(__fastcall *)(const uint64_t *guid);
+    reinterpret_cast<TargetByGuid_t>(
+        static_cast<uintptr_t>(Offsets::FUN_TARGET_BY_GUID))(&guid);
+    return 0;
+}
+
+// ---- GameTooltip:SetTotem(slot) -------------------------------------------
+//
+// Built with the engine's own tooltip primitives — the per-tooltip clear
+// and the raw add-line — exactly as retail's `Script_GameTooltip_SetTotem`
+// does (no Lua method dispatch). Colors are the packed `{b,g,r,a}` values
+// `FUN_GAMETOOLTIP_ADD_LINE` wants, pulled straight from `UI::ColorData`.
+
+using AddLine_t = void(__thiscall *)(void *self, const char *left, const char *right,
+                                     const void *leftColor, const void *rightColor, int wrap);
+using ClearTooltip_t = void(__fastcall *)(void *self);
+using ShowScript_t = int(__fastcall *)(void *L); // engine's Script_Show
+
+// Retail's two line colors, read verbatim from the 3.3.5 binary's SetTotem
+// color data: name = NORMAL_FONT_COLOR (0xFFFFD200), time = white. Both are
+// already in the 0xAARRGGBB packing the line-color setter consumes.
+constexpr uint32_t kNameColor = UI::ColorData::ByTag("NORMAL_FONT_COLOR");
+constexpr uint32_t kTimeColor = UI::ColorData::ByTag("HIGHLIGHT_FONT_COLOR");
+
+// Left-aligned colored line via the engine's raw add-line. `color` must
+// outlive the call (its address is passed through).
+void AddColoredLine(void *self, const char *text, const uint32_t &color) {
+    reinterpret_cast<AddLine_t>(Offsets::FUN_GAMETOOLTIP_ADD_LINE)(
+        self, text, nullptr, &color, nullptr, 0);
+}
+
+// `GameTooltip:SetTotem(slot)` — a TBC (2.4.0) tooltip method backported to
+// 1.12. Fills the tooltip with the slot's active totem, mirroring retail's
+// two-line shape (3.3.5 `Script_GameTooltip_SetTotem` at 0x006205c0):
+//
+//   <Totem Name>          NORMAL_FONT_COLOR (yellow, 0xFFFFD200)
+//   <Time Left>           white — SecondsToTimeAbbrev(SPELL_TIME_REMAINING)
+//
+// The time line mirrors retail's `SecondsToTimeAbbrev` with its round-up
+// flag: raw seconds under a minute, minutes rounded up above. The unit
+// wording is localized through the project's GlobalString helper (retail's
+// `SPELL_TIME_REMAINING_SEC`/`_MIN` keys, English fallback). No-op (tooltip
+// left untouched) when the slot has no active totem — same as retail's
+// `+8/+0xc` timing guard. Shows itself at the end (via the engine's
+// Script_Show) — retail's TotemFrame.xml OnEnter calls SetTotem with no
+// trailing :Show(), so the method is expected to show.
+int __fastcall Script_GameTooltipSetTotem(void *L) {
+    if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE ||
+        !Game::Lua::IsNumber(L, 2)) {
+        Game::Lua::Error(L, "Usage: GameTooltip:SetTotem(slot)");
+        return 0;
+    }
+    const int slot = static_cast<int>(Game::Lua::ToNumber(L, 2));
+    if (slot < 1 || slot > kSlots)
+        return 0;
+    const Slot &t = g_slots[slot - 1];
+    if (!t.active || t.spellID == 0)
+        return 0;
+
+    void *self = Game::Lua::ResolveObject(L, 1);
+    if (self == nullptr)
+        return 0;
+
+    const uint8_t *rec = Spell::Lookup::RecordForID(static_cast<int>(t.spellID));
+    if (rec == nullptr)
+        return 0;
+    const int locale =
+        *reinterpret_cast<const int *>(static_cast<uintptr_t>(Offsets::VAR_LOCALE_INDEX));
+    const char *name =
+        *reinterpret_cast<const char *const *>(rec + OFF_NAME + locale * 4);
+    if (name == nullptr || name[0] == '\0')
+        return 0;
+
+    // Milliseconds remaining (0 = unknown / expired duration).
+    uint32_t msLeft = 0;
+    if (t.durationMs != 0) {
+        const uint32_t now = NowMs();
+        const uint32_t end = t.startMs + t.durationMs;
+        if (now < end)
+            msLeft = end - now;
+    }
+
+    reinterpret_cast<ClearTooltip_t>(Offsets::FUN_GAMETOOLTIP_CLEAR)(self);
+    AddColoredLine(self, name, kNameColor);
+
+    if (msLeft > 0) {
+        const int savedTop = Game::Lua::GetTop(L);
+        if (msLeft < 60000) {
+            Game::Lua::PushLocalizedFormatInt(L, "SPELL_TIME_REMAINING_SEC",
+                                              "%d Sec",
+                                              static_cast<int>(msLeft / 1000));
+        } else {
+            const int minutes = static_cast<int>((msLeft + 59999) / 60000); // ceil
+            Game::Lua::PushLocalizedFormatInt(L, "SPELL_TIME_REMAINING_MIN",
+                                              "%d Min", minutes);
+        }
+        const char *timeText = Game::Lua::ToString(L, -1);
+        if (timeText != nullptr)
+            AddColoredLine(self, timeText, kTimeColor);
+        Game::Lua::SetTop(L, savedTop);
+    }
+
+    // Show ourselves — self is still at Lua stack index 1, which is what
+    // Script_Show reads.
+    reinterpret_cast<ShowScript_t>(Offsets::FUN_SCRIPT_FRAME_SHOW)(L);
+    return 0;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterGlobalFunction("GetTotemInfo", &Script_GetTotemInfo);
+    Game::Lua::RegisterGlobalFunction("GetTotemTimeLeft",
+                                      &Script_GetTotemTimeLeft);
+    Game::Lua::RegisterGlobalFunction("GetTotemDuration",
+                                      &Script_GetTotemDuration);
+    Game::Lua::RegisterGlobalFunction("TargetTotem", &Script_TargetTotem);
+
+    static const Game::Lua::FrameMethodEntry kTooltipMethods[] = {
+        {"SetTotem", &Script_GameTooltipSetTotem},
+    };
+    Game::Lua::RegisterFrameMethods(
+        reinterpret_cast<void *>(Offsets::VAR_GAMETOOLTIP_METHOD_REGISTRY),
+        kTooltipMethods,
+        static_cast<int>(sizeof(kTooltipMethods) / sizeof(kTooltipMethods[0])));
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+void OnPlayerSpellGo(uint32_t spellID) {
+    if (spellID == 0)
+        return;
+    const uint8_t *rec = Spell::Lookup::RecordForID(static_cast<int>(spellID));
+    if (rec == nullptr)
+        return;
+
+    const auto *effects = reinterpret_cast<const int32_t *>(rec + OFF_EFFECT);
+    const auto *misc = reinterpret_cast<const int32_t *>(rec + OFF_MISC_VALUE);
+    for (int i = 0; i < Offsets::SPELL_RECORD_EFFECT_COUNT; ++i) {
+        const int eff = effects[i];
+        if (eff < kEffectSummonTotemSlot1 || eff > kEffectSummonTotemSlot4)
+            continue;
+        const int idx = eff - kEffectSummonTotemSlot1; // 0..3 (Fire..Air)
+        Slot &t = g_slots[idx];
+        t.active = true;
+        t.seen = false;
+        t.spellID = spellID;
+        t.entry = static_cast<uint32_t>(misc[i]);
+        t.startMs = NowMs();
+        t.durationMs = SpellDurationMs(rec);
+        MarkDirty(idx); // totem dropped → PLAYER_TOTEM_UPDATE (fired next tick)
+        // The cast spell IS a totem of this element, so it names the slot's
+        // tool item directly — capture it (covers the slot even before the
+        // spellbook scan runs).
+        if (g_toolItem[idx] == 0)
+            g_toolItem[idx] = TotemToolItem(rec);
+        return; // one totem-slot effect per spell
+    }
+}
+
+} // namespace Totem::Tracker

src/totem/Tracker.h

@@ -0,0 +1,31 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <cstdint>
+
+// Client-side totem-slot tracker backing `GetTotemInfo(slot)`. Vanilla
+// 1.12 has no totem-bar / PLAYER_TOTEM_UPDATE machinery (all TBC
+// additions), so we track the four element slots ourselves. See
+// Tracker.cpp for the design.
+namespace Totem::Tracker {
+
+// Notify of a spell the LOCAL PLAYER just cast (from Aura::Source's
+// SpellGo hook — the totem summon doesn't apply an aura, so it must be
+// fed before that hook's aura gate). If `spellID` is a totem summon
+// (`Spell.dbc` effect 87-90 = SUMMON_TOTEM_SLOT1..4), it's recorded in the
+// matching element slot; otherwise ignored.
+void OnPlayerSpellGo(uint32_t spellID);
+
+} // namespace Totem::Tracker

src/turtle/BagFamily.cpp

@@ -0,0 +1,63 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// Turtle WoW custom bag families. Turtle added four cooking/gathering bag
+// families as `ItemBagFamily.dbc` rows 10–13 (Meat, Fish, Leather,
+// Mining) — beyond retail vanilla, which stops at Keys (9). Turtle's own
+// bags normally carry `m_bagFamily` directly, so this mapping is a safety
+// net for any custom container shipped with an empty field; it plugs into
+// the stock `Item::BagFamily` resolver chain rather than polluting the
+// stock table with non-vanilla data.
+//
+// Subclass → raw family ID cross-referenced by name between
+// ItemSubClass.dbc (class 1, Container) and ItemBagFamily.dbc. NOTE: the
+// resulting bitmasks (`1 << (id-1)`) land on `0x200`–`0x1000`, which
+// collide with retail's Gem/Mining bag bits — see docs/API.md's
+// GetItemFamily family table for the caveat. The values stay
+// self-consistent within Turtle (a Meat Bag and the meat it holds both
+// report `0x200`).
+//
+// This file is the home for Turtle-only custom content that layers onto a
+// stock engine surface; add further custom-data modules alongside it.
+
+#include "item/BagFamily.h"
+#include "turtle/Detect.h"
+
+#include <cstdint>
+
+namespace Turtle::BagFamily {
+
+namespace {
+
+// Turtle custom Container-class subclasses → `ItemBagFamily.dbc` raw IDs.
+// Stock subclasses (Soul/Herb/Enchanting/Engineering) are handled by
+// `Item::BagFamily`'s own table and never reach here. Gated on Turtle
+// detection so the custom mapping can't misfire on a stock client (where
+// these subclasses don't exist as containers anyway).
+uint32_t Resolve(uint32_t itemClass, uint32_t subclass) {
+    if (!Turtle::Detected() || itemClass != Item::BagFamily::kItemClassContainer)
+        return 0;
+    switch (subclass) {
+    case 6:  return 13;  // Mining Bag         → Mining Supplies
+    case 7:  return 12;  // Leatherworking Bag → Leather
+    case 8:  return 10;  // Meat Bag           → Meat
+    case 9:  return 11;  // Fish Bag           → Fish
+    default: return 0;
+    }
+}
+
+const Item::BagFamily::AutoResolver _register{&Resolve};
+
+} // namespace
+
+} // namespace Turtle::BagFamily

src/turtle/ComboDuration.cpp

@@ -0,0 +1,66 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// Turtle WoW reworked Rip — known combo-finisher durations for a spell
+// whose client DBC row is missing. All six Rip ranks point at
+// SpellDuration row 87, which Turtle added on the SERVER only
+// ({8000, 0, 18000} — live data shows 10/12/14/16/18s at 1..5 CP, i.e.
+// 8s + 2s per combo point); the client patch never shipped the row (the
+// client table jumps 86 → 105), so the index dangles. Verified the only
+// dangling duration index in the entire client Spell.dbc.
+//
+// This supplies the values through `Aura::ComboDuration`'s dangling-row
+// resolver so the Turtle-specific data lives here, not in the stock
+// module. Unlike the other `src/turtle/` modules it does NOT gate on
+// `Turtle::Detected()`: the activation gate is the dangling-row condition
+// in `Aura::ComboDuration` (a client-data bug unique to this Rip), which
+// is the deliberate design — gate on the bug, not the realm. On a stock
+// client Rip resolves to a valid row and this resolver is never consulted;
+// if Turtle ever ships the missing client row, the DBC takes over and this
+// goes dormant automatically.
+
+#include "aura/ComboDuration.h"
+
+#include <cstdint>
+
+namespace Turtle::ComboDuration {
+
+namespace {
+
+struct Known {
+    uint32_t spellId;
+    int32_t baseMs;
+    int32_t maxMs;
+};
+
+constexpr Known kRip[] = {
+    {1079, 8000, 18000}, {9492, 8000, 18000}, {9493, 8000, 18000},
+    {9752, 8000, 18000}, {9894, 8000, 18000}, {9896, 8000, 18000},
+};
+
+bool Resolve(uint32_t spellId, int32_t *baseMs, int32_t *maxMs) {
+    for (const auto &k : kRip) {
+        if (k.spellId == spellId) {
+            *baseMs = k.baseMs;
+            *maxMs = k.maxMs;
+            return true;
+        }
+    }
+    return false;
+}
+
+const Aura::ComboDuration::AutoDanglingResolver _register{&Resolve};
+
+} // namespace
+
+} // namespace Turtle::ComboDuration

src/turtle/Detect.cpp

@@ -0,0 +1,69 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#include "turtle/Detect.h"
+
+#include "Game.h"
+
+#include <cstring>
+
+namespace Turtle {
+
+namespace {
+
+// Latched once we've read the global as a string — Turtle never un-sets
+// it, so a true result is permanent. A false read is NOT cached: FrameXML
+// may not have run yet, so we re-probe on each call until it lands.
+bool g_detected = false;
+char g_version[32] = {0};
+
+void Probe() {
+    if (g_detected)
+        return;
+    void *L = Game::Lua::State();
+    if (L == nullptr)
+        return;
+
+    // Read `_G["TURTLE_WOW_VERSION"]` without disturbing the caller's
+    // stack. RawGet avoids any (nonexistent, but free-to-skip) metatable
+    // side effects on the globals table.
+    const int top = Game::Lua::GetTop(L);
+    Game::Lua::PushString(L, "TURTLE_WOW_VERSION");
+    Game::Lua::RawGet(L, Game::Lua::GLOBALS_INDEX);
+    if (Game::Lua::IsString(L, -1)) {
+        const char *v = Game::Lua::ToString(L, -1);
+        if (v != nullptr) {
+            const size_t n = std::strlen(v);
+            const size_t copy =
+                (n < sizeof(g_version) - 1) ? n : sizeof(g_version) - 1;
+            std::memcpy(g_version, v, copy);
+            g_version[copy] = '\0';
+        }
+        g_detected = true;
+    }
+    Game::Lua::SetTop(L, top);
+}
+
+} // namespace
+
+bool Detected() {
+    Probe();
+    return g_detected;
+}
+
+const char *Version() {
+    Probe();
+    return g_detected ? g_version : nullptr;
+}
+
+} // namespace Turtle

src/turtle/Detect.h

@@ -0,0 +1,37 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+// Turtle WoW client detection — the gate for every module under
+// `src/turtle/`. Turtle's FrameXML sets a `TURTLE_WOW_VERSION` global (see
+// `FrameXML/Globals.lua`, e.g. `"1.18.1"`); its presence is the
+// authoritative "this is the Turtle client" signal — no realm-list
+// sniffing (which conflates "connected to Turtle" with "running the
+// Turtle client" and was rejected for the Rip combo-duration work), no
+// binary fingerprinting.
+namespace Turtle {
+
+// True iff running on a Turtle WoW client. Reads the `TURTLE_WOW_VERSION`
+// global and LATCHES true once seen. Safe to call any time: it returns
+// false until the in-game Lua state exists AND FrameXML's Globals.lua has
+// run (so it can read false very early in boot / on the glue screen), then
+// flips true and stays true. Never caches a false result, so an early
+// probe can't wrongly pin a Turtle client as non-Turtle.
+bool Detected();
+
+// The Turtle client version string (e.g. `"1.18.1"`), or nullptr when not
+// Turtle / not yet detected. Points at an internally-cached copy.
+const char *Version();
+
+} // namespace Turtle

src/turtle/HealingAura.cpp

@@ -0,0 +1,44 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// Turtle WoW custom healing auras. Aura 199
+// (MOD_SPELL_HEALING_OF_ARMOR_PERCENT, "Ironclad") adds
+// `Armor × amount / 100` to the player's spell healing bonus — not a stock
+// vanilla aura index. Plugs into `Spell::HealingAura`'s resolver chain so
+// the Turtle-specific aura semantic lives here, not in the stock
+// GetSpellBonusHealing decoder. Gated on Turtle detection (the aura index
+// is a generic slot number that could mean something else on another
+// server).
+
+#include "spell/HealingAura.h"
+#include "turtle/Detect.h"
+
+#include <cstdint>
+
+namespace Turtle::HealingAura {
+
+namespace {
+
+constexpr int kAuraModHealingOfArmorPercent = 199; // × Armor (Ironclad)
+
+long Resolve(int auraIndex, long amount, int32_t /*spirit*/, int32_t armor) {
+    if (!Turtle::Detected() || auraIndex != kAuraModHealingOfArmorPercent)
+        return 0;
+    return static_cast<long>(armor) * amount / 100;
+}
+
+const Spell::HealingAura::AutoResolver _register{&Resolve};
+
+} // namespace
+
+} // namespace Turtle::HealingAura

src/ui/FrameObject.cpp

@@ -0,0 +1,86 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#include "ui/FrameObject.h"
+
+#include "Game.h"
+#include "Offsets.h"
+
+#include <cstdint>
+
+namespace UI::FrameObject {
+
+namespace {
+
+using LuaRawGetI_t = void(__fastcall *)(void *L, int idx, int n);
+using ScriptRegister_t = void(__fastcall *)(void *this_, void *edx_unused,
+                                            const char *name);
+
+} // namespace
+
+// Delegate wrapper construction to the engine's own
+// `FrameScript_Object::ScriptRegister`. First call for a never-seen frame
+// builds a `{[0] = lightuserdata}` table with the framescript metatable,
+// `luaL_ref`s it into the registry, and writes the refkey to `frame +
+// 0x08` (`OFF_COBJECT_LUA_REGISTRY_REF`). Subsequent calls find a
+// populated refkey and just rawgeti.
+//
+// Why delegate instead of building our own wrapper: single source of
+// truth. Every code path that pushes this frame — ours, addons'
+// `CreateFrame(..., parent)` extracting the frame, the engine's own
+// pushers — funnels through `rawgeti(REGISTRY, frame + 0x08)` and gets the
+// same Lua table, so addon fields set on the wrapper don't get orphaned
+// onto a divergent copy. See the long note in `nameplate/Info.cpp`'s
+// original implementation for the pfUI-divergence story that motivated
+// this.
+//
+// `ScriptRegister` unconditionally bumps the CObject refcount at `+0x04`,
+// which pins the frame against GC. That's benign for the pooled/permanent
+// frames we push here (nameplates, chat bubbles) — we call it at most
+// once per frame pointer (gated by `refKey <= 0`), so the refcount tops
+// out at one increment per pool slot.
+//
+// Defensive fallback: if the registry slot exists but isn't a table any
+// more (freed elsewhere), re-register to rebuild a fresh wrapper. This
+// shouldn't happen in practice — engines only unref on frame destruction.
+void Push(void *L, void *frame) {
+    auto rawgeti = reinterpret_cast<LuaRawGetI_t>(
+        Offsets::FUN_FRAMESCRIPT_PUSH_OBJECT);
+    auto scriptRegister = reinterpret_cast<ScriptRegister_t>(
+        static_cast<uintptr_t>(Offsets::FUN_FRAMESCRIPT_OBJECT_SCRIPT_REGISTER));
+
+    auto *cobj = static_cast<uint8_t *>(frame);
+    int refKey = *reinterpret_cast<const int *>(
+        cobj + Offsets::OFF_COBJECT_LUA_REGISTRY_REF);
+    if (refKey <= 0) {
+        scriptRegister(frame, nullptr, nullptr);
+        refKey = *reinterpret_cast<const int *>(
+            cobj + Offsets::OFF_COBJECT_LUA_REGISTRY_REF);
+    }
+
+    rawgeti(L, Game::Lua::REGISTRY_INDEX, refKey);
+    if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_TABLE)
+        return;
+    Game::Lua::SetTop(L, -2);
+
+    // Slot got freed somewhere — re-register to rebuild a fresh wrapper
+    // and slot. Zero the refcount so `ScriptRegister` re-enters its build
+    // branch.
+    *reinterpret_cast<int *>(cobj + Offsets::OFF_COBJECT_LUA_REFCOUNT) = 0;
+    scriptRegister(frame, nullptr, nullptr);
+    refKey = *reinterpret_cast<const int *>(
+        cobj + Offsets::OFF_COBJECT_LUA_REGISTRY_REF);
+    rawgeti(L, Game::Lua::REGISTRY_INDEX, refKey);
+}
+
+} // namespace UI::FrameObject

src/ui/FrameObject.h

@@ -0,0 +1,34 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+namespace UI::FrameObject {
+
+// Pushes a C++ `CFrameScriptObject`-derived frame onto the Lua stack as
+// its canonical wrapper table — the same object every other engine path
+// resolves via `rawgeti(REGISTRY, frame + 0x08)`, so addon-set fields on
+// the wrapper survive roundtrips through our API and method dispatch
+// (`:GetRegions()`, `:GetName()`, …) works normally.
+//
+// For frames the engine created purely in C++ without ever going through
+// `CreateFrame` (default nameplates, chat bubbles), the registry ref at
+// `+0x08` starts at 0; the first push delegates to the engine's own
+// `FrameScript_Object::ScriptRegister` to lazily build the wrapper +
+// registry slot. Subsequent pushes just `rawgeti` the cached slot.
+//
+// Leaves exactly one value (the wrapper table, or the re-registered
+// fallback) on the stack. `frame` must be non-null.
+void Push(void *L, void *frame);
+
+} // namespace UI::FrameObject