fix(unitmenu): stop stacking Focus/Cancel when a submenu opens

ClassicAPI_ToggleUnitMenu's initialize closure ran the same level-1
customization at every level. When the mouse crossed a nested entry
(Loot Method / Loot Threshold / Raid Target Icon) the menu builds its
level-2 submenu and re-invokes initialize; our AddFocusButton /
AddCancelButton call UIDropDownMenu_AddButton with no level, which
defaults to level 1 (not the current level), appending onto the still-
open level-1 list. Level 1 is not reset while a submenu rebuilds, so the
list grew every hover until "Too many buttons in UIDropDownMenu:
ClassicAPIUnitMenuDropDown", pushing the real entries out of reach.

Make initialize level-aware: at level >= 2 hand off to UnitPopup_ShowMenu
(it resolves the submenu from UIDROPDOWNMENU_MENU_VALUE and adds its own
Cancel); do the scratch-copy + Focus/Cancel append only at level 1 -
mirroring how Blizzard's own unit dropdowns init.

.github/workflows/build.yml

@@ -4,48 +4,112 @@ on:
   push:
     branches: ['**']
     tags: ['v*']
+  # Manual escape hatch (e.g. when push webhooks are throttled during a
+  # GitHub Actions incident). Run from the Actions UI:
+  #   - select a `vX.Y.Z` tag ref  -> release build of that tag, OR
+  #   - run from a branch and pass `tag: vX.Y.Z` -> release build that
+  #     creates/attaches the release to that tag.
+  # Leave `tag` blank on a branch run for a plain dev build (artifact).
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build (e.g. v2.0.0). Blank = dev build.'
+        required: false
+        default: ''
 
 permissions:
   contents: write
 
 jobs:
+  # Decide which runner the build lands on. `runs-on` is fixed before a job
+  # starts and a job pointed at an offline self-hosted runner queues forever
+  # instead of failing over — so we probe first and hand the label down.
+  pick-runner:
+    runs-on: ubuntu-latest
+    outputs:
+      label: ${{ steps.pick.outputs.label }}
+    steps:
+      - name: Probe for an online self-hosted runner
+        id: pick
+        env:
+          # Listing runners needs repo-admin access; the default GITHUB_TOKEN
+          # does NOT have it. Create a PAT (classic: `repo`; fine-grained:
+          # Administration → read) and store it as the RUNNER_CHECK_TOKEN
+          # secret. If the secret is missing, we fall back to windows-latest.
+          GH_TOKEN: ${{ secrets.RUNNER_CHECK_TOKEN }}
+        run: |
+          label=windows-latest
+          if [ -n "$GH_TOKEN" ]; then
+            online=$(gh api "repos/${{ github.repository }}/actions/runners" \
+              --jq '[.runners[] | select(.status=="online") | select([.labels[].name] | index("self-hosted"))] | length' \
+              2>/dev/null || echo 0)
+            if [ "${online:-0}" -gt 0 ]; then
+              label=self-hosted
+            fi
+          fi
+          echo "Selected runner: $label"
+          echo "label=$label" >> "$GITHUB_OUTPUT"
+
   build:
-    runs-on: windows-latest
+    needs: pick-runner
+    runs-on: ${{ needs.pick-runner.outputs.label }}
+    # Windows PowerShell 5.1 is always present; the runner's default `pwsh`
+    # (PowerShell Core) is not installed by default, and `shell: bash` on a
+    # self-hosted box resolves to the WSL launcher in System32.
+    defaults:
+      run:
+        shell: powershell
     steps:
       - uses: actions/checkout@v4
         with:
           submodules: recursive
 
-      - name: Stamp embedded TOC version
-        if: startsWith(github.ref, 'refs/tags/v')
-        shell: pwsh
+      # Resolve the effective version once so every step below agrees.
+      # is_release=true when a vX.Y.Z tag is in play (pushed tag,
+      # dispatched-from-tag, or a `tag` input); the embedded addon's
+      # `## Version:` and the compiled CLASSIC_API_VERSION are both
+      # stamped from it at embed/compile time (see cmake/embed_addon.cmake)
+      # — no source edit.
+      - name: Resolve version
+        id: ver
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
         run: |
-          $version = '${{ github.ref_name }}' -replace '^v',''
-          $toc = 'AddOns/!!!ClassicAPI/!!!ClassicAPI.toc'
-          (Get-Content $toc) -replace '^## Version:.*', "## Version: $version" |
-            Set-Content $toc
+          if ($env:GITHUB_EVENT_NAME -eq 'workflow_dispatch' -and $env:INPUT_TAG) {
+            $tag = $env:INPUT_TAG
+          } elseif ($env:GITHUB_REF -like 'refs/tags/v*') {
+            $tag = $env:GITHUB_REF_NAME
+          } else {
+            $tag = ''
+          }
+          $isRelease = if ($tag) { 'true' } else { 'false' }
+          Add-Content -Path $env:GITHUB_OUTPUT -Value "tag=$tag" -Encoding utf8
+          Add-Content -Path $env:GITHUB_OUTPUT -Value "is_release=$isRelease" -Encoding utf8
 
-      - name: Configure (tag)
-        if: startsWith(github.ref, 'refs/tags/v')
-        run: cmake -B build -A Win32 "-DCLASSICAPI_TAG=${{ github.ref_name }}"
+      - name: Configure (release)
+        if: steps.ver.outputs.is_release == 'true'
+        run: cmake -B build -A Win32 "-DCLASSICAPI_TAG=${{ steps.ver.outputs.tag }}"
 
-      - name: Configure (branch)
-        if: "!startsWith(github.ref, 'refs/tags/v')"
+      - name: Configure (dev)
+        if: steps.ver.outputs.is_release != 'true'
         run: cmake -B build -A Win32
 
       - name: Build
         run: cmake --build build --config Release
 
       - name: Upload artifact
-        if: "!startsWith(github.ref, 'refs/tags/v')"
+        if: steps.ver.outputs.is_release != 'true'
         uses: actions/upload-artifact@v4
         with:
           name: ClassicAPI-${{ github.sha }}
           path: build/Release/ClassicAPI.dll
 
       - name: Release
-        if: startsWith(github.ref, 'refs/tags/v')
+        if: steps.ver.outputs.is_release == 'true'
         uses: softprops/action-gh-release@v2
         with:
-          files: build/Release/ClassicAPI.dll
+          tag_name: ${{ steps.ver.outputs.tag }}
+          files: |
+            build/Release/ClassicAPI.dll
+            build/Release/ClassicAPI.map
           generate_release_notes: true

.gitignore

@@ -45,4 +45,6 @@
 # debug information files
 *.dwo
 
-CLAUDE.md
+CLAUDE.md
+
+/AddOns/!!!ClassicAPI/.classicapi-dev

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

@@ -42,3 +42,6 @@ Util\Rectangle.lua
 Util\Vector2D.lua
 Util\Vector3D.lua
 Util\Vector4D.lua
+Util\UIParent.lua
+Util\AuraDurationModifiers.lua
+Util\SecureUnitMenu.lua

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

@@ -43,3 +43,41 @@ end
 if C_AddOns.DoesAddOnExist("SpecialTalentUI") then
     EventUtil.ContinueOnAddOnLoaded("SpecialTalentUI", CAPI_ApplyStandardColorGlobals)
 end
+
+-- ShaguTweaks libpredict register's TBC events that ClassicAPI backports.
+if C_AddOns.DoesAddOnExist("ShaguTweaks") then
+    EventUtil.ContinueOnAddOnLoaded("ShaguTweaks", function()
+        local libp = ShaguTweaks.libpredict
+        if libp then
+            libp.sender:UnregisterEvent("COMBAT_LOG_EVENT_UNFILTERED")
+            libp.sender:UnregisterEvent("UNIT_SPELLCAST_START")
+            libp.sender:UnregisterEvent("UNIT_SPELLCAST_STOP")
+            libp.sender:UnregisterEvent("UNIT_SPELLCAST_FAILED")
+            libp.sender:UnregisterEvent("UNIT_SPELLCAST_INTERRUPTED")
+            libp.sender:UnregisterEvent("UNIT_SPELLCAST_SENT")
+        end
+    end)
+end
+
+-- Guard UPDATE_MOUSEOVER_UNIT handlers (issue #12).
+function CAPI_MouseoverClearedCompat(frame)
+    if not frame then return end
+    local originalOnEvent = frame:GetScript("OnEvent")
+    frame:SetScript("OnEvent", function()
+        if event == "UPDATE_MOUSEOVER_UNIT" and not UnitExists("mouseover") then
+            return
+        end
+
+        if originalOnEvent then
+            originalOnEvent()
+        end
+    end)
+end
+
+CAPI_MouseoverClearedCompat(GameTooltip)
+
+if C_AddOns.DoesAddOnExist("Puppeteer") then
+    EventUtil.ContinueOnAddOnLoaded("Puppeteer", function()
+        CAPI_MouseoverClearedCompat(PTEnemyUpdater)
+    end)
+end

AddOns/!!!ClassicAPI/Util/AuraDurationModifiers.lua

@@ -0,0 +1,40 @@
+-- Server-side DoT-duration adjustments the 1.12 client is never told about.
+--
+-- ClassicAPI derives C_UnitAuras expirationTime for a debuff on another unit
+-- from the cast packet (SMSG_SPELL_GO). The vanilla server never retransmits a
+-- LATER server-side duration change on a non-self unit -- verified in the
+-- server source: the change runs through SetAuraDuration / RefreshHolder, and
+-- the only duration packet (SMSG_UPDATE_AURA_DURATION) is self-scoped to the
+-- aura-bearer, so an observing caster hears nothing (and on a mob the packet
+-- isn't even built). We can't hear the change, but we DO see the *triggering*
+-- cast, so a registered rule mirrors the server's edit off that trigger.
+--
+-- A trigger keyed to a whole class of spells (rather than a named ability) is
+-- registered from Lua with RegisterAuraDurationModifierByTrigger, matched by
+-- SpellFamilyName + school index (see Shadow Weaving below). Exact-spellID
+-- triggers are registered from C++ (Aura::Source::AddDurationMod): Turtle's
+-- Conflagrate -> Immolate and Molten Blast -> Flame Shock live in the DLL
+-- (src/turtle/DurationMods.cpp), as does Carnage, whose per-combo-point roll no
+-- rule can express (src/turtle/Carnage.cpp).
+
+-- Shadow Weaving (priest): any shadow-school priest cast refreshes the caster's
+-- Shadow Vulnerability (15258, 15s, stacks to 5). The 1->5 stack changes fire
+-- OnAuraStacksChanged (already handled); the 5->5 refresh is the silent blind
+-- spot this covers. Matched by family(6) + school(5) so it spans every priest
+-- shadow spell/rank incl. Turtle additions, excluding holy/discipline casts
+-- (Smite, heals) which are priest-family but not shadow-school.
+--
+-- Gated on the 5/5 talent (15334), where the proc is 100% -> deterministic;
+-- below 5/5 it's chance-based and inferring on every cast would over-refresh.
+-- Deferred to SPELLS_CHANGED because talent/spell state isn't ready at load,
+-- and re-checked there so a respec INTO 5/5 registers without a reload.
+-- Caveat: DoT *ticks* (SW:P / Devouring Plague) refresh it server-side too but
+-- emit no cast packet, so a pure DoT-only phase (no direct casts) under-counts.
+local PRIEST, SHADOW = 6, 5
+local SW_FLAG, SW_ICON = tonumber("4000000", 16), 9 -- 15258 SpellFamilyFlags + icon
+
+EventUtil.RegisterOnceFrameEventAndCallback("SPELLS_CHANGED", function()
+    if IsPlayerSpell(15334) then
+        C_UnitAuras.RegisterAuraDurationModifierByTrigger(PRIEST, SHADOW, PRIEST, SW_FLAG, SW_ICON, "refresh")
+    end
+end)

AddOns/!!!ClassicAPI/Util/CallbackRegistry.lua

@@ -26,10 +26,17 @@ local function GenerateClosure(func, ...)
     for i = 1, boundN do bound[i] = arg[i] end
     return function(...)
         local callN = arg.n
-        local merged = {}
-        for i = 1, boundN do merged[i] = bound[i] end
-        for i = 1, callN do merged[boundN + i] = arg[i] end
-        return func(unpack(merged, 1, boundN + callN))
+        -- Forward bound + call args faithfully, embedded/leading nils and all.
+        -- The ONLY thing that makes unpack span holes on this Lua 5.0 build is
+        -- a `.n` field: unpack takes its count from getn (which returns t.n)
+        -- and ignores any explicit i/j, so a `.n`-less table stops dead at the
+        -- first hole (verified: unpack({1, 1, nil, 1}, 1, 4) yields just 1, 1).
+        local all = {}
+        local n = 0
+        for i = 1, boundN do n = n + 1; all[n] = bound[i] end
+        for i = 1, callN do n = n + 1; all[n] = arg[i] end
+        all.n = n
+        return func(unpack(all))
     end
 end
 
@@ -145,11 +152,14 @@ function CallbackRegistryMixin:TriggerEvent(event, ...)
     if funcs then
         for owner, func in pairs(funcs) do
             -- Stock 3.3.5 passes the owner as the first arg so callers can
-            -- distinguish multiple registrations of the same function.
-            local n = arg.n
-            local merged = { owner }
-            for i = 1, n do merged[i + 1] = arg[i] end
-            func(unpack(merged, 1, n + 1))
+            -- distinguish multiple registrations of the same function. `arg`
+            -- carries its own `.n`, so unpack(arg) forwards the payload with
+            -- leading/embedded nils intact. Do NOT instead merge into a
+            -- `{ owner, ... }` table and unpack that WITHOUT setting `.n`: this
+            -- build's unpack counts via getn, so a `.n`-less table collapses at
+            -- the first hole (verified in-game: reload's PLAYER_ENTERING_WORLD,
+            -- arg1=nil arg2=1, dropped the payload).
+            func(owner, unpack(arg))
         end
     end
 end

AddOns/!!!ClassicAPI/Util/FunctionUtil.lua

@@ -2,7 +2,9 @@
 --
 -- Implementation differences from the modern source:
 --   - Lua 5.0 has no select() and no `...` as expression; use the
---     implicit `arg` table (arg.n + arg[i]) and unpack(arg, 1, arg.n).
+--     implicit `arg` table (arg.n + arg[i]). unpack(arg) already spans
+--     arg[1..arg.n] via getn — this build's unpack ignores explicit i/j
+--     args, so the count must live in the table's `.n`.
 --   - Lua 5.0 has no `#` operator; use table.getn().
 --   - 5.0's xpcall is strictly (f, handler) — no trailing args. We wrap
 --     the script call in a local closure that captures frame + arg.
@@ -32,7 +34,7 @@ function ExecuteFrameScript(frame, scriptName, ...)
 	if script then
 		local args = arg;
 		local function invoke()
-			return script(frame, unpack(args, 1, args.n));
+			return script(frame, unpack(args));
 		end
 		xpcall(invoke, CallErrorHandler);
 	end
@@ -45,7 +47,7 @@ function CallMethodOnNearestAncestor(self, methodName, ...)
 	end
 
 	if ancestor then
-		return true, ancestor[methodName](ancestor, unpack(arg, 1, arg.n));
+		return true, ancestor[methodName](ancestor, unpack(arg));
 	end
 
 	return false;
@@ -58,7 +60,7 @@ function GetValueOrCallFunction(tbl, key, ...)
 
 	local value = tbl[key];
 	if type(value) == "function" then
-		return value(unpack(arg, 1, arg.n));
+		return value(unpack(arg));
 	else
 		return value;
 	end
@@ -117,12 +119,12 @@ function IterateTables(iteratorFunction, ...)
 end
 
 local s_passThroughClosureGenerators = {
-	function(f) return function(...) return f(unpack(arg, 1, arg.n)); end; end,
-	function(f, a) return function(...) return f(a, unpack(arg, 1, arg.n)); end; end,
-	function(f, a, b) return function(...) return f(a, b, unpack(arg, 1, arg.n)); end; end,
-	function(f, a, b, c) return function(...) return f(a, b, c, unpack(arg, 1, arg.n)); end; end,
-	function(f, a, b, c, d) return function(...) return f(a, b, c, d, unpack(arg, 1, arg.n)); end; end,
-	function(f, a, b, c, d, e) return function(...) return f(a, b, c, d, e, unpack(arg, 1, arg.n)); end; end,
+	function(f) return function(...) return f(unpack(arg)); end; end,
+	function(f, a) return function(...) return f(a, unpack(arg)); end; end,
+	function(f, a, b) return function(...) return f(a, b, unpack(arg)); end; end,
+	function(f, a, b, c) return function(...) return f(a, b, c, unpack(arg)); end; end,
+	function(f, a, b, c, d) return function(...) return f(a, b, c, d, unpack(arg)); end; end,
+	function(f, a, b, c, d, e) return function(...) return f(a, b, c, d, e, unpack(arg)); end; end,
 };
 
 local s_flatClosureGenerators = {
@@ -138,7 +140,7 @@ local function GenerateClosureInternal(generatorArray, f, ...)
 	local count = arg.n;
 	local generator = generatorArray[count + 1];
 	if generator then
-		return generator(f, unpack(arg, 1, count));
+		return generator(f, unpack(arg));
 	end
 
 	assertsafe(false, "Closure generation does not support more than " .. (table.getn(generatorArray) - 1) .. " parameters");
@@ -147,14 +149,14 @@ end
 
 -- Syntactic sugar for function(...) return f(a, b, c, ...); end
 function GenerateClosure(f, ...)
-	return GenerateClosureInternal(s_passThroughClosureGenerators, f, unpack(arg, 1, arg.n));
+	return GenerateClosureInternal(s_passThroughClosureGenerators, f, unpack(arg));
 end
 
 -- Generates a closure with the specified arguments that will ignore extra arguments when called later. Useful for passing
 -- through callbacks to APIs where we don't want extra arguments to be passed through, i.e. simple OnClick scripts.
 -- This is equivalent to: function() return f(a, b, c); end INSTEAD OF function(...) return f(a, b, c, ...); end
 function GenerateFlatClosure(f, ...)
-	return GenerateClosureInternal(s_flatClosureGenerators, f, unpack(arg, 1, arg.n));
+	return GenerateClosureInternal(s_flatClosureGenerators, f, unpack(arg));
 end
 
 function RunNextFrame(callback)
@@ -166,7 +168,7 @@ FunctionUtil = {};
 function FunctionUtil.SafeInvokeMethod(table, methodName, ...)
 	local method = table[methodName];
 	if method then
-		return method(table, unpack(arg, 1, arg.n));
+		return method(table, unpack(arg));
 	end
 
 	return nil;

AddOns/!!!ClassicAPI/Util/GlobalCallbackRegistry.lua

@@ -22,6 +22,18 @@ function EventRegistry:OnLoad()
         -- Lua-5.0 varargs, so we forward through a small wrapper.
         self:DispatchGameEvent(event, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
     end)
+
+    -- Stop delivering events once logout begins: a callback firing during the
+    -- engine's teardown can touch state that's already gone. A dedicated frame
+    -- owns PLAYER_LOGOUT so this fires regardless of what consumers registered
+    -- — folding the check into frameEventFrame's OnEvent would depend on the
+    -- ref-counted event set still holding PLAYER_LOGOUT at logout time.
+    self.logoutFrame = CreateFrame("Frame")
+    self.logoutFrame:RegisterEvent("PLAYER_LOGOUT")
+    self.logoutFrame:SetScript("OnEvent", function()
+        self.frameEventFrame:UnregisterAllEvents()
+        self.frameEventFrame:SetScript("OnEvent", nil)
+    end)
 end
 
 -- Helper so we can forward up to nine event args (the most any vanilla

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

@@ -216,8 +216,7 @@ function ItemMixin:GetItemLink() -- requires item data to be loaded
     end
 
     if self.itemID then
-        local _, link = GetItemInfo(self.itemID)
-        return link
+        return (select(2, C_Item.GetItemInfo(self.itemID)));
     end
 
     if not self:IsItemEmpty() then
@@ -299,9 +298,7 @@ end
 
 function ItemMixin:GetInventoryTypeName()
     if not self:IsItemEmpty() then
-        -- GetItemInfoInstant returns: itemID, itemType, itemSubType, equipLoc, ...
-        local _, _, _, equipLoc = C_Item.GetItemInfoInstant(self:GetItemID())
-        return equipLoc
+        return select(4, C_Item.GetItemInfoInstant(self:GetItemID()));
     end
 end
 

AddOns/!!!ClassicAPI/Util/Pools.lua

@@ -14,7 +14,8 @@
 --     consumer addons doesn't fail; they'll error at Acquire() time
 --     if anything actually invokes them.
 --   - Lua 5.0 has no `...` as expression; the converter mixins use
---     `unpack(arg, 1, arg.n)` to forward varargs.
+--     `unpack(arg)` to forward varargs (spans arg[1..arg.n] via getn;
+--     this build's unpack ignores explicit i/j — the count lives in `.n`).
 --   - assertsafe / nop aren't globals in stock 1.12; defined as local
 --     fallbacks (same pattern as FunctionUtil.lua).
 
@@ -381,12 +382,12 @@ function FramePoolCollectionConverterMixin:CreatePoolKeyFromPoolArgs(args)
 end
 
 function FramePoolCollectionConverterMixin:GetOrCreatePool(...)
-	local args = FramePoolCollection_ArgsToTable(unpack(arg, 1, arg.n));
+	local args = FramePoolCollection_ArgsToTable(unpack(arg));
 	return self:GetOrCreatePoolWithArgs(args);
 end
 
 function FramePoolCollectionConverterMixin:CreatePool(...)
-	local args = FramePoolCollection_ArgsToTable(unpack(arg, 1, arg.n));
+	local args = FramePoolCollection_ArgsToTable(unpack(arg));
 	return self:CreatePoolWithArgs(args);
 end
 
@@ -432,12 +433,12 @@ local function FontStringPoolCollection_ArgsToTable(parent, layer, subLayer, tem
 end
 
 function FontStringPoolCollectionMixin:GetOrCreatePool(...)
-	local args = FontStringPoolCollection_ArgsToTable(unpack(arg, 1, arg.n));
+	local args = FontStringPoolCollection_ArgsToTable(unpack(arg));
 	return self:GetOrCreatePoolWithArgs(args);
 end
 
 function FontStringPoolCollectionMixin:CreatePool(...)
-	local args = FontStringPoolCollection_ArgsToTable(unpack(arg, 1, arg.n));
+	local args = FontStringPoolCollection_ArgsToTable(unpack(arg));
 	return self:CreatePoolWithArgs(args);
 end
 

AddOns/!!!ClassicAPI/Util/SecureUnitMenu.lua

@@ -0,0 +1,125 @@
+-- Unit right-click menu for attribute-driven unit frames.
+--
+-- Backs the `menu` / `togglemenu` click verb of the Frame:SetAttribute
+-- backport (see src/frame/Attributes.cpp). When a frame with a `unit`
+-- attribute resolves a click to the `menu` verb, the DLL calls
+-- ClassicAPI_ToggleUnitMenu(unit), which pops the standard unit dropdown at
+-- the cursor -- the same UnitPopup menu Blizzard's PlayerFrame / TargetFrame /
+-- PartyMemberFrame show on right-click. Lets a unit frame express its
+-- right-click menu purely as an attribute (e.g. type2 = "menu") instead of a
+-- hand-rolled OnClick handler. pfUI's unit frames use exactly this path
+-- (api/unitframes.lua -> ClassicAPI_ToggleUnitMenu).
+--
+-- The unit -> menu-type resolution mirrors Blizzard's own generic resolver
+-- (TargetFrameDropDown_Initialize in FrameXML): self -> SELF, pet -> PET, a
+-- grouped player -> PARTY (whisper / inspect / trade / follow / promote / ...),
+-- any other player -> PLAYER (adds INVITE), anything else (NPC) ->
+-- RAID_TARGET_ICON (the raid-marker list). Vanilla's stock UI never wires a
+-- unit to the "RAID" menu (there are no clickable raid unit frames in 1.12),
+-- and PARTY carries the options players actually want on a grouped member, so
+-- grouped players (party or raid) use PARTY -- matching how pfUI drives its
+-- raid menu.
+--
+-- Focus / Clear Focus: we add one contextual entry -- "Set Focus" when the
+-- unit is not the current focus, "Clear Focus" when it is -- for every real,
+-- non-self unit, NPCs included. This is done entirely inside our own dropdown:
+-- no hooksecurefunc, and no mutation of Blizzard's shared UnitPopupMenus tables
+-- (so default frames and other addons are unaffected). Because
+-- UnitPopup_ShowMenu hardwires every button's click to UnitPopup_OnClick (which
+-- does not know our keys), we add the Focus button ourselves with our own func.
+-- To keep Cancel last, we show the standard menu MINUS its trailing Cancel,
+-- then append Focus and Cancel.
+--
+-- This also fixes NPCs opening no menu at all: an NPC resolves to the
+-- RAID_TARGET_ICON menu, whose entries UnitPopup_HideButtons hides entirely
+-- unless you are in a group and can place markers -- so solo the menu was
+-- empty and never opened. Appending Focus + Cancel ourselves guarantees the
+-- menu always opens (markers still show when they are allowed).
+--
+-- Backed by the DLL's FocusUnit / ClearFocus globals and the `focus` unit
+-- token (src/unit/Focus.cpp). Labels come from the localized SET_FOCUS /
+-- CLEAR_FOCUS globals (locales/*.lua).
+
+local dropdown;
+
+-- Scratch menu key we own, rebuilt each open as a copy of the resolved base
+-- menu with its trailing CANCEL removed. Kept out of Blizzard's tables so the
+-- stock menus are never mutated.
+local SCRATCH_MENU = "CLASSICAPI_UNITMENU";
+
+local function EnsureDropdown()
+    if not dropdown then
+        dropdown = CreateFrame("Frame", "ClassicAPIUnitMenuDropDown", UIParent, "UIDropDownMenuTemplate");
+        dropdown.displayMode = "MENU";
+    end
+    return dropdown;
+end
+
+local function ResolveMenu(unit)
+    if UnitIsUnit(unit, "player") then
+        return "SELF";
+    elseif UnitIsUnit(unit, "pet") then
+        return "PET";
+    elseif UnitIsPlayer(unit) then
+        if UnitInParty(unit) or UnitInRaid(unit) then
+            return "PARTY";
+        end
+        return "PLAYER";
+    end
+    return "RAID_TARGET_ICON";
+end
+
+-- Append the contextual Focus / Clear Focus button for `unit`, with our own
+-- click func. Skipped for the player themselves (focusing yourself is a no-op).
+local function AddFocusButton(unit)
+    if UnitIsUnit(unit, "player") then
+        return;
+    end
+    local info = {};
+    info.notCheckable = 1;
+    if UnitExists("focus") and UnitIsUnit(unit, "focus") then
+        info.text = CLEAR_FOCUS;
+        info.func = function() ClearFocus(); end;
+    else
+        info.text = SET_FOCUS;
+        info.func = function() FocusUnit(unit); end;
+    end
+    UIDropDownMenu_AddButton(info);
+end
+
+local function AddCancelButton()
+    local info = {};
+    info.text = CANCEL;
+    info.notCheckable = 1;
+    info.func = function() end;
+    UIDropDownMenu_AddButton(info);
+end
+
+function ClassicAPI_ToggleUnitMenu(unit)
+    if not unit or not UnitExists(unit) then
+        return;
+    end
+    local which = ResolveMenu(unit);
+    local dd = EnsureDropdown();
+    dd.initialize = function(level)
+        level = level or UIDROPDOWNMENU_MENU_LEVEL or 1;
+
+        if level > 1 then
+            UnitPopup_ShowMenu(dd, which, unit);
+            return;
+        end
+
+        local base = UnitPopupMenus[which];
+        local scratch = {};
+        for _, value in ipairs(base) do
+            if value ~= "CANCEL" then
+                table.insert(scratch, value);
+            end
+        end
+        UnitPopupMenus[SCRATCH_MENU] = scratch;
+        UnitPopup_ShowMenu(dd, SCRATCH_MENU, unit);
+        AddFocusButton(unit);
+        AddCancelButton();
+    end
+    ToggleDropDownMenu(1, nil, dd, "cursor");
+end

AddOns/!!!ClassicAPI/Util/TableUtil.lua

@@ -431,7 +431,7 @@ function SafePack(...)
 end
 
 function SafeUnpack(tbl)
-    return unpack(tbl, 1, tbl.n)
+    return unpack(tbl)
 end
 
 -- Returns the length of a table, accounting for the possibility of a table constructed using SafePack.

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

@@ -448,8 +448,8 @@ local function CreateFrame_TradeSkillLink()
 
 	prodIcon:SetScript("OnEnter", function()
 		GameTooltip:SetOwner(this, "ANCHOR_RIGHT");
-		if this.itemLink then
-			GameTooltip:SetHyperlink(this.itemLink);
+		if this.itemID then
+			GameTooltip:SetHyperlink("item:"..this.itemID);
 		elseif this.spellID then
 			GameTooltip:SetSpellByID(this.spellID);
 		end
@@ -490,12 +490,17 @@ local function CreateFrame_TradeSkillLink()
 		nm:SetJustifyV("MIDDLE");
 		btn.nameText = nm;
 		btn:SetScript("OnEnter", function()
-			if this.itemLink then
+			if this.itemID then
 				GameTooltip:SetOwner(this, "ANCHOR_RIGHT");
-				GameTooltip:SetHyperlink(this.itemLink);
+				GameTooltip:SetHyperlink("item:"..this.itemID);
 				GameTooltip:Show();
 			end
 		end);
+		btn:SetScript("OnClick", function()
+			if this.itemLink and IsShiftKeyDown() and ChatFrameEditBox:IsVisible() then
+				ChatFrameEditBox:Insert(this.itemLink);
+			end
+		end);
 		btn:SetScript("OnLeave", GameTooltip_Hide);
 		f.reagents[i] = btn;
 		return btn;
@@ -564,6 +569,7 @@ local function CreateFrame_TradeSkillLink()
 			local name, tex, link = itemInfo(reagent.itemID);
 			btn:SetNormalTexture(tex or "Interface\\Icons\\INV_Misc_QuestionMark");
 			btn.itemLink = link;
+			btn.itemID = reagent.itemID
 			btn.nameText:SetText(name or ("item:" .. reagent.itemID));
 			local need = reagent.count or 1;
 			local have = C_Item.GetItemCount(reagent.itemID) or 0;
@@ -582,6 +588,7 @@ local function CreateFrame_TradeSkillLink()
 		end
 		for i = total + 1, table.getn(self.reagents) do
 			self.reagents[i].itemLink = nil;
+			self.reagents[i].itemID = nil;
 			self.reagents[i]:Hide();
 		end
 
@@ -630,6 +637,7 @@ local function CreateFrame_TradeSkillLink()
 		self.prodDesc:SetText("");
 		for i = 1, table.getn(self.reagents) do
 			self.reagents[i].itemLink = nil;
+			self.reagents[i].itemID = nil;
 			self.reagents[i]:Hide();
 		end
 		self.detailChild:SetHeight(LO.detail[4]);
@@ -726,7 +734,7 @@ local function ShowTradeSkillLink(link, text)
 		local r = recipes[i];
 		if r.isKnown then
 			r.band = DifficultyBand(cur or 0, r.trivialLevel, r.greenLevel);
-			r.name = GetSpellInfo(r.spellID) or ("spell:" .. r.spellID);
+			r.name = C_Spell.GetSpellName(r.spellID) or ("spell:" .. r.spellID);
 			table.insert(knownList, r);
 		end
 	end

AddOns/!!!ClassicAPI/Util/UIParent.lua

@@ -0,0 +1,3 @@
+function MouseIsOver(region, topOffset, bottomOffset, leftOffset, rightOffset)
+	return region:IsMouseOver(topOffset, bottomOffset, leftOffset, rightOffset);
+end

AddOns/!!!ClassicAPI/locales/deDE.lua

@@ -2,7 +2,33 @@ if GetLocale() ~= "deDE" then return end
 
 BINDING_NAME_FOCUSTARGET = "Fokus setzen";
 BINDING_NAME_TARGETFOCUS = "Fokus anvisieren";
+CONFIRM_DELETE_EQUIPMENT_SET = "Seid Ihr sicher, dass Ihr das Ausrüstungsset \"%s\" löschen wollt?";
+CONFIRM_SAVE_EQUIPMENT_SET = "Möchtet Ihr das Ausrüstungsset \"%s\" speichern?";
+DEBUFF_SYMBOL_CURSE = "Fl";
+DEBUFF_SYMBOL_DISEASE = "Kr";
+DEBUFF_SYMBOL_MAGIC = "Ma";
+DEBUFF_SYMBOL_POISON = "Gi";
+DEBUG_FRAMESTACK = "Frame Stack";
+EQUIPMENT_MANAGER = "Ausrüstungsmanager";
+EQUIPMENT_MANAGER_IGNORE_SLOT = "Diesen Platz ignorieren";
+EQUIPMENT_MANAGER_IS_DISABLED = "Der Ausrüstungsmanager ist abgeschaltet.";
+EQUIPMENT_MANAGER_ITEMS_MISSING_TOOLTIP = "%d %s |cffff0000(%d fehlen)|r";
+EQUIPMENT_MANAGER_PLACE_IN_BAGS = "In Beuteln platzieren";
+EQUIPMENT_MANAGER_UNIGNORE_SLOT = "Diesen Platz einbeziehen";
+EQUIPMENT_SETS = "Ausrüstungs-Sets: |cFFFFFFFF%s|r";
+EQUIPMENT_SETS_CANT_RENAME = "Ein Ausrüstungsset mit diesem Namen gibt es bereits.";
+EQUIPMENT_SETS_TOO_MANY = "Ihr könnt keine weiteren Ausrüstungssets erstellen.";
+EQUIPMENT_SET_ASSIGN_TO_SPEC = "Spezialisierung zuweisen:";
+EQUIPMENT_SET_EDIT = "Name/Icon ändern";
+EQUIPMENT_SET_SETTINGS = "Einstellungen";
+EQUIPSET_EQUIP = "Anlegen";
+ERR_EQUIPMENT_MANAGER_BAGS_FULL = "Ausrüstungstausch fehlgeschlagen. Inventar ist voll.";
+ERR_EQUIPMENT_MANAGER_COMBAT_SWAP_S = "Einige Gegenstände des Sets '%s' können nicht gewechselt werden, da Ihr Euch im Kampf befindet.";
+ERR_EQUIPMENT_MANAGER_MISSING_ITEM_S = "Mindestens ein Teil des Sets '%s' fehlt und kann nicht ausgerüstet werden.";
+CLEAR_FOCUS = "Fokus löschen";
+SET_FOCUS = "Fokus setzen";
 FOCUSTARGET = "Ziel als Fokus festlegen";
+GEARSETS_POPUP_TEXT = "Setnamen eingeben (Max. 16 Zeichen):";
 ITEMS_VARIABLE_QUANTITY = "%d |4IGegenstand:Gegenstände;";
 ITEMS_EQUIPPED = "%d |4Gegenstand:Gegenstände; ausgerüstet";
 ITEMS_IN_INVENTORY = "%d |4Gegenstand:Gegenstände; im Inventar";
@@ -15,6 +41,10 @@ COPPER_AMOUNT_SYMBOL = "K";
 GENERIC_FRACTION_STRING = "%d/%d";
 GOLD_AMOUNT_SYMBOL = "G";
 HOURS_MINUTES_SECONDS = "%.2d:%.2d:%.2d";
+ICON_FILTER_ALL = "Alle Symbole";
+ICON_FILTER_ITEM = "Gegenstände";
+ICON_FILTER_SPELL = "Zauber";
+ICON_SELECTION_TITLE_CURRENT = "Aktuell ausgewählt";
 ITEM_DELTA_DESCRIPTION = "Wenn Ihr diesen Gegenstand ersetzt, werden sich folgende Werte ändern:";
 ITEM_MOD_MANA_SHORT = "Mana";
 ITEM_MOD_HEALTH_SHORT = "Gesundheit";
@@ -42,7 +72,11 @@ ITEM_MOD_BLOCK_VALUE_SHORT = "Blocken";
 ITEM_MOD_DAMAGE_PER_SECOND_SHORT = "Schaden pro Sekunde";
 LARGE_NUMBER_SEPERATOR = ".";
 MINUTES_SECONDS = "%.2d:%.2d";
+PAPERDOLL_EQUIPMENTMANAGER = "Ausrüstungsmanager";
+PAPERDOLL_NEWEQUIPMENTSET = "Neues Set";
 PERCENTAGE_STRING = "%d%%";
+SET_FRIENDNOTE_LABEL = "Notizen für %s eintragen:";
+SET_NOTE = "Notiz eintragen";
 SILVER_AMOUNT_SYMBOL = "S";
 SLASH_CLEARFOCUS1 = "/fokusaufheben";
 SLASH_CLEARFOCUS2 = "/clearfocus";

AddOns/!!!ClassicAPI/locales/enUS.lua

@@ -1,11 +1,41 @@
 BINDING_NAME_AOELOOT = "AoE Loot";
 BINDING_NAME_FOCUSTARGET = "Focus Target";
 BINDING_NAME_TARGETFOCUS = "Target Focus";
+CONFIRM_DELETE_EQUIPMENT_SET = "Are you sure you want to delete the equipment set %s?";
+CONFIRM_SAVE_EQUIPMENT_SET = "Would you like to save the equipment set \"%s\"?";
 COPPER_AMOUNT_SYMBOL = "c";
+DEBUFF_SYMBOL_CURSE = "Cu";
+DEBUFF_SYMBOL_DISEASE = "Di";
+DEBUFF_SYMBOL_MAGIC = "Ma";
+DEBUFF_SYMBOL_POISON = "Po";
+DEBUG_FRAMESTACK = "Frame Stack";
+EQUIPMENT_MANAGER = "Equipment Manager";
+EQUIPMENT_MANAGER_IGNORE_SLOT = "Ignore This Slot";
+EQUIPMENT_MANAGER_IS_DISABLED = "The Equipment Manager is disabled.";
+EQUIPMENT_MANAGER_ITEMS_MISSING_TOOLTIP = "%d %s |cffff0000(%d missing)|r";
+EQUIPMENT_MANAGER_PLACE_IN_BAGS = "Place In Bags";
+EQUIPMENT_MANAGER_UNIGNORE_SLOT = "Include This Slot";
+EQUIPMENT_SETS = "Equipment Sets: |cFFFFFFFF%s|r";
+EQUIPMENT_SETS_CANT_RENAME = "An equipment set with that name already exists.";
+EQUIPMENT_SETS_TOO_MANY = "You cannot create any more new equipment sets.";
+EQUIPMENT_SET_ASSIGN_TO_SPEC = "Assign to Specialization:";
+EQUIPMENT_SET_EDIT = "Change Name/Icon";
+EQUIPMENT_SET_SETTINGS = "Settings";
+EQUIPSET_EQUIP = "Equip";
+ERR_EQUIPMENT_MANAGER_BAGS_FULL = "Equipment swap failed. Inventory is full.";
+ERR_EQUIPMENT_MANAGER_COMBAT_SWAP_S = "Some items from set %s cannot be swapped because you are in combat.";
+ERR_EQUIPMENT_MANAGER_MISSING_ITEM_S = "One or more items from set %s were missing and could not be equipped.";
+CLEAR_FOCUS = "Clear Focus";
+SET_FOCUS = "Set Focus";
 FOCUSTARGET = "Focus Target";
+GEARSETS_POPUP_TEXT = "Enter Set Name (Max 16 Characters):";
 GENERIC_FRACTION_STRING = "%d/%d";
 GOLD_AMOUNT_SYMBOL = "g";
 HOURS_MINUTES_SECONDS = "%.2d:%.2d:%.2d";
+ICON_FILTER_ALL = "All Icons";
+ICON_FILTER_ITEM = "Items";
+ICON_FILTER_SPELL = "Spells";
+ICON_SELECTION_TITLE_CURRENT = "Currently Selected";
 ITEM_DELTA_DESCRIPTION = "If you replace this item, the following stat changes will occur:";
 ITEM_MOD_MANA_SHORT = "Mana";
 ITEM_MOD_HEALTH_SHORT = "Health";
@@ -39,7 +69,11 @@ ITEM_MISSING = "%s missing";
 ITEM_SLOTS_IGNORED = "%d |4slot:slots; ignored";
 LARGE_NUMBER_SEPERATOR = ",";
 MINUTES_SECONDS = "%.2d:%.2d";
+PAPERDOLL_EQUIPMENTMANAGER = "Equipment Manager";
+PAPERDOLL_NEWEQUIPMENTSET = "New Set";
 PERCENTAGE_STRING = "%d%%";
+SET_FRIENDNOTE_LABEL = "Set Notes for %s:";
+SET_NOTE = "Set Note";
 SILVER_AMOUNT_SYMBOL = "s";
 SLASH_CLEARFOCUS1 = "/clearfocus";
 SLASH_CLEARFOCUS2 = "/clearfocus";

AddOns/!!!ClassicAPI/locales/esES.lua

@@ -2,7 +2,33 @@ if GetLocale() ~= "esES" then return end
 
 BINDING_NAME_FOCUSTARGET = "Establecer objetivo";
 BINDING_NAME_TARGETFOCUS = "Seleccionar enfocado";
+CONFIRM_DELETE_EQUIPMENT_SET = "¿Seguro que quieres eliminar el equipamiento %s?";
+CONFIRM_SAVE_EQUIPMENT_SET = "¿Quieres guardar el conjunto de equipamiento \"%s\"?";
+DEBUFF_SYMBOL_CURSE = "Mal";
+DEBUFF_SYMBOL_DISEASE = "En";
+DEBUFF_SYMBOL_MAGIC = "Mag";
+DEBUFF_SYMBOL_POISON = "Ve";
+DEBUG_FRAMESTACK = "Trama de pila";
+EQUIPMENT_MANAGER = "Gestor de equipamiento";
+EQUIPMENT_MANAGER_IGNORE_SLOT = "Ignorar esta casilla";
+EQUIPMENT_MANAGER_IS_DISABLED = "El Gestor de equipamiento está desactivado.";
+EQUIPMENT_MANAGER_ITEMS_MISSING_TOOLTIP = "%d %s |cffff0000(falta %d)|r";
+EQUIPMENT_MANAGER_PLACE_IN_BAGS = "Colocar en bolsas";
+EQUIPMENT_MANAGER_UNIGNORE_SLOT = "Incluir esta casilla";
+EQUIPMENT_SETS = "Conjuntos de equipamiento: |cFFFFFFFF%s|r";
+EQUIPMENT_SETS_CANT_RENAME = "Ya existe un conjunto de equipamiento con ese nombre.";
+EQUIPMENT_SETS_TOO_MANY = "Ya no puedes crear más equipamientos.";
+EQUIPMENT_SET_ASSIGN_TO_SPEC = "Asignar a especialización:";
+EQUIPMENT_SET_EDIT = "Cambiar nombre/icono";
+EQUIPMENT_SET_SETTINGS = "Config.";
+EQUIPSET_EQUIP = "Equipar";
+ERR_EQUIPMENT_MANAGER_BAGS_FULL = "No se ha podido cambiar el equipamiento. Inventario lleno.";
+ERR_EQUIPMENT_MANAGER_COMBAT_SWAP_S = "Algunos objetos del equipo %s no se cambiarán porque estás en combate.";
+ERR_EQUIPMENT_MANAGER_MISSING_ITEM_S = "Falta uno o más objetos del equipo %s y no se ha podido equipar.";
+CLEAR_FOCUS = "Quitar foco";
+SET_FOCUS = "Establecer foco";
 FOCUSTARGET = "Establecer objetivo";
+GEARSETS_POPUP_TEXT = "Nombra este equipamiento (Máx. 16 carac.):";
 ITEMS_VARIABLE_QUANTITY = "%d |4objeto:objetos;";
 ITEMS_EQUIPPED = "Equipado: %d |4objeto:objetos;";
 ITEMS_IN_INVENTORY = "En inventario: %d |4objeto:objetos;";
@@ -15,6 +41,10 @@ COPPER_AMOUNT_SYMBOL = "c";
 GENERIC_FRACTION_STRING = "%d/%d";
 GOLD_AMOUNT_SYMBOL = "o";
 HOURS_MINUTES_SECONDS = "%.2d:%.2d:%.2d";
+ICON_FILTER_ALL = "Todos los iconos";
+ICON_FILTER_ITEM = "Objetos";
+ICON_FILTER_SPELL = "Hechizos";
+ICON_SELECTION_TITLE_CURRENT = "Selección actual";
 ITEM_DELTA_DESCRIPTION = "Si reemplazas este objeto, se producirán los siguientes cambios en las estadísticas:";
 ITEM_MOD_MANA_SHORT = "Maná";
 ITEM_MOD_HEALTH_SHORT = "Salud";
@@ -42,7 +72,11 @@ ITEM_MOD_BLOCK_VALUE_SHORT = "Valor de bloqueo";
 ITEM_MOD_DAMAGE_PER_SECOND_SHORT = "daño por segundo";
 LARGE_NUMBER_SEPERATOR = "";
 MINUTES_SECONDS = "%.2d:%.2d";
+PAPERDOLL_EQUIPMENTMANAGER = "Gestor de equipamiento";
+PAPERDOLL_NEWEQUIPMENTSET = "Nuevo conjunto";
 PERCENTAGE_STRING = "%d%%";
+SET_FRIENDNOTE_LABEL = "Establecer nota para %s:";
+SET_NOTE = "Establecer nota";
 SILVER_AMOUNT_SYMBOL = "p";
 SLASH_CLEARFOCUS1 = "/quitarenfoque";
 SLASH_CLEARFOCUS2 = "/clearfocus";

AddOns/!!!ClassicAPI/locales/frFR.lua

@@ -2,6 +2,31 @@ if GetLocale() ~= "frFR" then return end
 
 BINDING_NAME_FOCUSTARGET = "Définir cible";
 BINDING_NAME_TARGETFOCUS = "Reprendre cible";
+CONFIRM_DELETE_EQUIPMENT_SET = "Voulez-vous vraiment supprimer l'ensemble d'équipement %s ?";
+CONFIRM_SAVE_EQUIPMENT_SET = "Voulez-vous sauvegarder l'ensemble d'équipement %s ?";
+DEBUFF_SYMBOL_CURSE = "Mn";
+DEBUFF_SYMBOL_DISEASE = "Md";
+DEBUFF_SYMBOL_MAGIC = "Mg";
+DEBUFF_SYMBOL_POISON = "Po";
+DEBUG_FRAMESTACK = "Empilement des cadres";
+EQUIPMENT_MANAGER = "Gestionnaire d'équipement";
+EQUIPMENT_MANAGER_IGNORE_SLOT = "Ignorer cet emplacement";
+EQUIPMENT_MANAGER_IS_DISABLED = "Le Gestionnaire d'équipement est désactivé.";
+EQUIPMENT_MANAGER_ITEMS_MISSING_TOOLTIP = "%d %s |cffff0000(objet manquant : %d)|r";
+EQUIPMENT_MANAGER_PLACE_IN_BAGS = "Mettre en sac";
+EQUIPMENT_MANAGER_UNIGNORE_SLOT = "Inclure cet emplacement";
+EQUIPMENT_SETS = "Ensembles d'équipement : |cFFFFFFFF%s|r";
+EQUIPMENT_SETS_CANT_RENAME = "Un ensemble d'équipement portant ce nom existe déjà.";
+EQUIPMENT_SETS_TOO_MANY = "Vous ne pouvez plus créer de nouveaux ensembles d'équipement.";
+EQUIPMENT_SET_ASSIGN_TO_SPEC = "Assigner à la spécialisation :";
+EQUIPMENT_SET_EDIT = "Modifier le nom/l'icône";
+EQUIPMENT_SET_SETTINGS = "Réglages";
+EQUIPSET_EQUIP = "Equiper";
+ERR_EQUIPMENT_MANAGER_BAGS_FULL = "Échec de l'échange d'équipement. L'inventaire est plein.";
+ERR_EQUIPMENT_MANAGER_COMBAT_SWAP_S = "Certains objets de l'ensemble %s ne peuvent pas être échangés car vous êtes en combat.";
+ERR_EQUIPMENT_MANAGER_MISSING_ITEM_S = "Une ou plusieurs pièces de l'ensemble %s manquaient et n'ont pu être équipées.";
+CLEAR_FOCUS = "Effacer la focalisation";
+SET_FOCUS = "Définir la focalisation";
 FOCUSTARGET = "Définir la cible de focalisation";
 ITEMS_VARIABLE_QUANTITY = "%d |4objet:objets;";
 ITEMS_EQUIPPED = "%d |4objet:objets; équipés";
@@ -12,9 +37,14 @@ ITEMS_NOT_IN_INVENTORY = "%d |4objet:objets; manquants";
 TARGETFOCUS = "Cibler l'unité focalisée";
 -- BINDING_NAME_AOELOOT = "AoE Loot";
 COPPER_AMOUNT_SYMBOL = "c";
+GEARSETS_POPUP_TEXT = "Nom de l'ensemble (16 caractères max.) :";
 GENERIC_FRACTION_STRING = "%d/%d";
 GOLD_AMOUNT_SYMBOL = "o";
 HOURS_MINUTES_SECONDS = "%.2d:%.2d:%.2d";
+ICON_FILTER_ALL = "Toutes les icônes";
+ICON_FILTER_ITEM = "Objets";
+ICON_FILTER_SPELL = "Sorts";
+ICON_SELECTION_TITLE_CURRENT = "Sélection actuelle";
 ITEM_DELTA_DESCRIPTION = "Si vous remplacez cet objet, les caractéristiques suivantes seront modifiées :";
 ITEM_MOD_MANA_SHORT = "Mana";
 ITEM_MOD_HEALTH_SHORT = "Vie";
@@ -42,7 +72,11 @@ ITEM_MOD_BLOCK_VALUE_SHORT = "Valeur de blocage";
 ITEM_MOD_DAMAGE_PER_SECOND_SHORT = "Dégâts par seconde";
 LARGE_NUMBER_SEPERATOR = "";
 MINUTES_SECONDS = "%.2d:%.2d";
+PAPERDOLL_EQUIPMENTMANAGER = "Gestionnaire d'équipement";
+PAPERDOLL_NEWEQUIPMENTSET = "Nouvel ensemble";
 PERCENTAGE_STRING = "%d%%";
+SET_FRIENDNOTE_LABEL = "Écrire une note pour %s :";
+SET_NOTE = "Écrire une note";
 SILVER_AMOUNT_SYMBOL = "a";
 SLASH_CLEARFOCUS1 = "/clearfocus";
 SLASH_CLEARFOCUS2 = "/annulerfocal";

AddOns/!!!ClassicAPI/locales/ruRU.lua

@@ -2,6 +2,31 @@ if GetLocale() ~= "ruRU" then return end
 
 BINDING_NAME_FOCUSTARGET = "Запомненная цель";
 BINDING_NAME_TARGETFOCUS = "Восстановить цель";
+CONFIRM_DELETE_EQUIPMENT_SET = "Вы действительно хотите удалить комплект экипировки \"%s\"?";
+CONFIRM_SAVE_EQUIPMENT_SET = "Хотите сохранить комплект экипировки \"%s\"?";
+DEBUFF_SYMBOL_CURSE = "Пр";
+DEBUFF_SYMBOL_DISEASE = "Бз";
+DEBUFF_SYMBOL_MAGIC = "Мг";
+DEBUFF_SYMBOL_POISON = "Яд";
+DEBUG_FRAMESTACK = "Соединение рамок";
+EQUIPMENT_MANAGER = "Комплекты экипировки";
+EQUIPMENT_MANAGER_IGNORE_SLOT = "Пропустить ячейку";
+EQUIPMENT_MANAGER_IS_DISABLED = "Управление экипировкой отключено.";
+EQUIPMENT_MANAGER_ITEMS_MISSING_TOOLTIP = "%d %s |cffff0000(предмет для ячейки \"%d\" отсутствует)|r";
+EQUIPMENT_MANAGER_PLACE_IN_BAGS = "Поместить в сумку";
+EQUIPMENT_MANAGER_UNIGNORE_SLOT = "Учитывать ячейку";
+EQUIPMENT_SETS = "Комплекты экипировки: |cFFFFFFFF%s|r";
+EQUIPMENT_SETS_CANT_RENAME = "Это название уже используется для другого комплекта.";
+EQUIPMENT_SETS_TOO_MANY = "Вы не можете создавать новые комплекты экипировки.";
+EQUIPMENT_SET_ASSIGN_TO_SPEC = "Выбрать специализацию:";
+EQUIPMENT_SET_EDIT = "Изменить название/значок";
+EQUIPMENT_SET_SETTINGS = "Параметры";
+EQUIPSET_EQUIP = "Надеть";
+ERR_EQUIPMENT_MANAGER_BAGS_FULL = "Не удалось заменить комплект обмундирования. Инвентарь переполнен.";
+ERR_EQUIPMENT_MANAGER_COMBAT_SWAP_S = "Некоторые предметы из набора \"%s\" не будут экипированы, поскольку вы участвуете в бою.";
+ERR_EQUIPMENT_MANAGER_MISSING_ITEM_S = "Недостает одного или более предметов из набора \"%s\".";
+CLEAR_FOCUS = "Отменить запоминание цели";
+SET_FOCUS = "Запомнить цель";
 FOCUSTARGET = "Запомнить цель";
 ITEMS_VARIABLE_QUANTITY = "%d |4предмет:предмета:предметов;";
 ITEMS_EQUIPPED = "%d |4предмет экипирован:предмета экипировано:предметов экипировано;";
@@ -12,9 +37,14 @@ ITEMS_NOT_IN_INVENTORY = "%d |4предмет отсутствует:предм
 TARGETFOCUS = "Восстановить цель";
 -- BINDING_NAME_AOELOOT = "AoE Loot";
 COPPER_AMOUNT_SYMBOL = "м";
+GEARSETS_POPUP_TEXT = "Введите название комплекта (не более 16 символов):";
 GENERIC_FRACTION_STRING = "%d/%d";
 GOLD_AMOUNT_SYMBOL = "з";
 HOURS_MINUTES_SECONDS = "%.2d:%.2d:%.2d";
+ICON_FILTER_ALL = "Все значки";
+ICON_FILTER_ITEM = "Предметы";
+ICON_FILTER_SPELL = "Заклинания";
+ICON_SELECTION_TITLE_CURRENT = "Текущий выбор";
 ITEM_DELTA_DESCRIPTION = "Если вы замените этот предмет, произойдут следующие изменения:";
 ITEM_MOD_MANA_SHORT = "к мане";
 ITEM_MOD_HEALTH_SHORT = "к здоровью";
@@ -42,7 +72,11 @@ ITEM_MOD_BLOCK_VALUE_SHORT = "к показателю блокирования";
 ITEM_MOD_DAMAGE_PER_SECOND_SHORT = "к урону в секунду";
 LARGE_NUMBER_SEPERATOR = "";
 MINUTES_SECONDS = "%.2d:%.2d";
+PAPERDOLL_EQUIPMENTMANAGER = "Комплекты экипировки";
+PAPERDOLL_NEWEQUIPMENTSET = "Новый комплект";
 PERCENTAGE_STRING = "%d%%";
+SET_FRIENDNOTE_LABEL = "Заметка о |3-5(%s):";
+SET_NOTE = "Добавить заметку";
 SILVER_AMOUNT_SYMBOL = "с";
 SLASH_CLEARFOCUS1 = "/clearfocus";
 SLASH_CLEARFOCUS2 = "/сбросфокуса";

AddOns/!!!ClassicAPI/locales/zhCN.lua

@@ -2,6 +2,31 @@ if GetLocale() ~= "zhCN" then return end
 
 BINDING_NAME_FOCUSTARGET = "焦点目标";
 BINDING_NAME_TARGETFOCUS = "目标焦点";
+CONFIRM_DELETE_EQUIPMENT_SET = "你确认要删除装备方案%s吗？";
+CONFIRM_SAVE_EQUIPMENT_SET = "你想要保存装备方案\"%s\"吗？";
+DEBUFF_SYMBOL_CURSE = "诅";
+DEBUFF_SYMBOL_DISEASE = "疾";
+DEBUFF_SYMBOL_MAGIC = "魔";
+DEBUFF_SYMBOL_POISON = "毒";
+DEBUG_FRAMESTACK = "框架栈";
+EQUIPMENT_MANAGER = "装备管理";
+EQUIPMENT_MANAGER_IGNORE_SLOT = "忽略此栏位";
+EQUIPMENT_MANAGER_IS_DISABLED = "装备管理已禁用。";
+EQUIPMENT_MANAGER_ITEMS_MISSING_TOOLTIP = "%d %s |cffff0000（缺少%d）|r";
+EQUIPMENT_MANAGER_PLACE_IN_BAGS = "放入背包";
+EQUIPMENT_MANAGER_UNIGNORE_SLOT = "包括此栏位";
+EQUIPMENT_SETS = "装备配置方案：|cFFFFFFFF%s|r";
+EQUIPMENT_SETS_CANT_RENAME = "一个重名的装备方案已经存在。";
+EQUIPMENT_SETS_TOO_MANY = "你不能再创建新的装备方案了。";
+EQUIPMENT_SET_ASSIGN_TO_SPEC = "指定专精：";
+EQUIPMENT_SET_EDIT = "修改名称/图标";
+EQUIPMENT_SET_SETTINGS = "设置";
+EQUIPSET_EQUIP = "装备";
+ERR_EQUIPMENT_MANAGER_BAGS_FULL = "装备更换失败。背包已满。";
+ERR_EQUIPMENT_MANAGER_COMBAT_SWAP_S = "装备方案%s中的某些物品不能在战斗中切换。";
+ERR_EQUIPMENT_MANAGER_MISSING_ITEM_S = "未找到套装方案%s中的一件或多件物品，无法装备。";
+CLEAR_FOCUS = "清除焦点";
+SET_FOCUS = "设置焦点";
 FOCUSTARGET = "设定焦点目标";
 ITEMS_VARIABLE_QUANTITY = "%d件物品";
 ITEMS_EQUIPPED = "已装备%d件物品";
@@ -12,9 +37,14 @@ ITEMS_NOT_IN_INVENTORY = "缺少%d件物品";
 TARGETFOCUS = "选中焦点目标";
 -- BINDING_NAME_AOELOOT = "AoE Loot";
 COPPER_AMOUNT_SYMBOL = "铜";
+GEARSETS_POPUP_TEXT = "输入方案名称（最多16个字符）：";
 GENERIC_FRACTION_STRING = "%d/%d";
 GOLD_AMOUNT_SYMBOL = "金";
 HOURS_MINUTES_SECONDS = "%.2d:%.2d:%.2d";
+ICON_FILTER_ALL = "所有图标";
+ICON_FILTER_ITEM = "物品";
+ICON_FILTER_SPELL = "法术";
+ICON_SELECTION_TITLE_CURRENT = "当前已选择";
 ITEM_DELTA_DESCRIPTION = "如果你替换该物品，将会产生以下的属性变更：";
 ITEM_MOD_MANA_SHORT = "法力值";
 ITEM_MOD_HEALTH_SHORT = "生命值";
@@ -42,7 +72,11 @@ ITEM_MOD_BLOCK_VALUE_SHORT = "格挡值";
 ITEM_MOD_DAMAGE_PER_SECOND_SHORT = "每秒伤害";
 LARGE_NUMBER_SEPERATOR = ",";
 MINUTES_SECONDS = "%.2d：%.2d";
+PAPERDOLL_EQUIPMENTMANAGER = "装备管理";
+PAPERDOLL_NEWEQUIPMENTSET = "新的方案";
 PERCENTAGE_STRING = "%d%%";
+SET_FRIENDNOTE_LABEL = "为%s设置备注：";
+SET_NOTE = "设置备注";
 SILVER_AMOUNT_SYMBOL = "银";
 SLASH_CLEARFOCUS1 = "/clearfocus";
 SLASH_CLEARFOCUS2 = "/clearfocus";

AddOns/!!!ClassicAPI/locales/zhTW.lua

@@ -2,6 +2,31 @@ if GetLocale() ~= "zhTW" then return end
 
 BINDING_NAME_FOCUSTARGET = "鎖定目標";
 BINDING_NAME_TARGETFOCUS = "選定鎖定目標";
+CONFIRM_DELETE_EQUIPMENT_SET = "你確定要刪除裝備設定：%s嗎？";
+CONFIRM_SAVE_EQUIPMENT_SET = "你想要儲存裝備設定「%s」嗎？";
+DEBUFF_SYMBOL_CURSE = "咒";
+DEBUFF_SYMBOL_DISEASE = "疾";
+DEBUFF_SYMBOL_MAGIC = "魔";
+DEBUFF_SYMBOL_POISON = "毒";
+DEBUG_FRAMESTACK = "框架堆疊";
+EQUIPMENT_MANAGER = "裝備管理員";
+EQUIPMENT_MANAGER_IGNORE_SLOT = "忽略此欄位";
+EQUIPMENT_MANAGER_IS_DISABLED = "裝備管理員已關閉。";
+EQUIPMENT_MANAGER_ITEMS_MISSING_TOOLTIP = "%d件%s|cffff0000(缺少%d件)|r";
+EQUIPMENT_MANAGER_PLACE_IN_BAGS = "放進背包";
+EQUIPMENT_MANAGER_UNIGNORE_SLOT = "包含此欄位";
+EQUIPMENT_SETS = "裝備設定：|cFFFFFFFF%s|r";
+EQUIPMENT_SETS_CANT_RENAME = "您所選擇的名稱已經有裝備設定使用了。";
+EQUIPMENT_SETS_TOO_MANY = "你無法製造更多的新裝備設定。";
+EQUIPMENT_SET_ASSIGN_TO_SPEC = "指定專精：";
+EQUIPMENT_SET_EDIT = "改變名稱/圖示";
+EQUIPMENT_SET_SETTINGS = "設定";
+EQUIPSET_EQUIP = "裝備";
+ERR_EQUIPMENT_MANAGER_BAGS_FULL = "裝備切換失敗。物品欄已滿。";
+ERR_EQUIPMENT_MANAGER_COMBAT_SWAP_S = "%s設定中的某些物品必須等到你脫離戰鬥後才能更換。";
+ERR_EQUIPMENT_MANAGER_MISSING_ITEM_S = "%s設定中的一個或多個物品未尋獲，因此無法裝備。";
+CLEAR_FOCUS = "清除專注目標";
+SET_FOCUS = "設定專注目標";
 FOCUSTARGET = "設定鎖定目標";
 ITEMS_VARIABLE_QUANTITY = "%d件物品";
 ITEMS_EQUIPPED = "裝備%d件物品";
@@ -12,9 +37,14 @@ ITEMS_NOT_IN_INVENTORY = "缺少%d件物品";
 TARGETFOCUS = "選定鎖定單位";
 -- BINDING_NAME_AOELOOT = "AoE Loot";
 COPPER_AMOUNT_SYMBOL = "銅";
+GEARSETS_POPUP_TEXT = "輸入設定名稱(最多16個字元)：";
 GENERIC_FRACTION_STRING = "%d/%d";
 GOLD_AMOUNT_SYMBOL = "金";
 HOURS_MINUTES_SECONDS = "%.2d:%.2d:%.2d";
+ICON_FILTER_ALL = "所有圖示";
+ICON_FILTER_ITEM = "物品";
+ICON_FILTER_SPELL = "法術";
+ICON_SELECTION_TITLE_CURRENT = "目前選擇";
 ITEM_DELTA_DESCRIPTION = "若你更換此裝備，下列屬性將會改變：";
 ITEM_MOD_MANA_SHORT = "法力";
 ITEM_MOD_HEALTH_SHORT = "生命力";
@@ -42,7 +72,11 @@ ITEM_MOD_BLOCK_VALUE_SHORT = "格擋值";
 ITEM_MOD_DAMAGE_PER_SECOND_SHORT = "每秒傷害";
 LARGE_NUMBER_SEPERATOR = ",";
 MINUTES_SECONDS = "%.2d:%.2d";
+PAPERDOLL_EQUIPMENTMANAGER = "裝備管理員";
+PAPERDOLL_NEWEQUIPMENTSET = "新設定";
 PERCENTAGE_STRING = "%d%%";
+SET_FRIENDNOTE_LABEL = "設定%s的註記：";
+SET_NOTE = "設定註記";
 SILVER_AMOUNT_SYMBOL = "銀";
 SLASH_CLEARFOCUS1 = "/clearfocus";
 SLASH_CLEARFOCUS2 = "/清除專注目標";

AddOns/DebugTools/DebugTools.lua

@@ -155,25 +155,6 @@ _initFrame:SetScript("OnEvent", function()
     end
 end);
 
--- Vanilla has no Frame:IsMouseOver(); do it ourselves from cursor + bounds.
-local function DebugTools_IsMouseOver(frame)
-    if (not frame) then return false; end
-    local visOK, visible = pcall(frame.IsVisible, frame);
-    if (not visOK or not visible) then return false; end
-    local sOK, scale = pcall(frame.GetEffectiveScale, frame);
-    if (not sOK or not scale or scale == 0) then return false; end
-    local cx, cy = GetCursorPosition();
-    cx = cx / scale;
-    cy = cy / scale;
-    local lOK, left   = pcall(frame.GetLeft,   frame);
-    local rOK, right  = pcall(frame.GetRight,  frame);
-    local tOK, top    = pcall(frame.GetTop,    frame);
-    local bOK, bottom = pcall(frame.GetBottom, frame);
-    if (not (lOK and rOK and tOK and bOK)) then return false; end
-    if (not (left and right and top and bottom)) then return false; end
-    return cx >= left and cx <= right and cy >= bottom and cy <= top;
-end
-
 local _EventTraceFrame;
 
 _framesSinceLast = 0;
@@ -566,7 +547,7 @@ function EventTraceFrame_Update()
                         button:GetHighlightTexture():SetVertexColor(.8, .8, 1, .15);
                         button:UnlockHighlight();
                     end
-                    if (DebugTools_IsMouseOver(button)) then
+                    if MouseIsOver(button) then
                         EventTraceFrameEvent_OnEnter(button);
                     end
                 end
@@ -1016,8 +997,8 @@ local function _CollectFramesUnderMouse(showHidden)
     local frame = EnumerateFrames(nil);
     while (frame) do
         local visOK, visible = pcall(frame.IsVisible, frame);
-        local mouseOver = DebugTools_IsMouseOver(frame);
-        if (mouseOver and (showHidden or (visOK and visible))) then
+        local overOK, mouseOver = pcall(frame.IsMouseOver, frame);
+        if (overOK and mouseOver and (showHidden or (visOK and visible))) then
             local nameOK, name = pcall(frame.GetName, frame);
             if (not nameOK or not name) then name = "<anonymous>"; end
             table.insert(matches, { name = name, frame = frame });
@@ -1037,7 +1018,7 @@ end
 
 local function _UpdateFrameStackTooltip(tooltip, showHidden)
     tooltip:ClearLines();
-    tooltip:AddLine("Frame Stack", 1, 1, 1);
+    tooltip:AddLine(DEBUG_FRAMESTACK or "Frame Stack", 1, 1, 1);
     local matches = _CollectFramesUnderMouse(showHidden);
     local count = table.getn(matches);
     if (count == 0) then

AddOns/DebugTools/DebugTools.xml

@@ -456,14 +456,11 @@
                         </Anchor>
                     </Anchors>
                 </FontString>
-                <!-- Breadcrumb showing the active navigation path,
-                     e.g. "_G > MyFrame > backdrop". Updated each
-                     `TableInspectorFrame_Update` tick. -->
                 <FontString name="$parentBreadcrumb" inherits="GameFontHighlightSmall" justifyH="LEFT">
-                    <Size x="380" y="16"/>
+                    <Size x="300" y="16"/>
                     <Anchors>
                         <Anchor point="TOPLEFT">
-                            <Offset x="80" y="-34"/>
+                            <Offset x="156" y="-34"/>
                         </Anchor>
                     </Anchors>
                 </FontString>
@@ -510,6 +507,17 @@
                     <OnClick>TableInspector_Back();</OnClick>
                 </Scripts>
             </Button>
+            <Button name="$parentRefreshButton" inherits="UIPanelButtonTemplate" text="Refresh">
+                <Size x="70" y="20"/>
+                <Anchors>
+                    <Anchor point="LEFT" relativeTo="$parentBackButton" relativePoint="RIGHT">
+                        <Offset x="4" y="0"/>
+                    </Anchor>
+                </Anchors>
+                <Scripts>
+                    <OnClick>TableInspector_Refresh();</OnClick>
+                </Scripts>
+            </Button>
             <Slider name="$parentScroll" orientation="VERTICAL">
                 <Size x="16" y="0"/>
                 <Anchors>

AddOns/DebugTools/TableInspector.lua

@@ -20,6 +20,7 @@
 --   TableInspector_Show(tbl, label)   -- open with `tbl` as root, `label` shown in breadcrumb
 --   TableInspector_Push(tbl, label)   -- drill in (called by row click)
 --   TableInspector_Back()             -- pop one level
+--   TableInspector_Refresh()          -- re-read the current level's live table (scroll kept)
 --   TableInspector_Close()            -- hide the window
 --   /tinspect <luaexpr>               -- evaluate `<luaexpr>` as Lua and open if result is a table
 ------------------------------------------------------------------------------
@@ -184,6 +185,13 @@ function TableInspector_Back()
     TableInspectorFrame_Update();
 end
 
+function TableInspector_Refresh()
+    local top = _navStack[table.getn(_navStack)];
+    if (not top or type(top.tbl) ~= "table") then return; end
+    _RebuildEntries();
+    TableInspectorFrame_Update();
+end
+
 function TableInspector_Close()
     if (_TableInspectorFrame) then _TableInspectorFrame:Hide(); end
     _navStack = {};

CMakeLists.txt

@@ -25,6 +25,39 @@ set(TINYCBOR_SOURCES
     external/tinycbor/src/cborparser_float.c
     external/tinycbor/src/cborerrorstrings.c)
 
+# Version derivation. Dev builds use a sentinel "newer than every
+# plausible release" so addon-side `CLASSIC_API_VERSION >= X` gates
+# always pass locally. CI release builds pass `-DCLASSICAPI_TAG=vX.Y.Z`,
+# which drives BOTH the compiled `CLASSIC_API_VERSION` int AND the
+# embedded addon's `## Version:` toc line (substituted in
+# embed_addon.cmake). The on-disk source toc stays `## Version: DEV`;
+# only the embedded copy is stamped, so a release build needs nothing
+# but the flag — no source edit.
+set(CLASSICAPI_VERSION_VALUE 99999999)
+set(CLASSICAPI_VER_MAJOR 9999)
+set(CLASSICAPI_VER_MINOR 99)
+set(CLASSICAPI_VER_PATCH 99)
+set(CLASSICAPI_TOC_VERSION "DEV")
+
+set(CLASSICAPI_TAG
+    ""
+    CACHE STRING "Release tag like v1.2.3")
+
+if(CLASSICAPI_TAG MATCHES "^v([0-9]+)\\.([0-9]+)\\.([0-9]+)$")
+  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
+       "${CLASSICAPI_VER_MAJOR} * 10000 + ${CLASSICAPI_VER_MINOR} * 100 + ${CLASSICAPI_VER_PATCH}")
+  set(CLASSICAPI_TOC_VERSION
+      "${CLASSICAPI_VER_MAJOR}.${CLASSICAPI_VER_MINOR}.${CLASSICAPI_VER_PATCH}")
+elseif(CLASSICAPI_TAG)
+  message(
+    FATAL_ERROR
+      "Invalid CLASSICAPI_TAG: ${CLASSICAPI_TAG} (expected vMAJOR.MINOR.PATCH)"
+  )
+endif()
+
 # Bundle `AddOns/!!!ClassicAPI/` into a generated header so the DLL can
 # surface the addon to the engine even when the user doesn't have it
 # installed on disk. The file-read hook in `src/addons/Embedded.cpp`
@@ -34,12 +67,16 @@ set(EMBEDDED_CLASSICAPI_SRC "${CMAKE_CURRENT_SOURCE_DIR}/AddOns/!!!ClassicAPI")
 set(EMBEDDED_CLASSICAPI_HEADER "${CMAKE_BINARY_DIR}/generated/embedded_classicapi.h")
 file(GLOB_RECURSE EMBEDDED_CLASSICAPI_FILES CONFIGURE_DEPENDS
      "${EMBEDDED_CLASSICAPI_SRC}/*")
+# The `.classicapi-dev` marker is a disk-only developer signal — keep it
+# out of the embed inputs (embed_addon.cmake filters it too).
+list(FILTER EMBEDDED_CLASSICAPI_FILES EXCLUDE REGEX "/\\.classicapi-dev$")
 add_custom_command(
     OUTPUT "${EMBEDDED_CLASSICAPI_HEADER}"
     COMMAND ${CMAKE_COMMAND}
         -DSRC_DIR=${EMBEDDED_CLASSICAPI_SRC}
         -DOUT_HEADER=${EMBEDDED_CLASSICAPI_HEADER}
         -DADDON_NAME=ClassicAPI
+        -DADDON_VERSION=${CLASSICAPI_TOC_VERSION}
         -P "${CMAKE_CURRENT_SOURCE_DIR}/cmake/embed_addon.cmake"
     DEPENDS
         ${EMBEDDED_CLASSICAPI_FILES}
@@ -71,33 +108,6 @@ add_library(${PROJECT_NAME} SHARED
     ${EMBEDDED_CLASSICAPI_HEADER}
     ${EMBEDDED_BINDINGS_HEADER})
 
-# Dev-build sentinel — represents "newer than every plausible
-# release". Encoded as v9999.99.99 = 9999 * 10000 + 99 * 100 + 99 =
-# 99,999,999. Picked so addon-side feature gates of the form
-# `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(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
-       "${CLASSICAPI_VER_MAJOR} * 10000 + ${CLASSICAPI_VER_MINOR} * 100 + ${CLASSICAPI_VER_PATCH}")
-elseif(CLASSICAPI_TAG)
-  message(
-    FATAL_ERROR
-      "Invalid CLASSICAPI_TAG: ${CLASSICAPI_TAG} (expected vMAJOR.MINOR.PATCH)"
-  )
-endif()
-
 target_compile_definitions(
   ${PROJECT_NAME}
   PRIVATE CLASSICAPI_VERSION_VALUE=${CLASSICAPI_VERSION_VALUE})
@@ -134,5 +144,10 @@ set_target_properties(${PROJECT_NAME} PROPERTIES OUTPUT_NAME "ClassicAPI")
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /MT")
 set(CMAKE_CXX_FLAGS_RELEASE "/MT /O2 /Ob2 /DNDEBUG")
 set(CMAKE_SHARED_LINKER_FLAGS
-    "/OPT:REF /OPT:ICF /MERGE:.rdata=.text /MERGE:.pdata=.text /SECTION:.text,EWR /NODEFAULTLIB:MSVCRT"
+    # /MAP emits build/Release/ClassicAPI.map — a linker-only output (no effect
+    # on code layout) that maps `0001:offset` addresses from WoW's ERROR #132
+    # crash dumps back to functions. Published as a build/release artifact so
+    # any crash from a shipped DLL can be triaged exactly. (/OPT:ICF folds
+    # identical functions, so a few map symbols share an address — harmless.)
+    "/OPT:REF /OPT:ICF /MERGE:.rdata=.text /MERGE:.pdata=.text /SECTION:.text,EWR /NODEFAULTLIB:MSVCRT /MAP"
 )

README.md

@@ -35,20 +35,21 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | [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` |
+| [Frame](docs/API.md#frame) | `region:SetPoint("point")` (one-arg form), `region:SetSize`, `region:GetSize`, `region:IsMouseOver`, `region:GetRect`, `region:IsDragging`, `GetMouseFoci`, `frame:SetShown`, `frame:SetResizeBounds`, `frame:HookScript`, `frame:IsEventRegistered`, `frame:GetEffectiveAlpha`, `frame:SetAttribute`, `frame:SetAttributeNoHandler`, `frame:ClearAttribute`, `frame:GetAttribute`, `OnAttributeChanged` (script), `SetModernScriptArgs`, `GetModernScriptArgs` |
+| [FriendList](docs/API.md#friendlist) | `C_FriendList.GetFriendInfo`, `C_FriendList.GetFriendInfoByIndex`, `C_FriendList.GetNumFriends`, `C_FriendList.GetNumOnlineFriends`, `C_FriendList.GetNumWhoResults`, `C_FriendList.GetWhoInfo`, `C_FriendList.IsFriend`, `C_FriendList.IsIgnored`, `C_FriendList.IsIgnoredByGuid`, `C_FriendList.IsWhoQueryPending`, `C_FriendList.SendWhoQueryByName`, `C_FriendList.SetFriendNotes`, `C_FriendList.SetFriendNotesByIndex` |
 | [GameObject](docs/API.md#gameobject) | `C_GameObjectInfo.GetGameObjectInfoByID`, `C_GameObjectInfo.RequestLoadGameObjectByID`, `ClosestGameObjectPosition` |
+| [Glue](docs/API.md#glue) | `C_Glue.IsOnGlueScreen` |
 | [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: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.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` |
+| [Loot](docs/API.md#loot) | `C_Loot.GetNearbyLootableUnits`, `C_Loot.GetLastScanResults`, `C_Loot.IsScanInProgress`, `C_Loot.LootAllCorpses`, `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` |
+| [Macros](docs/API.md#macros) | `C_Macro.CreateMacro`, `C_Macro.EditMacro`, `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` |
 | [MapExplorationInfo](docs/API.md#mapexplorationinfo) | `C_MapExplorationInfo.GetExploredMapTextures`, `C_MapExplorationInfo.GetUnexploredMapTextures` |
@@ -58,19 +59,19 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | [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.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` |
+| [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.GetSpellDispelType`, `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.IsNextMeleeSpell`, `C_Spell.IsRangedAutoAttackSpell`, `C_Spell.IsSelfBuff`, `C_Spell.IsSpellHarmful`, `C_Spell.IsSpellHelpful`, `C_Spell.IsSpellInRange`, `C_Spell.IsSpellPassive`, `C_Spell.IsSpellUsable`, `C_Spell.ResetsMeleeSwing`, `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` |
+| [State](docs/API.md#state) | `CancelShapeshiftForm`, `Dismount`, `GetMirrorTimerInfo`, `GetMirrorTimerProgress`, `GetShapeshiftFormID`, `IsAssistingRitual`, `IsFalling`, `IsIndoors`, `IsInGroup`, `IsInRaid`, `IsLoggedIn`, `IsMounted`, `IsOutdoors`, `IsStealthed`, `IsSwimming` |
 | [System](docs/API.md#system) | `CopyToClipboard`, `GetPhysicalScreenSize` |
 | [Talent](docs/API.md#talent) | `GetTalentIDByIndex`, `GetTalentSpellID` |
 | [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` |
+| [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`, `GetTimeCached` |
 | [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) | `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` |
+| [Unit](docs/API.md#unit) | `ClosestUnitPosition`, `GetUnitSpeed`, `UnitClassBase`, `UnitCreatureFamilyID`, `UnitCreatureTypeID`, `UnitDistanceSquared`, `UnitGUID`, `UnitHealthMissing`, `UnitInLineOfSight`, `UnitInRange`, `UnitIsAFK`, `UnitIsDND`, `UnitIsFeignDeath`, `UnitIsInMyGuild`, `UnitIsMinion`, `UnitIsOtherPlayersPet`, `UnitIsPet`, `UnitIsPossessed`, `UnitOwnerGUID`, `UnitPosition`, `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.RegisterAuraDurationModifierByTrigger`, `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` |
 
@@ -90,6 +91,7 @@ the glue state because GlueXML had no way to reach them otherwise.
 | [Account](docs/API.md#account) | `SaveAccount`, `DeleteAccount`, `GetSavedAccounts`, `LoginWithSavedAccount` (passwords encrypted in Windows Credential Manager, scoped per realmlist; plaintext never returned to Lua) |
 | [CharacterList](docs/API.md#characterlist) | `GetSavedCharacterOrder`, `SetSavedCharacterOrder` (persist to `WTF\Account\...\ClassicAPI.txt`) |
 | CVar | `GetCVar`, `SetCVar`, `RegisterCVar`, `GetCVarDefault`, `C_CVar.GetCVarBool` (storage is process-global — writes from glue are visible in-world and vice versa) |
+| [Glue](docs/API.md#glue) | `C_Glue.IsFirstLoadThisSession`, `C_Glue.IsOnGlueScreen` |
 | Script | `RunScript` (compile and run a Lua chunk in the glue state's globals — useful for slash-command-style helpers in GlueXML) |
 | State | `IsLoggedIn` |
 
@@ -153,6 +155,19 @@ when launching with `-console`), not as Lua functions. See the
 | `QUEST_DATA_LOAD_RESULT` | `questID, success` |
 | `QUEST_REMOVED` | `questID` |
 | `QUEST_TURNED_IN` | `questID, xpReward, moneyReward` |
+| `UNIT_SPELLCAST_SENT` | `"player", target, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_START` | `unit, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_STOP` | `unit, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_DELAYED` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_SUCCEEDED` | `unit, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_INTERRUPTED` | `unit, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_FAILED` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_FAILED_QUIET` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_CHANNEL_START` | `unit, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_CHANNEL_UPDATE` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_CHANNEL_STOP` | `unit, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_RETICLE_TARGET` | `"player", "", spellID, spellName, rank` |
+| `UNIT_SPELLCAST_RETICLE_CLEAR` | `"player", "", spellID, spellName, rank` |
 | `UPDATE_INVENTORY_DURABILITY` | *(none)* |
 | `UPDATE_SHAPESHIFT_FORM` | *(none)* |
 | `VOICE_CHAT_TTS_PLAYBACK_STARTED` | `numConsumers, utteranceID, durationMS, destination` |
@@ -180,6 +195,7 @@ when launching with `-console`), not as Lua functions. See the
 |-------|-------------|
 | `nameplate1`..`nameplateN` | Unit behind the Nth visible nameplate, in creation-order. Works with every `UnitX` function — `UnitName`, `UnitGUID`, `UnitClass`, `UnitHealth`, etc. Suffix chains (`nameplate1target`, `nameplate1targettarget`) compose. See [NamePlate / Unit tokens](docs/API.md#unit-tokens-nameplaten). |
 | `focus` / `focustarget` | Sticky target set via [`FocusUnit`](docs/API.md#focusunitunit), cleared via [`ClearFocus`](docs/API.md#clearfocus). Same `UnitX` coverage as `nameplateN`. Fires [`PLAYER_FOCUS_CHANGED`](docs/API.md#player_focus_changed-event) on transition. See [Focus](docs/API.md#focus). |
+| `mark1`..`mark8` | Unit currently wearing the Nth raid-target marker (`mark1` = star … `mark8` = skull). Same `UnitX` coverage as `nameplateN`, and fires unit events (`UNIT_HEALTH`, `UNIT_AURA`, …) with `arg1 == "markN"`. `UnitExists("markN")` is `false` when the marker is unset, out of range, or on a non-unit. Suffix chains (`mark1target`) compose. See [Unit tokens (`markN`)](docs/API.md#unit-tokens-markn). |
 
 ### Bindings
 
@@ -223,36 +239,38 @@ The Lua-side companion library lives in
 [`AddOns/!!!ClassicAPI/`](AddOns/!!!ClassicAPI/). It's a 1.12.1 /
 Lua 5.0 backport of the modern Blizzard helpers that aren't engine
 functions but that consumer code still expects to find as globals —
-`Mixin` / `CreateFromMixins`, `CallbackRegistryMixin`, `EventRegistry`,
-`ColorMixin` + `CreateColor`, `Item` / `ItemLocation`, `MathUtil`
-(`Lerp` / `Clamp` / `CreateCounter`), `TableUtil` (`tCompare`,
-`MergeTable`, `SafePack`, etc.), and `EventUtil`
+`CallbackRegistryMixin`, `EventRegistry`, `ColorMixin` + `CreateColor`,
+`Item` / `ItemLocation`, `MathUtil`(`Lerp` / `Clamp` / `CreateCounter`),
+`TableUtil` (`tCompare`, `MergeTable`, `SafePack`, etc.), and `EventUtil`
 (`ContinueOnAddOnLoaded` etc.).
 
-Some of the addon's surface depends on engine functions ClassicAPI
-provides (`C_UIColor.GetColors` populates the modern color globals,
-`C_Item.GetItemInfoInstant` powers `ItemMixin`, the
-`ITEM_DATA_LOAD_RESULT` event drives `ContinueOnItemLoad`); the rest
-is pure Lua and would work standalone. Without the DLL the addon
-still loads, but those features no-op.
-
-The triple-`!` prefix is **load-order-significant** — WoW loads
-addons alphabetically, so `!!!ClassicAPI` is guaranteed to run before
-any consumer that depends on its globals. Don't rename the folder.
-
 **You don't have to install the addon manually** — the DLL embeds
 the contents of [`AddOns/!!!ClassicAPI/`](AddOns/!!!ClassicAPI/) and
 registers them with the engine as a synthetic addon on startup, so
-the library is always available when the DLL is loaded. The engine
-sees it as a normal addon: it appears in `GetAddOnInfo`, fires
-`ADDON_LOADED`, supports `SavedVariables`, the works.
+the library is always available when the DLL is loaded. It fires
+`ADDON_LOADED`, supports `SavedVariables`, and is resolvable by name —
+`IsAddOnLoaded("!!!ClassicAPI")`, `GetAddOnInfo("!!!ClassicAPI")`, and
+`## Dependencies: !!!ClassicAPI` all work as usual.
 
-If you do drop the folder into your `Interface/AddOns/` directory,
-**that copy wins** — the DLL's embedded version is only registered
-when the engine's normal scan doesn't already have an entry under
-that name. Useful for editing the Lua locally without rebuilding the
-DLL. The dispatch is transparent: addons consuming `Mixin`,
-`ColorMixin`, `TableUtil`, etc. behave identically in both cases.
+**It is intentionally always-on and cannot be disabled.** The library
+provides FrameXML-compat fixes that other addons and the DLL's own
+features rely on, so leaving it toggleable would let a user (or a
+one-off character-select uncheck) silently break them. The DLL
+therefore hides it from the character-select AddOns list and
+force-enables it every login — so it never appears as a checkbox and
+can't be switched off. Being hidden means it's omitted from the
+index-based `GetNumAddOns()` / `GetAddOnInfo(i)` enumeration, but every
+by-name lookup and dependency reference still resolves normally.
+
+If you drop the folder into your `Interface/AddOns/` directory, **that
+copy's files win** — the DLL's embedded version only serves files when
+the engine's normal scan doesn't already have a newer entry under that
+name. Useful for editing the Lua locally without rebuilding the DLL.
+The hidden + force-enabled treatment applies either way (it's keyed to
+the addon name, not to which copy serves the files), so the local copy
+is also absent from the AddOns list. The dispatch is transparent:
+addons consuming `Mixin`, `ColorMixin`, `TableUtil`, etc. behave
+identically in both cases.
 
 ## Bundled addon: DebugTools
 

cmake/embed_addon.cmake

@@ -34,6 +34,10 @@ if(NOT ADDON_NAME)
 endif()
 
 file(GLOB_RECURSE INPUT_FILES RELATIVE "${SRC_DIR}" "${SRC_DIR}/*")
+# Never embed the developer marker — it must reflect on-disk presence
+# only (see src/addons/Embedded.cpp DiskHasDevMarker), and it is
+# gitignored so it only exists in a developer working tree anyway.
+list(FILTER INPUT_FILES EXCLUDE REGEX "(^|/)\\.classicapi-dev$")
 list(SORT INPUT_FILES) # deterministic codegen
 
 set(BODY "")
@@ -41,7 +45,26 @@ set(MANIFEST "")
 set(INDEX 0)
 foreach(REL_PATH ${INPUT_FILES})
     set(ABS_PATH "${SRC_DIR}/${REL_PATH}")
-    file(READ "${ABS_PATH}" CONTENT_HEX HEX)
+
+    # Stamp the addon's `## Version:` line from the build flag rather
+    # than the committed source (which stays `DEV`). This is what makes
+    # a release build a pure function of `-DCLASSICAPI_TAG` — the source
+    # toc is never edited. Only the `.toc` file is rewritten, in-memory,
+    # before hex-encoding; every other file is embedded verbatim.
+    if(ADDON_VERSION AND REL_PATH MATCHES "\\.toc$")
+        file(READ "${ABS_PATH}" TOC_TEXT)
+        string(REGEX REPLACE "## Version:[^\n\r]*"
+               "## Version: ${ADDON_VERSION}" TOC_TEXT "${TOC_TEXT}")
+        # Round-trip through a temp file to hex-encode the modified text
+        # (portable to CMake 3.10; avoids requiring string(HEX), 3.18+).
+        set(TOC_TMP "${OUT_HEADER}.toc.tmp")
+        file(WRITE "${TOC_TMP}" "${TOC_TEXT}")
+        file(READ "${TOC_TMP}" CONTENT_HEX HEX)
+        file(REMOVE "${TOC_TMP}")
+    else()
+        file(READ "${ABS_PATH}" CONTENT_HEX HEX)
+    endif()
+
     string(LENGTH "${CONTENT_HEX}" HEX_LEN)
     math(EXPR FILE_SIZE "${HEX_LEN} / 2")
 

docs/Events.md

@@ -435,6 +435,17 @@ and other DLLs claim for custom events.
 
 ## Notes on specific entries
 
+- **`[336] UPDATE_MOUSEOVER_UNIT` now fires on loss too (ClassicAPI).**
+  Stock 1.12 fires this only when a mouseover unit is *gained*; moving
+  the cursor off a unit clears the mouseover and signals nothing.
+  ClassicAPI co-hooks the engine's mouseover set/clear chokepoint
+  (`0x00492890`, the sole writer of the mouseover GUID) and fires
+  `UPDATE_MOUSEOVER_UNIT` on the unit→non-unit transition, matching
+  retail. Gated on the *old* mouseover being a unit and the *new* one
+  not, so moving off a gameobject / item (which never fired a gain)
+  doesn't spuriously fire. No payload either way — handlers read
+  `UnitExists("mouseover")`, false at fire time on loss. See
+  [API.md](API.md#update_mouseover_unit-event-loss-fire-fix).
 - **Repeated `UNIT_*` entries at low indices** (e.g. four slots named
   `UNIT_DAMAGE` at 128–131, five `UNIT_STATS` at 144–148, seven
   `UNIT_RESISTANCES` at 149–155) — these are the per-stat /

src/Game.cpp

@@ -185,6 +185,33 @@ void SetGlobalNumber(void *L, const char *name, double value) {
     RawSet(L, GLOBALS_INDEX);
 }
 
+bool PushGlobalFunction(void *L, const char *name) {
+    PushString(L, name);
+    GetTable(L, GLOBALS_INDEX);
+    if (Type(L, -1) == TYPE_FUNCTION)
+        return true;
+    SetTop(L, -2); // pop the non-function
+    return false;
+}
+
+void CallGlobal(void *L, const char *name) {
+    const int top = GetTop(L);
+    if (PushGlobalFunction(L, name))
+        Call(L, 0, 0);
+    SetTop(L, top);
+}
+
+bool CallGlobalString(void *L, const char *name, const char *arg) {
+    const int top = GetTop(L);
+    const bool called = PushGlobalFunction(L, name);
+    if (called) {
+        PushString(L, arg);
+        Call(L, 1, 0);
+    }
+    SetTop(L, top);
+    return called;
+}
+
 void PushLocalizedString(void *L, const char *globalName, const char *fallback) {
     PushString(L, globalName);
     GetTable(L, GLOBALS_INDEX);

src/Game.h

@@ -244,6 +244,22 @@ void PushLocalizedString(void *L, const char *globalName, const char *fallback);
 // using `PushLocalizedString` + manual `string.format` invocation.
 void PushLocalizedFormatInt(void *L, const char *globalName,
                             const char *fallback, int n);
+
+// Pushes `_G[name]` and returns true only if it resolved to a function
+// (leaving it on the stack, ready to be called); otherwise pops it and
+// returns false. The building block for the CallGlobal* helpers below and for
+// any C module that dispatches to a Lua/FrameXML global by name (a pattern
+// several modules otherwise open-code).
+bool PushGlobalFunction(void *L, const char *name);
+
+// `_G[name]()` — no args, no results; a no-op if the global isn't a function.
+// Stack-neutral.
+void CallGlobal(void *L, const char *name);
+
+// `_G[name](arg)` — one string arg (NULL → nil), no results. Returns true iff
+// the global was a function and got called, so callers can fall back to a
+// native path when the FrameXML/addon global is absent. Stack-neutral.
+bool CallGlobalString(void *L, const char *name, const char *arg);
 } // namespace Lua
 
 // Developer-console command system — the `~` console available when the

src/Offsets.h

@@ -140,6 +140,51 @@ enum Offsets {
     //   and call the inner invoker, which is self-contained.
     FUN_GAMETOOLTIP_SCRIPT_RESOLVER = 0x005295D0,
     FUN_FRAME_INVOKE_SCRIPT = 0x00704D50,
+    // The arg-passing sibling of FUN_FRAME_INVOKE_SCRIPT — every frame
+    // script that carries values (OnClick(button), OnMouseWheel(delta),
+    // OnUpdate(elapsed), OnValueChanged(value), OnKeyDown(key), OnEvent's
+    // args, …) funnels through here. __cdecl(int handlerRef, void *frame,
+    // const char *fmt, void *vaPtr): fmt is a printf-style spec string
+    // (`%d`/`%u`/`%f`/`%s`), vaPtr points at the packed vararg buffer
+    // (4-byte stride for d/u/s, 8 for f). It sets the `arg1..argN` globals
+    // from the format (saving/restoring the previous values), sets the
+    // `this` global to `frame`, then runs the handler under a protected
+    // lua_pcall with **zero Lua args** and the engine error handler
+    // (VAR_FRAMESCRIPT_ERROR_HANDLER_REF) as errfunc. FUN_FRAME_INVOKE_SCRIPT
+    // is the same shape for the no-arg scripts (OnShow/OnHide/OnEnter/…).
+    // `Frame::ScriptArgs` co-hooks both to additionally pass the handler
+    // modern positional args (self, arg1..argN). The frame's own Lua object
+    // ref lives at frame+OFF_COBJECT_LUA_REF (refcount at
+    // OFF_COBJECT_LUA_REFCOUNT); FUN_FRAMESCRIPT_OBJECT_SCRIPT_REGISTER
+    // lazily creates it when the refcount is 0.
+    FUN_FRAME_RUN_SCRIPT_ARGS = 0x00704F10,
+    // The base ScriptObject's OnEvent handler slot — an 8-byte
+    // {handler, context} pair at frame+0x0C (from FUN_00702590, the base
+    // resolver every frame-type resolver chains through, and confirmed by
+    // the event dispatchers FUN_00703E50 / FUN_00703F50 passing `frame+0xC`
+    // as the slot). `*(int*)(frame + OFF_FRAME_ONEVENT_SLOT)` is the OnEvent
+    // handler ref; `Frame::ScriptArgs` compares it against the handler ref
+    // the runner is invoking to detect an OnEvent dispatch (exact — each
+    // SetScript makes a distinct ref, so a function bound to two scripts
+    // still differs per slot) and prepend the `event` positional.
+    OFF_FRAME_ONEVENT_SLOT = 0x0C,
+    // Registry ref (an int, not a pointer) to the frame-script message
+    // handler the engine passes as the `errfunc` to every script pcall —
+    // read as `*(int*)VAR_FRAMESCRIPT_ERROR_HANDLER_REF`, pushed via
+    // lua_rawgeti(REGISTRY, ref). Set once at engine init.
+    VAR_FRAMESCRIPT_ERROR_HANDLER_REF = 0x008722C8,
+    // The base Frame script-name resolver — __thiscall(frame, const char *name)
+    // -> int* slot, 0 for an unknown name. Maps the standard base-frame scripts
+    // to their 8-byte {handler, context} slots on the frame (OnLoad@+0x118,
+    // OnUpdate@+0x128, OnEnter@+0x140, … OnKeyUp@+0x190) after delegating to the
+    // ScriptObject base FUN_00702590 (OnEvent@+0xC). Every frame TYPE's resolver
+    // chains through this (the tooltip resolver above calls it first), so
+    // co-hooking it here lets `Frame::Attributes` make `OnAttributeChanged`
+    // SetScript/GetScript/HookScript-able on ALL frames — for that one name the
+    // co-hook hands back an external per-frame cell (frames are immortal in 1.12,
+    // so a pointer-keyed cell never goes stale). Same pattern + ABI modeling as
+    // FUN_GAMETOOLTIP_SCRIPT_RESOLVER.
+    FUN_FRAME_SCRIPT_RESOLVER = 0x0076A0D0,
     // 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
@@ -153,10 +198,23 @@ enum Offsets {
     //     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
+    //     hover populator; resolves the GO (TYPEMASK_GAMEOBJECT) and writes the
     //     GO field at +0x370.
     FUN_GAMETOOLTIP_BUILD_UNIT = 0x00529FE0,
     FUN_GAMETOOLTIP_BUILD_GAMEOBJECT = 0x0052AA20,
+    // Pointer to the GameTooltip CFrameScriptObject the engine's mouseover
+    // setter builds into (`DAT_00b4b3c4`; the value at this address is the
+    // tooltip object). `Frame::Attributes` reads it to build the unit tooltip
+    // for offline/out-of-range party & raid members, which FUN_00492890 skips.
+    VAR_GAMETOOLTIP_OBJECT_PTR = 0x00B4B3C4,
+    // The tooltip's OnTooltipSetDefaultAnchor handler slot (the `{handler,
+    // context}` pair the script resolver maps that name to). The engine
+    // mouseover setter fires this before building to (re)establish the
+    // tooltip owner/anchor via FrameXML's GameTooltip_SetDefaultAnchor —
+    // without it a rebuild after the tooltip was hidden has no owner and
+    // stays invisible. `Frame::Attributes` fires it (via the self-contained
+    // FUN_FRAME_INVOKE_SCRIPT) before the offline roster build.
+    OFF_TOOLTIP_SET_DEFAULT_ANCHOR_HANDLER = 0x444,
     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
@@ -316,6 +374,16 @@ enum Offsets {
     // C_Item.GetItemName exactly. Inner formatter FUN_005D8B00.
     FUN_ITEM_BUILD_INSTANCE_NAME = 0x005D8BC0,
 
+    // Inner name formatter behind FUN_ITEM_BUILD_INSTANCE_NAME, callable
+    // WITHOUT a CGItem: `__fastcall(char *out /*ecx*/, uint outSize /*edx*/,
+    // uint32 itemID, int suffixID)`. Fetches the ItemStats record for itemID
+    // and, when suffixID is a valid ItemRandomProperties row with a localized
+    // suffix name (record +0x1c + locale*4), formats base + suffix via
+    // ITEM_SUFFIX_TEMPLATE; otherwise the base name. Lets the by-STRING item
+    // paths (GetItemNameByID, C_Item.GetItemInfo) apply an item link's random
+    // suffix without a live item instance.
+    FUN_ITEM_BUILD_NAME_FROM_ID = 0x005D8B00,
+
     // Engine's inventory swap-and-send. Same primitive
     // `Script_EquipCursorItem` (0x00489660) uses after the cursor's
     // source location has been resolved. Sends opcode 0x10D
@@ -401,6 +469,12 @@ enum Offsets {
     // probe — equivalent to checking `this+0x08 > 0` but more direct.
     OFF_COBJECT_LUA_REFCOUNT = 0x04,
 
+    // `this+0x08` — the CObject's Lua-registry ref (an int key into the
+    // registry table). `lua_rawgeti(REGISTRY, this[+0x08])` pushes the
+    // frame's Lua-side object. Lazily populated by ScriptRegister when the
+    // refcount above is 0.
+    OFF_COBJECT_LUA_REF = 0x08,
+
     // Direct cvar lookup — `__fastcall(const char *name) → CVar* | NULL`.
     // Hash-table by-name lookup over the CVar registry; same call
     // `Script_GetCVar` makes internally before the engine wraps the
@@ -544,6 +618,49 @@ enum Offsets {
     // input it's the right primitive.
     FUN_TOKEN_TO_GUID = 0x00515970,
 
+    // `__fastcall(const uint64_t *guid /*ecx*/, int *outCount /*edx*/) ->
+    // char** tokenArray` — the engine's GUID → unit-token REVERSE map. Fills
+    // a reused static buffer array (the returned pointer) with the name
+    // string of every ENGINE-NATIVE token currently pointing at `guid` and
+    // writes the count to `*outCount`. Checks, in order: player, pet, target,
+    // party1..4, partypet1..4, raid1..40, raidpet1..40, npc, mouseover — the
+    // same slots the per-token unit-event broadcast `FUN_00515e50` fans out
+    // to (that function is just this map + a fire-per-token loop). Does NOT
+    // know ClassicAPI's synthetic `focus` / `nameplateN` tokens (the engine
+    // has no concept of them) — callers add those separately. Non-throwing:
+    // returns count 0 pre-world (resolves the active player internally and
+    // bails if absent). The returned array is a shared static reused on the
+    // next call, so snapshot the strings before doing anything that could
+    // re-enter. nampower names this `GetNamesFromGUID` (left as an unfilled
+    // TODO in its offsets.hpp). Used by `Unit::Identity::TokensForGUID` for
+    // the phase-2 `UNIT_SPELLCAST_*` remote-unit fan-out.
+    FUN_UNIT_TOKENS_FROM_GUID = 0x00515C50,
+
+    // Mouseover-unit GUID globals — the `"mouseover"` token resolves to
+    // these (see the token-dispatch list above). Written ONLY by
+    // `FUN_SET_MOUSEOVER_UNIT`; zero when nothing is moused over. Used by
+    // `Unit::Mouseover` to detect the loss transition.
+    VAR_MOUSEOVER_GUID_LO = 0x00B4E2C8,
+    VAR_MOUSEOVER_GUID_HI = 0x00B4E2CC,
+
+    // The engine's single mouseover set/clear chokepoint —
+    // `__stdcall(guidLo, guidHi, arg3, arg4)` (early returns are all
+    // `ret 0x10`, and the caller pushes 4 without cleaning). It is the
+    // ONLY writer of `VAR_MOUSEOVER_GUID_*`, so every mouseover
+    // gain/loss/change flows through it. On a unit gain it fires
+    // `UPDATE_MOUSEOVER_UNIT` itself (via `FUN_FIRE_EVENT_NO_ARGS(0x150)`
+    // in the friendly/hostile-unit tooltip case); on loss it clears the
+    // GUID but fires nothing — the gap `Unit::Mouseover` closes.
+    // Change-gated by its callers (if it ran per-frame the gain fire
+    // would spam every frame while hovering, which vanilla doesn't), so
+    // it's a cool hook target.
+    FUN_SET_MOUSEOVER_UNIT = 0x00492890,
+
+    // Event ID of `UPDATE_MOUSEOVER_UNIT` (name-table slot
+    // `0x00BE16D8` → `(0x16D8 - 0x1198) / 4`). Fired with no args via
+    // `FUN_FIRE_EVENT_NO_ARGS`; Lua handlers read `UnitExists("mouseover")`.
+    EVENT_UPDATE_MOUSEOVER_UNIT = 0x150,
+
     // `SStrCmpI(a, b, n)` — Storm's case-insensitive memcmp-style
     // comparator. **`int __stdcall(const char *a, const char *b, int n)`**
     // — the function ends with `ret 0xc`, so the callee pops the
@@ -952,6 +1069,10 @@ enum Offsets {
     // derive `dispelName` from `Spell.dbc[+0x10]` (see
     // `OFF_SPELL_DISPEL_TYPE` below), not from the flags nibble.
     OFF_UNIT_FIELD_AURA = 0xA4,                // u32 spell ID per slot, 48 slots total
+    // UNIT_AURA event id for FUN_UNIT_EVENT_BROADCAST. The per-token unit
+    // events use field-index == event-id; the aura field is index 0x29
+    // (OFF_UNIT_FIELD_AURA 0xA4 >> 2), per Unit::TokenObserver's watched set.
+    UNIT_EVENT_UNIT_AURA = 0x29,
     OFF_UNIT_FIELD_AURAFLAGS = 0x164,          // 4 bits per aura, 2 per byte, covers all 48
     OFF_UNIT_FIELD_AURALEVELS = 0x17C,         // u8 caster level per aura, 48 bytes
     OFF_UNIT_FIELD_AURAAPPLICATIONS = 0x1AC,   // u8 (stacks-1) per aura, display value = byte+1
@@ -1181,6 +1302,20 @@ enum Offsets {
     // collision, per-channel-start frequency).
     FUN_SPELL_CHANNEL_START = 0x006E7550,
 
+    // `MSG_CHANNEL_UPDATE` handler (`FUN_006e75f0`) — same `int __stdcall(
+    // uint32_t *opCode, CDataStore *packet)` shape. Body: a single u32 =
+    // the channel's new REMAINING time (ms). Sent to the caster on damage
+    // pushback (which shortens a vanilla channel) and once more at the
+    // channel's end (remaining == 0). Verified at 0x006e75f0: reads the u32,
+    // then fires vanilla's `SPELLCAST_CHANNEL_UPDATE(remaining)` (event
+    // 0x157) on pushback or `SPELLCAST_CHANNEL_STOP` (0x158) at end — but
+    // stores the new end NOWHERE, so `Spell::Cast`'s g_channel.endMs
+    // (computed once at start) never reflects pushback. Co-hooked to
+    // re-anchor endMs (and fire UNIT_SPELLCAST_CHANNEL_UPDATE). nampower
+    // hooks it too (SpellChannelUpdateHandlerHook — accepted co-hook, per-
+    // pushback frequency, same as the START sibling).
+    FUN_SPELL_CHANNEL_UPDATE = 0x006E75F0,
+
     // `SMSG_SPELL_FAILED_OTHER` handler — `int __stdcall(uint32_t *opCode,
     // CDataStore *packet)`, same shape as FUN_SPELL_DELAYED. Body:
     // `casterGuid(u64, plain), spellId(u32)`. In (v)mangos cores this is
@@ -1210,6 +1345,21 @@ enum Offsets {
     // hook it.
     FUN_SPELL_FAILURE = 0x006E8D80,
 
+    // `Spell_C_SpellFailed` — the CLIENT-side cast-failure entry, distinct
+    // from the two SMSG_SPELL_FAILURE/_OTHER packet handlers above. Fires
+    // for the local player's own cast rejections (out of range, no mana,
+    // "spell not ready", LoS, interrupted, …). `__fastcall(uint32_t
+    // spellId, uint8_t spellResult /*edx*/, int unk1, int unk2, bool
+    // failedByServer)` — signature per nampower's Spell_C_SpellFailedT.
+    // Backs `UNIT_SPELLCAST_FAILED` (`Spell::CastEvents`). Not hooked
+    // elsewhere in this project (we hook the packet handlers, not this).
+    FUN_SPELL_C_SPELL_FAILED = 0x006E1A00,
+
+    // `Spell_C_SpellFailed` result code for a fake/suppressed failure
+    // (Unleashed Potential and similar) — the engine's SPELL_FAILED_DONT_
+    // REPORT. nampower filters it out of its failure event; so do we.
+    SPELL_FAILED_DONT_REPORT = 23,
+
     // `CGUnit_C::ClearCastingSpell` — `__thiscall void(CGUnit *unit,
     // int spellID, char notify, char cleanup)` (nampower names the offset
     // but never hooks it). THE engine choke point for "this unit stopped
@@ -1243,9 +1393,29 @@ enum Offsets {
     // funnels through here (the raw-ingress sibling at 0x00537B10 only
     // special-cases 0x1DD compressed-moves before queueing into this).
     // Useful as a temporary whole-protocol sniff point: co-hook, peek the
-    // u16 at the cursor, restore, log.
+    // u16 at the cursor, restore, log. `Net::PacketDispatch` co-hooks it as
+    // the single fan-out point for incoming-packet subscribers — the
+    // collision-avoiding alternative to each feature MinHook-ing its
+    // per-opcode SMSG handler (which nampower/SuperWoW also hook). nampower
+    // does NOT hook this funnel (it detours the per-opcode handlers), so
+    // moving our parsing here removes those shared prologues.
     FUN_NET_MESSAGE_DISPATCH = 0x00537AA0,
 
+    // Incoming spell-subsystem SMSG opcodes — the u16 message ids the engine
+    // dispatch table (see FUN_006e7150) maps to per-opcode handlers. Used by
+    // the `Net::PacketDispatch` subscribers that replaced the per-handler
+    // co-hooks. Verified from the registrar: 0x131/0x132 both route to
+    // FUN_006E7640 (it branches on the opcode; the 0x132 path decodes and
+    // calls the SpellGo builder FUN_006E7A70).
+    SMSG_SPELL_START = 0x131,
+    SMSG_SPELL_GO = 0x132,
+    SMSG_SPELL_FAILURE = 0x133,
+    SMSG_SPELL_COOLDOWN = 0x134,
+    SMSG_SPELL_CHANNEL_START = 0x139,
+    SMSG_SPELL_CHANNEL_UPDATE = 0x13A,
+    SMSG_SPELL_DELAYED = 0x1E2,
+    SMSG_SPELL_FAILED_OTHER = 0x2A6,
+
     // NetClient send — `__thiscall void(void *conn, CDataStore *packet)`.
     // The outgoing counterpart of FUN_NET_MESSAGE_DISPATCH: every CMSG the
     // client sends funnels through it (the argless wrapper `FUN_005AB630`,
@@ -1314,12 +1484,75 @@ enum Offsets {
     FUN_SCRIPT_REGION_SETHEIGHT = 0x007A2150,
     FUN_SCRIPT_REGION_GETWIDTH = 0x007A1E00,
     FUN_SCRIPT_REGION_GETHEIGHT = 0x007A2030,
+    // Region rect getters (return a number, or nil when the region has no
+    // resolved rect). All on the REGION base registry → callable on any
+    // region type. Used by Frame::Modern's IsMouseOver.
+    FUN_SCRIPT_REGION_GETLEFT = 0x007A1980,
+    FUN_SCRIPT_REGION_GETRIGHT = 0x007A1AA0,
+    FUN_SCRIPT_REGION_GETTOP = 0x007A1BC0,
+    FUN_SCRIPT_REGION_GETBOTTOM = 0x007A1CE0,
+    // In-game GetCursorPosition (0x0046DAD0 is the glue-state copy). Pushes
+    // (x, y) in the same k = FUN_0041ad70()*DAT_007ffd68 space the region
+    // rect getters use — so dividing by the region's effective scale puts
+    // the cursor in the region's logical coordinate space.
+    FUN_SCRIPT_GETCURSORPOSITION = 0x0048B820,
+    // Region effective-scale field: `piVar[0x1f]` (float) read by both
+    // GetEffectiveScale (0x00774FC0) and internally by GetLeft/Top/etc. —
+    // present on every region object, so it's the all-region way to get the
+    // effective scale without the Frame-only GetEffectiveScale method.
+    OFF_REGION_EFFECTIVE_SCALE = 0x7C,
+
+    // Global UI/screen context pointer (every frame's +0xA0 field mirrors
+    // it; GetCursorPosition reads the cursor from *ptr + 0x1118). Its
+    // +0xCFC slot holds the frame currently being moved/sized via
+    // StartMoving/StartSizing (0 when idle) — the drag target. Backs
+    // Frame::Modern's IsDragging: StopMovingOrSizing (0x00776990) gates its
+    // clear on `*(context+0xCFC) == self`, i.e. the IsDragging predicate.
+    VAR_UI_CONTEXT_PTR = 0x00CF0BD8,
+    OFF_UI_CONTEXT_DRAG_TARGET = 0xCFC,
+    // Frame currently under the mouse (the CFrameScriptObject* that
+    // `GetMouseFocus` returns): `*(*VAR_UI_CONTEXT_PTR + 0x7C)`. 0 when the
+    // cursor is over no mouse-enabled frame. `Frame::Attributes` polls this to
+    // drive the `mouseover` override from the hovered frame's `unit` attribute.
+    OFF_UI_CONTEXT_MOUSE_FOCUS = 0x7C,
+    // Head of the engine's frame list (`*(*VAR_UI_CONTEXT_PTR + 0xCC4)`),
+    // and each frame CObject's next-in-enumeration pointer at +0x308 — the
+    // list `Script_EnumerateFrames` (0x00705F60) walks. A node with its low
+    // bit set (or null) is the end sentinel. `Frame::MouseFoci` walks it to
+    // build the GetMouseFoci stack.
+    OFF_UI_CONTEXT_FRAME_LIST_HEAD = 0xCC4,
+    OFF_FRAME_ENUM_NEXT = 0x308,
+    // Frame level, a plain int at CObject +0xC4 (the value `Script_GetFrameLevel`
+    // at 0x007744A0 pushes as `frame[0x31]`). Read directly for stack ordering.
+    OFF_FRAME_LEVEL = 0xC4,
     FUN_SCRIPT_FRAME_SHOW = 0x00775750,
     FUN_SCRIPT_FRAME_HIDE = 0x00775810,
     FUN_SCRIPT_FRAME_SETMINRESIZE = 0x00776020,
     FUN_SCRIPT_FRAME_SETMAXRESIZE = 0x007762A0,
     FUN_SCRIPT_FRAME_GETSCRIPT = 0x00774780,
     FUN_SCRIPT_FRAME_SETSCRIPT = 0x007748D0,
+    // `frame:EnableMouse(enable)` (Frame registry) — `Frame::Attributes` calls
+    // it so a unit-attributed frame registers as the mouse-focus (bare frames
+    // otherwise never hover). Standard `int __fastcall(void *L)` Script_* shape.
+    FUN_SCRIPT_FRAME_ENABLEMOUSE = 0x00777070,
+    // Frame predicates used by `Frame::MouseFoci` to filter the enumeration to
+    // the interactive stack (visible + mouse-enabled). Standard Script_* shape
+    // `int __fastcall(void *L)`, self at Lua idx 1, result pushed at idx 2.
+    FUN_SCRIPT_FRAME_IS_VISIBLE = 0x007758D0,
+    FUN_SCRIPT_FRAME_IS_MOUSE_ENABLED = 0x00777130,
+    // `frame:GetFrameStrata()` — pushes the strata name string; ranked for
+    // stack ordering (`Frame::MouseFoci`).
+    FUN_SCRIPT_FRAME_GET_STRATA = 0x007742A0,
+    // Button OnClick dispatcher — `__thiscall(button, buttonCode)` at
+    // 0x00779540, invoking the button's OnClick slot `[button+0x4CC]`. NOTE: do
+    // NOT MinHook it — SuperWoW's click-casting inline-hooks the same prologue
+    // and a second hook corrupts the trampoline (ERROR #132). `Frame::Attributes`
+    // instead installs a normal chained OnClick on the opted-in frame. Kept as
+    // the verified dispatch reference only.
+    // Frame GetAlpha (own alpha, 0..1) + Region GetParent — walked by
+    // Frame::Modern's GetEffectiveAlpha up the parent chain.
+    FUN_SCRIPT_FRAME_GETALPHA = 0x00774DC0,
+    FUN_SCRIPT_REGION_GETPARENT = 0x007A1460,
     FUN_SCRIPT_TEXTURE_SHOW = 0x0079B770,
     FUN_SCRIPT_TEXTURE_HIDE = 0x0079B830,
     FUN_SCRIPT_FONTSTRING_SHOW = 0x0079CDB0,
@@ -1666,7 +1899,7 @@ enum Offsets {
     // gated on the bank-open globals). Returns the CGContainer GUID of the bag
     // equipped in that slot, or 0 if none. This is the internal PackBagSlot
     // uses to resolve bags 1..4: get the bag GUID here, resolve the container
-    // via FUN_OBJECT_RESOLVE_BY_GUID(OBJ_TYPE_CONTAINER, guid), then call the
+    // via FUN_OBJECT_RESOLVE_BY_GUID(TYPEMASK_CONTAINER, guid), then call the
     // container's vtable[+OFF_CONTAINER_GET_INVENTORY] to get the inventory
     // object GetItemBySlot indexes. Lets us enumerate bag contents in pure C++
     // without PackBagSlot's Lua-stack coupling. (Reads GUID arrays at
@@ -1722,16 +1955,14 @@ enum Offsets {
     //
     // Type values: 2 = item (returns CGItem*), 4 = container/bag
     // (returns CGContainer*). Engine passes `"ItemMgr"` as debugName
-    // and `0x172` as priority for both call sites we've decoded.
+    // and `0x172` as priority for both call sites we've decoded. Some engine
+    // sites type it as `(u32 typeMask, void *unused, u64 guid, int)` —
+    // ABI-equivalent (the u64 occupies the same two stack dwords as
+    // guidLo/guidHi). All our callers go through `Object::ByGuid`
+    // (object/Resolve.h), which wraps this single address.
     FUN_OBJECT_RESOLVE_BY_GUID = 0x00468460,
-    // The type arg is a bitmask of object-type bits, not an enum
-    // index — `1<<1` for items, `1<<2` for containers, `1<<3` for
-    // units, matching what `FUN_00529FE0` passes for SetUnit (`ECX=8`).
-    OBJ_TYPE_ITEM = 2,
-    OBJ_TYPE_CONTAINER = 4,
-    OBJ_TYPE_UNIT = 8,
-    OBJ_TYPE_PLAYER = 0x10, // what the engine's bag observer FUN_004F8DB0 passes
-    OBJ_TYPE_GAMEOBJECT = 0x20, // 1<<5; passed by FUN_0052AA20 (hover-tooltip populator).
+    // The type arg is a bitmask of object-type bits (see the TYPEMASK_*
+    // block below), not an enum index.
 
     // `CGObject::GetName` — returns the display-name `const char *` for
     // a resolved CGObject (CGUnit / CGPlayer / CGCreature). Internally
@@ -2443,6 +2674,10 @@ enum Offsets {
     VAR_AREATABLE_RECORDS = 0x00C0E048,
     VAR_AREATABLE_COUNT = 0x00C0E04C,
     OFF_AREATABLE_NAMES = 0x2C,
+    // Parent AreaTable id @ +0x08 — a sub-area's enclosing zone (e.g. Goldshire
+    // → Elwynn Forest). GetFriendInfo resolves it to name the zone, not the
+    // sub-area. 0 for a top-level zone.
+    OFF_AREATABLE_PARENT_ID = 0x08,
     // AreaBit @ +0x0C: index into the player's explored-areas bitfield
     // (OFF_PLAYER_EXPLORED_BITS). Gate @ +0x28: when < 0 the area needs no
     // exploration (always counts explored); when >= 0 the AreaBit check
@@ -2613,15 +2848,11 @@ enum Offsets {
     // each callback invocation, guidLo/guidHi pushed as 8 stack bytes.
     FUN_CLNT_OBJ_MGR_ENUM_VISIBLE_OBJECTS = 0x00468380,
 
-    // GUID → CGObject resolver. __fastcall with this signature:
-    //   CGObject *(__fastcall *)(uint32_t typeMask, void *unused,
-    //                            uint64_t guid, int unused2);
-    // typeMask filters to specific object types; returns NULL if the
-    // GUID isn't loaded or its type doesn't match the mask.
-    FUN_CLNT_OBJ_MGR_OBJECT_PTR = 0x00468460,
-
-    // Type-mask flags accepted by FUN_CLNT_OBJ_MGR_OBJECT_PTR. Single-bit
-    // flags can be OR'd together.
+    // Type-mask flags accepted by FUN_OBJECT_RESOLVE_BY_GUID (and the SetUnit
+    // path FUN_00529FE0, which passes ECX=8 for UNIT). A bitmask of
+    // object-type bits, not an enum index — single-bit flags OR together.
+    // PLAYER (0x10) is what the bag observer FUN_004F8DB0 passes; GAMEOBJECT
+    // (0x20) what the hover-tooltip populator FUN_0052AA20 passes.
     TYPEMASK_OBJECT        = 0x01,
     TYPEMASK_ITEM          = 0x02,
     TYPEMASK_CONTAINER     = 0x04,
@@ -2866,11 +3097,16 @@ enum Offsets {
     VAR_FACTION_COLLAPSED_BITMASK = 0x0084A0A4,
     MAX_FACTION_HEADERS = 32,
 
-    // Who-query (the /who system).
+    // The social singleton (0x00C28168) — one object shared by the friend
+    // list, ignore list, and /who system. Layout: friend entries inline from
+    // offset 0 (stride 0x20, up to 50; each is {connected@+0x00, name char*
+    // @+0x04, GUID u64 @+0x08, level@+0x10, area@+0x14, class@+0x18}), the
+    // 25-entry ignore-GUID table at +0x650, and the who-query state. Read by
+    // GetNumFriends/GetFriendInfo, GetNumIgnores, and Script_SendWho.
     //
     // `Script_SendWho` (0x005AD3B0) is a 32-byte wrapper:
     //   - validate arg1 is a string via lua_isstring
-    //   - load WhoSystem singleton from `[VAR_WHO_SYSTEM]`
+    //   - load the singleton from `[VAR_SOCIAL_SYSTEM]`
     //   - if non-NULL, lua_tostring(L, 1) for the query string
     //   - tail-call `FUN_WHO_SYSTEM_SEND_QUERY` with
     //     `__thiscall(this = WhoSystem, queryStr)`
@@ -2891,9 +3127,13 @@ enum Offsets {
     // Server-side cooldown for CMSG_WHO is ~5 seconds — a faster
     // client gets silent-dropped, so any client-side gating just
     // matches that.
-    VAR_WHO_SYSTEM = 0x00C28168,
+    VAR_SOCIAL_SYSTEM = 0x00C28168,
     VAR_WHO_TO_UI_FLAG = 0x00C2A12C,
     FUN_WHO_SYSTEM_SEND_QUERY = 0x005AEBB0,
+    // Friend count: `__fastcall(socialSingleton) -> uint` — walks the inline
+    // entries and returns the number of populated friend slots. Backs
+    // GetNumFriends and C_FriendList.IsFriend.
+    FUN_FRIEND_LIST_COUNT = 0x005AE490,
 
     // SMSG_WHO opcode handler — opcode 0x63 (99) per the registration
     // in `FUN_005adc50`: `FUN_005ab650(99, FUN_005adf60, 0)`. Reads
@@ -2907,6 +3147,25 @@ enum Offsets {
     // user actually wanted both.
     FUN_SMSG_WHO_RESPONSE = 0x005ADF60,
 
+    // /who result list — the buffer `Script_GetWhoInfo` (0x005AD6E0) and
+    // `Script_GetNumWhoResults` (0x005AD690) read. An array of fixed-size
+    // entries at `VAR_WHO_RESULTS`, stride `WHO_RESULT_STRIDE`; the field
+    // offsets below are all relative to an entry. `name`/`guildName` are
+    // inline C strings; `race`/`class` index ChrRaces/ChrClasses.dbc and
+    // `zone` indexes AreaTable.dbc (own name, not parent-resolved).
+    // `VAR_WHO_RESULT_COUNT` is the displayed count (the first of the two
+    // values GetNumWhoResults returns; the second, total matches, is at +4).
+    // Verified by decompiling both accessors.
+    VAR_WHO_RESULTS = 0x00C281B8,
+    VAR_WHO_RESULT_COUNT = 0x00C2A120,
+    WHO_RESULT_STRIDE = 0xA0,
+    OFF_WHO_NAME = 0x00,   // char[] inline
+    OFF_WHO_GUILD = 0x30,  // char[] inline
+    OFF_WHO_LEVEL = 0x90,  // i32
+    OFF_WHO_RACE = 0x94,   // i32 → ChrRaces.dbc
+    OFF_WHO_CLASS = 0x98,  // i32 → ChrClasses.dbc
+    OFF_WHO_ZONE = 0x9C,   // i32 → AreaTable.dbc
+
     // Per-faction current standing — `__fastcall(ecx = factionID) → int`.
     // Returns `base + delta` where the two values are stored at
     // `+0x08` / `+0x0C` of the player's rep slot (slot stride 0x10,
@@ -3209,6 +3468,54 @@ enum Offsets {
     // without re-parsing the body. See `Macro::Spell::Script_GetMacroSpell`.
     FUN_MACRO_SLOT_TO_ENTRY = 0x004F0E40,
 
+    // Macro create/edit workers — back `C_Macro.CreateMacro` /
+    // `C_Macro.EditMacro` (see [[src/macro/Edit.cpp]]). Both store the
+    // icon as a BARE basename at `entry + OFF_MACRO_ICON` (256 bytes,
+    // no validation); `Script_GetMacroInfo` re-prefixes it as
+    // `Interface\Icons\%s` on read, which is why any texture that lives
+    // under `Interface\Icons\` — including index-less `INV_*` item icons
+    // — round-trips even though vanilla's index-based UI can't pick it.
+    //
+    // Create — `__fastcall(char *name /*ECX*/, char *iconBasename /*EDX,
+    // may be null*/, char *body /*may be null*/, uint local, int
+    // perCharacter) -> uint macroID`. SStrCopys name→`+0x24` (0x40),
+    // icon→`+0x64` (0x100) when non-null, body via `FUN_004f1550`
+    // (`+0x164`), runs the primary-spell parser `FUN_004EFE00`, sets the
+    // dirty flag `DAT_00bdcbf8=1`, and refreshes the UI. Returns 0 on
+    // failure (empty name, or the 18-per-scope list is full). Pass
+    // `local=0` to match the legacy `CreateMacro` default.
+    FUN_MACRO_CREATE = 0x004F1010,
+
+    // Edit — `__fastcall(uint macroID, char *name, char *iconBasename,
+    // char *body, uint flag)`. Hash-finds the entry by macroID (no-op if
+    // absent); each of name/icon/body is written only when its pointer is
+    // non-null (so nil = leave that field unchanged), then reparse + dirty
+    // flag + UI refresh, exactly like the create worker. It ALWAYS writes
+    // `entry + OFF_MACRO_LOCAL_FLAG = flag`, so read the current flag and
+    // pass it back to leave it unchanged. Chosen over replicating the
+    // field writes because it also fires the action-button refresh
+    // (`FUN_004e5cc0`/`FUN_004e5c00`) that direct writes would miss.
+    FUN_MACRO_EDIT = 0x004F1280,
+
+    // macroID → 0-based slot (linear scan of VAR_MACRO_SLOT_MAP);
+    // `0xFFFFFFFF` on miss. `slot = FUN_MACRO_ID_TO_SLOT(macroID) + 1`
+    // is how the legacy `CreateMacro` wrapper turns the worker's return
+    // into the 1-based index it hands back to Lua.
+    FUN_MACRO_ID_TO_SLOT = 0x004F0EC0,
+
+    // Macro name → 0-based slot; `0xFFFFFFFF` on miss (the resolver
+    // behind `GetMacroIndexByName`). Feeding its miss value straight to
+    // `FUN_MACRO_SLOT_TO_ENTRY` yields NULL (bounds-rejected), so the
+    // by-name and by-index EditMacro paths share one validation.
+    FUN_MACRO_NAME_TO_SLOT = 0x004F0FA0,
+
+    // MacroEntry field offsets. Name/body are handled by the workers; the
+    // icon offset is documentation, and the local flag must be read to be
+    // preserved across an EditMacro that doesn't mean to change it.
+    OFF_MACRO_NAME = 0x24,        // char[0x40] inline
+    OFF_MACRO_ICON = 0x64,        // char[0x100] inline bare basename
+    OFF_MACRO_LOCAL_FLAG = 0x20,  // uint32 `local` flag (echoed by GetMacroInfo)
+
     // Macro-icon database. Populated lazily by `FUN_LOAD_MACRO_ICONS`
     // on the first `GetNumMacroIcons` call — enumerates `Interface\Icons\`
     // for `*.blp` files plus a wildcard match, sorts, and de-dupes. Each
@@ -3453,6 +3760,23 @@ enum Offsets {
     // `FUN_006E3D10`. Non-zero means "the cast bar is showing this
     // spell"; cleared to 0 when the cast finishes or is cancelled.
     VAR_CURRENT_CAST_SPELL = 0x00CECA88,
+
+    // Ground/reticle-targeting flags — non-zero while a spell is awaiting a
+    // target click (the AoE reticle / target cursor). `SpellIsTargeting()`
+    // (`0x006E6CD0`) returns true iff this != 0 (via its predicate
+    // `FUN_006E48A0`, `return DAT_00CECAC0 != 0`); `Spell_C_TargetSpell`
+    // (`0x006E5250`) sets the flag bits from the spell's target type, and the
+    // clear helper `FUN_006E4900` (from `SpellStopTargeting`) / a ground
+    // placement zeroes it. Polled by `Spell::CastEvents::PollReticle` to fire
+    // UNIT_SPELLCAST_RETICLE_TARGET / _CLEAR.
+    VAR_SPELL_TARGETING_FLAGS = 0x00CECAC0,
+    // The pending cast spellID — written by `Spell_C_CastSpell` (`0x006E4B60`)
+    // to the spell being cast, and used elsewhere as a `Spell.dbc` index (e.g.
+    // `CancelSpell`'s `records[this]`). While `VAR_SPELL_TARGETING_FLAGS` is
+    // set it's the spell whose reticle is up, so the RETICLE events read the
+    // spellID from here.
+    VAR_PENDING_CAST_SPELL = 0x00CEAC58,
+
     // The cast-start state writer — `__fastcall(int spellID, int
     // targetState)`. Sets `VAR_CURRENT_CAST_SPELL` (pushing any current
     // spell into `VAR_QUEUED_CAST_SPELL`; `spellID == 0` restores the queued
@@ -3760,6 +4084,19 @@ enum Offsets {
     // `Script_IsInInstance`).
     VAR_CURRENT_MAP_ID = 0x00B4E378,
 
+    // "World is live" flag — 1 while the player is fully in the world, 0 during
+    // any loading screen (initial login, zone/instance transition, logout to
+    // glue). Set to 1 by the enter-world init `FUN_004908C0` (guarded
+    // `if (==0){=1;...}`) and back to 0 by the world-teardown `FUN_00490A80`
+    // (`if(!=0){=0;...}`) that runs at the start of every transition. Byte flag.
+    // The clean pollable gate for "can this happen in the world right now" —
+    // e.g. suppressing server resync packets that arrive behind a loading
+    // screen. Verified via the enter/leave pair in Ghidra.
+    //
+    // (NOTE: 0x00B4E37C is NOT this flag — an earlier note wrongly claimed it
+    // was. That address is instance grace-period state, read only by the
+    // "recently left an instance" 90-second check in `FUN_00495c90`.)
+    VAR_IN_WORLD = 0x00B4B424,
 
     // Local player's current AreaTable.dbc area ID (u32 storage; only
     // the low 16 bits are used — the value is broadcast over the wire
@@ -3864,6 +4201,17 @@ enum Offsets {
     VAR_PARTY_MEMBER_GUIDS = 0x00BC6F48,
     VAR_RAID_MEMBER_PTRS = 0x00B712A8,
 
+    // Raid-target-marker GUID table — 8 contiguous `uint64` slots, one
+    // per raid icon (slot 0 = mark1/star … slot 7 = mark8/skull), `0`
+    // when that marker is unassigned. Written by the
+    // `SMSG_RAID_TARGET_UPDATE` handler cluster (`FUN_004ba0b0` /
+    // `FUN_004ba220` / `FUN_004ba550`); the reverse lookup
+    // `FUN_004bb190(guidLo, guidHi)` walks it as `(&table)[i*2]` for
+    // `i` in 0..7 and returns the mark index or 8. `Unit::RaidTarget`
+    // reads it to resolve the `markN` token and to drive the per-mark
+    // unit-event observers. Matches nampower's `CGRaidInfo_m_raidtargets`.
+    VAR_RAID_TARGET_GUIDS = 0x00B71368,
+
     VAR_LOCALE_INDEX = 0x00C0E080,             // 0..8, picks one of the 9 localized strings
 
     LUA_IS_NUMBER = 0x6F34D0,
@@ -3912,6 +4260,15 @@ enum Offsets {
     LUA_NEW_TABLE = 0x6F3C90,
     LUA_GET_TABLE = 0x6F3A40,     // (was 0x6F3EA0, which is lua_rawset)
     LUA_RAW_GET = 0x6F3B00,
+    // `lua_rawgeti(L, idx, n)` — pushes `table_at_idx[n]` without invoking
+    // metamethods. __fastcall(L /*ecx*/, idx /*edx*/, n /*stack*/). The
+    // frame-script runner uses it with `idx = REGISTRY` to push a value
+    // stored under an integer ref (handler, frame object, message handler,
+    // and luaL_ref'd saved globals). Note it also carries the WoW
+    // frame-script exec-context stamp (the `DAT_00ceeac0` dance) for pushed
+    // CObjects — which is exactly why the engine pushes handler/frame
+    // through it rather than a plain rawget.
+    LUA_RAWGETI = 0x6F3BC0,
     LUA_SET_TABLE = 0x6F3E20,
     LUA_RAW_SET = 0x6F3EA0,
     LUA_INSERT = 0x6F31A0,
@@ -4153,6 +4510,14 @@ enum Offsets {
     // No `%b` for boolean — pass `%d` with 0/1; the engine has no native
     // bool concept here. No bounds check on eventID; pass valid indices.
     FUN_FIRE_EVENT = 0x00703F50,
+    // Per-token unit-event broadcast. Fires unit event `eventCode` for every
+    // unit token currently mapping to `*guid` (target / party / raid /
+    // nameplateN / mouseover / focus), via the engine's own GUID->token reverse
+    // map -- the same path the descriptor-field observers drive on a real field
+    // change. `void __fastcall(uint64_t *guid, uint32_t eventCode)`; verified
+    // against nampower's SendUnitSignal (0x00515e50). `eventCode` is the unit
+    // field index, which doubles as the event id (see UNIT_EVENT_UNIT_AURA).
+    FUN_UNIT_EVENT_BROADCAST = 0x00515E50,
     // Event name strings live in `.data` (mostly clustered around
     // 0x00851000..0x00855000); event-name string pointers also reach into
     // `.rdata` (starts at 0x007FF000) for some entries. Bound the dereference
@@ -4570,6 +4935,22 @@ enum Offsets {
     FUN_ADDON_CAN_LOAD = 0x0051E780,
     FUN_ADDON_GET_SECURITY_INDEX = 0x0051E990,
 
+    // Per-character enable-state resolver — the inner check
+    // `FUN_ADDON_CAN_LOAD` (`0x0051E780`) consults to decide whether an
+    // addon is enabled: `__fastcall(const char *name /*ecx*/,
+    // const char *account /*edx*/, char resolveAll /*stack*/) -> uint`.
+    // Returns 0 = disabled (load pass then skips the addon, reason
+    // DISABLED), non-zero = enabled (2 = "enabled for all"). Walks the
+    // per-character override list at `0x00BE1BD8`; with no override it
+    // falls back to the entry's DefaultState byte (`+0x2b`):
+    // `-(uint)(entry[+0x2b] != 0) & 2`. `Addons::Embedded` co-hooks this
+    // to force-enable the embedded `!!!ClassicAPI` unconditionally — so a
+    // stale WTF disable-override (from back when the addon was still
+    // shown in the character-select list) can't leave it hidden AND
+    // unloaded. Cold: runs only during the login/reload load pass, once
+    // per addon.
+    FUN_ADDON_ENABLE_RESOLVE = 0x0051E470,
+
     // Returns a pointer to the inline-stored login account name buffer
     // at `0x00C27D88`, or NULL if no character is logged in yet.
     // `Script_GetAddOnInfo` feeds this into the loadable + enabled
@@ -4674,6 +5055,23 @@ enum Offsets {
     // `castGameObject != 0`).
     OFF_CGPLAYER_CAST_GAMEOBJECT_PTR = 0xB4,
 
+    // Indoor/outdoor query for a unit — backs `IsIndoors()` / `IsOutdoors()`
+    // (`unit/State.cpp`). `__fastcall(unit) -> uint` where **nonzero =
+    // outdoors**, 0 = indoors. A 2-instruction thunk: reads the unit's
+    // world/collision-context pointer at `unit + 0xE0` and tail-jumps to the
+    // WMO query `FUN_006706f0`. That query is fully null-safe — null context
+    // or a unit not inside a WMO group returns 1 (outdoors); otherwise it
+    // resolves the current WMO group via `FUN_0069d4f0` and returns bit 15
+    // (`0x8000`) of the group's runtime flags word (the OUTDOOR bit).
+    //
+    // Derived from SuperWoW 2.2's `IsIndoors` handler (which does exactly
+    // `unit = ObjMgr(0x10, PlayerGUID()); push (query(unit)==0)`), then
+    // confirmed against the vanilla binary. Vanilla ships no Lua binding for
+    // this; the 3.3.5 client's `IsIndoors` (`0x00612300`) uses the identical
+    // shape (`unit + 0xB8` → WMO group flag test), so the semantics are
+    // cross-checked across both clients.
+    FUN_UNIT_IS_OUTDOORS = 0x00612cc0,
+
     // No `MOVEFLAG_FLYING` constant intentionally. Vanilla 1.12
     // doesn't flip a flying bit during taxi flights (verified
     // empirically: `IsFlying()` checking 0x01000000 stayed false
@@ -4793,18 +5191,19 @@ enum Offsets {
     //
     // Single caller (the packet dispatcher's jump table for opcode
     // 0x155) — quiet hook target, no contention with other DLLs.
-    // Hooked by `Player::HearthstoneBound` to fire `HEARTHSTONE_BOUND`
-    // every time the user re-binds at an innkeeper. Gating off the
-    // bind-valid flag's transition distinguishes "initial sync" (the
-    // one we suppress) from "user rebound at an inn" (the one we
-    // fire on — even when the area string stays the same, since the
-    // bind ACTION is what fires the event).
+    // Hooked by `Player::HearthstoneBound` to fire `HEARTHSTONE_BOUND`.
+    // Two packets must be suppressed so the event reflects only a real
+    // innkeeper bind: (1) the initial post-login/char-switch sync
+    // (gated on VAR_BIND_POINT_VALID being 0 before the handler runs),
+    // and (2) Turtle's per-map-transition resync, which re-sends the
+    // packet behind a loading screen — gated on VAR_IN_WORLD (the
+    // player can't bind mid-load). See `Player::HearthstoneBound`.
     FUN_BINDPOINT_UPDATE_HANDLER = 0x005ED3C0,
     // "Bind point is valid" flag. Set to 1 by the BINDPOINTUPDATE
     // handler after the packet has been fully parsed. Zeroed by
     // `FUN_005E2510` (the per-character-entry init routine).
     // Reading this BEFORE the handler runs distinguishes initial
-    // sync (`== 0`) from a real re-bind (`== 1`).
+    // sync (`== 0`) from a later packet (`== 1`).
     VAR_BIND_POINT_VALID = 0x00C4D4E0,
 
     // SMSG_QUESTGIVER_QUEST_COMPLETE handler (opcode 0x191). Server
@@ -5018,6 +5417,20 @@ enum Offsets {
     // delayed crashes on unrelated vtable reads.
     FUN_CMSG_LOOT_ITEM = 0x005E1AD0,
 
+    // `__fastcall(player)` — sends `CMSG_LOOT_MONEY` (the coin/money
+    // request) for the player's currently-open loot window. Vanilla has
+    // no `LootMoney` Lua global; coin is virtual loot slot 0 and the Lua
+    // `LootSlot` handler `FUN_004C2790` routes the coin slot here (its
+    // `param_1 == 0 && VAR_LOOT_LOOTABLE != 0` branch calls this with the
+    // resolved local player). Guards internally on the player's active
+    // loot GUID at `[player + 0x1D28]` — which `FUN_CMSG_LOOT_UNIT` writes
+    // when it sends the loot request — so it silently no-ops if no window
+    // is open. Pass the SAME player pointer used for `FUN_CMSG_LOOT_UNIT`
+    // so the `+0x1D28` guard it just wrote is the one read here.
+    // `Loot::Scan`'s `LootAllCorpses` path uses it to grab coin alongside
+    // the per-slot `CMSG_LOOT_ITEM` sends.
+    FUN_CMSG_LOOT_MONEY = 0x005EA8C0,
+
     // UNIT_DYNAMIC_FLAGS within `m_objectFields`. Standard
     // server-driven dynamic-state bitmask. Empirically verified by
     // cross-referencing three `Script_*` accessors that all read
@@ -5353,6 +5766,7 @@ enum Offsets {
     // ENCHANT_ITEM / _TEMPORARY (enchants), and LEARN_SPELL (Turtle's custom
     // recipes, e.g. "Steel Plate Boots" = effect 36).
     OFF_SPELL_RECORD_EFFECT = 0xF4,                   // int32[3]
+    SPELL_EFFECT_SCHOOL_DAMAGE = 2,                    // direct damage (verified vs server SpellDefines.h)
     SPELL_EFFECT_CREATE_ITEM = 24,
     SPELL_EFFECT_LEARN_SPELL = 36,
     SPELL_EFFECT_ENCHANT_ITEM = 53,
@@ -5384,13 +5798,46 @@ enum Offsets {
     // VAR_SPELLMOD_*). Verified from FUN_006e6b30: SpellFamilyName at
     // +0x280 (gates whether the player's class mods apply), 64-bit
     // SpellFamilyFlags at +0x284 (selects which familyFlagBit rows to
-    // sum). AttributesEx2 (+0x24) bit 0x20000000 disables spell mods.
+    // sum). AttributesEx3 (+0x24) bit 0x20000000 (IGNORE_CASTER_MODIFIERS)
+    // disables spell mods — the client reads [record + 0x24] in FUN_006e6b30.
     OFF_SPELL_RECORD_FAMILY_NAME = 0x280,             // u32
     OFF_SPELL_RECORD_FAMILY_FLAGS = 0x284,            // u64
-    OFF_SPELL_RECORD_ATTRIBUTES = 0x18,               // u32 (base Attributes)
+    OFF_SPELL_RECORD_ICON_ID = 0x1D4,                 // u32 SpellIconID (→ SpellIcon.dbc)
+    OFF_SPELL_RECORD_ATTRIBUTES = 0x18,               // u32 (column 6, 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,
+    OFF_SPELL_RECORD_ATTRIBUTES_EX = 0x1C,            // u32 (column 7)
+    OFF_SPELL_RECORD_ATTRIBUTES_EX2 = 0x20,           // u32 (column 8)
+    OFF_SPELL_RECORD_ATTRIBUTES_EX3 = 0x24,           // u32 (column 9)
+    // The client's spell-mod core (FUN_006e6b30) skips all mods when this bit
+    // is set: it reads [record + 0x24] & 0x20000000 — AttributesEx3 bit 29,
+    // SPELL_ATTR_EX3_IGNORE_CASTER_MODIFIERS (verified via disassembly; the
+    // server enum agrees). NOT AttributesEx2's bit 29 (that's CANT_CRIT).
+    SPELL_ATTR_EX3_IGNORE_CASTER_MODIFIERS = 0x20000000,
+    // AttributesEx channel bits (CHANNELED_1 0x4 | CHANNELED_2 0x40) and the
+    // AttributesEx2 autorepeat flag (bit 5, Auto Shot / Shoot) — each shared
+    // by more than one module, so kept here rather than redefined locally.
+    SPELL_ATTR_EX_CHANNELED = 0x4 | 0x40,
+    SPELL_ATTR_EX2_AUTOREPEAT_FLAG = 0x20,
+    OFF_SPELL_RECORD_INTERRUPT_FLAGS = 0x54,          // u32 (column 21)
+
+    // Remaining Spell.dbc record fields — the single source of truth for the
+    // record layout (byte = column * 4). Modules must use these rather than
+    // redefining local copies.
+    OFF_SPELL_RECORD_CASTING_TIME_INDEX = 0x48,       // u32 → SpellCastTimes.dbc
+    OFF_SPELL_RECORD_MAX_LEVEL = 0x6C,                // u32 (scaling cap level)
+    OFF_SPELL_RECORD_SPELL_LEVEL = 0x74,              // u32 (this rank's effective level)
+    OFF_SPELL_RECORD_POWER_TYPE = 0x7C,               // i32 (0=mana,1=rage,2=focus,3=energy,4=happiness)
+    OFF_SPELL_RECORD_MANA_COST = 0x80,                // u32 base cost
+    OFF_SPELL_RECORD_RANGE_INDEX = 0x90,              // u32 → SpellRange.dbc
+    OFF_SPELL_RECORD_EFFECT_IMPLICIT_TARGET_A = 0x148,// i32[3] implicit target A
+    OFF_SPELL_RECORD_EFFECT_IMPLICIT_TARGET_B = 0x154,// i32[3] implicit target B
+    OFF_SPELL_RECORD_MANA_COST_PERCENT = 0x270,       // i32 % of base resource (0 = flat)
+    OFF_SPELL_RECORD_RANK = 0x204,                    // char*[9] localized rank text
+    OFF_SPELL_RECORD_TOTEM = 0xA0,                    // i32[2] required totem/tool item IDs
+
+    // SpellIcon.dbc record's path string field (char* at +0x04). Distinct
+    // struct from Spell.dbc — reached via SpellIcon.dbc[Spell.SpellIconID].
+    OFF_SPELLICON_PATH = 0x04,
 
     // Spell.dbc Mechanic field — the spell-level SpellMechanic ID (→
     // SpellMechanic.dbc), 0 = none. Field 5 of the record
@@ -5412,6 +5859,10 @@ enum Offsets {
     SPELL_AURA_MOD_CHARM = 6,
     SPELL_AURA_MOD_FEAR = 7,
     SPELL_AURA_MOD_STUN = 12,
+    // Movement slow / snare. Not a loss-of-control (C_LossOfControl omits it),
+    // but the C_UnitAuras CROWD_CONTROL filter counts it — see
+    // Spell::CrowdControl::IsCrowdControl.
+    SPELL_AURA_MOD_DECREASE_SPEED = 33,
     SPELL_AURA_MOD_PACIFY = 25,
     SPELL_AURA_MOD_ROOT = 26,
     SPELL_AURA_MOD_SILENCE = 27,

src/addons/Embedded.cpp

@@ -60,6 +60,13 @@ namespace {
 constexpr const char *kAddonName = "!!!ClassicAPI";
 constexpr const char *kAddonTocFile = "!!!ClassicAPI.toc";
 
+// Developer marker. When this file exists in the on-disk addon folder,
+// the disk copy wins unconditionally (see `DiskHasDevMarker` /
+// `DecideSource`). It is gitignored, excluded from the embed, and the
+// release ships only the DLL — so it can only exist where a developer
+// deliberately created it, never in a normal user's install.
+constexpr const char *kDevMarkerFile = ".classicapi-dev";
+
 // `Interface\AddOns\!!!ClassicAPI\` — the prefix the engine
 // constructs for any of our addon's files. Comparing case-
 // insensitively because the TOC parser uses `Interface\AddOns\%s\…`
@@ -156,17 +163,20 @@ bool ExtractTocVersion(const char *content, size_t size,
     return false;
 }
 
-// Returns -1/0/+1 for `a < b` / `a == b` / `a > b`. "DEV" is a
-// sentinel meaning "newer than any real release" — local dev builds
-// always win against installed-on-disk versions. Otherwise the two
-// strings are walked as dot-separated numeric semver components
+// Returns -1/0/+1 for `a < b` / `a == b` / `a > b`. "DEV" is the
+// local-build sentinel: two DEV builds are equal, but a DEV build sorts
+// BELOW any real release. Dev-over-release precedence is signalled
+// explicitly by the `.classicapi-dev` marker now — NOT by the toc
+// version — so a stray `## Version: DEV` disk copy (repo clone / old
+// bundle) never silently shadows a newer embedded release. Otherwise
+// the two strings are walked as dot-separated numeric semver components
 // (`1.2` < `1.10`).
 int CompareVersions(const char *a, const char *b) {
     const bool aDev = std::strcmp(a, "DEV") == 0;
     const bool bDev = std::strcmp(b, "DEV") == 0;
     if (aDev && bDev) return 0;
-    if (aDev) return 1;
-    if (bDev) return -1;
+    if (aDev) return -1;
+    if (bDev) return 1;
     while (*a || *b) {
         int va = 0, vb = 0;
         while (*a >= '0' && *a <= '9') { va = va * 10 + (*a - '0'); ++a; }
@@ -203,16 +213,48 @@ void EnsureEmbeddedVersionExtracted() {
     }
 }
 
+// True iff the on-disk addon folder contains the `.classicapi-dev`
+// marker. Read via the ORIGINAL `FUN_FILE_READ` (bypassing our embed
+// hook), so it reflects a real file on disk / in an MPQ — never an
+// embedded copy. That makes it a clean "is this a developer working
+// tree" signal: the marker is gitignored + excluded from the embed and
+// the release ships only the DLL, so a normal user's install can't
+// carry it.
+bool DiskHasDevMarker() {
+    char fullPath[256];
+    std::snprintf(fullPath, sizeof(fullPath), "%s%s",
+                  kAddonPathPrefix, kDevMarkerFile);
+    void *buf = nullptr;
+    size_t size = 0;
+    const int ok = FileRead_o(0, fullPath, &buf, &size, 1, 1, 0);
+    if (ok == 0 || buf == nullptr)
+        return false;
+    auto SMemFree = reinterpret_cast<SMemFree_t>(Offsets::FUN_STORM_SMEM_FREE);
+    SMemFree(buf, __FILE__, __LINE__, 0);
+    return true;
+}
+
 // Decide whether disk or embedded should serve all reads for this
 // addon. Called on the first FileRead_h call with a matching prefix.
-// Reads the on-disk TOC via the original `FUN_FILE_READ` (bypassing
-// our hook), parses its version, compares to the embedded version,
-// and caches the winner. If disk has no TOC at all, embedded wins by
-// default.
+// The `.classicapi-dev` marker forces disk unconditionally (explicit
+// developer override). Otherwise reads the on-disk TOC via the original
+// `FUN_FILE_READ` (bypassing our hook), parses its version, compares to
+// the embedded version, and caches the newer. If disk has no TOC at
+// all, embedded wins by default.
 void DecideSource() {
     if (g_source != Source::Undecided) return;
     EnsureEmbeddedVersionExtracted();
 
+    // Explicit developer override: disk wins regardless of version. This
+    // is how a dev keeps disk precedence when running local Lua against a
+    // *released* DLL (where the embedded version would otherwise be newer
+    // and win). Dev intent lives in this marker, decoupled from the toc
+    // version — so users never get silently shadowed by a stray copy.
+    if (DiskHasDevMarker()) {
+        g_source = Source::Disk;
+        return;
+    }
+
     char fullPath[256];
     std::snprintf(fullPath, sizeof(fullPath), "%s%s",
                   kAddonPathPrefix, kAddonTocFile);
@@ -336,7 +378,32 @@ using ListInsert_t = void(__thiscall *)(void *listCtrl, void *entry,
 constexpr uintptr_t VAR_ADDON_LIST_HEAD = 0x00BE1B6C;
 constexpr int OFF_ADDON_ENTRY_NAME_PTR = 0x14;
 
-void MoveEmbeddedToListHead() {
+// `entry+0x29` — the "filter-out" byte. The flat display-array builder
+// `FUN_0051da70` walks the linked list and copies an entry into
+// `GetNumAddOns`/`GetAddOnInfo`'s array ONLY when this byte is 0, so
+// setting it hides `!!!ClassicAPI` from the character-select AddOns
+// list — there's no checkbox, so it can't be toggled off. The builder
+// only ever *writes* this byte on the secure/SMSG path (`entry+0x28 !=
+// 0`); our entry is non-secure, so a manual `1` here is stable across
+// rebuilds. Hiding does NOT stop loading (the load pass `FUN_0051f600`
+// never reads `+0x29`) and does NOT break dependency resolution or
+// by-name queries (those use the addon hash table, which keeps the
+// entry regardless).
+constexpr int OFF_ADDON_ENTRY_FILTER_OUT = 0x29;
+
+// `entry+0x2b` — DefaultState (`## DefaultState: enabled/disabled`).
+// The enable resolver `FUN_ADDON_ENABLE_RESOLVE` falls back to this
+// when the player has no per-character override. Belt-and-suspenders
+// alongside the resolver co-hook below (which forces enabled anyway).
+constexpr int OFF_ADDON_ENTRY_DEFAULT_STATE = 0x2b;
+
+// Post-registration finalize for the embedded entry: move it to the
+// head of the load-order list (so consumers that read our globals from
+// their main chunk see them — see the block comment above the offsets),
+// hide it from the addon list, and mark it default-enabled. Combined
+// with the `FUN_ADDON_ENABLE_RESOLVE` co-hook, `!!!ClassicAPI` always
+// loads and never appears as a toggleable entry.
+void FinalizeEmbeddedEntry() {
     uintptr_t entry = *reinterpret_cast<uintptr_t *>(VAR_ADDON_LIST_HEAD);
     const int linkOffset = *reinterpret_cast<const int *>(
         static_cast<uintptr_t>(Offsets::VAR_ADDON_LIST_CTRL));
@@ -344,6 +411,11 @@ void MoveEmbeddedToListHead() {
         const char *name = *reinterpret_cast<const char *const *>(
             entry + OFF_ADDON_ENTRY_NAME_PTR);
         if (name != nullptr && std::strcmp(name, kAddonName) == 0) {
+            // Hide from the character-select AddOns list and default it
+            // to enabled.
+            *reinterpret_cast<uint8_t *>(entry + OFF_ADDON_ENTRY_FILTER_OUT) = 1;
+            *reinterpret_cast<uint8_t *>(entry + OFF_ADDON_ENTRY_DEFAULT_STATE) = 1;
+
             auto fn = reinterpret_cast<ListInsert_t>(
                 Offsets::FUN_INTRUSIVE_LIST_INSERT);
             fn(reinterpret_cast<void *>(
@@ -361,7 +433,24 @@ void __fastcall AddonInit_h(const char *accountName) {
     AddonInit_o(accountName);
     auto TocParser = reinterpret_cast<TocParser_t>(Offsets::FUN_TOC_PARSER);
     TocParser(kAddonName);
-    MoveEmbeddedToListHead();
+    FinalizeEmbeddedEntry();
+}
+
+// `FUN_ADDON_ENABLE_RESOLVE` — per-character enable resolver. We
+// co-hook it to force-enable `!!!ClassicAPI` regardless of DefaultState
+// or any stale WTF disable-override, so hiding it from the addon list
+// can never leave it stuck off. Returns 2 ("enabled for all"); the
+// load-pass gate only tests `!= 0`. Every other addon falls through to
+// the original untouched. See the Offsets.h note for the ABI.
+using AddonEnableResolve_t =
+    uint32_t(__fastcall *)(const char *name, const char *account, char resolveAll);
+AddonEnableResolve_t AddonEnableResolve_o = nullptr;
+
+uint32_t __fastcall AddonEnableResolve_h(const char *name, const char *account,
+                                         char resolveAll) {
+    if (name != nullptr && PathEqualsCI(name, kAddonName))
+        return 2;
+    return AddonEnableResolve_o(name, account, resolveAll);
 }
 
 const Game::HookAutoRegister _hookFileRead{
@@ -374,6 +463,11 @@ const Game::HookAutoRegister _hookAddonInit{
     reinterpret_cast<void *>(&AddonInit_h),
     reinterpret_cast<void **>(&AddonInit_o)};
 
+const Game::HookAutoRegister _hookEnableResolve{
+    Offsets::FUN_ADDON_ENABLE_RESOLVE,
+    reinterpret_cast<void *>(&AddonEnableResolve_h),
+    reinterpret_cast<void **>(&AddonEnableResolve_o)};
+
 } // namespace
 
 } // namespace Addons::Embedded

src/auctionhouse/PostItem.cpp

@@ -55,8 +55,10 @@
 #include "Game.h"
 #include "Offsets.h"
 #include "event/Custom.h"
+#include "item/CGItem.h"
 #include "item/ID.h"
 #include "item/Location.h"
+#include "item/Record.h"
 #include "item/Swap.h"
 #include "tick/WorldTick.h"
 
@@ -97,27 +99,15 @@ 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);
+    auto *desc = Item::ObjectFields(item);
     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);
+    auto *inst = Item::InstanceBlock(item);
     if (inst == nullptr)
         return 0;
     return *reinterpret_cast<const uint64_t *>(inst + Offsets::OFF_INSTANCE_BLOCK_GUID);
@@ -188,7 +178,7 @@ bool BagIsGeneral(int bag) {
     const int id = Item::ID::FromCGItem(bagItem);
     if (id == 0)
         return false;
-    const uint8_t *rec = PeekItemRecord(static_cast<uint32_t>(id));
+    const uint8_t *rec = Item::PeekRecord(static_cast<uint32_t>(id));
     if (rec == nullptr)
         return false;
     return *reinterpret_cast<const uint32_t *>(

src/aura/Api.cpp

@@ -17,12 +17,20 @@
 // nameplate flags, etc.) are populated with vanilla-truthful
 // defaults so consumers reading those keys get sensible values.
 //
-// Filter parsing here mirrors what most modern addons actually pass:
-// "HELPFUL" / "HARMFUL" are honored, every other modern filter
-// (`PLAYER` / `RAID` / `CANCELABLE` / `INCLUDE_NAME_PLATE_ONLY`) is
-// accepted but no-ops — they'd require either source-GUID tracking
-// (`PLAYER`), class-dispel-matrix infra (`RAID`), or systems
-// vanilla doesn't have at all.
+// Filter parsing (`ParseFilters`) tokenizes the modern AuraFilters string:
+// tokens separated by `|` and/or whitespace, each optionally negated with a
+// leading `!`. Whole-token matching, so `RAID_PLAYER_DISPELLABLE` is not
+// mistaken for `PLAYER` and `!PLAYER` is a negation rather than a match.
+// Honored: `HELPFUL` / `HARMFUL` (descriptor slot ranges), `PLAYER` /
+// `!PLAYER` (caster == / != the local player, from the Aura::Source cache),
+// `DISPELLABLE` / `!DISPELLABLE` (dispel type is / isn't one a
+// dispel/purge/steal can remove — Spell.dbc Dispel ∈ Magic/Curse/Disease/
+// Poison, matching the server's DISPEL_ALL_MASK), and `CROWD_CONTROL` /
+// `!CROWD_CONTROL` (is / isn't a hard control effect, via the shared
+// `Spell::CrowdControl` classifier that also backs C_LossOfControl). Every
+// other modern token (`RAID`, `CANCELABLE`, `INCLUDE_NAME_PLATE_ONLY`, `MAW`,
+// …) is accepted and ignored — they need a class-dispel matrix or systems
+// vanilla has no data for.
 
 #include "Data.h"
 
@@ -60,24 +68,72 @@ uint64_t GuidForOutOfRange(const char *token) {
     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
-// (`"HELPFUL"` etc.) and addons that pass them through case-changing
-// transforms are already broken on modern too.
-Data::Filter ParseFilter(const char *filter) {
-    if (filter == nullptr)
-        return Data::Filter::Helpful;
-    if (strstr(filter, "HARMFUL") != nullptr)
-        return Data::Filter::Harmful;
-    return Data::Filter::Helpful;
+// Parsed AuraFilters string. `helpful`/`harmful` record which range tokens
+// were present (neither → both, matching modern's default); `caster` carries
+// the PLAYER / !PLAYER restriction.
+struct ParsedFilter {
+    bool helpful = false;
+    bool harmful = false;
+    Data::CasterMode caster = Data::CasterMode::Any;
+    Data::DispelMode dispel = Data::DispelMode::Any;
+    Data::CcMode cc = Data::CcMode::Any;
+
+    Data::Match ToMatch() const { return Data::Match{caster, dispel, cc}; }
+};
+
+// Reduces the parsed range tokens to the single `Data::Filter` the indexed /
+// by-id / by-name getters take: Harmful when HARMFUL was given, else Helpful
+// (the modern default). HELPFUL wins ties are irrelevant here — an indexed
+// getter reads one range.
+Data::Filter RangeFilter(const ParsedFilter &pf) {
+    return pf.harmful && !pf.helpful ? Data::Filter::Harmful
+                                     : Data::Filter::Helpful;
 }
 
-// The `PLAYER` filter token restricts results to auras the local player
-// cast. No other modern token contains the substring "PLAYER", so a plain
-// substring test is safe.
-bool HasPlayerFilter(const char *filter) {
-    return filter != nullptr && strstr(filter, "PLAYER") != nullptr;
+// Tokenizes the filter string. Case-sensitive (modern documents the tokens as
+// upper-case constants). `HELPFUL`/`HARMFUL` are positive range selectors;
+// negating them is meaningless for our slot-based ranges, so a leading `!` is
+// ignored on those. `PLAYER` honors negation (`!PLAYER` → NotPlayer). Any
+// unrecognized token is accepted and skipped.
+ParsedFilter ParseFilters(const char *filter) {
+    ParsedFilter out;
+    if (filter == nullptr)
+        return out;
+    for (const char *p = filter; *p != '\0';) {
+        while (*p == '|' || *p == ' ' || *p == '\t')
+            ++p;
+        if (*p == '\0')
+            break;
+        bool negate = false;
+        if (*p == '!') {
+            negate = true;
+            ++p;
+        }
+        char tok[64];
+        size_t n = 0;
+        while (*p != '\0' && *p != '|' && *p != ' ' && *p != '\t') {
+            if (n + 1 < sizeof(tok))
+                tok[n++] = *p;
+            ++p;
+        }
+        tok[n] = '\0';
+
+        if (strcmp(tok, "HELPFUL") == 0)
+            out.helpful = true;
+        else if (strcmp(tok, "HARMFUL") == 0)
+            out.harmful = true;
+        else if (strcmp(tok, "PLAYER") == 0)
+            out.caster = negate ? Data::CasterMode::NotPlayer
+                                : Data::CasterMode::PlayerOnly;
+        else if (strcmp(tok, "DISPELLABLE") == 0)
+            out.dispel = negate ? Data::DispelMode::NotDispellable
+                                : Data::DispelMode::DispellableOnly;
+        else if (strcmp(tok, "CROWD_CONTROL") == 0)
+            out.cc = negate ? Data::CcMode::NotCrowdControl
+                            : Data::CcMode::CrowdControlOnly;
+        // else: accepted and ignored (retail-only / unimplemented token).
+    }
+    return out;
 }
 
 const char *ArgUnit(void *L, int idx) {
@@ -102,10 +158,10 @@ const char *ArgOptString(void *L, int idx) {
 // or nil if no such aura. Used by `GetAuraDataByIndex` and the
 // filter-locked aliases.
 int PushAuraByIndex(void *L, const char *unitToken, int index,
-                    Data::Filter filter, bool playerOnly = false) {
+                    Data::Filter filter, Data::Match match = {}) {
     const uint8_t *unit = ResolveUnit(unitToken);
     if (unit != nullptr) {
-        const int slot = Data::FindNthSlot(unit, index, filter, playerOnly);
+        const int slot = Data::FindNthSlot(unit, index, filter, match);
         if (slot >= 0) {
             Data::Push(L, unit, slot);
             return 1;
@@ -113,14 +169,14 @@ int PushAuraByIndex(void *L, const char *unitToken, int index,
         // 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))
+        if (Data::PushNthCacheFallback(L, unit, index, filter, match))
             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))
+                                   filter, match))
             return 1;
     }
     Game::Lua::PushNil(L);
@@ -135,8 +191,8 @@ int __fastcall Script_GetAuraDataByIndex(void *L) {
         Game::Lua::PushNil(L);
         return 1;
     }
-    return PushAuraByIndex(L, unit, index, ParseFilter(filterStr),
-                           HasPlayerFilter(filterStr));
+    const ParsedFilter pf = ParseFilters(filterStr);
+    return PushAuraByIndex(L, unit, index, RangeFilter(pf), pf.ToMatch());
 }
 
 int __fastcall Script_GetBuffDataByIndex(void *L) {
@@ -168,23 +224,19 @@ int __fastcall Script_GetUnitAuraBySpellID(void *L) {
         return 1;
     }
     const uint8_t *unit = ResolveUnit(unitToken);
-    Data::Filter f;
-    const Data::Filter *fp = nullptr;
-    if (filterStr != nullptr) {
-        f = ParseFilter(filterStr);
-        fp = &f;
-    }
-    const bool playerOnly = HasPlayerFilter(filterStr);
+    const ParsedFilter pf = ParseFilters(filterStr);
+    Data::Filter f = RangeFilter(pf);
+    const Data::Filter *fp = (pf.helpful || pf.harmful) ? &f : nullptr;
     if (unit != nullptr) {
         const int slot = Data::FindSlotBySpellID(
-            unit, static_cast<uint32_t>(spellID), fp, playerOnly);
+            unit, static_cast<uint32_t>(spellID), fp, pf.ToMatch());
         if (slot >= 0) {
             Data::Push(L, unit, slot);
             return 1;
         }
     } else if (Data::PushGroupAuraBySpellID(L, GuidForOutOfRange(unitToken),
                                             static_cast<uint32_t>(spellID), fp,
-                                            playerOnly)) {
+                                            pf.ToMatch())) {
         // Out-of-range groupmate — read from the group-member aura array.
         return 1;
     }
@@ -201,21 +253,17 @@ int __fastcall Script_GetAuraDataBySpellName(void *L) {
         return 1;
     }
     const uint8_t *unit = ResolveUnit(unitToken);
-    Data::Filter f;
-    const Data::Filter *fp = nullptr;
-    if (filterStr != nullptr) {
-        f = ParseFilter(filterStr);
-        fp = &f;
-    }
-    const bool playerOnly = HasPlayerFilter(filterStr);
+    const ParsedFilter pf = ParseFilters(filterStr);
+    Data::Filter f = RangeFilter(pf);
+    const Data::Filter *fp = (pf.helpful || pf.harmful) ? &f : nullptr;
     if (unit != nullptr) {
-        const int slot = Data::FindSlotBySpellName(unit, spellName, fp, playerOnly);
+        const int slot = Data::FindSlotBySpellName(unit, spellName, fp, pf.ToMatch());
         if (slot >= 0) {
             Data::Push(L, unit, slot);
             return 1;
         }
     } else if (Data::PushGroupAuraBySpellName(L, GuidForOutOfRange(unitToken),
-                                              spellName, fp, playerOnly)) {
+                                              spellName, fp, pf.ToMatch())) {
         // Out-of-range groupmate — read from the group-member aura array.
         return 1;
     }
@@ -243,7 +291,7 @@ int __fastcall Script_GetPlayerAuraBySpellID(void *L) {
 // sequential keys starting from `nextKey`. Updates `nextKey` so a
 // follow-up call can append to the same outer table.
 void AppendRangeToArray(void *L, const uint8_t *unit, int outerIdx,
-                       Data::Filter filter, int &nextKey, bool playerOnly) {
+                       Data::Filter filter, int &nextKey, Data::Match match) {
     const int start = (filter == Data::Filter::Harmful)
                           ? Offsets::UNIT_AURA_BUFF_COUNT
                           : 0;
@@ -253,14 +301,15 @@ void AppendRangeToArray(void *L, const uint8_t *unit, int outerIdx,
     for (int slot = start; slot < end; ++slot) {
         if (!Data::IsSlotPopulated(unit, slot))
             continue;
-        if (playerOnly && !Data::IsPlayerCast(unit, slot))
+        if (!Data::MatchesAura(match, Data::IsPlayerCast(unit, slot),
+                               Data::ReadSpellID(unit, slot)))
             continue;
         Game::Lua::PushNumber(L, static_cast<double>(nextKey++));
         Data::Push(L, unit, slot);
         Game::Lua::SetTable(L, outerIdx);
     }
     // Append auras the descriptor dropped but Aura::Source still has live.
-    Data::AppendCacheFallbacks(L, unit, filter, playerOnly, outerIdx, nextKey);
+    Data::AppendCacheFallbacks(L, unit, filter, match, outerIdx, nextKey);
 }
 
 int __fastcall Script_GetUnitAuras(void *L) {
@@ -274,26 +323,24 @@ int __fastcall Script_GetUnitAuras(void *L) {
     // Range tokens are independent of PLAYER: an explicit HELPFUL/HARMFUL
     // selects that range, neither selects both. So `"PLAYER"` alone returns
     // both ranges restricted to player-cast auras (matching retail).
-    const bool playerOnly = HasPlayerFilter(filterStr);
-    const bool hasHelpful = filterStr != nullptr && strstr(filterStr, "HELPFUL") != nullptr;
-    const bool hasHarmful = filterStr != nullptr && strstr(filterStr, "HARMFUL") != nullptr;
-    const bool both = !hasHelpful && !hasHarmful;
+    const ParsedFilter pf = ParseFilters(filterStr);
+    const bool both = !pf.helpful && !pf.harmful;
 
     int nextKey = 1;
     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);
+        if (pf.helpful || both)
+            AppendRangeToArray(L, unit, 1, Data::Filter::Helpful, nextKey, pf.ToMatch());
+        if (pf.harmful || both)
+            AppendRangeToArray(L, unit, 1, Data::Filter::Harmful, nextKey, pf.ToMatch());
     } 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);
+        if (pf.helpful || both)
+            Data::AppendGroupAuras(L, guid, Data::Filter::Helpful, pf.ToMatch(), 1, nextKey);
+        if (pf.harmful || both)
+            Data::AppendGroupAuras(L, guid, Data::Filter::Harmful, pf.ToMatch(), 1, nextKey);
     }
     return 1;
 }

src/aura/ComboDuration.cpp

@@ -21,6 +21,7 @@
 #include "Offsets.h"
 #include "dbc/Lookup.h"
 #include "net/PacketReader.h"
+#include "net/SendObserver.h"
 #include "spell/Mod.h"
 #include "unit/Identity.h"
 
@@ -56,28 +57,52 @@ uint8_t CurrentComboPoints() {
     return *(info + Offsets::OFF_CGPLAYER_COMBO_POINTS);
 }
 
-// One cast in flight at a time is the practical case (a second finisher
-// can't be cast until the server consumes the first one's combo points),
-// so a single slot with a spellID match and a short TTL suffices.
+// Keyed by spellID, because a finisher's own SMSG_SPELL_GO is not reliably
+// the next one to arrive after its cast. A talent that procs an aura on the
+// finisher (Turtle's rogue Taste for Blood casts spell 52529 on the player)
+// lands its SPELL_GO first, and every player-cast aura spell reaches
+// TryComboScaledMs. A single slot -- or a lookup that cleared the slot on a
+// spellID mismatch -- therefore lost the snapshot to the proc, and the
+// finisher fell back to its 0-CP base duration. Only the matching entry is
+// ever consumed; a miss leaves every other capture intact.
 struct Capture {
     uint32_t spellId;
     uint8_t comboPoints;
     uint32_t capturedMs;
 };
-Capture g_capture{0, 0, 0};
+constexpr int kCaptureCount = 8;
+Capture g_captures[kCaptureCount];
+int g_captureCursor = 0;
 
 // Worst-case send -> SMSG_SPELL_GO roundtrip. Past this the snapshot is
 // stale (the cast failed / was rejected) and must not scale a later cast.
 constexpr uint32_t kCaptureTtlMs = 2000;
 
+void RememberCapture(uint32_t spellId, uint8_t comboPoints, uint32_t nowMs) {
+    for (auto &c : g_captures) {
+        if (c.spellId == spellId) { // re-cast before the first resolved
+            c.comboPoints = comboPoints;
+            c.capturedMs = nowMs;
+            return;
+        }
+    }
+    g_captures[g_captureCursor] = {spellId, comboPoints, nowMs};
+    g_captureCursor = (g_captureCursor + 1) % kCaptureCount;
+}
+
 int ConsumeCapturedCP(uint32_t spellId) {
-    const Capture c = g_capture;
-    g_capture = {0, 0, 0};
-    if (c.spellId != spellId || c.comboPoints == 0)
-        return 0;
-    if (NowMs() - c.capturedMs >= kCaptureTtlMs)
-        return 0;
-    return c.comboPoints;
+    for (auto &c : g_captures) {
+        if (c.spellId != spellId)
+            continue;
+        const Capture got = c;
+        c = {0, 0, 0};
+        if (got.comboPoints == 0)
+            return 0;
+        if (NowMs() - got.capturedMs >= kCaptureTtlMs)
+            return 0;
+        return got.comboPoints;
+    }
+    return 0;
 }
 
 // Co-hook on the NetClient send — the one funnel every outgoing CMSG
@@ -86,28 +111,17 @@ int ConsumeCapturedCP(uint32_t spellId) {
 // re-entry, but still build and send CMSG_CAST_SPELL through the engine).
 // Snapshot the combo points at the moment the cast request leaves: the
 // server consumes them before SMSG_SPELL_GO arrives, so reading at
-// SpellGo time is too late.
-using NetSend_t = void(__fastcall *)(void *conn, void *edx,
-                                     CDataStore *packet);
-NetSend_t g_origNetSend = nullptr;
-
-void __fastcall NetSend_h(void *conn, void *edx, CDataStore *packet) {
-    if (packet != nullptr) {
-        const uint32_t saved = packet->m_read;
-        const uint32_t opcode = Net::Read<uint32_t>(packet);
-        if (opcode == Offsets::OP_CMSG_CAST_SPELL) {
-            const uint32_t spellId = Net::Read<uint32_t>(packet);
-            if (spellId != 0)
-                g_capture = {spellId, CurrentComboPoints(), NowMs()};
-        }
-        packet->m_read = saved;
-    }
-    g_origNetSend(conn, edx, packet);
+// SpellGo time is too late. We watch sends through the shared
+// `Net::SendObserver` rather than owning the funnel hook ourselves.
+void OnSend(uint32_t opcode, Net::CDataStore *packet) {
+    if (opcode != Offsets::OP_CMSG_CAST_SPELL)
+        return;
+    const uint32_t spellId = Net::Read<uint32_t>(packet);
+    if (spellId != 0)
+        RememberCapture(spellId, CurrentComboPoints(), NowMs());
 }
 
-const Game::HookAutoRegister _sendHook{
-    Offsets::FUN_NET_SEND, reinterpret_cast<void *>(&NetSend_h),
-    reinterpret_cast<void **>(&g_origNetSend)};
+const Net::SendObserver::AutoSubscribe _sendSub{&OnSend};
 
 // ---- Duration data (SpellDuration.dbc + Lua overrides) --------------------
 

src/aura/Data.cpp

@@ -19,6 +19,8 @@
 #include "dbc/Lookup.h"
 #include "group/MemberStats.h"
 #include "guid/Guid.h"
+#include "spell/CrowdControl.h"
+#include "spell/IsSelfBuff.h"
 #include "unit/Identity.h"
 
 #include <cstdint>
@@ -28,13 +30,6 @@ namespace Aura::Data {
 
 namespace {
 
-// Spell.dbc record field offsets used locally. `spell/Info.cpp` has
-// the same set of locals for `Script_GetSpellInfo`; promoting them
-// to `Offsets.h` is a future refactor — for now we mirror its
-// convention so both files stay in sync.
-constexpr int OFF_SPELL_ICON_ID = 0x1D4;
-constexpr int OFF_SPELLICON_PATH = 0x04;
-
 const uint8_t *Descriptor(const uint8_t *unit) {
     if (unit == nullptr)
         return nullptr;
@@ -72,13 +67,13 @@ const char *SpellIconPath(const uint8_t *spellRecord) {
     if (spellRecord == nullptr)
         return nullptr;
     const int iconID = *reinterpret_cast<const int *>(
-        spellRecord + OFF_SPELL_ICON_ID);
+        spellRecord + Offsets::OFF_SPELL_RECORD_ICON_ID);
     if (iconID <= 0)
         return nullptr;
     return DBC::StringField(Offsets::VAR_SPELL_ICON_RECORDS,
                             Offsets::VAR_SPELL_ICON_COUNT,
                             static_cast<uint32_t>(iconID),
-                            OFF_SPELLICON_PATH);
+                            Offsets::OFF_SPELLICON_PATH);
 }
 
 using ResolveUnitToken_t = void *(__fastcall *)(const char *);
@@ -209,6 +204,18 @@ double SpellBaseDurationSeconds(uint32_t spellID, int unitLevel) {
 // Reads the player's level from UNIT_FIELD_LEVEL. Returns 0 when
 // unresolved (pre-login, no descriptor) — caller should treat that
 // as "skip level scaling".
+// True if the engine-tick expiration `expMs` has already reached/passed now.
+// Same signed-wrap-safe compare `PlayerBuffExpirationSeconds` uses (absorbs
+// the ~24.86-day GetTickCount wrap). An already-elapsed cached expiration is
+// not meaningful — the caster is kept regardless, but the time is reported as
+// unknown rather than as a negative remaining.
+bool ExpirationElapsed(uint32_t expMs) {
+    using TickCount_t = uint32_t(__fastcall *)();
+    const uint32_t nowMs = reinterpret_cast<TickCount_t>(
+        static_cast<uintptr_t>(Offsets::FUN_OS_TICKCOUNT_MS))();
+    return static_cast<int32_t>(nowMs - expMs) >= 0;
+}
+
 int PlayerLevel(const uint8_t *player) {
     auto *desc = Descriptor(player);
     if (desc == nullptr)
@@ -217,6 +224,25 @@ int PlayerLevel(const uint8_t *player) {
         desc + Offsets::OFF_UNIT_FIELD_LEVEL);
 }
 
+// The caster GUID attributed to `(guid, spellID)`: the observed caster from
+// the Aura::Source cache, else — when we never saw the cast — the unit itself
+// if the spell is a self-only-target buff (self-buffs can't be cross-cast).
+// 0 when genuinely unknown. Single source of truth for both display
+// (sourceGUID/sourceUnit) and the PLAYER caster filter, so a self-buff shows a
+// source AND matches HELPFUL|PLAYER instead of the two paths disagreeing.
+uint64_t EffectiveCaster(uint64_t guid, uint32_t spellID) {
+    if (guid == 0 || spellID == 0)
+        return 0;
+    uint64_t c = 0;
+    uint32_t expMs = 0;
+    uint32_t durMs = 0;
+    if (Aura::Source::Get(guid, spellID, &c, &expMs, &durMs) && c != 0)
+        return c; // observed caster
+    if (Spell::IsSelfBuff::IsSelfBuff(spellID))
+        return guid; // self-only-target aura → cast by the unit itself
+    return 0;
+}
+
 } // namespace
 
 uint32_t ReadSpellID(const uint8_t *unit, int slot) {
@@ -250,16 +276,67 @@ bool IsPlayerCast(const uint8_t *unit, int slot) {
     const uint32_t spellID = ReadSpellID(unit, slot);
     if (spellID == 0)
         return false;
-    uint64_t casterGuid = 0;
-    uint32_t expMs = 0;
-    uint32_t durMs = 0;
-    if (!Aura::Source::Get(UnitGuid(unit), spellID, &casterGuid, &expMs, &durMs))
+    const uint64_t player = Unit::Identity::PlayerGuid();
+    return player != 0 && EffectiveCaster(UnitGuid(unit), spellID) == player;
+}
+
+// Applies the PLAYER / !PLAYER caster restriction. `isPlayerCast` is the
+// per-aura "was this cast by the local player" answer (false on a cache miss).
+bool CasterMatches(CasterMode caster, bool isPlayerCast) {
+    switch (caster) {
+        case CasterMode::PlayerOnly: return isPlayerCast;
+        case CasterMode::NotPlayer:  return !isPlayerCast;
+        default:                     return true; // Any
+    }
+}
+
+bool IsDispellable(uint32_t spellID) {
+    const uint8_t *rec = SpellRecord(spellID);
+    if (rec == nullptr)
         return false;
-    return casterGuid != 0 && casterGuid == Unit::Identity::PlayerGuid();
+    const uint32_t dispelType = *reinterpret_cast<const uint32_t *>(
+        rec + Offsets::OFF_SPELL_DISPEL_TYPE);
+    // Magic(1) / Curse(2) / Disease(3) / Poison(4) — the server's
+    // DISPEL_ALL_MASK. None(0) / Stealth(5) / Invisibility(6) / Enrage(9)
+    // etc. are not dispellable by any mechanism.
+    return dispelType >= 1 && dispelType <= 4;
+}
+
+bool DispelMatches(DispelMode dispel, uint32_t spellID) {
+    switch (dispel) {
+        case DispelMode::DispellableOnly: return IsDispellable(spellID);
+        case DispelMode::NotDispellable:  return !IsDispellable(spellID);
+        default:                          return true; // Any
+    }
+}
+
+bool CcMatches(CcMode cc, uint32_t spellID) {
+    switch (cc) {
+        case CcMode::CrowdControlOnly:
+            return Spell::CrowdControl::IsCrowdControl(spellID);
+        case CcMode::NotCrowdControl:
+            return !Spell::CrowdControl::IsCrowdControl(spellID);
+        default:
+            return true; // Any
+    }
+}
+
+bool MatchesAura(const Match &match, bool isPlayerCast, uint32_t spellID) {
+    return CasterMatches(match.caster, isPlayerCast) &&
+           DispelMatches(match.dispel, spellID) &&
+           CcMatches(match.cc, spellID);
+}
+
+// Group-array analog of IsPlayerCast: the group aura carries no caster, so we
+// consult the Aura::Source cache by (guid, spellID). A miss counts as "not the
+// player" (same as IsPlayerCast).
+bool GroupIsPlayerCast(uint64_t guid, uint32_t spellID) {
+    const uint64_t player = Unit::Identity::PlayerGuid();
+    return player != 0 && EffectiveCaster(guid, spellID) == player;
 }
 
 int FindNthSlot(const uint8_t *unit, int oneBasedIndex, Filter filter,
-                bool playerOnly) {
+                Match match) {
     if (unit == nullptr || oneBasedIndex < 1)
         return -1;
     const int start = (filter == Filter::Harmful)
@@ -272,7 +349,7 @@ int FindNthSlot(const uint8_t *unit, int oneBasedIndex, Filter filter,
     for (int slot = start; slot < end; ++slot) {
         if (!IsSlotPopulated(unit, slot))
             continue;
-        if (playerOnly && !IsPlayerCast(unit, slot))
+        if (!MatchesAura(match, IsPlayerCast(unit, slot), ReadSpellID(unit, slot)))
             continue;
         if (++matches == oneBasedIndex)
             return slot;
@@ -281,7 +358,7 @@ int FindNthSlot(const uint8_t *unit, int oneBasedIndex, Filter filter,
 }
 
 int FindSlotBySpellID(const uint8_t *unit, uint32_t spellID,
-                      const Filter *filter, bool playerOnly) {
+                      const Filter *filter, Match match) {
     if (unit == nullptr || spellID == 0)
         return -1;
     const int start = (filter != nullptr && *filter == Filter::Harmful)
@@ -295,7 +372,7 @@ int FindSlotBySpellID(const uint8_t *unit, uint32_t spellID,
             continue;
         if (ReadSpellID(unit, slot) != spellID)
             continue;
-        if (playerOnly && !IsPlayerCast(unit, slot))
+        if (!MatchesAura(match, IsPlayerCast(unit, slot), ReadSpellID(unit, slot)))
             continue;
         return slot;
     }
@@ -303,7 +380,7 @@ int FindSlotBySpellID(const uint8_t *unit, uint32_t spellID,
 }
 
 int FindSlotBySpellName(const uint8_t *unit, const char *spellName,
-                        const Filter *filter, bool playerOnly) {
+                        const Filter *filter, Match match) {
     if (unit == nullptr || spellName == nullptr || *spellName == '\0')
         return -1;
     const int start = (filter != nullptr && *filter == Filter::Harmful)
@@ -318,7 +395,7 @@ int FindSlotBySpellName(const uint8_t *unit, const char *spellName,
         const char *name = LocalizedSpellName(SpellRecord(ReadSpellID(unit, slot)));
         if (name == nullptr || std::strcmp(name, spellName) != 0)
             continue;
-        if (playerOnly && !IsPlayerCast(unit, slot))
+        if (!MatchesAura(match, IsPlayerCast(unit, slot), ReadSpellID(unit, slot)))
             continue;
         return slot;
     }
@@ -469,12 +546,21 @@ static void PushEnriched(void *L, uint64_t guid, uint32_t spellID,
         uint32_t expMs = 0;
         uint32_t durMs = 0;
         if (Aura::Source::Get(guid, spellID, &c, &expMs, &durMs)) {
-            if (expirationTime == 0.0 && expMs != 0)
+            // A cached expiration that already elapsed while the aura is still
+            // present (non-player casters get an underestimated base duration)
+            // is not meaningful — report unknown (0) rather than a negative
+            // remaining time.
+            if (expirationTime == 0.0 && expMs != 0 && !ExpirationElapsed(expMs))
                 expirationTime = static_cast<double>(expMs) * 0.001;
             if (durMs != 0)
                 duration = static_cast<double>(durMs) * 0.001;
-            casterGuid = c;
         }
+        // Caster (sourceGUID/sourceUnit): observed caster, else the self-buff
+        // inference — same resolution the PLAYER filter uses, so a self-buff
+        // both shows a source and matches HELPFUL|PLAYER. Timing stays unknown
+        // when we never saw the cast; only the caster is inferred, and it's
+        // exact.
+        casterGuid = EffectiveCaster(guid, spellID);
     }
     BuildTable(L, spellID, applications, isHelpful, duration, expirationTime,
                casterGuid);
@@ -548,8 +634,8 @@ bool DescriptorHasVisibleAura(const uint8_t *unit) {
     return false;
 }
 
-// Counts populated descriptor slots matching `filter` (and `playerOnly`).
-int CountSlots(const uint8_t *unit, Filter filter, bool playerOnly) {
+// Counts populated descriptor slots matching `filter` (and `caster`).
+int CountSlots(const uint8_t *unit, Filter filter, Match match) {
     if (unit == nullptr)
         return 0;
     const int start = (filter == Filter::Harmful)
@@ -561,7 +647,7 @@ int CountSlots(const uint8_t *unit, Filter filter, bool playerOnly) {
     for (int slot = start; slot < end; ++slot) {
         if (!IsSlotPopulated(unit, slot))
             continue;
-        if (playerOnly && !IsPlayerCast(unit, slot))
+        if (!MatchesAura(match, IsPlayerCast(unit, slot), ReadSpellID(unit, slot)))
             continue;
         ++n;
     }
@@ -571,21 +657,21 @@ int CountSlots(const uint8_t *unit, Filter filter, bool playerOnly) {
 constexpr int kFallbackMax = Offsets::UNIT_AURA_TOTAL;
 
 // Whether cache entry `c` should be surfaced as a fallback for `unit` under
-// `filter`/`playerOnly`: the spell must be a user-visible aura, it must not
+// `filter`/`caster`: the spell must be a user-visible aura, it must not
 // already be in a populated descriptor slot (no double-listing the same live
 // aura) and, when player-filtered, must have been cast by us. Superseded /
 // dispelled auras are kept out of the cache by `Aura::Source`'s removal
 // eviction, not filtered here.
 bool FallbackEligible(const uint8_t *unit, const Aura::Source::CachedAura &c,
-                      Filter filter, bool playerOnly) {
+                      Filter filter, Match match) {
     if (!IsVisible(SpellRecord(c.spellId)))
         return false; // hidden/internal aura (e.g. SPELL_ATTR_HIDDEN_CLIENTSIDE):
                       // the descriptor path drops these via IsSlotPopulated, so
                       // the cache path must apply the same engine predicate or
                       // they leak through as tooltip-less phantom buffs.
-    if (FindSlotBySpellID(unit, c.spellId, &filter, false) >= 0)
+    if (FindSlotBySpellID(unit, c.spellId, &filter, Match{}) >= 0)
         return false; // still in the descriptor — returned via the slot path
-    if (playerOnly && c.casterGuid != Unit::Identity::PlayerGuid())
+    if (!MatchesAura(match, c.casterGuid == Unit::Identity::PlayerGuid(), c.spellId))
         return false;
     return true;
 }
@@ -593,7 +679,7 @@ bool FallbackEligible(const uint8_t *unit, const Aura::Source::CachedAura &c,
 } // namespace
 
 bool PushNthCacheFallback(void *L, const uint8_t *unit, int oneBasedIndex,
-                          Filter filter, bool playerOnly) {
+                          Filter filter, Match match) {
     if (unit == nullptr)
         return false;
     ReconcileCache(unit); // drop entries the (synced) descriptor contradicts
@@ -602,7 +688,7 @@ bool PushNthCacheFallback(void *L, const uint8_t *unit, int oneBasedIndex,
     // The descriptor held `descCount` matches; the caller already found fewer
     // than `oneBasedIndex` there, so the cache supplies index
     // `oneBasedIndex - descCount` (1-based) of the entries it didn't.
-    const int target = oneBasedIndex - CountSlots(unit, filter, playerOnly);
+    const int target = oneBasedIndex - CountSlots(unit, filter, match);
     if (target < 1)
         return false;
     const uint64_t guid = UnitGuid(unit);
@@ -613,7 +699,7 @@ bool PushNthCacheFallback(void *L, const uint8_t *unit, int oneBasedIndex,
         guid, filter == Filter::Harmful, buf, kFallbackMax);
     int seen = 0;
     for (int i = 0; i < n; ++i) {
-        if (!FallbackEligible(unit, buf[i], filter, playerOnly))
+        if (!FallbackEligible(unit, buf[i], filter, match))
             continue;
         if (++seen == target) {
             PushFromCache(L, unit, buf[i], filter == Filter::Helpful);
@@ -624,7 +710,7 @@ 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) {
+                          Match match, int outerIdx, int &nextKey) {
     if (unit == nullptr)
         return;
     ReconcileCache(unit); // drop entries the (synced) descriptor contradicts
@@ -637,7 +723,7 @@ void AppendCacheFallbacks(void *L, const uint8_t *unit, Filter filter,
     const int n = Aura::Source::Enumerate(
         guid, filter == Filter::Harmful, buf, kFallbackMax);
     for (int i = 0; i < n; ++i) {
-        if (!FallbackEligible(unit, buf[i], filter, playerOnly))
+        if (!FallbackEligible(unit, buf[i], filter, match))
             continue;
         Game::Lua::PushNumber(L, static_cast<double>(nextKey++));
         PushFromCache(L, unit, buf[i], filter == Filter::Helpful);
@@ -668,22 +754,16 @@ uint32_t GroupSpellID(const uint16_t *arr, int slot) {
 // 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
+// `caster` 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) {
+                       Match match) {
     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;
-    }
+    if (!MatchesAura(match, GroupIsPlayerCast(guid, id), id))
+        return false;
     return true;
 }
 
@@ -715,13 +795,13 @@ bool GroupArrayHasVisibleAura(const uint16_t *arr) {
 // 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) {
+                           Match match) {
     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())
+    if (!MatchesAura(match, c.casterGuid == Unit::Identity::PlayerGuid(), c.spellId))
         return false;
     return true;
 }
@@ -729,13 +809,13 @@ bool GroupFallbackEligible(const uint16_t *arr, const Aura::Source::CachedAura &
 // 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) {
+                               int oneBasedIndex, Filter filter, Match match) {
     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))
+        if (!GroupFallbackEligible(arr, buf[i], match))
             continue;
         if (++seen == oneBasedIndex) {
             PushEnriched(L, guid, buf[i].spellId, filter == Filter::Helpful, 1,
@@ -748,14 +828,14 @@ bool PushNthGroupCacheFallback(void *L, uint64_t guid, const uint16_t *arr,
 
 // 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,
+                               Filter filter, Match match, 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))
+        if (!GroupFallbackEligible(arr, buf[i], match))
             continue;
         Game::Lua::PushNumber(L, static_cast<double>(nextKey++));
         PushEnriched(L, guid, buf[i].spellId, filter == Filter::Helpful, 1, level,
@@ -768,7 +848,7 @@ void AppendGroupCacheFallbacks(void *L, uint64_t guid, const uint16_t *arr,
 // (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) {
+                                 const char *spellName, Match match) {
     Aura::Source::CachedAura buf[kFallbackMax];
     const int n = Aura::Source::Enumerate(guid, harmful, buf, kFallbackMax);
     for (int i = 0; i < n; ++i) {
@@ -779,7 +859,7 @@ bool PushGroupCacheFallbackMatch(void *L, uint64_t guid, const uint16_t *arr,
             if (nm == nullptr || std::strcmp(nm, spellName) != 0)
                 continue;
         }
-        if (!GroupFallbackEligible(arr, buf[i], playerOnly))
+        if (!GroupFallbackEligible(arr, buf[i], match))
             continue;
         PushEnriched(L, guid, buf[i].spellId, !harmful, 1, GroupMemberLevel(guid),
                      false);
@@ -791,7 +871,7 @@ bool PushGroupCacheFallbackMatch(void *L, uint64_t guid, const uint16_t *arr,
 } // namespace
 
 bool PushNthGroupAura(void *L, uint64_t guid, int oneBasedIndex, Filter filter,
-                      bool playerOnly) {
+                      Match match) {
     if (guid == 0 || oneBasedIndex < 1)
         return false;
     const uint16_t *arr = Group::MemberStats::AuraArray(guid);
@@ -802,7 +882,7 @@ bool PushNthGroupAura(void *L, uint64_t guid, int oneBasedIndex, Filter filter,
     GroupRange(filter, start, end);
     int matches = 0;
     for (int slot = start; slot < end; ++slot) {
-        if (!GroupSlotEligible(guid, arr, slot, playerOnly))
+        if (!GroupSlotEligible(guid, arr, slot, match))
             continue;
         if (++matches == oneBasedIndex) {
             PushEnriched(L, guid, GroupSpellID(arr, slot),
@@ -814,12 +894,12 @@ bool PushNthGroupAura(void *L, uint64_t guid, int oneBasedIndex, Filter filter,
     // Empty array (server delta-resend gap): supplement from the cache.
     if (!GroupArrayHasVisibleAura(arr))
         return PushNthGroupCacheFallback(L, guid, arr, oneBasedIndex, filter,
-                                         playerOnly);
+                                         match);
     return false;
 }
 
 bool PushGroupAuraBySpellID(void *L, uint64_t guid, uint32_t spellID,
-                            const Filter *filter, bool playerOnly) {
+                            const Filter *filter, Match match) {
     if (guid == 0 || spellID == 0)
         return false;
     const uint16_t *arr = Group::MemberStats::AuraArray(guid);
@@ -835,7 +915,7 @@ bool PushGroupAuraBySpellID(void *L, uint64_t guid, uint32_t spellID,
     for (int slot = start; slot < end; ++slot) {
         if (GroupSpellID(arr, slot) != spellID)
             continue;
-        if (!GroupSlotEligible(guid, arr, slot, playerOnly))
+        if (!GroupSlotEligible(guid, arr, slot, match))
             continue;
         PushEnriched(L, guid, spellID, slot < Offsets::UNIT_AURA_BUFF_COUNT, 1,
                      GroupMemberLevel(guid), false);
@@ -845,18 +925,18 @@ bool PushGroupAuraBySpellID(void *L, uint64_t guid, uint32_t spellID,
         const bool both = (filter == nullptr);
         if ((both || *filter == Filter::Helpful) &&
             PushGroupCacheFallbackMatch(L, guid, arr, false, spellID, nullptr,
-                                        playerOnly))
+                                        match))
             return true;
         if ((both || *filter == Filter::Harmful) &&
             PushGroupCacheFallbackMatch(L, guid, arr, true, spellID, nullptr,
-                                        playerOnly))
+                                        match))
             return true;
     }
     return false;
 }
 
 bool PushGroupAuraBySpellName(void *L, uint64_t guid, const char *spellName,
-                              const Filter *filter, bool playerOnly) {
+                              const Filter *filter, Match match) {
     if (guid == 0 || spellName == nullptr || *spellName == '\0')
         return false;
     const uint16_t *arr = Group::MemberStats::AuraArray(guid);
@@ -876,7 +956,7 @@ bool PushGroupAuraBySpellName(void *L, uint64_t guid, const char *spellName,
         const char *name = LocalizedSpellName(SpellRecord(id));
         if (name == nullptr || std::strcmp(name, spellName) != 0)
             continue;
-        if (!GroupSlotEligible(guid, arr, slot, playerOnly))
+        if (!GroupSlotEligible(guid, arr, slot, match))
             continue;
         PushEnriched(L, guid, id, slot < Offsets::UNIT_AURA_BUFF_COUNT, 1,
                      GroupMemberLevel(guid), false);
@@ -886,17 +966,17 @@ bool PushGroupAuraBySpellName(void *L, uint64_t guid, const char *spellName,
         const bool both = (filter == nullptr);
         if ((both || *filter == Filter::Helpful) &&
             PushGroupCacheFallbackMatch(L, guid, arr, false, 0, spellName,
-                                        playerOnly))
+                                        match))
             return true;
         if ((both || *filter == Filter::Harmful) &&
             PushGroupCacheFallbackMatch(L, guid, arr, true, 0, spellName,
-                                        playerOnly))
+                                        match))
             return true;
     }
     return false;
 }
 
-void AppendGroupAuras(void *L, uint64_t guid, Filter filter, bool playerOnly,
+void AppendGroupAuras(void *L, uint64_t guid, Filter filter, Match match,
                       int outerIdx, int &nextKey) {
     if (guid == 0)
         return;
@@ -908,7 +988,7 @@ void AppendGroupAuras(void *L, uint64_t guid, Filter filter, bool playerOnly,
     GroupRange(filter, start, end);
     const int level = GroupMemberLevel(guid);
     for (int slot = start; slot < end; ++slot) {
-        if (!GroupSlotEligible(guid, arr, slot, playerOnly))
+        if (!GroupSlotEligible(guid, arr, slot, match))
             continue;
         Game::Lua::PushNumber(L, static_cast<double>(nextKey++));
         PushEnriched(L, guid, GroupSpellID(arr, slot),
@@ -917,7 +997,7 @@ void AppendGroupAuras(void *L, uint64_t guid, Filter filter, bool playerOnly,
     }
     // Empty array (server delta-resend gap): supplement from the cache.
     if (!GroupArrayHasVisibleAura(arr))
-        AppendGroupCacheFallbacks(L, guid, arr, filter, playerOnly, outerIdx,
+        AppendGroupCacheFallbacks(L, guid, arr, filter, match, outerIdx,
                                   nextKey);
 }
 

src/aura/Data.h

@@ -33,6 +33,37 @@ namespace Aura::Data {
 // to helpful when no filter is specified.
 enum class Filter { Helpful, Harmful };
 
+// Caster restriction from the `PLAYER` / `!PLAYER` aura filter tokens.
+// `Any` = no restriction; `PlayerOnly` = only auras the local player cast
+// (`PLAYER`); `NotPlayer` = only auras NOT cast by the local player
+// (`!PLAYER`). Caster attribution comes from the `Aura::Source` cache; a
+// cache miss counts as "not the player" (so `PlayerOnly` excludes it and
+// `NotPlayer` includes it — matching `IsPlayerCast`'s miss semantics).
+enum class CasterMode { Any, PlayerOnly, NotPlayer };
+
+// Restriction from the `DISPELLABLE` / `!DISPELLABLE` aura filter tokens.
+// `Any` = no restriction; `DispellableOnly` = only auras that can be
+// dispelled / purged / stolen by SOME mechanism (dispel type Magic, Curse,
+// Disease, or Poison — the server's DISPEL_ALL_MASK); `NotDispellable` = the
+// complement. "Regardless of whether the local player can dispel it" —
+// matching the modern AuraFilters semantics.
+enum class DispelMode { Any, DispellableOnly, NotDispellable };
+
+// Restriction from the `CROWD_CONTROL` / `!CROWD_CONTROL` aura filter tokens.
+// `Any` = no restriction; `CrowdControlOnly` = only auras that are a crowd-
+// control effect (stun / fear / silence / root / etc., per
+// `Spell::CrowdControl`); `NotCrowdControl` = the complement.
+enum class CcMode { Any, CrowdControlOnly, NotCrowdControl };
+
+// A parsed aura-filter's per-aura predicates (beyond the helpful/harmful
+// range, which is the separate `Filter`). Extensible: new orthogonal filter
+// dimensions add a field here rather than another function parameter.
+struct Match {
+    CasterMode caster = CasterMode::Any;
+    DispelMode dispel = DispelMode::Any;
+    CcMode cc = CcMode::Any;
+};
+
 // Reads the spell ID at the given absolute slot (0..47). Returns 0
 // if the slot is empty or the unit pointer is null.
 uint32_t ReadSpellID(const uint8_t *unit, int slot);
@@ -50,27 +81,41 @@ bool IsSlotPopulated(const uint8_t *unit, int slot);
 // UNIT_AURA_TOTAL-1 for Harmful. When `playerOnly` is true, only auras
 // the local player cast (per `IsPlayerCast`) are counted/returned.
 int FindNthSlot(const uint8_t *unit, int oneBasedIndex, Filter filter,
-                bool playerOnly = false);
+                Match match = {});
 
 // Finds the absolute slot of a populated aura with the given spell
 // ID, optionally restricted to one filter range. `filter` of
 // nullptr searches both ranges (helpful first, then harmful).
 // `playerOnly` restricts to player-cast auras. Returns -1 if not found.
 int FindSlotBySpellID(const uint8_t *unit, uint32_t spellID,
-                      const Filter *filter, bool playerOnly = false);
+                      const Filter *filter, Match match = {});
 
 // Finds the absolute slot of a populated aura whose locale-resolved
 // spell name exactly matches `spellName`. Case-sensitive. Otherwise
 // same semantics as `FindSlotBySpellID`. Returns -1 if not found
 // or if `spellName` is null/empty.
 int FindSlotBySpellName(const uint8_t *unit, const char *spellName,
-                        const Filter *filter, bool playerOnly = false);
+                        const Filter *filter, Match match = {});
 
 // True iff the aura at `slot` was cast by the local player, per the
 // `Aura::Source` cache. False on a cache miss (caster unknown) — so a
 // PLAYER-filtered query excludes auras whose cast we didn't observe.
 bool IsPlayerCast(const uint8_t *unit, int slot);
 
+// Applies a `CasterMode` to a per-aura "was cast by the local player" answer.
+// `Any` → always true; `PlayerOnly` → the answer; `NotPlayer` → its negation.
+bool CasterMatches(CasterMode caster, bool isPlayerCast);
+
+// True iff the spell's dispel type is one a dispel/purge/steal can remove —
+// Magic, Curse, Disease, or Poison (`Spell.dbc` Dispel ∈ 1..4). None,
+// Stealth, Invisibility, Enrage, etc. are not dispellable. Verified against
+// the server's DISPEL_ALL_MASK.
+bool IsDispellable(uint32_t spellID);
+
+// Applies a full `Match` (caster + dispel predicates) to one aura, given the
+// per-aura "was cast by the local player" answer and its spell ID.
+bool MatchesAura(const Match &match, bool isPlayerCast, uint32_t spellID);
+
 // Display stack count for the given slot (engine stores stacks-1,
 // we add 1). Returns 0 if the unit is null.
 int ReadStacks(const uint8_t *unit, int slot);
@@ -122,7 +167,7 @@ void Push(void *L, const uint8_t *unit, int slot);
 // helpful/harmful classification matches `filter` and that aren't already in a
 // populated descriptor slot are considered.
 bool PushNthCacheFallback(void *L, const uint8_t *unit, int oneBasedIndex,
-                          Filter filter, bool playerOnly = false);
+                          Filter filter, Match match = {});
 
 // Appends every eligible `Aura::Source` cache fallback for `unit` matching
 // `filter` into the array table at `outerIdx`, continuing from `nextKey`
@@ -130,7 +175,7 @@ bool PushNthCacheFallback(void *L, const uint8_t *unit, int oneBasedIndex,
 // for `GetUnitAuras`. Skips entries already present in a populated descriptor
 // slot so it never double-lists.
 void AppendCacheFallbacks(void *L, const uint8_t *unit, Filter filter,
-                          bool playerOnly, int outerIdx, int &nextKey);
+                          Match match, int outerIdx, int &nextKey);
 
 // ── Out-of-range groupmate path ────────────────────────────────────────────
 //
@@ -154,23 +199,23 @@ void AppendCacheFallbacks(void *L, const uint8_t *unit, Filter filter,
 // 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);
+                      Match match = {});
 
 // 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);
+                            const Filter *filter, Match match = {});
 
 // 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);
+                              const Filter *filter, Match match = {});
 
 // 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,
+void AppendGroupAuras(void *L, uint64_t guid, Filter filter, Match match,
                       int outerIdx, int &nextKey);
 
 } // namespace Aura::Data

src/aura/Source.cpp

@@ -19,14 +19,18 @@
 #include "Data.h"
 #include "Game.h"
 #include "Offsets.h"
+#include "net/PacketDispatch.h"
 #include "net/PacketReader.h"
+#include "object/Resolve.h"
 #include "player/StatSignal.h"
+#include "spell/CastEvents.h"
 #include "spell/Lookup.h"
 #include "tick/WorldTick.h"
 #include "totem/Tracker.h"
 #include "unit/Identity.h"
 
 #include <cstdint>
+#include <cstring>
 
 namespace Aura::Source {
 
@@ -127,13 +131,64 @@ struct Entry {
     uint32_t spellId;
     uint32_t expirationMs; // 0 = infinite / unknown duration
     uint32_t durationMs;   // applied duration (incl. caster mods); 0 = none
+    uint32_t stampMs;      // last write time; EvictAbsent grace (see below)
     int8_t kind;           // Kind; descriptor-slot-derived, KIND_UNKNOWN if only seen via SpellGo
     bool used;
 };
 
-constexpr int kCacheSize = 256;
+// Sized for the realistic worst case: a fully raid-buffed 40-man plus its
+// debuff load. We cache one entry per (target, spellId) for EVERY
+// aura-applying SMSG_SPELL_GO we observe — not just auras on the player, but
+// every buff cast on every unit in view — so the live working set in a raid
+// is ~40 members × ~30 persistent buffs ≈ 1200, plus debuffs. At the old 256
+// the table was permanently full and the overflow path evicted live buffs,
+// dropping their source (the "lost sourceGUID on a buff" report). 2048 gives
+// a fully-buffed 40-man comfortable headroom; the tick sweep still reclaims
+// expired/orphaned entries so it rarely approaches full outside a raid.
+// (~40 bytes/entry → ~80 KB static.)
+constexpr int kCacheSize = 2048;
 Entry g_cache[kCacheSize];
-int g_writeCursor = 0;
+
+// SMSG_SPELL_GO arrives before the SMSG_UPDATE_OBJECT that adds the aura to
+// the target's descriptor, so for a brief window a just-captured entry names
+// an aura the descriptor doesn't list yet. `EvictAbsent` (run from a query's
+// ReconcileCache) must not drop such a fresh entry — doing so discards the
+// caster we just captured, which OnAuraAdded then recreates caster-less
+// (verified: druid buff → sourceGUID lost). Entries younger than this window
+// are exempt from EvictAbsent; a genuinely-removed aura is far older and still
+// gets dropped (and OnAuraRemoved evicts real removals directly regardless).
+constexpr uint32_t kEvictGraceMs = 2000;
+
+// True if `guid`'s live unit descriptor still lists `spellId` in any aura
+// slot. The descriptor is the presence authority while the unit is in view,
+// so an entry backing a still-listed aura must never be timer-reclaimed: the
+// caster (sourceGUID / sourceUnit) is immutable for the aura's lifetime, but
+// our `expirationMs` is only a base-duration estimate for non-player casters
+// (we lack their mod tables), which underestimates talent-extended auras and
+// elapses while the aura is still up. Resolves the GUID through the object
+// manager — non-throwing, returns null when the unit isn't loaded / is out of
+// range — so an out-of-range or stealthed unit reports false and its
+// fallback-only entry stays timer-reclaimable exactly as before.
+bool DescriptorListsAura(uint64_t guid, uint32_t spellId) {
+    if (guid == 0 || spellId == 0)
+        return false;
+    constexpr int kUnitOrPlayerMask =
+        (1 << Offsets::OBJECT_TYPE_UNIT) | (1 << Offsets::OBJECT_TYPE_PLAYER);
+    const auto *unit = static_cast<const uint8_t *>(
+        Object::ByGuid(kUnitOrPlayerMask, guid, nullptr, 0));
+    if (unit == nullptr)
+        return false;
+    const auto *desc = *reinterpret_cast<const uint8_t *const *>(
+        unit + Offsets::OFF_CGUNIT_OBJECT_FIELDS);
+    if (desc == nullptr)
+        return false;
+    for (int slot = 0; slot < Offsets::UNIT_AURA_TOTAL; ++slot) {
+        if (*reinterpret_cast<const uint32_t *>(
+                desc + Offsets::OFF_UNIT_FIELD_AURA + slot * 4) == spellId)
+            return true;
+    }
+    return false;
+}
 
 // `fromCast` true: the SpellGo hook — authoritative caster + caster-modified
 // (talented) timing. False: the OnAuraAdded application hook — timing only,
@@ -146,9 +201,12 @@ void Store(uint64_t targetGuid, uint32_t spellId, uint64_t casterGuid,
     if (targetGuid == 0 || spellId == 0)
         return;
 
+    const uint32_t now = NowMs();
+
     // Update an existing entry for this exact aura instance.
     for (auto &e : g_cache) {
         if (e.used && e.targetGuid == targetGuid && e.spellId == spellId) {
+            e.stampMs = now; // refresh EvictAbsent grace on any touch
             // Learn the classification whenever a slot-derived kind arrives —
             // independent of caster/timing ownership, and never downgrade a
             // known kind back to unknown.
@@ -163,19 +221,44 @@ void Store(uint64_t targetGuid, uint32_t spellId, uint64_t casterGuid,
             return;
         }
     }
-    // Take a free slot, else an expired one, else evict round-robin.
-    const uint32_t now = NowMs();
+    // Take a free slot, else an expired one whose aura the descriptor no
+    // longer lists (a still-present aura keeps its slot so its caster isn't
+    // lost — see DescriptorListsAura), else evict round-robin.
     for (auto &e : g_cache) {
-        if (!e.used || (e.expirationMs != 0 && now >= e.expirationMs)) {
+        if (!e.used ||
+            (e.expirationMs != 0 && now >= e.expirationMs &&
+             !DescriptorListsAura(e.targetGuid, e.spellId))) {
             e = {targetGuid, casterGuid, spellId, expirationMs, durationMs,
-                 kind, true};
+                 now, kind, true};
             return;
         }
     }
-    Entry &slot = g_cache[g_writeCursor];
-    g_writeCursor = (g_writeCursor + 1) % kCacheSize;
-    slot = {targetGuid, casterGuid, spellId, expirationMs, durationMs, kind,
-            true};
+    // Saturated. Honor the same invariant as the tick sweep: an entry whose
+    // aura is still present on a resolvable unit is NEVER evicted — its caster
+    // can't be recovered once dropped (the "buff still on the player lost its
+    // source" case). Prefer the least-recently-updated ORPHAN (no live
+    // descriptor backing: out of range / despawned / genuinely gone); only if
+    // every single slot is a present, live aura — true saturation we can't
+    // avoid — fall back to the global LRU victim. With kCacheSize sized to the
+    // raid working set, reaching here is already unlikely and the saturated
+    // fallback is practically unreachable.
+    Entry *orphan = nullptr;
+    Entry *lru = &g_cache[0];
+    for (auto &e : g_cache) {
+        if (!e.used) { // defensive: a freed slot always wins outright
+            orphan = &e;
+            break;
+        }
+        if (e.stampMs < lru->stampMs)
+            lru = &e;
+        if (DescriptorListsAura(e.targetGuid, e.spellId))
+            continue; // still present on a live descriptor — protect it
+        if (orphan == nullptr || e.stampMs < orphan->stampMs)
+            orphan = &e;
+    }
+    Entry *victim = (orphan != nullptr) ? orphan : lru;
+    *victim = {targetGuid, casterGuid, spellId, expirationMs, durationMs, now,
+               kind, true};
 }
 
 // ---- Out-of-range group-member aura snapshots ---------------------------
@@ -234,6 +317,267 @@ void Evict(uint64_t targetGuid, uint32_t spellId) {
     }
 }
 
+// ---- Server-side duration modifiers (trigger-driven inference) -----------
+//
+// Some server mechanics change a DoT's remaining time on another unit with
+// NO client-visible signal — verified in tortoise-wow: the change goes
+// through SetAuraDuration / RefreshHolder, and UpdateAuraDuration only
+// notifies the aura's target-if-a-player (self-scoped), never the observing
+// caster; on a mob the packet isn't even built. We can't hear the *change*,
+// but we DO see the TRIGGERING cast's SMSG_SPELL_GO, so we mirror the
+// server's edit on the cached entry. Rules are registered two ways: the
+// family/school-matched form from Lua (`RegisterAuraDurationModifierByTrigger`,
+// e.g. Shadow Weaving), and the exact-spellID form from C++ (`AddDurationMod`),
+// which src/turtle uses for the server's built-in mods. Turtle examples
+// (registered in src/turtle/DurationMods.cpp):
+//   Conflagrate  -> Immolate:    reduce 3s   (Immolate keeps ticking, -3s)
+//   Molten Blast -> Flame Shock:  refresh    (RefreshHolder → reset to max)
+// A trigger is matched either by exact spellID (from the server's script
+// binding, stable across ranks) or by SpellFamilyName + school; the affected
+// aura by SpellFamilyName + a family-flag overlap (+ optional icon) — rank-proof,
+// exactly how the server's scripts find it. Conflagrate's *full*-consume path
+// removes Immolate, which clears
+// the descriptor slot → OnAuraRemoved already handles it; the reduce rule
+// covers the keep-ticking case. Probabilistic refreshes (Carnage's roll) are
+// deliberately NOT shipped as defaults — the client can't know the server's
+// roll outcome, so inferring them would show wrong timers.
+
+enum ModOp { MOD_REFRESH = 0, MOD_REDUCE = 1, MOD_SET = 2, MOD_REMOVE = 3 };
+
+struct DurationMod {
+    uint32_t triggerSpellId; // exact trigger; 0 = match by family+school below
+    uint32_t triggerFamily;  // (triggerSpellId==0) trigger's SpellFamilyName
+    int32_t triggerSchool;   // (triggerSpellId==0) school index; -1 = any school
+    uint32_t affectedFamily; // SpellFamilyName of the affected aura
+    uint64_t affectedMask;   // must overlap the affected aura's SpellFamilyFlags
+    uint32_t affectedIcon;   // 0 = any; else affected aura's SpellIconID must equal
+    int32_t op;
+    int32_t valueMs; // REDUCE/SET amount; ignored by REFRESH/REMOVE
+};
+constexpr int kMaxMods = 128;
+DurationMod g_mods[kMaxMods];
+int g_modCount = 0;
+
+// The affected-aura selector alone, shared with the Lua-facing by-family
+// refresh so the two cannot disagree about what they match.
+bool AffectedMatchesRaw(const uint8_t *rec, uint32_t family, uint64_t mask,
+                        uint32_t icon) {
+    if (!Spell::Lookup::IsFitToFamily(rec, family, mask))
+        return false;
+    if (icon != 0 &&
+        *reinterpret_cast<const uint32_t *>(
+            rec + Offsets::OFF_SPELL_RECORD_ICON_ID) != icon)
+        return false;
+    return true;
+}
+
+bool AffectedMatches(const uint8_t *rec, const DurationMod &m) {
+    return AffectedMatchesRaw(rec, m.affectedFamily, m.affectedMask,
+                              m.affectedIcon);
+}
+
+// A rule's trigger matches either by exact spellID, or (triggerSpellId == 0)
+// by the cast spell's SpellFamilyName + school index — one rule then covers
+// every rank / server-added spell of a class's school (e.g. any priest
+// shadow-school cast, for Shadow Weaving). triggerSchool < 0 = any school.
+bool TriggerMatches(const DurationMod &m, uint32_t triggerSpellId,
+                    const uint8_t *triggerRec) {
+    if (m.triggerSpellId != 0)
+        return m.triggerSpellId == triggerSpellId;
+    if (triggerRec == nullptr)
+        return false;
+    if (*reinterpret_cast<const uint32_t *>(
+            triggerRec + Offsets::OFF_SPELL_RECORD_FAMILY_NAME) != m.triggerFamily)
+        return false;
+    if (m.triggerSchool >= 0 &&
+        static_cast<int32_t>(*reinterpret_cast<const uint32_t *>(
+            triggerRec + Offsets::OFF_SPELL_SCHOOL)) != m.triggerSchool)
+        return false;
+    return true;
+}
+
+// A cache duration edit has no engine packet behind it, so nothing re-fires
+// UNIT_AURA and event-driven consumers (aura-bar addons that read the duration
+// once and count down locally) never see the change. Re-broadcast UNIT_AURA for
+// the affected unit so they re-read. Deferred to the world tick, not fired
+// inline: the callers run inside the SMSG_SPELL_GO subscriber, and firing a
+// unit event there would run addon Lua mid-packet (the re-entrancy class this
+// codebase keeps getting bitten by). The tick flush is the context the engine's
+// own UNIT_AURA fires are safe in. Repeats within a frame are coalesced.
+constexpr int kPendingSignalMax = 32;
+uint64_t g_pendingSignals[kPendingSignalMax];
+int g_pendingSignalCount = 0;
+
+void SignalAuraChanged(uint64_t guid) {
+    if (guid == 0)
+        return;
+    for (int i = 0; i < g_pendingSignalCount; ++i)
+        if (g_pendingSignals[i] == guid)
+            return;
+    if (g_pendingSignalCount < kPendingSignalMax)
+        g_pendingSignals[g_pendingSignalCount++] = guid;
+}
+
+void FlushAuraSignals() {
+    using Broadcast_t = void(__fastcall *)(uint64_t *guid, uint32_t eventCode);
+    auto broadcast = reinterpret_cast<Broadcast_t>(
+        static_cast<uintptr_t>(Offsets::FUN_UNIT_EVENT_BROADCAST));
+    for (int i = 0; i < g_pendingSignalCount; ++i)
+        broadcast(&g_pendingSignals[i], Offsets::UNIT_EVENT_UNIT_AURA);
+    g_pendingSignalCount = 0;
+}
+
+void ApplyMod(Entry &e, const DurationMod &m, uint32_t now) {
+    switch (m.op) {
+    case MOD_REFRESH:
+        if (e.durationMs > 0) {
+            e.expirationMs = now + e.durationMs; // RefreshHolder → reset to max
+            SignalAuraChanged(e.targetGuid);
+        }
+        break;
+    case MOD_SET:
+        e.durationMs = static_cast<uint32_t>(m.valueMs);
+        e.expirationMs = now + static_cast<uint32_t>(m.valueMs);
+        SignalAuraChanged(e.targetGuid);
+        break;
+    case MOD_REDUCE:
+        if (e.expirationMs != 0) {
+            if (e.expirationMs > now + static_cast<uint32_t>(m.valueMs)) {
+                e.expirationMs -= static_cast<uint32_t>(m.valueMs);
+                SignalAuraChanged(e.targetGuid);
+            } else {
+                e.used = false; // shaved to/past now → server removes it
+            }
+        }
+        break;
+    case MOD_REMOVE:
+        e.used = false; // removal — OnAuraRemoved / descriptor path fires UNIT_AURA
+        break;
+    }
+}
+
+// On a trigger cast landing on its hit targets, mirror the server's duration
+// edit on the caster's own matching cached aura. Called from SpellGo_h before
+// the aura gate — triggers (Conflagrate, Molten Blast) apply no aura of their
+// own, so they'd otherwise be dropped.
+void ApplyDurationModifiers(uint32_t triggerSpellId, uint64_t caster,
+                            const uint64_t *targets, int numTargets) {
+    if (triggerSpellId == 0 || caster == 0 || numTargets <= 0)
+        return;
+    const uint8_t *triggerRec =
+        Spell::Lookup::RecordForID(static_cast<int>(triggerSpellId));
+    const uint32_t now = NowMs();
+    for (int r = 0; r < g_modCount; ++r) {
+        const DurationMod &m = g_mods[r];
+        if (!TriggerMatches(m, triggerSpellId, triggerRec))
+            continue;
+        for (int t = 0; t < numTargets; ++t) {
+            for (auto &e : g_cache) {
+                if (!e.used || e.targetGuid != targets[t])
+                    continue;
+                // The mechanic acts on the trigger-caster's own aura. Cast-applied
+                // auras (Immolate, Flame Shock) carry caster == player from SpellGo;
+                // but PROC-applied ones (Shadow Weaving) enter the cache via the
+                // application hooks with casterGuid 0 (no SMSG_SPELL_GO ever named a
+                // caster), so accept those too and attribute them to this trigger
+                // caster (also gives them a sourceUnit).
+                if (e.casterGuid != 0 && e.casterGuid != caster)
+                    continue;
+                if (!AffectedMatches(
+                        Spell::Lookup::RecordForID(static_cast<int>(e.spellId)), m))
+                    continue;
+                if (e.casterGuid == 0)
+                    e.casterGuid = caster;
+                ApplyMod(e, m, now);
+                break; // one matching aura per (rule, target), like the server
+            }
+        }
+    }
+}
+
+bool RegisterDurationMod(uint32_t triggerSpellId, uint32_t triggerFamily,
+                         int32_t triggerSchool, uint32_t affectedFamily,
+                         uint64_t affectedMask, uint32_t affectedIcon, int op,
+                         int32_t valueMs) {
+    // Trigger must be identified one way or the other.
+    if ((triggerSpellId == 0 && triggerFamily == 0) || affectedMask == 0 ||
+        op < MOD_REFRESH || op > MOD_REMOVE)
+        return false;
+    for (int i = 0; i < g_modCount; ++i) { // replace an identical rule
+        DurationMod &m = g_mods[i];
+        if (m.triggerSpellId == triggerSpellId && m.triggerFamily == triggerFamily &&
+            m.triggerSchool == triggerSchool && m.affectedFamily == affectedFamily &&
+            m.affectedMask == affectedMask && m.affectedIcon == affectedIcon) {
+            m.op = op;
+            m.valueMs = valueMs;
+            return true;
+        }
+    }
+    if (g_modCount >= kMaxMods)
+        return false;
+    g_mods[g_modCount++] = {triggerSpellId, triggerFamily, triggerSchool,
+                            affectedFamily, affectedMask, affectedIcon, op, valueMs};
+    return true;
+}
+
+int OpFromString(const char *s) {
+    if (s == nullptr)
+        return -1;
+    if (_stricmp(s, "refresh") == 0)
+        return MOD_REFRESH;
+    if (_stricmp(s, "reduce") == 0)
+        return MOD_REDUCE;
+    if (_stricmp(s, "set") == 0)
+        return MOD_SET;
+    if (_stricmp(s, "remove") == 0)
+        return MOD_REMOVE;
+    return -1;
+}
+
+// `C_UnitAuras.RegisterAuraDurationModifierByTrigger(triggerFamily,
+//     triggerSchool, affectedFamily, affectedFamilyFlags, affectedIcon, op
+//     [, valueSeconds])` -> bool. Like the above, but the trigger is matched
+// by SpellFamilyName + school index instead of an exact spellID — one rule
+// covers every rank / server-added spell of a class's school. triggerSchool
+// < 0 = any school. E.g. Shadow Weaving: priest (6) shadow-school (5) casts
+// refresh the target's Shadow Vulnerability.
+int __fastcall Script_RegisterAuraDurationModifierByTrigger(void *L) {
+    if (!Game::Lua::IsNumber(L, 1) || !Game::Lua::IsNumber(L, 2) ||
+        !Game::Lua::IsNumber(L, 3) || !Game::Lua::IsNumber(L, 4) ||
+        !Game::Lua::IsNumber(L, 5) || !Game::Lua::IsString(L, 6)) {
+        Game::Lua::Error(
+            L, "Usage: C_UnitAuras.RegisterAuraDurationModifierByTrigger("
+               "triggerFamily, triggerSchool, affectedFamily, affectedFamilyFlags, "
+               "affectedIcon, op[, valueSeconds])");
+        return 0;
+    }
+    const auto tfamily = static_cast<uint32_t>(Game::Lua::ToNumber(L, 1));
+    const auto tschool = static_cast<int32_t>(Game::Lua::ToNumber(L, 2));
+    const auto family = static_cast<uint32_t>(Game::Lua::ToNumber(L, 3));
+    const auto mask = static_cast<uint64_t>(Game::Lua::ToNumber(L, 4));
+    const auto icon = static_cast<uint32_t>(Game::Lua::ToNumber(L, 5));
+    const int op = OpFromString(Game::Lua::ToString(L, 6));
+    const int32_t valueMs =
+        Game::Lua::IsNumber(L, 7)
+            ? static_cast<int32_t>(Game::Lua::ToNumber(L, 7) * 1000.0)
+            : 0;
+    if (op < 0 || tfamily == 0) {
+        Game::Lua::PushBool(L, false);
+        return 1;
+    }
+    Game::Lua::PushBool(L, RegisterDurationMod(/*triggerSpellId*/ 0, tfamily, tschool,
+                                               family, mask, icon, op, valueMs));
+    return 1;
+}
+
+void RegisterDurationModLua() {
+    Game::Lua::RegisterTableFunction("C_UnitAuras",
+                                     "RegisterAuraDurationModifierByTrigger",
+                                     &Script_RegisterAuraDurationModifierByTrigger);
+}
+
+const Game::ModuleAutoRegister _autoregDurationMod{&RegisterDurationModLua};
+
 // Wipe the whole cache. Used on a map transition (see OnWorldTick).
 void FlushAll() {
     for (auto &e : g_cache)
@@ -274,8 +618,18 @@ void OnWorldTick() {
 
     const uint32_t now = NowMs();
     for (auto &e : g_cache) {
-        if (e.used && e.expirationMs != 0 && now >= e.expirationMs)
-            e.used = false;
+        if (!e.used || e.expirationMs == 0 || now < e.expirationMs)
+            continue;
+        // A timer elapse doesn't prove the aura is gone — expirationMs is only
+        // a base-duration estimate for non-player casters. Keep any entry whose
+        // aura the owning unit's descriptor still lists (descriptor = presence
+        // authority in view; caster is immutable for the aura's life). Only
+        // genuinely orphaned entries (unit out of range / stealthed / despawned
+        // → no descriptor backing) are timer-reclaimed; the fallback path
+        // already skips expired entries, so this can't resurface a phantom.
+        if (DescriptorListsAura(e.targetGuid, e.spellId))
+            continue;
+        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.
@@ -283,6 +637,9 @@ void OnWorldTick() {
         if (s.used && now - s.touchMs > kGroupSnapshotTtlMs)
             s.used = false;
     }
+    // Re-fire UNIT_AURA for units whose cached duration a mod/refresh changed
+    // this frame (see SignalAuraChanged).
+    FlushAuraSignals();
 }
 
 const Tick::WorldTick::AutoSubscribe _tickSub{&OnWorldTick};
@@ -296,37 +653,33 @@ const Tick::WorldTick::AutoSubscribe _tickSub{&OnWorldTick};
 // keeps the parse short and robust.
 constexpr int kMaxTargets = 16;
 
-using SpellGo_t = void(__fastcall *)(uint64_t *itemGUID, uint64_t *casterGUID,
-                                     uint32_t spellId, CDataStore *packet);
-SpellGo_t g_origSpellGo = nullptr;
-
-void __fastcall SpellGo_h(uint64_t *itemGUID, uint64_t *casterGUID,
-                          uint32_t spellId, CDataStore *packet) {
-    uint64_t targets[kMaxTargets];
-    int numTargets = 0;
-
-    if (packet != nullptr) {
-        const uint32_t savedRead = packet->m_read;
-        Net::Read<int16_t>(packet); // castFlags (unused)
-        const uint8_t numHit = Net::Read<uint8_t>(packet);
-        for (int i = 0; i < numHit; ++i) {
-            const uint64_t guid = Net::Read<uint64_t>(packet);
-            if (numTargets < kMaxTargets)
-                targets[numTargets++] = guid;
-        }
-        packet->m_read = savedRead; // restore so the engine re-parses cleanly
-    }
-
-    g_origSpellGo(itemGUID, casterGUID, spellId, packet);
-
-    const uint64_t caster = (casterGUID != nullptr) ? *casterGUID : 0;
+// The self-contained SPELL_GO processing (succeeded events, server-side
+// duration edits, aura-source caching). None of it reads engine descriptor
+// state, so it's order-independent of the engine's own SPELL_GO handler —
+// which is why it can run from the dispatch funnel (before the leaf handler)
+// rather than after a co-hook's original call. The aura *application* hooks
+// fire off a separate SMSG_UPDATE_OBJECT, so RememberPlayerCast's handoff to
+// them is unaffected by the move.
+void HandleSpellGo(uint64_t caster, uint32_t spellId, const uint64_t *targets,
+                   int numTargets) {
     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())
+    // Feed the totem tracker + fire UNIT_SPELLCAST_SUCCEEDED BEFORE the aura
+    // gate below — a totem summon (and any non-aura spell) applies no aura,
+    // so it would otherwise be dropped. SPELL_GO is "the spell went off", so
+    // this is the succeeded signal for instants too. Player casts only.
+    if (caster == Unit::Identity::PlayerGuid()) {
         Totem::Tracker::OnPlayerSpellGo(spellId);
+        Spell::CastEvents::OnPlayerSucceeded(static_cast<int>(spellId));
+    } else {
+        Spell::CastEvents::OnRemoteSucceeded(caster, static_cast<int>(spellId));
+    }
+
+    // Mirror server-side duration edits the client is never told about
+    // (Conflagrate -3s Immolate, Molten Blast refresh Flame Shock, …). Runs
+    // before the aura gate below: the trigger spell applies no aura itself.
+    ApplyDurationModifiers(spellId, caster, targets, numTargets);
 
     const uint8_t *rec = Spell::Lookup::RecordForID(static_cast<int>(spellId));
     if (!SpellAppliesAura(rec))
@@ -361,9 +714,33 @@ void __fastcall SpellGo_h(uint64_t *itemGUID, uint64_t *casterGUID,
               KIND_UNKNOWN);
 }
 
-const Game::HookAutoRegister _hook{Offsets::FUN_SPELL_GO,
-                                   reinterpret_cast<void *>(&SpellGo_h),
-                                   reinterpret_cast<void **>(&g_origSpellGo)};
+// SMSG_SPELL_GO parse (funnel subscriber). At the leaf handler the engine has
+// pre-decoded itemGuid/casterGuid/spellId; here we're at the raw body, so we
+// decode them ourselves before the hit list:
+//   itemGuid(packed), casterGuid(packed), spellId(u32), castFlags(i16),
+//   numHit(u8), hitGuids(u64 × numHit).
+void ParseSpellGo(CDataStore *packet) {
+    Net::ReadPackedGuid(packet); // itemGuid (unused)
+    const uint64_t caster = Net::ReadPackedGuid(packet);
+    const uint32_t spellId = Net::Read<uint32_t>(packet);
+    Net::Read<int16_t>(packet); // castFlags (unused)
+    const uint8_t numHit = Net::Read<uint8_t>(packet);
+    uint64_t targets[kMaxTargets];
+    int numTargets = 0;
+    for (int i = 0; i < numHit; ++i) {
+        const uint64_t guid = Net::Read<uint64_t>(packet);
+        if (numTargets < kMaxTargets)
+            targets[numTargets++] = guid;
+    }
+    HandleSpellGo(caster, spellId, targets, numTargets);
+}
+
+void SpellGoSub(uint32_t opcode, CDataStore *packet) {
+    if (opcode == Offsets::SMSG_SPELL_GO && packet != nullptr)
+        ParseSpellGo(packet);
+}
+
+const Net::PacketDispatch::AutoSubscribe _spellGoSub{&SpellGoSub};
 
 // ---- Aura-application co-hooks (timing for proc / triggered auras) -------
 
@@ -492,12 +869,59 @@ bool Get(uint64_t unitGuid, uint32_t spellId, uint64_t *outCaster,
     return false;
 }
 
+bool AddDurationMod(uint32_t triggerSpellId, uint32_t affectedFamily,
+                    uint64_t affectedMask, uint32_t affectedIcon, int op,
+                    int32_t valueMs) {
+    // Exact-spellID trigger (triggerFamily 0, triggerSchool -1).
+    return RegisterDurationMod(triggerSpellId, /*triggerFamily*/ 0,
+                               /*triggerSchool*/ -1, affectedFamily, affectedMask,
+                               affectedIcon, op, valueMs);
+}
+
+uint32_t RefreshDurationByFamily(uint64_t unitGuid, uint32_t family,
+                                 uint64_t mask, uint32_t icon,
+                                 uint64_t casterGuid) {
+    if (unitGuid == 0 || mask == 0 || casterGuid == 0)
+        return 0;
+    const uint32_t now = NowMs();
+    for (auto &e : g_cache) {
+        if (!e.used || e.targetGuid != unitGuid)
+            continue;
+        // Caller's own aura only, scoped as ApplyDurationModifiers scopes a
+        // rule; a caster-less entry is claimed rather than skipped, same as
+        // there.
+        if (e.casterGuid != 0 && e.casterGuid != casterGuid)
+            continue;
+        if (!AffectedMatchesRaw(
+                Spell::Lookup::RecordForID(static_cast<int>(e.spellId)), family,
+                mask, icon))
+            continue;
+        if (e.durationMs == 0)
+            continue; // never invent a duration
+        if (e.casterGuid == 0)
+            e.casterGuid = casterGuid;
+        // The applied duration, not a recomputed one (the server's
+        // RefreshHolder): a Rip cast at 3 combo points returns to its own
+        // duration, not a five-point one.
+        e.expirationMs = now + e.durationMs;
+        e.stampMs = now;
+        SignalAuraChanged(e.targetGuid);
+        return e.spellId;
+    }
+    return 0;
+}
+
 void EvictAbsent(uint64_t unitGuid, const uint32_t *presentSpellIds, int count) {
     if (unitGuid == 0 || presentSpellIds == nullptr || count <= 0)
         return;
+    const uint32_t now = NowMs();
     for (auto &e : g_cache) {
         if (!e.used || e.targetGuid != unitGuid)
             continue;
+        // Fresh SpellGo capture the descriptor hasn't synced yet — see
+        // kEvictGraceMs. Don't evict it; that's the sourceGUID-loss race.
+        if (now - e.stampMs < kEvictGraceMs)
+            continue;
         bool present = false;
         for (int i = 0; i < count; ++i)
             if (presentSpellIds[i] == e.spellId) {

src/aura/Source.h

@@ -42,6 +42,34 @@ namespace Aura::Source {
 bool Get(uint64_t unitGuid, uint32_t spellId, uint64_t *outCaster,
          uint32_t *outExpirationMs, uint32_t *outDurationMs);
 
+// Refreshes `casterGuid`'s aura on `unitGuid` matching the same selector the
+// duration rules use — SpellFamilyName + family-flag overlap + optional icon
+// (0 = any) — to a full duration from now. Returns the spellID refreshed, or 0
+// if nothing matched. For a mechanic whose duration edit reaches the client
+// too late to be attributed to a cast packet, so no rule can express it.
+uint32_t RefreshDurationByFamily(uint64_t unitGuid, uint32_t family,
+                                 uint64_t mask, uint32_t icon,
+                                 uint64_t casterGuid);
+
+// Op codes for AddDurationMod (mirror the Lua op strings).
+enum DurationModOp {
+    DURATION_MOD_REFRESH = 0,
+    DURATION_MOD_REDUCE = 1,
+    DURATION_MOD_SET = 2,
+    DURATION_MOD_REMOVE = 3,
+};
+
+// Register a server duration-modifier rule from C++. The trigger is matched by
+// exact `triggerSpellId`; the affected aura by SpellFamilyName + a family-flag
+// overlap (+ optional `affectedIcon`, 0 = any). `valueMs` is the reduce/set
+// amount in milliseconds (ignored by refresh/remove). Used by src/turtle
+// modules for the server's built-in mods (the family/school-matched variant is
+// still Lua-registerable via C_UnitAuras.RegisterAuraDurationModifierByTrigger).
+// Returns false on bad input or a full table.
+bool AddDurationMod(uint32_t triggerSpellId, uint32_t affectedFamily,
+                    uint64_t affectedMask, uint32_t affectedIcon, int op,
+                    int32_t valueMs);
+
 // One cached aura, as returned by `Enumerate`.
 struct CachedAura {
     uint32_t spellId;

src/bag/UpdateDelayed.cpp

@@ -60,6 +60,8 @@
 #include "event/Custom.h"
 #include "tick/WorldTick.h"
 
+#include <cstdint>
+
 namespace Bag::UpdateDelayed {
 
 namespace {
@@ -127,6 +129,19 @@ unsigned __fastcall KeyringDescChange_h(void *bagDesc, void *edx,
 void OnWorldTick() {
     if (!g_pending)
         return;
+    // Bag changes aren't meaningful until the player is actually in the world.
+    // During any loading screen (initial login, zone/instance transition) the
+    // engine re-populates bag slots as objects stream in (setting g_pending)
+    // while still behind the screen; the per-frame world tick runs there too,
+    // so firing BAG_UPDATE_DELAYED would make addons rescan bags repeatedly
+    // mid-load for no real change. Hold the pending flag — do NOT clear it —
+    // until the engine's in-world flag is set; the first in-world frame then
+    // emits a single DELAYED covering the settled inventory (matching retail's
+    // one BAG_UPDATE_DELAYED per load). VAR_IN_WORLD clears on every transition,
+    // so this re-suppresses on later zone changes too, not just initial login.
+    if (*reinterpret_cast<const volatile uint8_t *>(
+            static_cast<uintptr_t>(Offsets::VAR_IN_WORLD)) == 0)
+        return;
     g_pending = false;
     const int slot = Event::Custom::Lookup(kEventName);
     if (slot >= 0)

src/baselib/Ascii.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
+
+// Tiny ASCII string helpers. Header-only — no locale, no allocation, safe from
+// any context (hook callbacks, DBC walks). Use these instead of hand-rolling
+// yet another case-insensitive compare.
+
+namespace Ascii {
+
+// Fold a single ASCII char to lower case (non-letters unchanged).
+inline char ToLower(char c) {
+    return (c >= 'A' && c <= 'Z') ? static_cast<char>(c - 'A' + 'a') : c;
+}
+
+// Case-insensitive full-string equality over ASCII. Two null pointers compare
+// equal; a null vs non-null does not.
+inline bool EqualCI(const char *a, const char *b) {
+    if (a == nullptr || b == nullptr)
+        return a == b;
+    for (; *a && *b; ++a, ++b)
+        if (ToLower(*a) != ToLower(*b))
+            return false;
+    return *a == *b;
+}
+
+} // namespace Ascii

src/baselib/StringLib.cpp

@@ -265,6 +265,7 @@ 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::RegisterTableFunction("string", "split", &Script_strsplit);
     Game::Lua::RegisterGlobalFunction("strsplit", &Script_strsplit);
     Game::Lua::RegisterGlobalFunction("strjoin", &Script_strjoin);
     Game::Lua::RegisterGlobalFunction("strtrim", &Script_strtrim);

src/bindings/Bindings.xml

@@ -13,8 +13,6 @@
 		TargetUnit("focus");
 	</Binding>
 	<Binding name="AOELOOT">
-          if not C_Loot.IsScanInProgress() then
-		     C_Loot.ScanNearbyLoot()
-          end
+		C_Loot.LootAllCorpses()
 	</Binding>
 </Bindings>

src/classes/Info.cpp

@@ -15,6 +15,7 @@
 
 #include "Game.h"
 #include "Offsets.h"
+#include "dbc/Names.h"
 
 #include <cstdint>
 
@@ -22,21 +23,11 @@ namespace Classes::Info {
 
 namespace {
 
-const uint8_t *const *Records() {
-    return *reinterpret_cast<const uint8_t *const *const *>(
-        static_cast<uintptr_t>(Offsets::VAR_CHRCLASSES_RECORDS));
-}
-
 int Count() {
     return *reinterpret_cast<const int *>(
         static_cast<uintptr_t>(Offsets::VAR_CHRCLASSES_COUNT));
 }
 
-int LocaleIndex() {
-    return *reinterpret_cast<const int *>(
-        static_cast<uintptr_t>(Offsets::VAR_LOCALE_INDEX));
-}
-
 // `FillLocalizedClassList(table [, isFemale]) → table` — fills the
 // passed-in table with `[classToken] = localizedName` pairs for every
 // class in `ChrClasses.dbc`, then returns the same table for chaining.
@@ -58,15 +49,7 @@ int __fastcall Script_FillLocalizedClassList(void *L) {
         return 0;
     }
 
-    auto *records = Records();
-    if (records == nullptr) {
-        // DBC not loaded yet — return the table unchanged. Matches
-        // modern behavior of "fill what's available, don't crash".
-        Game::Lua::SetTop(L, 1);
-        return 1;
-    }
     const int count = Count();
-    const int locale = LocaleIndex();
 
     // Drop the optional `isFemale` arg (and any further junk) so the
     // table sits alone at idx 1. Each loop iteration pushes key+value
@@ -74,19 +57,14 @@ int __fastcall Script_FillLocalizedClassList(void *L) {
     // [table] before the next iteration.
     Game::Lua::SetTop(L, 1);
     for (int i = 1; i <= count; i++) {
-        const uint8_t *record = records[i];
-        if (record == nullptr)
+        // DBC::* are null-safe (empty result if ChrClasses.dbc isn't loaded)
+        // and skip empty strings, so a sparse/absent class id just falls
+        // through — same "fill what's available, don't crash" behavior.
+        const char *token = DBC::ClassToken(static_cast<uint32_t>(i));
+        if (token == nullptr)
             continue;
-
-        const char *token = *reinterpret_cast<const char *const *>(
-            record + Offsets::OFF_CHRCLASSES_FILENAME);
-        if (token == nullptr || *token == '\0')
-            continue;
-
-        const char *const *names = reinterpret_cast<const char *const *>(
-            record + Offsets::OFF_CHRCLASSES_NAMES);
-        const char *name = names[locale];
-        if (name == nullptr || *name == '\0')
+        const char *name = DBC::ClassName(static_cast<uint32_t>(i));
+        if (name == nullptr)
             continue;
 
         Game::Lua::PushString(L, token);

src/container/FreeSlots.cpp

@@ -16,6 +16,7 @@
 #include "item/BagFamily.h"
 #include "item/ID.h"
 #include "item/Location.h"
+#include "item/Record.h"
 
 #include <cstdint>
 
@@ -23,21 +24,6 @@ namespace Container::FreeSlots {
 
 namespace {
 
-using GetItemRecord_t = const uint8_t *(__thiscall *)(void *cache, uint32_t itemID,
-                                                       const uint64_t *guid, void *callback,
-                                                       void *userData, int unused);
-
-// Same `Peek the item cache without firing a query` shape as
-// `Item::Info::FetchItemRecord`. We don't share that helper because it's
-// file-static there; copying the four-line lookup is simpler than
-// promoting it to a header for one extra caller.
-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);
-}
-
 // Resolves the bag's metadata: total slot count + BagFamily bitfield.
 //
 // - bagID 0 (backpack) → (16, 0). Vanilla 1.12 backpack is fixed at 16
@@ -68,7 +54,7 @@ BagInfo ResolveBagInfo(int bagID) {
     if (itemID == 0)
         return {0, 0};
 
-    auto *record = PeekItemRecord(static_cast<uint32_t>(itemID));
+    auto *record = Item::PeekRecord(static_cast<uint32_t>(itemID));
     if (record == nullptr)
         return {0, 0};
 

src/container/ItemInfo.cpp

@@ -50,9 +50,11 @@
 #include "Game.h"
 #include "Offsets.h"
 #include "dbc/Lookup.h"
+#include "item/CGItem.h"
 #include "item/ID.h"
 #include "item/Link.h"
 #include "item/Location.h"
+#include "item/Record.h"
 #include "item/StatAccum.h"
 
 #include <cstdint>
@@ -80,8 +82,7 @@ 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);
+    const uint8_t *descriptor = Item::ObjectFields(item);
     return descriptor != nullptr &&
            *reinterpret_cast<const uint32_t *>(
                descriptor + Offsets::OFF_DESCRIPTOR_READABLE_TEXT_ID) != 0;
@@ -107,12 +108,11 @@ int __fastcall Script_C_Container_GetContainerItemInfo(void *L) {
     // 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))
+        ? Item::PeekRecord(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);
+    const uint8_t *descriptor = Item::ObjectFields(item);
     int stackCount = 0;
     bool isBound = false;
     if (descriptor != nullptr) {

src/creature/Info.cpp

@@ -54,6 +54,7 @@
 #include "Offsets.h"
 #include "cache/QueryLoad.h"
 #include "dbc/Lookup.h"
+#include "dbc/Names.h"
 #include "event/Custom.h"
 
 #include <cstdint>
@@ -143,17 +144,10 @@ int __fastcall Script_GetRaceInfo(void *L) {
         return 0; // nil
     const int raceID = static_cast<int>(Game::Lua::ToNumber(L, 1));
     const char *file =
-        (raceID > 0) ? DBC::StringField(Offsets::VAR_CHRRACES_RECORDS,
-                                        Offsets::VAR_CHRRACES_COUNT,
-                                        static_cast<uint32_t>(raceID),
-                                        Offsets::OFF_CHRRACES_FILENAME)
-                     : nullptr;
+        (raceID > 0) ? DBC::RaceToken(static_cast<uint32_t>(raceID)) : nullptr;
     if (file == nullptr)
         return 0; // unknown id -> nil
-    const char *name = DBC::LocalizedField(Offsets::VAR_CHRRACES_RECORDS,
-                                           Offsets::VAR_CHRRACES_COUNT,
-                                           static_cast<uint32_t>(raceID),
-                                           Offsets::OFF_CHRRACES_NAMES);
+    const char *name = DBC::RaceName(static_cast<uint32_t>(raceID));
 
     Game::Lua::NewTable(L);
     Game::Lua::SetFieldString(L, "raceName", name); // NULL coerced to ""
@@ -169,17 +163,10 @@ int __fastcall Script_GetClassInfo(void *L) {
         return 0; // nil
     const int classID = static_cast<int>(Game::Lua::ToNumber(L, 1));
     const char *file =
-        (classID > 0) ? DBC::StringField(Offsets::VAR_CHRCLASSES_RECORDS,
-                                         Offsets::VAR_CHRCLASSES_COUNT,
-                                         static_cast<uint32_t>(classID),
-                                         Offsets::OFF_CHRCLASSES_FILENAME)
-                      : nullptr;
+        (classID > 0) ? DBC::ClassToken(static_cast<uint32_t>(classID)) : nullptr;
     if (file == nullptr)
         return 0; // unknown id -> nil
-    const char *name = DBC::LocalizedField(Offsets::VAR_CHRCLASSES_RECORDS,
-                                           Offsets::VAR_CHRCLASSES_COUNT,
-                                           static_cast<uint32_t>(classID),
-                                           Offsets::OFF_CHRCLASSES_NAMES);
+    const char *name = DBC::ClassName(static_cast<uint32_t>(classID));
 
     Game::Lua::NewTable(L);
     Game::Lua::SetFieldString(L, "className", name); // NULL coerced to ""

src/cursor/Info.cpp

@@ -53,6 +53,7 @@
 #include "item/Link.h"
 #include "item/Location.h"
 #include "item/QualityColor.h"
+#include "item/Record.h"
 #include "spell/Lookup.h"
 
 #include <cstdint>
@@ -140,17 +141,6 @@ int PushBagItemCursor(void *L) {
     return PushItem(L, cgItem);
 }
 
-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);
-}
-
 // Builds a basic `"|cffRRGGBB|Hitem:N:0:0:0|h[Name]|h|r"` link from
 // the cached ItemStats record for `itemID`. No enchant / random-
 // suffix decoration — the cursor only stores the bare itemID for
@@ -158,7 +148,7 @@ const uint8_t *PeekItemRecord(uint32_t itemID) {
 // instance state from. Returns true and writes into `out` (size
 // `outSize`) on success; returns false if the item isn't cached.
 bool BuildBasicItemLink(uint32_t itemID, char *out, size_t outSize) {
-    const uint8_t *record = PeekItemRecord(itemID);
+    const uint8_t *record = Item::PeekRecord(itemID);
     if (record == nullptr) return false;
     const char *name = *reinterpret_cast<const char *const *>(
         record + Offsets::OFF_ITEMSTATS_NAME);

src/dbc/Names.cpp

@@ -0,0 +1,117 @@
+// 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 "Names.h"
+
+#include "Lookup.h"
+#include "Offsets.h"
+#include "baselib/Ascii.h"
+
+namespace DBC {
+
+namespace {
+
+// Reverse lookup shared by ClassIdForToken / RaceIdForToken: the id whose
+// single-string field at `offset` matches `token` (case-insensitive), or 0.
+uint32_t IdForStringField(uintptr_t recordsVar, uintptr_t countVar, int offset,
+                          const char *token) {
+    if (token == nullptr || *token == '\0')
+        return 0;
+    const int count = *reinterpret_cast<const int *>(countVar);
+    const uint8_t *const *records =
+        *reinterpret_cast<const uint8_t *const *const *>(recordsVar);
+    if (records == nullptr)
+        return 0;
+    for (int i = 1; i <= count; ++i) {
+        const uint8_t *rec = records[i];
+        if (rec == nullptr)
+            continue;
+        const char *field =
+            *reinterpret_cast<const char *const *>(rec + offset);
+        if (field != nullptr && Ascii::EqualCI(field, token))
+            return static_cast<uint32_t>(i);
+    }
+    return 0;
+}
+
+} // namespace
+
+const char *ClassName(uint32_t classID) {
+    if (classID == 0)
+        return nullptr;
+    return LocalizedField(Offsets::VAR_CHRCLASSES_RECORDS,
+                          Offsets::VAR_CHRCLASSES_COUNT, classID,
+                          Offsets::OFF_CHRCLASSES_NAMES);
+}
+
+const char *ClassToken(uint32_t classID) {
+    if (classID == 0)
+        return nullptr;
+    return StringField(Offsets::VAR_CHRCLASSES_RECORDS,
+                       Offsets::VAR_CHRCLASSES_COUNT, classID,
+                       Offsets::OFF_CHRCLASSES_FILENAME);
+}
+
+const char *RaceName(uint32_t raceID) {
+    if (raceID == 0)
+        return nullptr;
+    return LocalizedField(Offsets::VAR_CHRRACES_RECORDS,
+                          Offsets::VAR_CHRRACES_COUNT, raceID,
+                          Offsets::OFF_CHRRACES_NAMES);
+}
+
+const char *RaceToken(uint32_t raceID) {
+    if (raceID == 0)
+        return nullptr;
+    return StringField(Offsets::VAR_CHRRACES_RECORDS,
+                       Offsets::VAR_CHRRACES_COUNT, raceID,
+                       Offsets::OFF_CHRRACES_FILENAME);
+}
+
+uint32_t ClassIdForToken(const char *token) {
+    return IdForStringField(Offsets::VAR_CHRCLASSES_RECORDS,
+                            Offsets::VAR_CHRCLASSES_COUNT,
+                            Offsets::OFF_CHRCLASSES_FILENAME, token);
+}
+
+uint32_t RaceIdForToken(const char *token) {
+    return IdForStringField(Offsets::VAR_CHRRACES_RECORDS,
+                            Offsets::VAR_CHRRACES_COUNT,
+                            Offsets::OFF_CHRRACES_FILENAME, token);
+}
+
+const char *AreaName(uint32_t areaID, bool resolveToParent) {
+    if (areaID == 0)
+        return nullptr;
+    // Only the parent-resolving path needs the record; the direct read goes
+    // straight through LocalizedField (which bounds-checks the id itself), so
+    // the common !resolveToParent case is a single lookup.
+    uint32_t use = areaID;
+    if (resolveToParent) {
+        const uint8_t *rec = Record(Offsets::VAR_AREATABLE_RECORDS,
+                                    Offsets::VAR_AREATABLE_COUNT, areaID);
+        if (rec != nullptr) {
+            const uint32_t parent = *reinterpret_cast<const uint32_t *>(
+                rec + Offsets::OFF_AREATABLE_PARENT_ID);
+            if (parent != 0 &&
+                Record(Offsets::VAR_AREATABLE_RECORDS,
+                       Offsets::VAR_AREATABLE_COUNT, parent) != nullptr)
+                use = parent;
+        }
+    }
+    return LocalizedField(Offsets::VAR_AREATABLE_RECORDS,
+                          Offsets::VAR_AREATABLE_COUNT, use,
+                          Offsets::OFF_AREATABLE_NAMES);
+}
+
+} // namespace DBC

src/dbc/Names.h

@@ -0,0 +1,54 @@
+// 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>
+
+// `DBC::*` display-name resolvers for the character/zone DBCs. Thin wrappers
+// over `DBC::Record` / `LocalizedField` / `StringField` (see `Lookup.h`) that
+// bake in the specific table + field for a game concept, so callers don't
+// repeat the `(recordsVar, countVar, id, offset)` tuple. Shared by the
+// friends-list and /who surfaces (and any future class/race/zone display).
+// All return `nullptr` when the id is 0 / out of range / the field is empty.
+
+namespace DBC {
+
+// Localized class name for a `ChrClasses.dbc` id (e.g. "Mage").
+const char *ClassName(uint32_t classID);
+
+// Locale-independent class token for a `ChrClasses.dbc` id (e.g. "MAGE") —
+// the key addons use for RAID_CLASS_COLORS and other class tables.
+const char *ClassToken(uint32_t classID);
+
+// Localized race name for a `ChrRaces.dbc` id (e.g. "Night Elf").
+const char *RaceName(uint32_t raceID);
+
+// Locale-independent race token for a `ChrRaces.dbc` id — the client-filename
+// column (e.g. "NightElf", "Scourge"), the race analog of ClassToken and what
+// `UnitRace`'s second return / GetPlayerInfoByGUID's englishRace use.
+const char *RaceToken(uint32_t raceID);
+
+// Reverse of ClassToken / RaceToken: the `ChrClasses.dbc` / `ChrRaces.dbc` id
+// whose client-filename token matches `token` (case-insensitive), or 0 if none
+// matches. Walks the table (cheap — a handful of records).
+uint32_t ClassIdForToken(const char *token);
+uint32_t RaceIdForToken(const char *token);
+
+// Localized zone name for an `AreaTable.dbc` id. When `resolveToParent` is
+// true, a sub-area reports its parent zone (so "Goldshire" → "Elwynn
+// Forest"); when false, the area's own name is returned (what the engine's
+// GetWhoInfo does — /who zones are already zone-level).
+const char *AreaName(uint32_t areaID, bool resolveToParent);
+
+} // namespace DBC

src/encoding/CBOR.cpp

@@ -17,6 +17,7 @@ extern "C" {
 #include <cbor.h>
 }
 
+#include <algorithm>
 #include <cmath>
 #include <cstdint>
 #include <cstdlib>
@@ -76,6 +77,27 @@ int CountTablePairs(void *L, int idx) {
     return n;
 }
 
+// Encode a single Lua value at `idx` into a standalone byte vector,
+// reusing the same grow-and-retry contract as Script_SerializeCBOR.
+// Used to obtain a map key's encoded bytes for canonical sorting; the
+// Lua stack is left untouched (EncodeValue reads but never pops).
+bool EncodeValueToVector(void *L, int idx, int depth, std::vector<uint8_t> &out) {
+    out.assign(64, 0);
+    for (;;) {
+        CborEncoder enc;
+        cbor_encoder_init(&enc, out.data(), out.size(), 0);
+        if (!EncodeValue(L, idx, &enc, depth))
+            return false;
+        const size_t extra = cbor_encoder_get_extra_bytes_needed(&enc);
+        if (extra > 0) {
+            out.resize(out.size() + extra);
+            continue;
+        }
+        out.resize(cbor_encoder_get_buffer_size(&enc, out.data()));
+        return true;
+    }
+}
+
 bool EncodeTable(void *L, int idx, CborEncoder *enc, int depth) {
     if (depth >= kMaxDepth) return false;
     if (idx < 0) idx = Game::Lua::GetTop(L) + idx + 1;
@@ -102,15 +124,63 @@ bool EncodeTable(void *L, int idx, CborEncoder *enc, int depth) {
     CborEncoder map;
     if (!EncOk(cbor_encoder_create_map(enc, &map, static_cast<size_t>(pairs))))
         return false;
+
+    // Canonical CBOR (RFC 7049 §3.9): emit map entries sorted by their
+    // encoded-key bytes (shorter key first, then bytewise). Lua gives no
+    // stable iteration order for string-keyed tables, so without this the
+    // same config serializes to different byte orders each call. We stash
+    // the keys in a holding array table (`hold`), remember each key's
+    // encoded bytes + slot, sort, then re-fetch key/value in sorted order.
+    struct Entry {
+        std::vector<uint8_t> key;
+        int slot;
+    };
+    std::vector<Entry> entries;
+    entries.reserve(static_cast<size_t>(pairs));
+
+    Game::Lua::NewTable(L);
+    const int hold = Game::Lua::GetTop(L);
+    int slot = 0;
     Game::Lua::PushNil(L);
     while (Game::Lua::Next(L, idx) != 0) {
-        if (!EncodeValue(L, -2, &map, depth + 1) ||
-            !EncodeValue(L, -1, &map, depth + 1)) {
-            Game::Lua::SetTop(L, -3);
+        // key @ -2, value @ -1
+        std::vector<uint8_t> keyBytes;
+        if (!EncodeValueToVector(L, -2, depth + 1, keyBytes)) {
+            Game::Lua::SetTop(L, hold - 1); // drop hold + key + value
             return false;
         }
-        Game::Lua::SetTop(L, -2);
+        ++slot;
+        Game::Lua::PushNumber(L, static_cast<double>(slot));
+        Game::Lua::PushValue(L, -3);        // copy key to top
+        Game::Lua::RawSet(L, hold);         // hold[slot] = key
+        entries.push_back(Entry{std::move(keyBytes), slot});
+        Game::Lua::SetTop(L, -2);           // pop value, keep key for Next
     }
+
+    std::sort(entries.begin(), entries.end(),
+              [](const Entry &a, const Entry &b) {
+                  if (a.key.size() != b.key.size())
+                      return a.key.size() < b.key.size();
+                  return std::lexicographical_compare(
+                      a.key.begin(), a.key.end(), b.key.begin(), b.key.end());
+              });
+
+    for (const Entry &e : entries) {
+        Game::Lua::PushNumber(L, static_cast<double>(e.slot));
+        Game::Lua::RawGet(L, hold);         // push key = hold[slot]
+        if (!EncodeValue(L, -1, &map, depth + 1)) {
+            Game::Lua::SetTop(L, hold - 1);
+            return false;
+        }
+        Game::Lua::RawGet(L, idx);          // key -> value = table[key]
+        if (!EncodeValue(L, -1, &map, depth + 1)) {
+            Game::Lua::SetTop(L, hold - 1);
+            return false;
+        }
+        Game::Lua::SetTop(L, -2);           // pop value
+    }
+
+    Game::Lua::SetTop(L, hold - 1);         // drop holding table
     return EncOk(cbor_encoder_close_container(enc, &map));
 }
 

src/equipmentset/Api.cpp

@@ -35,6 +35,7 @@
 #include "Offsets.h"
 #include "Set.h"
 #include "event/Custom.h"
+#include "item/CGItem.h"
 #include "item/Location.h"
 #include "item/Swap.h"
 
@@ -72,8 +73,7 @@ const char *ArgString(void *L, int idx) {
 int ResolveItemID(const uint8_t *cgItem) {
     if (cgItem == nullptr)
         return 0;
-    auto *instance = *reinterpret_cast<const uint8_t *const *>(
-        cgItem + Offsets::OFF_ITEM_INSTANCE_BLOCK);
+    auto *instance = Item::InstanceBlock(cgItem);
     if (instance == nullptr)
         return 0;
     return static_cast<int>(*reinterpret_cast<const uint32_t *>(

src/equipmentset/Locations.cpp

@@ -15,6 +15,7 @@
 
 #include "Offsets.h"
 #include "item/Location.h"
+#include "object/Resolve.h"
 #include "unit/Identity.h"
 
 #include <cstdint>
@@ -58,13 +59,7 @@ int InvMgrSlotCount(const uint8_t *invMgr) {
 uint8_t *ResolveByGUID(int type, uint64_t guid) {
     if (guid == 0)
         return nullptr;
-    using ResolveByGUID_t = void *(__fastcall *)(int, const char *, uint32_t,
-                                                  uint32_t, int);
-    auto fn = reinterpret_cast<ResolveByGUID_t>(Offsets::FUN_OBJECT_RESOLVE_BY_GUID);
-    return static_cast<uint8_t *>(fn(type, "ItemMgr",
-                                     static_cast<uint32_t>(guid),
-                                     static_cast<uint32_t>(guid >> 32),
-                                     0x172));
+    return static_cast<uint8_t *>(Object::ByGuid(type, guid, "ItemMgr", 0x172));
 }
 
 // Walks one bag's contents for a matching GUID. Returns the 1-based
@@ -73,7 +68,7 @@ uint8_t *ResolveByGUID(int type, uint64_t guid) {
 // bank bags (linear 63..68) — the only differences are the source of
 // the bag's GUID and how the result encodes back into a location.
 int WalkBagContents(uint64_t bagGuid, uint64_t targetGuid) {
-    auto *bag = ResolveByGUID(Offsets::OBJ_TYPE_CONTAINER, bagGuid);
+    auto *bag = ResolveByGUID(Offsets::TYPEMASK_CONTAINER, bagGuid);
     if (bag == nullptr)
         return 0;
     auto *bagInvMgr =

src/equipmentset/Tooltip.cpp

@@ -52,6 +52,7 @@
 #include "equipmentset/Data.h"
 #include "equipmentset/Locations.h"
 #include "equipmentset/Set.h"
+#include "item/Record.h"
 
 #include <cstdint>
 
@@ -108,17 +109,6 @@ struct Tally {
     uint32_t missingItemIDs[SLOT_COUNT];
 };
 
-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);
-}
-
 // Walks a set's slots, classifying each non-empty entry into the
 // equipped / in-inventory / ignored / missing buckets via
 // `Locations::FindGUID`. For missing slots, also records the saved
@@ -215,7 +205,7 @@ int __fastcall Script_GameTooltipSetEquipmentSet(void *L) {
             unnamedMissing++;
             continue;
         }
-        auto *record = PeekItemRecord(id);
+        auto *record = Item::PeekRecord(id);
         if (record == nullptr) {
             unnamedMissing++;
             continue;

src/event/Custom.cpp

@@ -282,6 +282,22 @@ int LookupByName(const char *name) {
     return -1;
 }
 
+bool HasListeners(int slot) {
+    if (slot < 0)
+        return false;
+    auto *base = *reinterpret_cast<uint8_t **>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
+    const int count = *reinterpret_cast<int *>(Offsets::VAR_EVENT_TABLE_COUNT);
+    if (base == nullptr || slot >= count)
+        return false;
+    // The entry's chain head (`+0x0C`): a populated subscriber chain is a
+    // non-zero pointer with the low bit clear; `0` or an odd (tagged)
+    // value is the empty self-sentinel — same test the grow-safety scan
+    // uses. So this is true iff at least one frame registered for the event.
+    const uint32_t head = *reinterpret_cast<const uint32_t *>(
+        base + slot * Offsets::EVENT_ENTRY_STRIDE + Offsets::OFF_EVENT_ENTRY_HEAD);
+    return head != 0 && (head & 1) == 0;
+}
+
 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

src/event/Custom.h

@@ -64,6 +64,15 @@ int Lookup(const char *name);
 // fire ourselves (e.g., polyfilling missing event dispatches).
 int LookupByName(const char *name);
 
+// True iff at least one frame is currently registered for the event in
+// `slot` (its subscriber chain is non-empty). Reads the entry's chain
+// head at `+0x0C` — a couple of pointer derefs, no allocation. Use this
+// to gate expensive per-fire work (arg synthesis, DBC lookups) so an
+// event nobody listens to costs almost nothing: `if (HasListeners(slot))
+// { …build args…; Fire(slot, …); }`. `false` for `slot < 0` or a slot
+// past the live table.
+bool HasListeners(int slot);
+
 // Dispatches a custom event via the engine's printf-style event
 // dispatcher at `FUN_FIRE_EVENT` (`0x00703F50`). `format` is a
 // concatenation of `%d` (int), `%u` (uint), `%f` (double), `%s`

src/frame/Attributes.cpp

@@ -0,0 +1,996 @@
+// 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/>.
+
+// Frame attributes + unit-frame mouseover/click backport.
+//
+// Backports `frame:SetAttribute` / `frame:SetAttributeNoHandler` /
+// `frame:ClearAttribute` / `frame:GetAttribute` to 1.12 as native methods on the base Frame registry
+// (every frame gets them, like the modern clients). Vanilla has no attribute
+// system at all — it arrived in 2.0 with secure frames. Attributes are just a
+// per-frame, case-insensitive key→value store (verified from the 3.3.5
+// implementation: a name→Lua-value map plus a getter with prefix/name/suffix
+// wildcard precedence). We store the map in the Lua registry keyed by the frame
+// (registry[frame]) — invisible to Lua script and tamper-proof, like retail's
+// C-side attribute store (see PushSub).
+//
+// The headline use — SecureUnitButton behavior, minus the secure wrapper (1.12
+// has no combat lockdown or taint, so protected actions just work):
+//
+//     unitFrame:SetAttribute("unit", "party1")   -- hover → mouseover = party1
+//     unitFrame:SetAttribute("type1", "target")  -- left-click → target party1
+//
+// ── Mouseover (needs C — the engine's mouseover is a GUID slot) ──
+//
+// Installing OnEnter/OnLeave would be clobbered by an addon's own
+// `SetScript("OnEnter", …)` (pfUI sets `unit` before its scripts), and there's
+// nothing to read from Lua anyway — the mouseover unit is an engine global. So
+// we mirror retail / SuperWoW's `SetMouseoverUnit`: watch the engine's
+// mouse-focus frame (`*(*VAR_UI_CONTEXT_PTR + OFF_UI_CONTEXT_MOUSE_FOCUS)`, the
+// CFrameScriptObject* `GetMouseFocus` returns) once per frame on the shared
+// WorldTick, and when it's a `unit`-attributed frame call the engine's FULL
+// mouseover setter (FUN_00492890) — 1:1 with hovering the unit's 3D model:
+// model highlight, mouseover tooltip, UPDATE_MOUSEOVER_UNIT, and the GUID slot.
+// Stomp-proof: the engine's own 3D-hover setter is event-driven, so nothing
+// overwrites the slot while the cursor is over UI.
+//
+// ── Clicks (the frame's own OnClick — scoped, native) ──
+//
+// Clicks are events, not state, so they belong on the frame's OnClick — but
+// ONLY on frames that opt in with a `type` attribute. When a `type*` attribute
+// is set we install a chained OnClick on that frame (protected, because OnClick
+// is Button-only). It mirrors retail's SecureActionButton_OnClick: resolve ONE
+// verb per click from the modifier/button-qualified `type` attribute, perform
+// it, done. No global hook, no handler on frames that never asked for one.
+//
+// Resolution (retail-style): the attribute is `[prefix]type[suffix]`, where the
+// prefix is the held modifiers ("alt-"/"ctrl-"/"shift-") and the suffix is the
+// button number (1=Left, 2=Right, …). So `type1`, `shift-type1`, `type` all
+// resolve via ReadModAttr's precedence. Verbs: `target` (with the engine's
+// default-interaction precedence — pending spell / cursor item cast/drop on the
+// unit instead of switching target), `assist`, `focus`, `spell` (reads the
+// `spell` attribute and casts it on the unit via our native C_Spell.CastAtUnit —
+// the unit's GUID goes straight to the cast dispatcher, no target juggling, and
+// ground-target spells land at the unit's feet), `item` (uses the `item`
+// attribute — a name/itemID/link via C_Item.UseItemByName with the unit as the
+// use target, or a "bag slot" string like "0 1" via UseContainerItem; the
+// deprecated `bag`/`slot` attributes also work), `macro` (from the
+// `macrotext`/`macro` attribute — prefers an addon RunMacro, else runs natively
+// via the stock ChatEdit_ParseText), `stopcasting`, `menu`/`togglemenu` (pops
+// the standard unit dropdown at the cursor via the addon's
+// ClassicAPI_ToggleUnitMenu). Actions call ordinary Lua globals where the entry
+// is the engine's (TargetUnit, IsAltKeyDown, …); where we own a C++ module the
+// dispatch goes straight to it, no Lua round-trip (Spell::AtUnit for `spell`,
+// Unit::Focus for `focus`). All run under the engine's protected OnClick.
+//
+// One verb per click is the point: because we own the click when a verb
+// resolves (and only then chain the previous handler), a configured `type1` no
+// longer runs *alongside* the addon's own conditional OnClick — that double
+// dispatch (our fixed "target" + pfUI's ClickAction) was the conflict. An addon
+// expresses all its click behavior as attributes; unconfigured clicks fall
+// through to its OnClick (e.g. a right-click menu).
+//
+// Ordering / clobbering: it chains the handler present when `type*` is set, so
+// set `type*` AFTER the frame's own `OnClick`. Addons that re-`SetScript`
+// `OnClick` later (pfUI does on every raid relayout) replace our closure — so
+// re-set `type*` after re-SetScript to recover. Re-wiring is safe: WireOnClick
+// re-wraps a clobbered (Lua) handler but skips its own C closure, so it never
+// double-chains. The frame must be a Button registered for the relevant clicks
+// (`RegisterForClicks`) — left is the Button default; right needs
+// `RegisterForClicks("RightButtonUp")`, which real unit frames do.
+//
+// `OnAttributeChanged` is a real SetScript-able handler: SetAttribute (not
+// SetAttributeNoHandler) fires it with `this` = frame, `arg1` = name, `arg2` =
+// value. Implemented by co-hooking the base-frame script-name resolver
+// (`FUN_FRAME_SCRIPT_RESOLVER`) and handing out an external per-frame cell for
+// that name — the `Tooltip::SetEvents` analog, applied to every frame.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "baselib/Ascii.h"
+#include "cursor/Info.h"
+#include "object/Resolve.h"
+#include "spell/AtCursor.h"
+#include "spell/AtUnit.h"
+#include "tick/WorldTick.h"
+#include "unit/Focus.h"
+#include "unit/Identity.h"
+
+#include <cctype>
+#include <cstdint>
+#include <cstdlib>
+#include <cstring>
+#include <string>
+#include <unordered_map>
+
+namespace Frame::Attributes {
+
+namespace {
+
+using ScriptFn_t = int(__fastcall *)(void *L);
+
+int CallScript(uintptr_t fn, void *L) {
+    return reinterpret_cast<ScriptFn_t>(fn)(L);
+}
+
+// ---- small string helpers --------------------------------------------------
+
+void LowerCopy(char *dst, const char *src, size_t n) {
+    size_t i = 0;
+    for (; src && src[i] && i + 1 < n; ++i)
+        dst[i] = static_cast<char>(std::tolower(static_cast<unsigned char>(src[i])));
+    dst[i] = '\0';
+}
+
+// Bounded, always-terminated copy (avoids the C4996 strncpy/strcpy warnings).
+void BoundedCopy(char *dst, const char *src, size_t n) {
+    size_t i = 0;
+    for (; src && src[i] && i + 1 < n; ++i)
+        dst[i] = src[i];
+    dst[i] = '\0';
+}
+
+// dst = tolower(a .. b .. c). Truncates at n-1.
+void Compose3Lower(char *dst, size_t n, const char *a, const char *b, const char *c) {
+    size_t i = 0;
+    const char *parts[3] = {a, b, c};
+    for (const char *s : parts)
+        for (; s && *s && i + 1 < n; ++s)
+            dst[i++] = static_cast<char>(std::tolower(static_cast<unsigned char>(*s)));
+    dst[i] = '\0';
+}
+
+// True if `lname` (already lowercase) is a click "type" action attribute: an
+// optional modifier prefix (alt-/ctrl-/shift-, any order/combo) followed by
+// "type" and an optional button digit — i.e. anything the click resolver
+// (ButtonSuffix + ReadModAttr) reads as a verb selector: type, type1..type5,
+// shift-type1, alt-ctrl-type2, … . This is the exact set WireOnClick must
+// (re)install for; keying the wiring off it (rather than a fixed
+// type/type1/type2 list) means a middle-click (type3) or modifier-only config
+// still installs the chained OnClick.
+bool IsTypeAttr(const char *lname) {
+    const char *p = lname;
+    for (bool advanced = true; advanced;) {
+        if (std::strncmp(p, "alt-", 4) == 0)        p += 4;
+        else if (std::strncmp(p, "ctrl-", 5) == 0)  p += 5;
+        else if (std::strncmp(p, "shift-", 6) == 0) p += 6;
+        else                                        advanced = false;
+    }
+    if (std::strncmp(p, "type", 4) != 0)
+        return false;
+    p += 4;
+    if (p[0] == '\0')
+        return true;                                     // "type"
+    return p[0] >= '1' && p[0] <= '5' && p[1] == '\0';   // "typeN"
+}
+
+// ---- attribute storage (in the Lua registry, keyed by the frame) -----------
+
+// Pushes the frame's attribute subtable onto the stack. Stored as
+// registry[frame] in the Lua registry (LUA_REGISTRYINDEX) rather than as a
+// field on the frame's own table — the registry is C-side and has no _G path,
+// so the store is invisible to `pairs(frame)` and can't be read or tampered
+// with from Lua, matching how retail keeps attributes C-side. With create=true,
+// lazily creates and stores it. Returns true iff a subtable is left on top;
+// false (nothing left on the stack) when absent and !create. 1.12 frames are
+// immortal, so the strong registry key never leaks.
+bool PushSub(void *L, int frameIdx, bool create) {
+    Game::Lua::PushValue(L, frameIdx);                  // [.., frame]  (key)
+    Game::Lua::RawGet(L, Game::Lua::REGISTRY_INDEX);    // [.., sub|nil]
+    if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_TABLE)
+        return true;                                    // [.., sub]
+    Game::Lua::SetTop(L, Game::Lua::GetTop(L) - 1);     // drop the nil -> [..]
+    if (!create)
+        return false;
+    Game::Lua::NewTable(L);                             // [.., sub]
+    Game::Lua::PushValue(L, frameIdx);                  // [.., sub, frame]  (key)
+    Game::Lua::PushValue(L, -2);                        // [.., sub, frame, sub]  (value)
+    Game::Lua::RawSet(L, Game::Lua::REGISTRY_INDEX);    // registry[frame] = sub -> [.., sub]
+    return true;
+}
+
+// Copies string attribute `lname` (already lowercase) of the frame at
+// frameIdx into buf. Returns true iff a string value was found. Restores the
+// stack.
+bool CopyAttr(void *L, int frameIdx, const char *lname, char *buf, size_t n) {
+    const int top = Game::Lua::GetTop(L);
+    bool ok = false;
+    if (PushSub(L, frameIdx, false)) {       // [.., sub]
+        const int si = Game::Lua::GetTop(L);
+        Game::Lua::PushString(L, lname);
+        Game::Lua::RawGet(L, si);            // [.., sub, val]
+        if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_STRING) {
+            const char *s = Game::Lua::ToString(L, -1);
+            if (s) {
+                BoundedCopy(buf, s, n);
+                ok = true;
+            }
+        }
+    }
+    Game::Lua::SetTop(L, top);
+    return ok;
+}
+
+// If the frame's attribute subtable has a non-nil value for keyLower, leave that
+// value on the stack top and return true; otherwise restore the stack and
+// return false.
+bool TryPushValue(void *L, int frameIdx, const char *keyLower) {
+    const int top = Game::Lua::GetTop(L);
+    if (PushSub(L, frameIdx, false)) {       // [.., sub]
+        const int si = Game::Lua::GetTop(L);
+        Game::Lua::PushString(L, keyLower);
+        Game::Lua::RawGet(L, si);            // [.., sub, val]
+        if (Game::Lua::Type(L, -1) != Game::Lua::TYPE_NIL) {
+            Game::Lua::Remove(L, si);        // [.., val]
+            return true;
+        }
+    }
+    Game::Lua::SetTop(L, top);
+    return false;
+}
+
+// Unit token → GUID goes through `Unit::Identity::GuidForToken` (engine
+// resolver + `"player"` fast-path, handling our focus / nameplateN / raw-GUID
+// extensions). For recognized tokens it never raises; unit attributes are
+// tokens by contract.
+
+// ---- Lua-global call helpers (used by the click dispatcher) -----------------
+//
+// The click dispatch mirrors retail's SecureActionButton_OnClick: it's C. It
+// performs engine actions by calling ordinary Lua globals (TargetUnit,
+// IsAltKeyDown, …) and our own actions by calling the C++ module directly
+// (Spell::AtUnit, Unit::Focus). Both run under the engine's protected OnClick
+// invocation, so a Lua error inside one is caught there (no crash).
+
+// The plain global-call primitives (push-if-function, call with no/one arg)
+// live in Game::Lua now (PushGlobalFunction / CallGlobal / CallGlobalString) —
+// shared with the other modules that dispatch to FrameXML globals by name. The
+// two shapes below are specific enough to stay here.
+
+// _G[name]() -> boolean (false if the global isn't a function). Distinct from
+// Game::Lua::CallGlobal in that it returns the call's boolean RESULT (used for
+// the IsAltKeyDown/IsShiftKeyDown modifier probes).
+bool CallBoolGlobal(void *L, const char *name) {
+    const int top = Game::Lua::GetTop(L);
+    bool r = false;
+    if (Game::Lua::PushGlobalFunction(L, name)) {
+        Game::Lua::Call(L, 0, 1);
+        r = Game::Lua::ToBoolean(L, -1) != 0;
+    }
+    Game::Lua::SetTop(L, top);
+    return r;
+}
+
+// _G[table][method](a, b) — two string args (null → nil, since PushString maps
+// NULL to nil), no results. Returns true iff the method resolved to a function
+// and got called. Used when the target is our own C_* function but the call must
+// cross the Lua boundary — e.g. C_Item.UseItemByName, whose bag walk does
+// SetTop(L, 0); going through lua_call gives it its own stack frame so that reset
+// clears only its frame, not the dispatcher's (a direct C++ call would wipe our
+// stack — the reason `spell`, which is stack-free, calls Spell::AtUnit directly
+// while `item` routes through here).
+bool CallTableFunc2Str(void *L, const char *table, const char *method,
+                       const char *a, const char *b) {
+    const int top = Game::Lua::GetTop(L);
+    bool called = false;
+    Game::Lua::PushString(L, table);
+    Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX);   // _G[table]
+    if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_TABLE) {
+        const int t = Game::Lua::GetTop(L);
+        Game::Lua::PushString(L, method);
+        Game::Lua::GetTable(L, t);                       // _G[table][method]
+        if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_FUNCTION) {
+            Game::Lua::PushString(L, a);
+            Game::Lua::PushString(L, b);
+            Game::Lua::Call(L, 2, 0);
+            called = true;
+        }
+    }
+    Game::Lua::SetTop(L, top);
+    return called;
+}
+
+// ---- macrotext execution (stock ChatEdit_ParseText, no addon dependency) ----
+//
+// 1.12 has no `RunMacroText`/`RunMacro` global — those are addon shims (pfUI
+// wraps `ChatEdit_ParseText`; SuperCleveRoidMacros ships its own `RunMacro`).
+// To run macro text without depending on an addon, we replicate pfUI's shim in
+// C: build a throwaway "edit box" whose `GetText` returns the line and whose
+// every other method is a harmless no-op (via an `__index` metamethod), then
+// hand it to the stock FrameXML `ChatEdit_ParseText(editBox, 1)` — the same
+// path the real chat box uses to dispatch a slash command / send a line.
+
+// GetText: returns upvalue(1), the captured line.
+int __fastcall MacroGetText_c(void *L) {
+    Game::Lua::PushValue(L, Game::Lua::UpvalueIndex(1));
+    return 1;
+}
+
+// A no-op standing in for any edit-box method the parser happens to call.
+int __fastcall MacroNoop_c(void *) { return 0; }
+
+// __index(tab, key): hand back the no-op so `editBox:AnyMethod()` is safe.
+int __fastcall MacroIndex_c(void *L) {
+    Game::Lua::PushCClosure(L, &MacroNoop_c, 0);
+    return 1;
+}
+
+// Runs a single macro line through the stock chat parser.
+void RunMacroLineC(void *L, const char *line, size_t len) {
+    if (len == 0) return;
+    const int top = Game::Lua::GetTop(L);
+
+    Game::Lua::NewTable(L);                    // fake editBox
+    const int obj = Game::Lua::GetTop(L);
+
+    Game::Lua::PushString(L, "GetText");       // obj.GetText = closure over line
+    Game::Lua::PushLString(L, line, static_cast<unsigned int>(len));
+    Game::Lua::PushCClosure(L, &MacroGetText_c, 1);
+    Game::Lua::SetTable(L, obj);
+
+    Game::Lua::NewTable(L);                     // metatable { __index = noop }
+    const int mt = Game::Lua::GetTop(L);
+    Game::Lua::PushString(L, "__index");
+    Game::Lua::PushCClosure(L, &MacroIndex_c, 0);
+    Game::Lua::SetTable(L, mt);
+
+    // No lua_setmetatable binding — use the Lua global.
+    if (Game::Lua::PushGlobalFunction(L, "setmetatable")) {
+        Game::Lua::PushValue(L, obj);
+        Game::Lua::PushValue(L, mt);
+        Game::Lua::Call(L, 2, 0);
+    }
+
+    if (Game::Lua::PushGlobalFunction(L, "ChatEdit_ParseText")) {
+        Game::Lua::PushValue(L, obj);
+        Game::Lua::PushNumber(L, 1);           // send = 1
+        Game::Lua::Call(L, 2, 0);
+    }
+
+    Game::Lua::SetTop(L, top);
+}
+
+// Runs macro text one line at a time — a real macro is line-delimited, and a
+// single ChatEdit_ParseText call only dispatches one command.
+void RunMacroTextC(void *L, const char *text) {
+    if (!text) return;
+    for (const char *p = text; *p;) {
+        const char *nl = p;
+        while (*nl && *nl != '\n') ++nl;
+        RunMacroLineC(L, p, static_cast<size_t>(nl - p));
+        p = (*nl == '\n') ? nl + 1 : nl;
+    }
+}
+
+// ---- mouse-focus poll (drives the native mouseover slot) -------------------
+
+// frame CFrameScriptObject* → current `unit` token, for the mouse-focus poll.
+// Keyed by the same pointer the engine stores at the mouse-focus slot. Single-
+// threaded (Lua + WorldTick on the main thread), so no synchronization needed.
+std::unordered_map<const void *, std::string> g_unitByFrame;
+
+// The last GUID *we* wrote into the mouseover slot. We only touch the slot on a
+// change of our own value, so when the cursor isn't over a unit frame (guid 0)
+// we never clobber the engine's own 3D mouseover.
+uint64_t g_lastSet = 0;
+
+const void *CurrentMouseFocus() {
+    const void *ctx = *reinterpret_cast<const void *const *>(
+        static_cast<uintptr_t>(Offsets::VAR_UI_CONTEXT_PTR));
+    if (ctx == nullptr)
+        return nullptr;
+    return *reinterpret_cast<const void *const *>(
+        reinterpret_cast<const uint8_t *>(ctx) + Offsets::OFF_UI_CONTEXT_MOUSE_FOCUS);
+}
+
+// The engine's real mouseover setter — `__stdcall(guidLo, guidHi, prevLo,
+// prevHi)`. Highlights the unit's model, builds the mouseover tooltip, fires
+// UPDATE_MOUSEOVER_UNIT, and writes the GUID slot; pass 0,0 for the optional
+// previous, and (0,0,0,0) to clear. Same address `Unit::Mouseover` co-hooks, so
+// calling it here goes through that hook (loss events keep firing correctly).
+void CallEngineMouseover(uint64_t guid) {
+    reinterpret_cast<void(__stdcall *)(uint32_t, uint32_t, uint32_t, uint32_t)>(
+        static_cast<uintptr_t>(Offsets::FUN_SET_MOUSEOVER_UNIT))(
+        static_cast<uint32_t>(guid), static_cast<uint32_t>(guid >> 32), 0, 0);
+}
+
+// True when the GUID resolves to a live unit/player object (loaded, in range).
+// False for an offline or far out-of-range party/raid member — the case the
+// engine mouseover setter skips the tooltip for. Same resolver Unit::Mouseover
+// uses for its unit test.
+bool GuidHasLiveUnit(uint64_t guid) {
+    if (guid == 0)
+        return false;
+    constexpr int kUnitOrPlayerMask =
+        (1 << Offsets::OBJECT_TYPE_UNIT) | (1 << Offsets::OBJECT_TYPE_PLAYER);
+    return Object::ByGuid(kUnitOrPlayerMask, guid, "ClassicAPI", 0) != nullptr;
+}
+
+// Build the mouseover tooltip for a unit with no live object, straight from the
+// party/raid roster. FUN_00529FE0 is the same unit-tooltip builder SetUnit and
+// the engine mouseover use; with no object it fills name/level/class + the
+// "Offline" line from the roster (verified: `GameTooltip:SetUnit("party1")`
+// works for an offline member). The engine's setter (FUN_00492890) gates this
+// call on a live object, so offline members get nothing — we do it here.
+void BuildRosterUnitTooltip(uint64_t guid) {
+    void *tooltip = *reinterpret_cast<void *const *>(
+        static_cast<uintptr_t>(Offsets::VAR_GAMETOOLTIP_OBJECT_PTR));
+    if (tooltip == nullptr)
+        return;
+
+    // Fire OnTooltipSetDefaultAnchor first, exactly as the engine mouseover
+    // setter (FUN_00492890) does before it builds — FrameXML's handler sets
+    // the tooltip's owner + anchor, which is what actually shows it. Without
+    // this, a rebuild after the tooltip was hidden on the previous leave has
+    // no owner and never re-appears (only a subsequent live-unit hover, which
+    // takes the engine's own anchor path, would). Use the self-contained
+    // invoker FUN_FRAME_INVOKE_SCRIPT, safe to call from the WorldTick.
+    const int anchorHandler = *reinterpret_cast<const int *>(
+        reinterpret_cast<uint8_t *>(tooltip) +
+        Offsets::OFF_TOOLTIP_SET_DEFAULT_ANCHOR_HANDLER);
+    if (anchorHandler != 0)
+        reinterpret_cast<void(__fastcall *)(int, void *)>(
+            static_cast<uintptr_t>(Offsets::FUN_FRAME_INVOKE_SCRIPT))(anchorHandler,
+                                                                      tooltip);
+
+    uint32_t packed[2] = {static_cast<uint32_t>(guid),
+                          static_cast<uint32_t>(guid >> 32)};
+    reinterpret_cast<void(__thiscall *)(void *, uint32_t *)>(
+        static_cast<uintptr_t>(Offsets::FUN_GAMETOOLTIP_BUILD_UNIT))(tooltip, packed);
+}
+
+void MouseoverTick() {
+    const void *focus = CurrentMouseFocus();
+
+    uint64_t guid = 0;
+    if (focus != nullptr) {
+        auto it = g_unitByFrame.find(focus);
+        if (it != g_unitByFrame.end())
+            guid = Unit::Identity::GuidForToken(
+                it->second.c_str()); // live — follows target changes
+    }
+
+    if (guid != g_lastSet) {
+        CallEngineMouseover(guid); // sets slot + highlight + tooltip + event
+        // Offline / far out-of-range party or raid member: the setter wrote the
+        // GUID slot but skipped the tooltip (no live object). Build it from the
+        // roster so hovering the frame still shows name / level / "Offline".
+        if (guid != 0 && !GuidHasLiveUnit(guid))
+            BuildRosterUnitTooltip(guid);
+        g_lastSet = guid;
+    }
+}
+
+// ---- click dispatch (the frame's own chained OnClick) ----------------------
+
+// Runs the chained-onto previous handler (upvalue 1), vanilla-style with no
+// args (it reads the `this`/`arg1` globals the engine set for this invocation).
+void ChainOld(void *L) {
+    if (Game::Lua::Type(L, Game::Lua::UpvalueIndex(1)) == Game::Lua::TYPE_FUNCTION) {
+        Game::Lua::PushValue(L, Game::Lua::UpvalueIndex(1));
+        Game::Lua::Call(L, 0, 0);
+    }
+}
+
+// Builds the modifier prefix ("alt-"/"ctrl-"/"shift-", in that order — retail's
+// order) from the live key state, e.g. "alt-shift-". Empty when none held.
+void BuildModifierPrefix(void *L, char *buf, size_t n) {
+    buf[0] = '\0';
+    size_t i = 0;
+    auto add = [&](const char *s) {
+        for (const char *p = s; *p && i + 1 < n; ++p)
+            buf[i++] = *p;
+        buf[i] = '\0';
+    };
+    if (CallBoolGlobal(L, "IsAltKeyDown"))     add("alt-");
+    if (CallBoolGlobal(L, "IsControlKeyDown")) add("ctrl-");
+    if (CallBoolGlobal(L, "IsShiftKeyDown"))   add("shift-");
+}
+
+// Button name -> attribute suffix (retail's convention: the button number).
+const char *ButtonSuffix(const char *btn) {
+    if (Ascii::EqualCI(btn, "RightButton"))  return "2";
+    if (Ascii::EqualCI(btn, "MiddleButton")) return "3";
+    if (Ascii::EqualCI(btn, "Button4"))      return "4";
+    if (Ascii::EqualCI(btn, "Button5"))      return "5";
+    return "1"; // LeftButton / unknown
+}
+
+// Resolves a modified attribute into `buf`. Precedence (practical subset of the
+// GetAttribute wildcard rules): prefix..name..suffix (e.g. "shift-type1"),
+// then name..suffix ("type1"), then name ("type"). So a plain `type1` still
+// applies under any modifier unless a modifier-specific attribute overrides it.
+bool ReadModAttr(void *L, int fi, const char *prefix, const char *name,
+                 const char *suffix, char *buf, size_t n) {
+    char key[128];
+    Compose3Lower(key, sizeof key, prefix, name, suffix);
+    if (CopyAttr(L, fi, key, buf, n)) return true;
+    Compose3Lower(key, sizeof key, "", name, suffix);
+    if (CopyAttr(L, fi, key, buf, n)) return true;
+    Compose3Lower(key, sizeof key, "", name, "");
+    return CopyAttr(L, fi, key, buf, n);
+}
+
+// Reads attribute `keyLower` as an int (stored as a number, or a numeric
+// string) into *out. Leaves the stack as it found it. Returns true on success.
+bool ReadAttrInt(void *L, int fi, const char *keyLower, int *out) {
+    bool ok = false;
+    if (TryPushValue(L, fi, keyLower)) {                 // value left on top
+        const int t = Game::Lua::Type(L, -1);
+        if (t == Game::Lua::TYPE_NUMBER) {
+            *out = static_cast<int>(Game::Lua::ToNumber(L, -1));
+            ok = true;
+        } else if (t == Game::Lua::TYPE_STRING) {
+            const char *s = Game::Lua::ToString(L, -1);
+            char *end = nullptr;
+            const long v = s ? std::strtol(s, &end, 10) : 0;
+            if (s && end != s) {
+                *out = static_cast<int>(v);
+                ok = true;
+            }
+        }
+        Game::Lua::SetTop(L, Game::Lua::GetTop(L) - 1);  // pop the peeked value
+    }
+    return ok;
+}
+
+// Numeric analog of ReadModAttr (prefix..name..suffix precedence).
+bool ReadModAttrInt(void *L, int fi, const char *prefix, const char *name,
+                    const char *suffix, int *out) {
+    char key[128];
+    Compose3Lower(key, sizeof key, prefix, name, suffix);
+    if (ReadAttrInt(L, fi, key, out)) return true;
+    Compose3Lower(key, sizeof key, "", name, suffix);
+    if (ReadAttrInt(L, fi, key, out)) return true;
+    Compose3Lower(key, sizeof key, "", name, "");
+    return ReadAttrInt(L, fi, key, out);
+}
+
+// Parses a "bag slot" string (two integers, e.g. "0 1") into bag/slot. Returns
+// false unless the whole string is exactly two integers, so a normal item name
+// or a bare itemID ("12345") falls through to the name path.
+bool ParseBagSlot(const char *s, int *bag, int *slot) {
+    char *end = nullptr;
+    const long b = std::strtol(s, &end, 10);
+    if (end == s) return false;                          // not a leading number
+    const char *p = end;
+    const long sl = std::strtol(p, &end, 10);
+    if (end == p) return false;                          // only one number
+    while (*end == ' ' || *end == '\t') ++end;
+    if (*end != '\0') return false;                      // trailing junk
+    *bag = static_cast<int>(b);
+    *slot = static_cast<int>(sl);
+    return true;
+}
+
+// _G[name](a, b) — two number args, no results. Returns true iff called.
+bool CallGlobalNum2(void *L, const char *name, double a, double b) {
+    const int top = Game::Lua::GetTop(L);
+    const bool called = Game::Lua::PushGlobalFunction(L, name);
+    if (called) {
+        Game::Lua::PushNumber(L, a);
+        Game::Lua::PushNumber(L, b);
+        Game::Lua::Call(L, 2, 0);
+    }
+    Game::Lua::SetTop(L, top);
+    return called;
+}
+
+// Performs the resolved `verb` on `unit` (a token attribute value, may be null).
+// Returns true if it owned the click (so the chained handler is skipped).
+bool DispatchVerb(void *L, int fi, const char *prefix, const char *suffix,
+                  const char *verb, const char *unit) {
+    if (Ascii::EqualCI(verb, "target")) {
+        if (!unit) return false;
+        // `unit="none"` clears the target (retail's SecureActionButton behavior).
+        if (Ascii::EqualCI(unit, "none")) {
+            Game::Lua::CallGlobal(L, "ClearTarget");
+            return true;
+        }
+        // Cursor / pending-spell take precedence, matching the engine's default
+        // unit interaction — cast the pending spell / drop the item on the unit
+        // instead of switching target. The two predicates are ours (direct C++);
+        // the actions are engine-only, so they go through the Lua globals (which
+        // are the engine's own entries, with token→GUID resolution).
+        if (Spell::AtCursor::IsPlacementActive())
+            Game::Lua::CallGlobalString(L, "SpellTargetUnit", unit);
+        else if (Cursor::Info::HasItem())
+            Game::Lua::CallGlobalString(L, "DropItemOnUnit", unit);
+        else
+            Game::Lua::CallGlobalString(L, "TargetUnit", unit);
+        return true;
+    }
+    if (Ascii::EqualCI(verb, "assist")) {
+        if (!unit) return false;
+        Game::Lua::CallGlobalString(L, "AssistUnit", unit);
+        return true;
+    }
+    if (Ascii::EqualCI(verb, "focus")) {
+        if (!unit) return false;
+        Unit::Focus::Set(Unit::Identity::GuidForToken(unit));
+        return true;
+    }
+    if (Ascii::EqualCI(verb, "spell")) {
+        if (!unit) return false;
+        char spell[128];
+        if (!ReadModAttr(L, fi, prefix, "spell", suffix, spell, sizeof spell))
+            return false;
+        Spell::AtUnit::CastByName(spell, unit);
+        return true;
+    }
+    if (Ascii::EqualCI(verb, "item")) {
+        char item[128];
+        int bag, slot;
+        if (ReadModAttr(L, fi, prefix, "item", suffix, item, sizeof item)) {
+            if (ParseBagSlot(item, &bag, &slot))
+                CallGlobalNum2(L, "UseContainerItem", bag, slot);
+            else
+                CallTableFunc2Str(L, "C_Item", "UseItemByName", item, unit);
+            return true;
+        }
+        // Deprecated form: no `item`, take the `bag` + `slot` attributes.
+        if (ReadModAttrInt(L, fi, prefix, "bag", suffix, &bag) &&
+            ReadModAttrInt(L, fi, prefix, "slot", suffix, &slot)) {
+            CallGlobalNum2(L, "UseContainerItem", bag, slot);
+            return true;
+        }
+        return false;
+    }
+    if (Ascii::EqualCI(verb, "macro")) {
+        char macro[512];
+        if (!ReadModAttr(L, fi, prefix, "macrotext", suffix, macro, sizeof macro) &&
+            !ReadModAttr(L, fi, prefix, "macro", suffix, macro, sizeof macro))
+            return false;
+        // Prefer an addon-provided RunMacro (SuperCleveRoidMacros, pfUI, …) — it
+        // handles named macros and extended macro text; fall back to the stock
+        // ChatEdit_ParseText path when no RunMacro global is present.
+        if (!Game::Lua::CallGlobalString(L, "RunMacro", macro))
+            RunMacroTextC(L, macro);
+        return true;
+    }
+    if (Ascii::EqualCI(verb, "stop") || Ascii::EqualCI(verb, "stopcasting")) {
+        Game::Lua::CallGlobal(L, "SpellStopCasting");
+        return true;
+    }
+    if (Ascii::EqualCI(verb, "menu") || Ascii::EqualCI(verb, "togglemenu")) {
+        if (!unit) return false;
+        // The unit dropdown is pure FrameXML work (UnitPopup + ToggleDropDown),
+        // so it lives in the !!!ClassicAPI addon; we just pop it at the cursor.
+        Game::Lua::CallGlobalString(L, "ClassicAPI_ToggleUnitMenu", unit);
+        return true;
+    }
+    // Unknown verb → not handled here; the chained handler runs.
+    return false;
+}
+
+// The chained OnClick handler. Upvalues: 1 = previous handler (or nil), 2 = the
+// frame (captured at install time, so we don't depend on the `this` global).
+// Resolves one verb per click from the (modifier/button) `type` attribute and
+// performs it — retail's one-action-per-click model. Only chains the previous
+// handler when we DIDN'T own the click, so a configured `type1` no longer runs
+// alongside the addon's own OnClick (that double-dispatch was the conflict).
+int __fastcall OnClick_c(void *L) {
+    const int top = Game::Lua::GetTop(L);
+    Game::Lua::PushValue(L, Game::Lua::UpvalueIndex(2)); // frame
+    const int fi = Game::Lua::GetTop(L);
+    bool handled = false;
+    if (Game::Lua::Type(L, fi) == Game::Lua::TYPE_TABLE) {
+        char btn[32] = {0};
+        Game::Lua::PushString(L, "arg1");
+        Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX);
+        if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_STRING) {
+            const char *b = Game::Lua::ToString(L, -1);
+            if (b)
+                BoundedCopy(btn, b, sizeof btn);
+        }
+        Game::Lua::SetTop(L, fi); // drop arg1, keep frame
+
+        const char *suffix = ButtonSuffix(btn);
+        char prefix[24];
+        BuildModifierPrefix(L, prefix, sizeof prefix);
+
+        char verb[32];
+        if (ReadModAttr(L, fi, prefix, "type", suffix, verb, sizeof verb)) {
+            char unit[128];
+            const bool haveUnit =
+                ReadModAttr(L, fi, prefix, "unit", suffix, unit, sizeof unit);
+            handled = DispatchVerb(L, fi, prefix, suffix, verb,
+                                   haveUnit ? unit : nullptr);
+        }
+    }
+    Game::Lua::SetTop(L, top);
+    if (!handled)
+        ChainOld(L); // let the frame's own OnClick handle unconfigured clicks
+    return 0;
+}
+
+// Installs OnClick as a closure over (previous handler, frame). Operates on
+// self at stack index 1. Raises if `self` isn't a Button (OnClick is a Button
+// script) — callers run it under PCall.
+//
+// Self-healing against clobbering: addons re-`SetScript("OnClick", …)` their
+// own handler (pfUI does it on every raid relayout via UpdateScripts), which
+// replaces our closure. So we re-wire whenever a `type*` attribute is (re)set,
+// but only when the current OnClick is a *Lua* handler (a real clobber) or nil
+// — if it's already a C function it's our own closure, and re-wrapping would
+// double-chain. `IsCFunction` cleanly distinguishes the two here (addon click
+// handlers are Lua; the only C-function OnClick we ever see is ours).
+int __fastcall WireOnClick(void *L) {
+    Game::Lua::SetTop(L, 1);                             // (self)
+    Game::Lua::PushString(L, "OnClick");                 // (self, name)
+    CallScript(Offsets::FUN_SCRIPT_FRAME_GETSCRIPT, L);  // (self, name, old)
+    if (Game::Lua::GetTop(L) < 3)                        // defensive
+        Game::Lua::PushNil(L);
+    Game::Lua::SetTop(L, 3);                             // (self, name, old|nil)
+    if (Game::Lua::Type(L, 3) == Game::Lua::TYPE_FUNCTION &&
+        Game::Lua::IsCFunction(L, 3) != 0)
+        return 0;                                        // already our closure
+    Game::Lua::PushValue(L, 1);                          // (self, name, old, self)
+    Game::Lua::PushCClosure(L, &OnClick_c, 2);           // upvalues (old, self)
+    CallScript(Offsets::FUN_SCRIPT_FRAME_SETSCRIPT, L);
+    return 0;
+}
+
+// ---- OnAttributeChanged script (settable via SetScript, like retail) --------
+//
+// Backport of the modern `OnAttributeChanged` widget script: SetAttribute (but
+// NOT SetAttributeNoHandler) fires the frame's OnAttributeChanged handler. 1.12
+// has no such script, so we make it SetScript/GetScript/HookScript-able the same
+// way Tooltip::SetEvents adds OnTooltipSet* — co-hook the frame script-name
+// resolver (FUN_FRAME_SCRIPT_RESOLVER, the base every frame type delegates to)
+// and, for the one name the engine doesn't know, hand back an external 8-byte
+// {handler, context} cell. Frames are immortal in 1.12 (no destroy), so a cell
+// keyed by the frame's C object pointer never goes stale.
+//
+// 1.12 passes script args as globals, not params (see OnClick_c reading arg1),
+// so we fire with `this` = frame (bound by the invoker), `arg1` = name and
+// `arg2` = the new value: `function() local name, value = arg1, arg2 … end`.
+
+struct AttrScriptSlot { uint32_t v[2]; }; // {handler, exec context}
+std::unordered_map<const void *, AttrScriptSlot> g_attrHandlers;
+
+uint32_t *AttrSlotFor(const void *frame, bool create) {
+    auto it = g_attrHandlers.find(frame);
+    if (it != g_attrHandlers.end())
+        return it->second.v;
+    if (!create)
+        return nullptr;
+    AttrScriptSlot &s = g_attrHandlers[frame]; // node-based → stable address
+    s.v[0] = 0;
+    s.v[1] = 0;
+    return s.v;
+}
+
+// Resolver co-hook. The engine's __thiscall(frame, name) is modelled as
+// __fastcall with a dummy edx — `name` lands on the first stack slot either way
+// (same trick as Tooltip::SetEvents). The original returns 0 for a name it
+// doesn't know; we then claim "OnAttributeChanged".
+using FrameResolver_t = int(__fastcall *)(void *frame, void *edx, const char *name);
+FrameResolver_t g_frameResolverOriginal = nullptr;
+
+int __fastcall FrameResolver_h(void *frame, void *edx, const char *name) {
+    const int slot = g_frameResolverOriginal(frame, edx, name);
+    if (slot != 0) // a real base-frame / subtype script — leave it
+        return slot;
+    if (Ascii::EqualCI(name, "onattributechanged"))
+        return reinterpret_cast<int>(AttrSlotFor(frame, /*create*/ true));
+    return 0;
+}
+
+const Game::HookAutoRegister _attrResolverHook{
+    Offsets::FUN_FRAME_SCRIPT_RESOLVER,
+    reinterpret_cast<void *>(&FrameResolver_h),
+    reinterpret_cast<void **>(&g_frameResolverOriginal)};
+
+// Fire OnAttributeChanged on `frame`, with arg1 = name and arg2 = the new value
+// (still at stack[3] in DoSet). Recursion-guarded so a handler that itself calls
+// SetAttribute doesn't loop. The invoker (FUN_FRAME_INVOKE_SCRIPT) binds `this`
+// and runs the handler under its own protected pcall; it doesn't restore the
+// stack top, so snapshot/restore around it (as Tooltip::SetEvents does).
+int g_firingAttr = 0;
+
+using InvokeAttrScript_t = void(__fastcall *)(uint32_t handler, void *frame);
+
+void FireAttributeChanged(void *L, void *frame, const char *name) {
+    if (frame == nullptr || g_firingAttr > 0)
+        return;
+    uint32_t *slot = AttrSlotFor(frame, /*create*/ false);
+    if (slot == nullptr || slot[0] == 0)
+        return;
+
+    const int savedTop = Game::Lua::GetTop(L);
+
+    // Snapshot the caller's arg1/arg2 first. SetAttribute can be called from
+    // inside a running script handler that still needs them, and the invoker
+    // below neither saves the globals nor restores the stack top — so we save
+    // (onto the stack, below anything the invoker pushes), overwrite, fire,
+    // then put them back. 1.12 passes handler args as globals, not params.
+    Game::Lua::PushString(L, "arg1");
+    Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX);        // [.., oldArg1]
+    Game::Lua::PushString(L, "arg2");
+    Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX);        // [.., oldArg1, oldArg2]
+    const int oldArg1 = savedTop + 1;
+    const int oldArg2 = savedTop + 2;
+
+    Game::Lua::PushString(L, "arg1");
+    Game::Lua::PushString(L, name);
+    Game::Lua::RawSet(L, Game::Lua::GLOBALS_INDEX);          // _G.arg1 = name
+    Game::Lua::PushString(L, "arg2");
+    if (savedTop >= 3)
+        Game::Lua::PushValue(L, 3);                          // the new value
+    else
+        Game::Lua::PushNil(L);
+    Game::Lua::RawSet(L, Game::Lua::GLOBALS_INDEX);          // _G.arg2 = value
+
+    ++g_firingAttr;
+    reinterpret_cast<InvokeAttrScript_t>(Offsets::FUN_FRAME_INVOKE_SCRIPT)(slot[0], frame);
+    --g_firingAttr;
+
+    // Restore arg1/arg2 from the snapshot (the fired handler may also have
+    // written them; the caller's values win).
+    Game::Lua::PushString(L, "arg1");
+    Game::Lua::PushValue(L, oldArg1);
+    Game::Lua::RawSet(L, Game::Lua::GLOBALS_INDEX);
+    Game::Lua::PushString(L, "arg2");
+    Game::Lua::PushValue(L, oldArg2);
+    Game::Lua::RawSet(L, Game::Lua::GLOBALS_INDEX);
+
+    Game::Lua::SetTop(L, savedTop);
+}
+
+// ---- the methods -----------------------------------------------------------
+
+// Enables the frame's mouse so it can become the mouse-focus (a bare frame
+// otherwise never registers as hovered). Operates on self at index 1.
+void EnableFrameMouse(void *L) {
+    Game::Lua::SetTop(L, 1); // (self)
+    Game::Lua::PushBoolean(L, 1);
+    CallScript(Offsets::FUN_SCRIPT_FRAME_ENABLEMOUSE, L);
+}
+
+int DoSet(void *L, bool fireHandler) { // (self, name, value)
+    if (!Game::Lua::IsString(L, 2)) {
+        Game::Lua::Error(L, "Usage: frame:SetAttribute(\"name\", value)");
+        return 0;
+    }
+    char lname[256];
+    LowerCopy(lname, Game::Lua::ToString(L, 2), sizeof lname);
+
+    if (PushSub(L, 1, true)) {               // [.., sub]
+        const int si = Game::Lua::GetTop(L);
+        Game::Lua::PushString(L, lname);     // [.., sub, key]
+        Game::Lua::PushValue(L, 3);          // [.., sub, key, value]  (nil if absent)
+        Game::Lua::RawSet(L, si);            // sub[lname] = value
+        Game::Lua::SetTop(L, si - 1);        // drop sub
+    }
+
+    const bool isString = Game::Lua::Type(L, 3) == Game::Lua::TYPE_STRING;
+
+    // `unit` drives the mouseover binding: index it by the frame's C object
+    // (the key the mouse-focus poll uses) and enable its mouse so it can be
+    // hovered.
+    if (std::strcmp(lname, "unit") == 0) {
+        void *obj = Game::Lua::ResolveObject(L, 1);
+        if (obj != nullptr) {
+            if (isString) {
+                const char *tok = Game::Lua::ToString(L, 3);
+                const bool isNew = g_unitByFrame.find(obj) == g_unitByFrame.end();
+                g_unitByFrame[obj] = tok ? tok : "";
+                if (isNew)
+                    EnableFrameMouse(L);
+            } else {
+                g_unitByFrame.erase(obj);
+            }
+        }
+    }
+    // A `type*` attribute makes the frame a clickable unit button: (re)install
+    // the chained OnClick (PCall-guarded — OnClick is Button-only). WireOnClick
+    // is idempotent and self-healing, so calling it on every `type*` set both
+    // avoids double-chaining and reinstalls after an addon clobbered our
+    // OnClick — set `type*` again after re-SetScript to recover. The handler
+    // reads all the attributes fresh at click time. IsTypeAttr covers every
+    // form the resolver reads (type, typeN, modifier-prefixed), so a middle-
+    // click or modifier-only binding still wires.
+    else if (IsTypeAttr(lname) && isString) {
+        Game::Lua::PushCClosure(L, &WireOnClick, 0);
+        Game::Lua::PushValue(L, 1); // arg = self
+        Game::Lua::PCall(L, 1, 0, 0); // ignore errors (non-Button frame)
+    }
+
+    if (fireHandler)
+        FireAttributeChanged(L, Game::Lua::ResolveObject(L, 1), lname);
+    return 0;
+}
+
+int __fastcall Script_SetAttribute(void *L) { return DoSet(L, /*fireHandler*/ true); }
+int __fastcall Script_SetAttributeNoHandler(void *L) { return DoSet(L, /*fireHandler*/ false); }
+
+// `cleared = frame:ClearAttribute("name")` — retail (11.2.0) attribute removal;
+// `cleared` is true iff the attribute was set (and is now gone). Routes through
+// DoSet's nil-value path so it also drops a `unit` mouseover binding, but does
+// NOT fire OnAttributeChanged — verified against retail (a live 12.0 test showed
+// ClearAttribute firing no handler, unlike SetAttribute).
+int __fastcall Script_ClearAttribute(void *L) {
+    if (!Game::Lua::IsString(L, 2)) {
+        Game::Lua::Error(L, "Usage: frame:ClearAttribute(\"name\")");
+        return 0;
+    }
+    char lname[256];
+    LowerCopy(lname, Game::Lua::ToString(L, 2), sizeof lname);
+
+    const bool existed = TryPushValue(L, 1, lname); // leaves the value on top if set
+    if (existed)
+        Game::Lua::SetTop(L, Game::Lua::GetTop(L) - 1); // drop the peeked value
+
+    Game::Lua::SetTop(L, 2);   // (self, name)
+    Game::Lua::PushNil(L);     // (self, name, nil) → value = nil clears the key
+    DoSet(L, /*fireHandler*/ false); // retail ClearAttribute fires no OnAttributeChanged
+
+    Game::Lua::PushBool(L, existed);
+    return 1;
+}
+
+int __fastcall Script_GetAttribute(void *L) {
+    if (!Game::Lua::IsString(L, 2)) {
+        Game::Lua::Error(L, "Usage: frame:GetAttribute(\"name\")");
+        return 0;
+    }
+    // 3-arg form: (prefix, name, suffix) with wildcard precedence.
+    if (Game::Lua::GetTop(L) >= 4 && Game::Lua::IsString(L, 3)) {
+        const char *pfx = Game::Lua::IsString(L, 2) ? Game::Lua::ToString(L, 2) : "";
+        const char *nm = Game::Lua::ToString(L, 3);
+        const char *sfx = Game::Lua::IsString(L, 4) ? Game::Lua::ToString(L, 4) : "";
+        char key[256];
+        Compose3Lower(key, sizeof key, pfx, nm, sfx);
+        if (TryPushValue(L, 1, key)) return 1;
+        Compose3Lower(key, sizeof key, "*", nm, sfx);
+        if (TryPushValue(L, 1, key)) return 1;
+        Compose3Lower(key, sizeof key, pfx, nm, "*");
+        if (TryPushValue(L, 1, key)) return 1;
+        Compose3Lower(key, sizeof key, "*", nm, "*");
+        if (TryPushValue(L, 1, key)) return 1;
+        Compose3Lower(key, sizeof key, "", nm, "");
+        if (TryPushValue(L, 1, key)) return 1;
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+
+    char lname[256];
+    LowerCopy(lname, Game::Lua::ToString(L, 2), sizeof lname);
+    if (TryPushValue(L, 1, lname))
+        return 1;
+    Game::Lua::PushNil(L);
+    return 1;
+}
+
+// ---- registration ----------------------------------------------------------
+
+const Game::Lua::FrameMethodEntry g_frameMethods[] = {
+    {"SetAttribute", &Script_SetAttribute},
+    {"SetAttributeNoHandler", &Script_SetAttributeNoHandler},
+    {"ClearAttribute", &Script_ClearAttribute},
+    {"GetAttribute", &Script_GetAttribute},
+};
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterFrameMethods(
+        reinterpret_cast<void *>(Offsets::VAR_FRAME_METHOD_REGISTRY),
+        g_frameMethods,
+        static_cast<int>(sizeof(g_frameMethods) / sizeof(g_frameMethods[0])));
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+const Tick::WorldTick::AutoSubscribe _tick{&MouseoverTick};
+
+} // namespace
+
+} // namespace Frame::Attributes

src/frame/Modern.cpp

@@ -26,6 +26,12 @@
 //   - `region:SetSize(w, h)` / `region:GetSize()` — registered on the
 //     REGION base method registry, so they resolve on frames, buttons,
 //     textures, fontstrings — everything.
+//   - `region:IsMouseOver([top, bottom, left, right])` — cursor-in-rect
+//     test with optional per-edge offsets, also on the REGION registry.
+//   - `region:GetRect()` — left, bottom, width, height, composed from the
+//     engine's Region getters. Also on the REGION registry.
+//   - `region:IsDragging()` — true while the region is the frame currently
+//     being moved/sized. Reads the engine's global drag target.
 //   - `frame:SetShown(shown)` — Show/Hide are per-branch script functions
 //     (each with its own object typecheck), so SetShown is registered
 //     separately on Frame / Texture / FontString with matching delegates.
@@ -34,6 +40,9 @@
 //   - `frame:HookScript(scriptType, handler)` — absent in vanilla
 //     entirely. Chains after any existing handler and invokes `handler`
 //     with modern positional args (see the implementation comment).
+//   - `frame:GetEffectiveAlpha()` — own alpha × the parent chain's, the
+//     product WoW composites at render time. Frame-scoped (matches
+//     GetAlpha); walks the parents via the engine's own getters.
 //
 // Implementation style: each new method delegates to the ENGINE's own
 // Script_* implementations by reshaping the Lua stack and calling them
@@ -83,6 +92,119 @@ int __fastcall Script_GetSize(void *L) {
     return 2;
 }
 
+// ---- IsMouseOver (Region base — all region types) --------------------------
+
+// `region:IsMouseOver([topOffset, bottomOffset, leftOffset, rightOffset])` —
+// true when the cursor is within the region's rect, each edge optionally
+// shifted by the matching offset (added to that edge, modern semantics:
+// +top/-bottom/-left/+right enlarges). Vanilla addons have always done this
+// in Lua as MouseIsOver(); we register it as the native Region method later
+// clients expose.
+//
+// The math mirrors the engine exactly: GetLeft/Right/Top/Bottom (Region
+// registry, all types) and GetCursorPosition both return values scaled by the
+// same k = FUN_0041ad70()*DAT_007ffd68 factor, but the rect getters also
+// divide by the region's effective scale — so dividing the cursor by that same
+// effective scale (read from obj+0x7C, the field GetLeft/GetEffectiveScale
+// themselves read) puts both in the region's logical space. A getter returns
+// nil for an unpositioned region → we report false.
+
+// Calls a Region getter that returns one number; false if it pushed nil/none.
+bool CallRegionNumber(void *L, uintptr_t fn, double *out) {
+    Game::Lua::SetTop(L, 1); // (self)
+    CallScript(fn, L);       // (self, value | nil)
+    if (!Game::Lua::IsNumber(L, 2))
+        return false;
+    *out = Game::Lua::ToNumber(L, 2);
+    return true;
+}
+
+int __fastcall Script_IsMouseOver(void *L) {
+    // Offsets first — the stack gets reshaped by the delegated getters.
+    const double offTop = Game::Lua::IsNumber(L, 2) ? Game::Lua::ToNumber(L, 2) : 0.0;
+    const double offBottom = Game::Lua::IsNumber(L, 3) ? Game::Lua::ToNumber(L, 3) : 0.0;
+    const double offLeft = Game::Lua::IsNumber(L, 4) ? Game::Lua::ToNumber(L, 4) : 0.0;
+    const double offRight = Game::Lua::IsNumber(L, 5) ? Game::Lua::ToNumber(L, 5) : 0.0;
+
+    void *obj = Game::Lua::ResolveObject(L, 1);
+    if (obj == nullptr) {
+        Game::Lua::PushBool(L, false);
+        return 1;
+    }
+    const float effScale = *reinterpret_cast<const float *>(
+        reinterpret_cast<const uint8_t *>(obj) + Offsets::OFF_REGION_EFFECTIVE_SCALE);
+
+    double left, right, top, bottom;
+    if (effScale == 0.0f ||
+        !CallRegionNumber(L, Offsets::FUN_SCRIPT_REGION_GETLEFT, &left) ||
+        !CallRegionNumber(L, Offsets::FUN_SCRIPT_REGION_GETRIGHT, &right) ||
+        !CallRegionNumber(L, Offsets::FUN_SCRIPT_REGION_GETTOP, &top) ||
+        !CallRegionNumber(L, Offsets::FUN_SCRIPT_REGION_GETBOTTOM, &bottom)) {
+        Game::Lua::PushBool(L, false); // no resolved rect
+        return 1;
+    }
+
+    Game::Lua::SetTop(L, 0);
+    CallScript(Offsets::FUN_SCRIPT_GETCURSORPOSITION, L); // (x, y)
+    const double x = Game::Lua::ToNumber(L, 1) / effScale;
+    const double y = Game::Lua::ToNumber(L, 2) / effScale;
+
+    left += offLeft;
+    right += offRight;
+    top += offTop;
+    bottom += offBottom;
+
+    const bool inside = x >= left && x <= right && y >= bottom && y <= top;
+    Game::Lua::PushBool(L, inside);
+    return 1;
+}
+
+// ---- GetRect (Region base — all region types) ------------------------------
+
+// `region:GetRect()` → left, bottom, width, height. Composed from the
+// engine's own Region getters (so all UI-scale conversion is its code).
+// Matches retail: returns nothing for a region with no resolved rect —
+// gated on GetLeft, which pushes nil when the position isn't resolved (a
+// size-only region with no anchor has width/height but no rect).
+int __fastcall Script_GetRect(void *L) {
+    double left, bottom, width, height;
+    if (!CallRegionNumber(L, Offsets::FUN_SCRIPT_REGION_GETLEFT, &left))
+        return 0;
+    CallRegionNumber(L, Offsets::FUN_SCRIPT_REGION_GETBOTTOM, &bottom);
+    CallRegionNumber(L, Offsets::FUN_SCRIPT_REGION_GETWIDTH, &width);
+    CallRegionNumber(L, Offsets::FUN_SCRIPT_REGION_GETHEIGHT, &height);
+    Game::Lua::SetTop(L, 1);
+    Game::Lua::PushNumber(L, left);
+    Game::Lua::PushNumber(L, bottom);
+    Game::Lua::PushNumber(L, width);
+    Game::Lua::PushNumber(L, height);
+    return 4;
+}
+
+// ---- IsDragging (Region base — all region types) ---------------------------
+
+// `region:IsDragging()` — true while this region is the frame currently
+// being moved/sized (StartMoving/StartSizing active, before
+// StopMovingOrSizing). The engine tracks a single drag target in the global
+// UI context at +0xCFC; StopMovingOrSizing itself gates on
+// `context+0xCFC == self`, which is exactly this predicate. Reading the
+// global context (rather than self+0xA0) keeps it correct for non-frame
+// regions — a texture/fontstring self can never match the frame stored
+// there, so it reports false, as it should.
+int __fastcall Script_IsDragging(void *L) {
+    void *self = Game::Lua::ResolveObject(L, 1);
+    void *ctx = *reinterpret_cast<void *const *>(
+        static_cast<uintptr_t>(Offsets::VAR_UI_CONTEXT_PTR));
+    void *dragTarget =
+        ctx != nullptr
+            ? *reinterpret_cast<void *const *>(
+                  reinterpret_cast<const uint8_t *>(ctx) +
+                  Offsets::OFF_UI_CONTEXT_DRAG_TARGET)
+            : nullptr;
+    Game::Lua::PushBool(L, self != nullptr && self == dragTarget);
+    return 1;
+}
+
 // ---- SetShown (per-branch Show/Hide delegates) -----------------------------
 
 // `object:SetShown(shown)` — any falsy value hides, truthy shows,
@@ -95,6 +217,33 @@ int __fastcall Script_SetShown(void *L) {
     return 0;
 }
 
+// ---- GetEffectiveAlpha (Frame) ---------------------------------------------
+
+// `frame:GetEffectiveAlpha()` — the frame's own alpha times every
+// ancestor's alpha, i.e. the product WoW composites at render time (fading
+// UIParent fades all children). Vanilla exposes only GetAlpha (own alpha);
+// we walk self → parent → … via the engine's own GetAlpha (Frame) and
+// GetParent (Region), so no field offsets or scale math are re-derived. The
+// iteration cap is a defensive guard against a pathological chain (WoW frame
+// trees are shallow; the loop normally ends when GetParent returns nil at
+// the top of the tree).
+int __fastcall Script_GetEffectiveAlpha(void *L) {
+    Game::Lua::SetTop(L, 1); // (obj) = self
+    double eff = 1.0;
+    for (int guard = 0; guard < 128; ++guard) {
+        CallScript(Offsets::FUN_SCRIPT_FRAME_GETALPHA, L); // (obj, alpha)
+        eff *= Game::Lua::ToNumber(L, 2);
+        Game::Lua::SetTop(L, 1);                             // (obj)
+        CallScript(Offsets::FUN_SCRIPT_REGION_GETPARENT, L); // (obj, parent|nil)
+        if (Game::Lua::Type(L, 2) == Game::Lua::TYPE_NIL)
+            break;
+        Game::Lua::Remove(L, 1); // drop obj → (parent) becomes index 1
+    }
+    Game::Lua::SetTop(L, 0);
+    Game::Lua::PushNumber(L, eff);
+    return 1;
+}
+
 // ---- SetResizeBounds (Frame) -----------------------------------------------
 
 // `frame:SetResizeBounds(minWidth, minHeight [, maxWidth, maxHeight])` —
@@ -274,6 +423,9 @@ const Game::HookAutoRegister _setPointHook{
 const Game::Lua::FrameMethodEntry g_regionMethods[] = {
     {"SetSize", &Script_SetSize},
     {"GetSize", &Script_GetSize},
+    {"IsMouseOver", &Script_IsMouseOver},
+    {"GetRect", &Script_GetRect},
+    {"IsDragging", &Script_IsDragging},
 };
 
 const Game::Lua::FrameMethodEntry g_frameMethods[] = {
@@ -282,6 +434,7 @@ const Game::Lua::FrameMethodEntry g_frameMethods[] = {
     {"SetResizeBounds", &Script_SetResizeBounds},
     {"HookScript", &Script_HookScript},
     {"IsEventRegistered", &Script_IsEventRegistered},
+    {"GetEffectiveAlpha", &Script_GetEffectiveAlpha},
 };
 
 const Game::Lua::FrameMethodEntry g_textureMethods[] = {

src/frame/MouseFoci.cpp

@@ -0,0 +1,211 @@
+// 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/>.
+
+// `GetMouseFoci()` -> table of every frame under the cursor, top-first.
+//
+// Modern WoW exposes GetMouseFoci() alongside GetMouseFocus(), with the
+// invariant `GetMouseFocus() == GetMouseFoci()[1]`. Vanilla stores only the
+// single topmost focus — Script_GetMouseFocus (0x0048DF40) reads
+// `*(*VAR_UI_CONTEXT_PTR + OFF_UI_CONTEXT_MOUSE_FOCUS)` and there is no stored
+// stack — so this is a native reimplementation of the frame-stack walk
+// Blizzard_DebugTools does in Lua (`EnumerateFrames` + `IsMouseOver`):
+//
+//   1. Walk the engine frame list (the same one Script_EnumerateFrames
+//      0x00705F60 iterates): head at `*(ctx + OFF_UI_CONTEXT_FRAME_LIST_HEAD)`,
+//      each frame's next at `+OFF_FRAME_ENUM_NEXT`, a low-bit-set / null node
+//      ends it.
+//   2. Keep frames that are visible + mouse-enabled and whose rect contains the
+//      cursor (hit-test mirrors Frame::Modern's IsMouseOver: Region getters +
+//      cursor / effective-scale).
+//   3. Order top-first by strata rank then frame level.
+//   4. Force index 1 to be the engine's stored focus so the documented
+//      invariant holds exactly, regardless of how our sort tie-breaks.
+//
+// Pure query — no hooks, registered like GetMouseFocus.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "ui/FrameObject.h"
+
+#include <algorithm>
+#include <cstdint>
+#include <cstring>
+#include <vector>
+
+namespace Frame::MouseFoci {
+
+namespace {
+
+using ScriptFn_t = int(__fastcall *)(void *L);
+
+int CallScript(uintptr_t fn, void *L) {
+    return reinterpret_cast<ScriptFn_t>(fn)(L);
+}
+
+// The UI context is a pointer stored at VAR_UI_CONTEXT_PTR (null pre-world).
+void *UIContext() {
+    return *reinterpret_cast<void *const *>(
+        static_cast<uintptr_t>(Offsets::VAR_UI_CONTEXT_PTR));
+}
+
+// Strata name -> draw rank, low (behind) to high (on top). Unknown -> 0.
+int StrataRank(const char *s) {
+    if (s == nullptr)
+        return 0;
+    static const struct {
+        const char *name;
+        int rank;
+    } kStrata[] = {
+        {"WORLD", 0},      {"BACKGROUND", 1},        {"LOW", 2},
+        {"MEDIUM", 3},     {"HIGH", 4},              {"DIALOG", 5},
+        {"FULLSCREEN", 6}, {"FULLSCREEN_DIALOG", 7}, {"TOOLTIP", 8},
+    };
+    for (const auto &e : kStrata)
+        if (std::strcmp(s, e.name) == 0)
+            return e.rank;
+    return 0;
+}
+
+// Region getter that pushes one number, called with `self` at Lua idx 1.
+// Returns false when it pushed nil/none (unresolved rect).
+bool SelfNumber(void *L, uintptr_t fn, double *out) {
+    Game::Lua::SetTop(L, 1); // (self)
+    CallScript(fn, L);       // (self, value | nil)
+    if (!Game::Lua::IsNumber(L, 2))
+        return false;
+    *out = Game::Lua::ToNumber(L, 2);
+    return true;
+}
+
+// Boolean predicate (IsVisible / IsMouseEnabled), `self` at Lua idx 1.
+bool SelfBool(void *L, uintptr_t fn) {
+    Game::Lua::SetTop(L, 1);
+    CallScript(fn, L);
+    return Game::Lua::ToBoolean(L, 2) != 0;
+}
+
+struct Cursor {
+    double x, y;
+};
+
+// GetCursorPosition and the Region rect getters share the same scale factor;
+// dividing the cursor by the frame's effective scale (the field GetLeft/etc.
+// themselves divide by) puts both in the frame's logical space. Mirrors
+// Frame::Modern's IsMouseOver exactly.
+Cursor ReadCursor(void *L) {
+    Game::Lua::SetTop(L, 0);
+    CallScript(Offsets::FUN_SCRIPT_GETCURSORPOSITION, L); // (x, y)
+    return Cursor{Game::Lua::ToNumber(L, 1), Game::Lua::ToNumber(L, 2)};
+}
+
+// With `self` at Lua idx 1, is the cursor within the frame's rect?
+bool CursorOverSelf(void *L, void *obj, const Cursor &cur) {
+    const float effScale = *reinterpret_cast<const float *>(
+        reinterpret_cast<const uint8_t *>(obj) + Offsets::OFF_REGION_EFFECTIVE_SCALE);
+    if (effScale == 0.0f)
+        return false; // unpositioned region — no rect
+    double left, right, top, bottom;
+    if (!SelfNumber(L, Offsets::FUN_SCRIPT_REGION_GETLEFT, &left) ||
+        !SelfNumber(L, Offsets::FUN_SCRIPT_REGION_GETRIGHT, &right) ||
+        !SelfNumber(L, Offsets::FUN_SCRIPT_REGION_GETTOP, &top) ||
+        !SelfNumber(L, Offsets::FUN_SCRIPT_REGION_GETBOTTOM, &bottom))
+        return false;
+    const double x = cur.x / effScale;
+    const double y = cur.y / effScale;
+    return x >= left && x <= right && y >= bottom && y <= top;
+}
+
+struct Hit {
+    void *obj;
+    int strata;
+    int level;
+};
+
+int __fastcall Script_GetMouseFoci(void *L) {
+    void *ctx = UIContext();
+    Game::Lua::SetTop(L, 0);
+    if (ctx == nullptr) {
+        Game::Lua::NewTable(L); // pre-world → empty table
+        return 1;
+    }
+
+    // The engine's authoritative topmost focus — the frame GetMouseFocus
+    // returns. Forced to index 1 below.
+    void *focus = *reinterpret_cast<void *const *>(
+        reinterpret_cast<uint8_t *>(ctx) + Offsets::OFF_UI_CONTEXT_MOUSE_FOCUS);
+
+    const Cursor cur = ReadCursor(L);
+
+    std::vector<Hit> hits;
+    void *node = *reinterpret_cast<void *const *>(
+        reinterpret_cast<uint8_t *>(ctx) + Offsets::OFF_UI_CONTEXT_FRAME_LIST_HEAD);
+    while (node != nullptr && (reinterpret_cast<uintptr_t>(node) & 1) == 0) {
+        // Read the next link before any Lua work (the walk is engine-list
+        // based, independent of the Lua stack, but this keeps it obvious).
+        void *next = *reinterpret_cast<void *const *>(
+            reinterpret_cast<uint8_t *>(node) + Offsets::OFF_FRAME_ENUM_NEXT);
+
+        Game::Lua::SetTop(L, 0);
+        UI::FrameObject::Push(L, node); // (self)
+
+        if (SelfBool(L, Offsets::FUN_SCRIPT_FRAME_IS_VISIBLE) &&
+            SelfBool(L, Offsets::FUN_SCRIPT_FRAME_IS_MOUSE_ENABLED) &&
+            CursorOverSelf(L, node, cur)) {
+            Game::Lua::SetTop(L, 1);
+            CallScript(Offsets::FUN_SCRIPT_FRAME_GET_STRATA, L); // (self, strata)
+            const int rank = StrataRank(Game::Lua::ToString(L, 2));
+            const int level = *reinterpret_cast<const int *>(
+                reinterpret_cast<uint8_t *>(node) + Offsets::OFF_FRAME_LEVEL);
+            hits.push_back(Hit{node, rank, level});
+        }
+
+        node = next;
+    }
+
+    // Top-first: higher strata, then higher level within a strata.
+    std::sort(hits.begin(), hits.end(), [](const Hit &a, const Hit &b) {
+        if (a.strata != b.strata)
+            return a.strata > b.strata;
+        return a.level > b.level;
+    });
+
+    // Order the frames, forcing GetMouseFocus() to be [1] so the invariant
+    // holds by construction (focus may be a frame our rect test skips, e.g.
+    // the WorldFrame, or a same-strata/level tie our sort orders differently).
+    std::vector<void *> ordered;
+    ordered.reserve(hits.size() + 1);
+    if (focus != nullptr)
+        ordered.push_back(focus);
+    for (const Hit &h : hits)
+        if (h.obj != focus)
+            ordered.push_back(h.obj);
+
+    Game::Lua::SetTop(L, 0);
+    Game::Lua::NewTable(L); // result at idx 1
+    for (size_t i = 0; i < ordered.size(); ++i) {
+        Game::Lua::PushNumber(L, static_cast<double>(i + 1));
+        UI::FrameObject::Push(L, ordered[i]);
+        Game::Lua::RawSet(L, 1); // result[i+1] = frame
+    }
+    return 1;
+}
+
+void Register() {
+    Game::Lua::RegisterGlobalFunction("GetMouseFoci", &Script_GetMouseFoci);
+}
+
+const Game::ModuleAutoRegister _autoreg{&Register};
+
+} // namespace
+
+} // namespace Frame::MouseFoci

src/frame/ScriptArgs.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/>.
+
+// Modern positional script arguments — make every frame-script handler
+// receive `(self, arg1..argN)` the way later clients do, on top of the
+// vanilla `this`/`arg1`/`event` globals.
+//
+//   frame:SetScript("OnMouseWheel", function()            print(this, arg1) end)  -- vanilla
+//   frame:SetScript("OnMouseWheel", function(self, delta)  print(self, delta) end)  -- modern
+//
+// Vanilla ALWAYS invokes a script handler with ZERO Lua arguments: the two
+// runners the engine funnels every dispatch through — FUN_FRAME_INVOKE_SCRIPT
+// (no-arg scripts) and FUN_FRAME_RUN_SCRIPT_ARGS (scripts with values) — set
+// the `this`/`arg1..argN` globals and then `lua_pcall(handler, /*nargs*/0)`.
+// So `function(self, delta)` gets nothing today.
+//
+// We co-hook both runners and REPLACE their pcall tail: keep setting the same
+// globals (so vanilla handlers reading `this`/`arg1` keep working — this is
+// purely additive; Lua silently drops the extra positional args a zero-param
+// handler doesn't declare), but push `self` + `arg1..argN` as real arguments
+// and `pcall` with `nargs = 1 + N`. The reimplementation mirrors the engine's
+// message-handler errfunc, but saves the clobbered globals on the Lua stack
+// (not registry refs like the engine) so an out-of-memory longjmp mid-push
+// unwinds them for free — no leaked refs, no per-call ref churn. See RunModern.
+//
+// Convention: `(self, arg1..argN)` for every script, plus `event` inserted as
+// the first positional for OnEvent — `(self, event, arg1..argN)` — matching
+// retail (and Frame::Modern's HookScript). An OnEvent dispatch is detected
+// structurally at the runner: the handler ref being invoked equals the frame's
+// OnEvent slot handler (frame+OFF_FRAME_ONEVENT_SLOT). This is exact — each
+// SetScript creates a distinct ref, so a function bound to two scripts still
+// differs per slot — so no fragile "are we mid event-dispatch" flag is needed.
+//
+// Runtime switch, default OFF (opt-in): `SetModernScriptArgs(true)` enables it,
+// `GetModernScriptArgs()` reads the state. While disabled both detours are a
+// straight passthrough to the original runner (zero reimplementation risk).
+// Opt-in because this lands on the hottest Lua path in the engine
+// (FUN_FRAME_RUN_SCRIPT_ARGS fires for every OnUpdate frame).
+
+#include "Game.h"
+#include "Offsets.h"
+
+#include <cstdint>
+
+namespace Frame::ScriptArgs {
+
+namespace {
+
+// Runtime switch. Default OFF (opt-in). When false, both detours tail-call the
+// original runner unchanged (exact vanilla behavior, no reimplementation risk).
+bool g_enabled = false;
+
+// Engine cap: the runner stops setting arg globals at index 19 (arg1..arg19).
+constexpr int kMaxArgs = 19;
+
+// --- raw engine primitives not exposed via Game::Lua -----------------------
+// lua_rawgeti(L, idx, n) — push table_at_idx[n]. Used with idx = REGISTRY to
+// push a value stored under an integer ref (handler / frame object / message
+// handler / luaL_ref'd saved globals).
+using RawGetI_t = void(__fastcall *)(void *L, int idx, int ref);
+// FUN_FRAMESCRIPT_OBJECT_SCRIPT_REGISTER — __thiscall(frame, nameOrNull);
+// lazily materializes the frame's Lua-registry ref at frame+OFF_COBJECT_LUA_REF.
+using ScriptRegister_t = void(__thiscall *)(void *frame, void *nameOrNull);
+
+const auto RawGetI = reinterpret_cast<RawGetI_t>(Offsets::LUA_RAWGETI);
+
+// Returns the frame's Lua object ref (frame+0x08), lazily creating it exactly
+// as the engine runner does (`if (refcount == 0) ScriptRegister(frame, 0)`).
+int EnsureLuaRef(void *frame) {
+    auto *f = reinterpret_cast<uint8_t *>(frame);
+    if (*reinterpret_cast<int *>(f + Offsets::OFF_COBJECT_LUA_REFCOUNT) == 0)
+        reinterpret_cast<ScriptRegister_t>(
+            Offsets::FUN_FRAMESCRIPT_OBJECT_SCRIPT_REGISTER)(frame, nullptr);
+    return *reinterpret_cast<int *>(f + Offsets::OFF_COBJECT_LUA_REF);
+}
+
+// Writes "arg" + k (k in 1..19) into buf; buf must hold at least 6 bytes.
+void ArgName(char *buf, int k) {
+    buf[0] = 'a';
+    buf[1] = 'r';
+    buf[2] = 'g';
+    if (k < 10) {
+        buf[3] = static_cast<char>('0' + k);
+        buf[4] = '\0';
+    } else {
+        buf[3] = static_cast<char>('0' + k / 10);
+        buf[4] = static_cast<char>('0' + k % 10);
+        buf[5] = '\0';
+    }
+}
+
+// One parsed positional argument from the runner's printf-style format.
+// Numbers ('d'/'u'/'f') land in `num`; strings ('s') keep the char* the engine
+// handed us (stable for the duration of the call).
+struct Arg {
+    char name[6]; // "arg1".."arg19"
+    char kind;    // 'd' | 'u' | 'f' | 's'
+    double num;
+    const char *str;
+};
+
+// Decodes `fmt`/`vaPtr` (the runner's %d/%u/%f/%s specs over a packed vararg
+// buffer) into `out`, returning the count (capped at kMaxArgs). Unknown specs
+// are skipped and consume no vararg — mirroring the engine runner's switch.
+// Pure C, touches no Lua state, so it can never throw.
+int ParseArgs(const char *fmt, const void *vaPtr, Arg *out) {
+    if (fmt == nullptr)
+        return 0;
+    const char *cur = static_cast<const char *>(vaPtr);
+    int n = 0;
+    for (const char *p = fmt; *p != '\0' && n < kMaxArgs; ++p) {
+        if (*p != '%')
+            continue;
+        ++p;
+        if (*p == '\0')
+            break;
+        Arg &a = out[n];
+        switch (*p) {
+        case 'd':
+            a.num = static_cast<double>(*reinterpret_cast<const int *>(cur));
+            cur += 4;
+            break;
+        case 'u':
+            a.num = static_cast<double>(
+                *reinterpret_cast<const unsigned int *>(cur));
+            cur += 4;
+            break;
+        case 'f':
+            a.num = *reinterpret_cast<const double *>(cur);
+            cur += 8;
+            break;
+        case 's':
+            a.str = *reinterpret_cast<const char *const *>(cur);
+            cur += 4;
+            break;
+        default:
+            continue; // unknown spec — consume nothing
+        }
+        a.kind = *p;
+        ArgName(a.name, n + 1);
+        ++n;
+    }
+    return n;
+}
+
+// Pushes a parsed argument's value onto the Lua stack.
+void PushArg(void *L, const Arg &a) {
+    if (a.kind == 's')
+        Game::Lua::PushString(L, a.str);
+    else
+        Game::Lua::PushNumber(L, a.num);
+}
+
+// Reimplements the runner tail: set the `this`/`arg1..argN` globals, invoke the
+// handler with modern positional args `(self, [event,] arg1..argN)` under the
+// engine's own message-handler errfunc, then restore the globals. `fmt`/`vaPtr`
+// are null for the no-arg runner (N == 0).
+//
+// Unlike the engine (and our first cut), the old global values are saved on the
+// Lua STACK, not in the registry via luaL_ref. A registry save leaks its ref if
+// any push before the protected call longjmps — and out-of-memory, the one
+// failure that actually fires here, does exactly that. Stack slots need no
+// cleanup: an unwinding error resets `L->top` past them for free, so nothing
+// leaks and there's no per-call ref churn on the OnUpdate hot path. The cost is
+// a deeper stack (up to ~2*N slots live at once), so we CheckStack up front.
+//
+// Returns false WITHOUT side effects when it declines (no Lua state, or the
+// stack can't grow); the caller then runs the original. Every false path is
+// before the first push, so falling back never double-runs the handler.
+bool RunModern(int handlerRef, void *frame, const char *fmt, const void *vaPtr) {
+    using namespace Game::Lua;
+    void *L = State();
+    if (L == nullptr)
+        return false;
+    // Headroom for the saved-old block plus the transient set/call pushes.
+    if (CheckStack(L, 2 * kMaxArgs + 16) == 0)
+        return false;
+
+    const bool haveThis = frame != nullptr;
+    // OnEvent dispatch? The event dispatchers invoke the frame's OnEvent slot
+    // (frame+0x0C); matching the handler ref against that slot identifies it
+    // exactly. When so, `event` (a global the dispatcher has set) is prepended
+    // as the first positional to mirror retail's (self, event, arg1..argN).
+    const bool isOnEvent =
+        haveThis &&
+        *reinterpret_cast<const int *>(reinterpret_cast<uint8_t *>(frame) +
+                                       Offsets::OFF_FRAME_ONEVENT_SLOT) ==
+            handlerRef;
+    const int selfRef = haveThis ? EnsureLuaRef(frame) : 0;
+
+    Arg args[kMaxArgs];
+    const int n = ParseArgs(fmt, vaPtr, args);
+
+    // --- save the globals we're about to clobber, onto the stack ------------
+    // Absolute indices, live until the closing SetTop(base):
+    //   base+1                = old _G.this        (if haveThis)
+    //   savedArgBase+1 .. +n   = old _G.arg1..argN
+    const int base = GetTop(L);
+    if (haveThis) {
+        PushString(L, "this");
+        GetTable(L, GLOBALS_INDEX); // [.. oldThis]
+    }
+    const int savedArgBase = base + (haveThis ? 1 : 0);
+    for (int k = 0; k < n; ++k) {
+        PushString(L, args[k].name);
+        GetTable(L, GLOBALS_INDEX); // [.. oldArgk]
+    }
+
+    // --- set the new globals (each op is stack-neutral) ---------------------
+    if (haveThis) {
+        PushString(L, "this");
+        RawGetI(L, REGISTRY_INDEX, selfRef); // frame object
+        SetTable(L, GLOBALS_INDEX);
+    }
+    for (int k = 0; k < n; ++k) {
+        PushString(L, args[k].name);
+        PushArg(L, args[k]);
+        SetTable(L, GLOBALS_INDEX);
+    }
+
+    // --- call handler(self, [event,] arg1..argN) ---------------------------
+    const int callBase = GetTop(L); // == base + saved-block size
+    const int errRef = *reinterpret_cast<const int *>(
+        static_cast<uintptr_t>(Offsets::VAR_FRAMESCRIPT_ERROR_HANDLER_REF));
+    int errIdx = 0;
+    if (errRef > 0) {
+        RawGetI(L, REGISTRY_INDEX, errRef); // message handler
+        errIdx = callBase + 1;              // absolute index of the errfunc
+    }
+    RawGetI(L, REGISTRY_INDEX, handlerRef); // handler
+    if (haveThis)
+        RawGetI(L, REGISTRY_INDEX, selfRef); // self
+    else
+        PushNil(L);
+    if (isOnEvent) { // event goes before the args, retail-style
+        PushString(L, "event");
+        GetTable(L, GLOBALS_INDEX);
+    }
+    for (int k = 0; k < n; ++k)
+        PushArg(L, args[k]);
+    PCall(L, 1 + (isOnEvent ? 1 : 0) + n, 0, errIdx);
+    SetTop(L, callBase); // drop the message handler + any leftover error object
+
+    // --- restore globals from the saved block, then drop it -----------------
+    for (int k = 0; k < n; ++k) {
+        PushString(L, args[k].name);
+        PushValue(L, savedArgBase + 1 + k);
+        SetTable(L, GLOBALS_INDEX);
+    }
+    if (haveThis) {
+        PushString(L, "this");
+        PushValue(L, base + 1);
+        SetTable(L, GLOBALS_INDEX);
+    }
+    SetTop(L, base);
+    return true;
+}
+
+// --- FUN_FRAME_RUN_SCRIPT_ARGS co-hook (scripts with values) ----------------
+using RunArgs_t = void(__cdecl *)(int handlerRef, void *frame, const char *fmt,
+                                  const void *vaPtr);
+RunArgs_t g_origRunArgs = nullptr;
+
+void __cdecl RunArgs_h(int handlerRef, void *frame, const char *fmt,
+                       const void *vaPtr) {
+    if (g_enabled && handlerRef != 0 && fmt != nullptr &&
+        RunModern(handlerRef, frame, fmt, vaPtr))
+        return;
+    g_origRunArgs(handlerRef, frame, fmt, vaPtr);
+}
+
+// --- FUN_FRAME_INVOKE_SCRIPT co-hook (no-arg scripts) -----------------------
+// Same address Tooltip::SetEvents calls directly to fire OnTooltipSet*; with
+// the switch enabled those fire with (self) too, which is the modern shape.
+using Invoke_t = void(__fastcall *)(int handlerRef, void *frame);
+Invoke_t g_origInvoke = nullptr;
+
+void __fastcall Invoke_h(int handlerRef, void *frame) {
+    if (g_enabled && handlerRef != 0 && frame != nullptr &&
+        RunModern(handlerRef, frame, /*fmt*/ nullptr, /*vaPtr*/ nullptr))
+        return;
+    g_origInvoke(handlerRef, frame);
+}
+
+const Game::HookAutoRegister _runArgsHook{
+    Offsets::FUN_FRAME_RUN_SCRIPT_ARGS,
+    reinterpret_cast<void *>(&RunArgs_h),
+    reinterpret_cast<void **>(&g_origRunArgs)};
+
+const Game::HookAutoRegister _invokeHook{
+    Offsets::FUN_FRAME_INVOKE_SCRIPT,
+    reinterpret_cast<void *>(&Invoke_h),
+    reinterpret_cast<void **>(&g_origInvoke)};
+
+// --- Lua toggle -------------------------------------------------------------
+int __fastcall Script_SetModernScriptArgs(void *L) {
+    g_enabled = Game::Lua::ToBoolean(L, 1) != 0;
+    Game::Lua::PushBool(L, g_enabled);
+    return 1;
+}
+
+int __fastcall Script_GetModernScriptArgs(void *L) {
+    Game::Lua::PushBool(L, g_enabled);
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterGlobalFunction("SetModernScriptArgs",
+                                      &Script_SetModernScriptArgs);
+    Game::Lua::RegisterGlobalFunction("GetModernScriptArgs",
+                                      &Script_GetModernScriptArgs);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace Frame::ScriptArgs

src/friendlist/FriendList.h

@@ -0,0 +1,127 @@
+// 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 "Offsets.h"
+
+#include <cstdint>
+
+// Shared access to the client's friend list. The friend entries live inline
+// in the social singleton (`VAR_SOCIAL_SYSTEM`, shared with the ignore list
+// and /who): up to 50 entries from offset 0, stride 0x20. The field offsets
+// are verified from GetNumFriends (FUN_005AD000), GetFriendInfo
+// (FUN_005AD060), and the count walker FUN_005AE490.
+//
+// The ignore list lives in the same singleton: a flat array of u64 GUIDs at
+// `+0x650`, stride 8, up to 25 entries, terminated by the first zero GUID.
+// Vanilla ignores are GUID-keyed, not name-keyed — GetIgnoreName (0x005AD460)
+// reads the GUID via FUN_005AE570 (`social + 0x650 + index*8`) and resolves it
+// to a name through the NameCache, and GetNumIgnores (0x005AD400 → the count
+// walker FUN_005AE550) stops at the first zero GUID and caps at 25.
+
+namespace FriendList {
+
+constexpr int FRIEND_ENTRY_STRIDE = 0x20;
+constexpr int MAX_FRIENDS = 50;
+
+constexpr int OFF_FRIEND_CONNECTED = 0x00; // u8  — 0 = offline
+constexpr int OFF_FRIEND_STATUS = 0x01;    // u8  — bit 0x02 AFK, 0x04 DND
+constexpr int OFF_FRIEND_NAME = 0x04;      // char*
+constexpr int OFF_FRIEND_GUID = 0x08;      // u64
+constexpr int OFF_FRIEND_LEVEL = 0x10;     // i32
+constexpr int OFF_FRIEND_CLASS_INDEX = 0x14; // i32 → ChrClasses.dbc
+constexpr int OFF_FRIEND_AREA_INDEX = 0x18;  // i32 → AreaTable.dbc
+
+constexpr uint8_t FRIEND_STATUS_AFK = 0x02;
+constexpr uint8_t FRIEND_STATUS_DND = 0x04;
+
+constexpr int OFF_IGNORE_LIST = 0x650;   // u64 GUID array in the social singleton
+constexpr int IGNORE_ENTRY_STRIDE = 0x8; // one packed u64 GUID per entry
+constexpr int MAX_IGNORES = 25;          // 0x19 — GetNumIgnores' cap
+
+// The social singleton, or null before login.
+inline const uint8_t *Social() {
+    return *reinterpret_cast<const uint8_t *const *>(
+        static_cast<uintptr_t>(Offsets::VAR_SOCIAL_SYSTEM));
+}
+
+// Number of populated friend slots (what GetNumFriends returns).
+inline int Count() {
+    const uint8_t *social = Social();
+    if (social == nullptr)
+        return 0;
+    using CountFn = uint32_t(__fastcall *)(const void *social);
+    auto fn = reinterpret_cast<CountFn>(
+        static_cast<uintptr_t>(Offsets::FUN_FRIEND_LIST_COUNT));
+    return static_cast<int>(fn(social));
+}
+
+// Friend entry at 0-based `index`, or null if there is no list or the index
+// is out of the fixed slot range. Does not bounds-check against the live
+// count — callers that iterate should use `Count()`.
+inline const uint8_t *EntryByIndex(int index) {
+    const uint8_t *social = Social();
+    if (social == nullptr || index < 0 || index >= MAX_FRIENDS)
+        return nullptr;
+    return social + index * FRIEND_ENTRY_STRIDE;
+}
+
+// The inline name of the friend with GUID `guid`, or null if that GUID is
+// not on the friends list. The list keeps name + GUID for online AND offline
+// friends (SMSG_FRIEND_LIST), so this resolves a GUID to a name even when the
+// unit is not synced in the object manager and not in the name cache.
+inline const char *NameForGuid(uint64_t guid) {
+    if (guid == 0)
+        return nullptr;
+    const int count = Count();
+    for (int i = 0; i < count; ++i) {
+        const uint8_t *entry = EntryByIndex(i);
+        if (entry == nullptr)
+            break;
+        if (*reinterpret_cast<const uint64_t *>(entry + OFF_FRIEND_GUID) == guid) {
+            const char *name =
+                *reinterpret_cast<const char *const *>(entry + OFF_FRIEND_NAME);
+            return (name != nullptr && *name != '\0') ? name : nullptr;
+        }
+    }
+    return nullptr;
+}
+
+// The ignore-list GUID at 0-based `index`, or 0 if there is no list or the
+// index is past the fixed cap. Mirrors FUN_005AE570.
+inline uint64_t IgnoreGuidByIndex(int index) {
+    const uint8_t *social = Social();
+    if (social == nullptr || index < 0 || index >= MAX_IGNORES)
+        return 0;
+    return *reinterpret_cast<const uint64_t *>(
+        social + OFF_IGNORE_LIST + index * IGNORE_ENTRY_STRIDE);
+}
+
+// True if `guid` is on the ignore list. Walks the GUID array, stopping at the
+// first zero entry (the list is contiguous — same terminate-on-zero contract
+// GetNumIgnores relies on).
+inline bool IsGuidIgnored(uint64_t guid) {
+    if (guid == 0)
+        return false;
+    for (int i = 0; i < MAX_IGNORES; ++i) {
+        const uint64_t entry = IgnoreGuidByIndex(i);
+        if (entry == 0)
+            break;
+        if (entry == guid)
+            return true;
+    }
+    return false;
+}
+
+} // namespace FriendList

src/friendlist/GetFriendInfo.cpp

@@ -0,0 +1,166 @@
+// 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_FriendList.GetFriendInfo(name)` / `GetFriendInfoByIndex(index)` — the
+// modern FriendInfo table, plus `C_FriendList.GetNumFriends()`.
+//
+// Reads the friend entries directly (see `FriendList.h`). The class and zone
+// names come from the same DBC lookups the engine's own GetFriendInfo uses:
+// ChrClasses.dbc by the entry's class index, and AreaTable.dbc by the area
+// index — resolved to the parent zone so a sub-area reports its zone. Both
+// are locale-applied through `DBC::LocalizedField`.
+//
+// vanilla 1.12 stores no friend notes, so `notes` is omitted (nil). `mobile`
+// and `referAFriend` are always false, and `rafLinkType` is 0 — vanilla has
+// none of those systems; the fields exist so modern consumers do not nil-out.
+
+#include "FriendList.h"
+#include "Notes.h"
+
+#include "Game.h"
+#include "dbc/Names.h"
+#include "guid/Guid.h"
+
+#include <cstdint>
+#include <cstring>
+
+namespace FriendList::Info {
+
+namespace {
+
+// Push the modern FriendInfo table for `entry` on top of the Lua stack.
+void PushFriendInfo(void *L, const uint8_t *entry) {
+    const bool connected = *(entry + OFF_FRIEND_CONNECTED) != 0;
+    const char *name =
+        *reinterpret_cast<const char *const *>(entry + OFF_FRIEND_NAME);
+    const int level = *reinterpret_cast<const int *>(entry + OFF_FRIEND_LEVEL);
+    const uint64_t guid =
+        *reinterpret_cast<const uint64_t *>(entry + OFF_FRIEND_GUID);
+    const uint8_t status = *(entry + OFF_FRIEND_STATUS);
+    const uint32_t classIndex =
+        *reinterpret_cast<const uint32_t *>(entry + OFF_FRIEND_CLASS_INDEX);
+    const uint32_t areaIndex =
+        *reinterpret_cast<const uint32_t *>(entry + OFF_FRIEND_AREA_INDEX);
+
+    Game::Lua::NewTable(L);
+    Game::Lua::SetFieldString(L, "name", name);
+    Game::Lua::SetFieldBool(L, "connected", connected);
+    Game::Lua::SetFieldNumber(L, "level", static_cast<double>(level));
+    // Optional strings: leave the field nil (unset) when unresolved rather
+    // than "" — SetFieldString coerces null to "", which is truthy in Lua and
+    // would fool an `if info.notes then` presence check. Matches retail, where
+    // these are nil when absent.
+    if (const char *className = DBC::ClassName(classIndex))
+        Game::Lua::SetFieldString(L, "className", className);
+    // classFilename: the locale-independent class token ("MAGE", "WARRIOR"),
+    // the key for RAID_CLASS_COLORS and other class tables. nil when unknown,
+    // so `className` and `classFilename` appear together.
+    if (const char *classToken = DBC::ClassToken(classIndex))
+        Game::Lua::SetFieldString(L, "classFilename", classToken);
+    // Resolve a sub-area to its parent zone for friends (e.g. "Goldshire" ->
+    // "Elwynn Forest"), matching what the friends UI shows.
+    if (const char *area = DBC::AreaName(areaIndex, /*resolveToParent=*/true))
+        Game::Lua::SetFieldString(L, "area", area);
+    if (guid != 0) {
+        char buf[Guid::STRING_SIZE];
+        Game::Lua::SetFieldString(L, "guid",
+                                  Guid::FormatAsString(guid, buf, sizeof buf));
+    }
+    if (const char *note = Notes::Get(guid)) // client-side note (see Notes.h)
+        Game::Lua::SetFieldString(L, "notes", note);
+    Game::Lua::SetFieldBool(L, "afk", (status & FRIEND_STATUS_AFK) != 0);
+    Game::Lua::SetFieldBool(L, "dnd", (status & FRIEND_STATUS_DND) != 0);
+    Game::Lua::SetFieldBool(L, "mobile", false);
+    Game::Lua::SetFieldBool(L, "referAFriend", false);
+    Game::Lua::SetFieldNumber(L, "rafLinkType", 0);
+}
+
+int __fastcall Script_GetNumFriends(void *L) {
+    Game::Lua::PushNumber(L, static_cast<double>(FriendList::Count()));
+    return 1;
+}
+
+// `C_FriendList.GetNumOnlineFriends()` — how many friends are online. Vanilla
+// stores no online count, so we count entries whose `connected` byte is set
+// (the same flag GetFriendInfo reports as `connected`).
+int __fastcall Script_GetNumOnlineFriends(void *L) {
+    int online = 0;
+    const int count = FriendList::Count();
+    for (int i = 0; i < count; ++i) {
+        const uint8_t *entry = FriendList::EntryByIndex(i);
+        if (entry == nullptr)
+            break;
+        if (*(entry + OFF_FRIEND_CONNECTED) != 0)
+            ++online;
+    }
+    Game::Lua::PushNumber(L, static_cast<double>(online));
+    return 1;
+}
+
+int __fastcall Script_GetFriendInfoByIndex(void *L) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+    const int index = static_cast<int>(Game::Lua::ToNumber(L, 1)); // 1-based
+    if (index < 1 || index > FriendList::Count()) {
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+    const uint8_t *entry = FriendList::EntryByIndex(index - 1);
+    if (entry == nullptr) {
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+    PushFriendInfo(L, entry);
+    return 1;
+}
+
+int __fastcall Script_GetFriendInfo(void *L) {
+    const char *name = Game::Lua::IsString(L, 1) ? Game::Lua::ToString(L, 1) : nullptr;
+    if (name == nullptr || *name == '\0') {
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+    const int count = FriendList::Count();
+    for (int i = 0; i < count; ++i) {
+        const uint8_t *entry = FriendList::EntryByIndex(i);
+        if (entry == nullptr)
+            break;
+        const char *fname =
+            *reinterpret_cast<const char *const *>(entry + OFF_FRIEND_NAME);
+        if (fname != nullptr && _stricmp(fname, name) == 0) {
+            PushFriendInfo(L, entry);
+            return 1;
+        }
+    }
+    Game::Lua::PushNil(L);
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_FriendList", "GetNumFriends",
+                                     &Script_GetNumFriends);
+    Game::Lua::RegisterTableFunction("C_FriendList", "GetNumOnlineFriends",
+                                     &Script_GetNumOnlineFriends);
+    Game::Lua::RegisterTableFunction("C_FriendList", "GetFriendInfoByIndex",
+                                     &Script_GetFriendInfoByIndex);
+    Game::Lua::RegisterTableFunction("C_FriendList", "GetFriendInfo",
+                                     &Script_GetFriendInfo);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace FriendList::Info

src/friendlist/IsFriend.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_FriendList.IsFriend(guid)` — is the given player on the friends list?
+//
+// Matches the input GUID against each friend entry's GUID (+0x08) — the same
+// GUID `SMSG_FRIEND_LIST` populates for online AND offline friends — and also
+// falls back to a name compare (resolving the GUID through the NameCache) so
+// the answer holds even if a build stores the GUID differently. As a
+// ClassicAPI convenience the arg may also be a bare character name, since
+// vanilla's friends list is fundamentally name-keyed (AddFriend(name)). See
+// `FriendList.h` for the entry layout.
+
+#include "FriendList.h"
+
+#include "Game.h"
+#include "guid/Guid.h"
+#include "unit/Identity.h"
+
+#include <cstdint>
+#include <cstring>
+
+namespace FriendList::IsFriend {
+
+namespace {
+
+bool IsFriendByGuidOrName(uint64_t guid, const char *name) {
+    const int count = FriendList::Count();
+    for (int i = 0; i < count; ++i) {
+        const uint8_t *entry = FriendList::EntryByIndex(i);
+        if (entry == nullptr)
+            break;
+        if (guid != 0 &&
+            *reinterpret_cast<const uint64_t *>(entry + FriendList::OFF_FRIEND_GUID) == guid)
+            return true;
+        if (name != nullptr) {
+            const char *fname = *reinterpret_cast<const char *const *>(
+                entry + FriendList::OFF_FRIEND_NAME);
+            if (fname != nullptr && _stricmp(fname, name) == 0)
+                return true;
+        }
+    }
+    return false;
+}
+
+} // namespace
+
+int __fastcall Script_IsFriend(void *L) {
+    const char *arg = Game::Lua::IsString(L, 1) ? Game::Lua::ToString(L, 1) : nullptr;
+    if (arg == nullptr || *arg == '\0') {
+        Game::Lua::PushBool(L, false);
+        return 1;
+    }
+
+    uint64_t guid = 0;
+    const char *name = nullptr;
+    if (Guid::Parse(arg, &guid) && guid != 0)
+        name = Unit::Identity::NameForGuid(guid); // GUID input → name for the fallback compare
+    else
+        name = arg; // not a GUID → treat the string as a character name
+
+    Game::Lua::PushBool(L, IsFriendByGuidOrName(guid, name));
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_FriendList", "IsFriend", &Script_IsFriend);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace FriendList::IsFriend

src/friendlist/IsIgnored.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/>.
+
+// `C_FriendList.IsIgnored(token)` / `C_FriendList.IsIgnoredByGuid(guid)` — is
+// the given player on the ignore list?
+//
+// The ignore list is a flat array of u64 GUIDs in the social singleton (see
+// `FriendList.h`) — vanilla ignores are GUID-keyed, not name-keyed. So
+// `IsIgnoredByGuid` is a direct GUID walk, and `IsIgnored` accepts either a
+// GUID string or a character name: for a name it resolves each ignored GUID to
+// its cached name through the NameCache and compares (the same GUID→name path
+// GetIgnoreName uses), so it matches any ignored player the client has synced.
+// An ignored player never seen this session has no cached name and so cannot
+// match by name — identical to GetIgnoreName returning "Unknown" for them.
+
+#include "FriendList.h"
+
+#include "Game.h"
+#include "guid/Guid.h"
+#include "unit/Identity.h"
+
+#include <cstdint>
+#include <cstring>
+
+namespace FriendList::IsIgnored {
+
+namespace {
+
+// True if any ignored GUID matches `guid`, or (when `name` is given) resolves
+// to `name`. Single walk of the GUID array.
+bool IgnoredByGuidOrName(uint64_t guid, const char *name) {
+    for (int i = 0; i < FriendList::MAX_IGNORES; ++i) {
+        const uint64_t entry = FriendList::IgnoreGuidByIndex(i);
+        if (entry == 0)
+            break; // contiguous list — first zero is the end
+        if (guid != 0 && entry == guid)
+            return true;
+        if (name != nullptr) {
+            const char *ename = Unit::Identity::NameForGuid(entry);
+            if (ename != nullptr && _stricmp(ename, name) == 0)
+                return true;
+        }
+    }
+    return false;
+}
+
+} // namespace
+
+// `IsIgnored(token)` — token is a character name or a GUID string.
+int __fastcall Script_IsIgnored(void *L) {
+    const char *arg = Game::Lua::IsString(L, 1) ? Game::Lua::ToString(L, 1) : nullptr;
+    if (arg == nullptr || *arg == '\0') {
+        Game::Lua::PushBool(L, false);
+        return 1;
+    }
+
+    uint64_t guid = 0;
+    const char *name = nullptr;
+    if (Guid::Parse(arg, &guid) && guid != 0)
+        name = Unit::Identity::NameForGuid(guid); // GUID input → name for the fallback compare
+    else
+        name = arg; // not a GUID → treat the string as a character name
+
+    Game::Lua::PushBool(L, IgnoredByGuidOrName(guid, name));
+    return 1;
+}
+
+// `IsIgnoredByGuid(guid)` — GUID string only.
+int __fastcall Script_IsIgnoredByGuid(void *L) {
+    const char *arg = Game::Lua::IsString(L, 1) ? Game::Lua::ToString(L, 1) : nullptr;
+    uint64_t guid = 0;
+    if (arg == nullptr || !Guid::Parse(arg, &guid) || guid == 0) {
+        Game::Lua::PushBool(L, false);
+        return 1;
+    }
+    Game::Lua::PushBool(L, FriendList::IsGuidIgnored(guid));
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_FriendList", "IsIgnored", &Script_IsIgnored);
+    Game::Lua::RegisterTableFunction("C_FriendList", "IsIgnoredByGuid",
+                                     &Script_IsIgnoredByGuid);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace FriendList::IsIgnored

src/friendlist/Notes.cpp

@@ -0,0 +1,206 @@
+// 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/>.
+
+// See `Notes.h`. Mirrors the equipment manager's storage approach
+// (equipmentset/Storage.cpp): a small text file under WTF, atomic
+// tmp+rename write, path re-resolved on every access so a
+// logout→character-select→login (no DLL reload) picks up the new realm.
+
+#include "Notes.h"
+
+#include "Offsets.h"
+
+#include <cstdint>
+#include <cstdio>
+#include <cstdlib>
+#include <fstream>
+#include <string>
+#include <unordered_map>
+
+namespace FriendList::Notes {
+
+namespace {
+
+struct Entry {
+    std::string name; // last-seen name, for a readable file (not the key)
+    std::string note;
+};
+
+std::unordered_map<uint64_t, Entry> g_notes;
+std::string g_path;
+bool g_loaded = false;
+
+const char *ReadAccountName() {
+    return *reinterpret_cast<const char *const *>(Offsets::VAR_ACCOUNT_NAME_PTR);
+}
+
+const char *ReadRealmName() {
+    auto *info = *reinterpret_cast<uint8_t **>(Offsets::VAR_REALM_INFO_PTR);
+    if (info == nullptr)
+        return nullptr;
+    return *reinterpret_cast<const char *const *>(info + Offsets::OFF_REALM_INFO_NAME);
+}
+
+const char *ReadCharacterName() {
+    auto *p = reinterpret_cast<const char *>(Offsets::VAR_CHARACTER_NAME);
+    return (p[0] == '\0') ? nullptr : p;
+}
+
+// WTF\Account\<acct>\<realm>\<char>\ClassicAPI_FriendNotes.txt, or empty until
+// the account + realm + character session globals are populated. Per-character
+// because the friends list is per-character in vanilla.
+std::string ResolveFilePath() {
+    const char *account = ReadAccountName();
+    if (account == nullptr || account[0] == '\0')
+        return {};
+    const char *realm = ReadRealmName();
+    if (realm == nullptr || realm[0] == '\0')
+        return {};
+    const char *character = ReadCharacterName();
+    if (character == nullptr)
+        return {};
+    std::string out = "WTF\\Account\\";
+    out += account;
+    out += '\\';
+    out += realm;
+    out += '\\';
+    out += character;
+    out += "\\ClassicAPI_FriendNotes.txt";
+    return out;
+}
+
+// Notes are a single line each; the file is tab-delimited, so a note must
+// carry no tab or newline. Replace any with a space and trim trailing space.
+void Sanitize(std::string *s) {
+    for (char &c : *s)
+        if (c == '\r' || c == '\n' || c == '\t')
+            c = ' ';
+    while (!s->empty() && s->back() == ' ')
+        s->pop_back();
+}
+
+void Load() {
+    g_notes.clear();
+    std::ifstream file(g_path);
+    if (!file.is_open())
+        return; // first run for this character — empty store is fine
+
+    std::string line;
+    while (std::getline(file, line)) {
+        while (!line.empty() && (line.back() == '\r' || line.back() == '\n'))
+            line.pop_back();
+        if (line.empty() || line[0] == '#')
+            continue;
+        // Format: `0xGUID<tab>name<tab>note`.
+        const auto t1 = line.find('\t');
+        if (t1 == std::string::npos)
+            continue;
+        const auto t2 = line.find('\t', t1 + 1);
+        const uint64_t guid = std::strtoull(line.c_str(), nullptr, 0);
+        if (guid == 0 || t2 == std::string::npos)
+            continue;
+        std::string name = line.substr(t1 + 1, t2 - (t1 + 1));
+        std::string note = line.substr(t2 + 1);
+        if (note.empty())
+            continue;
+        if (static_cast<int>(note.size()) > MAX_NOTE_LEN)
+            note.resize(MAX_NOTE_LEN);
+        g_notes[guid] = Entry{std::move(name), std::move(note)};
+    }
+}
+
+void Save() {
+    if (g_path.empty())
+        return;
+    const std::string tmp = g_path + ".tmp";
+    {
+        std::ofstream out(tmp, std::ios::binary | std::ios::trunc);
+        if (!out.is_open())
+            return;
+        out << "# ClassicAPI Friend Notes v1\n";
+        out << "# <0xGUID>\\t<name>\\t<note>  (per-character, GUID-keyed)\n";
+        for (const auto &kv : g_notes) {
+            char buf[24];
+            std::snprintf(buf, sizeof(buf), "0x%016llX",
+                          static_cast<unsigned long long>(kv.first));
+            out << buf << '\t' << kv.second.name << '\t' << kv.second.note << '\n';
+        }
+    }
+    std::remove(g_path.c_str());
+    std::rename(tmp.c_str(), g_path.c_str());
+}
+
+// Re-resolve the path each call; reload when it changes. The DLL survives a
+// character/realm switch, so a permanent latch would keep the old character's
+// file — matching EquipmentSet::Data::EnsureLoaded.
+void EnsureLoaded() {
+    std::string path = ResolveFilePath();
+    if (path.empty()) {
+        // Session globals not ready (login / char-select / loading screen).
+        // Drop any cached state so a stale path from the PREVIOUS character
+        // can never be read from or written to — that is the "didn't wipe
+        // between characters" trap. Nothing queries notes out of world, so
+        // there is nothing to lose; the next in-world call reloads cleanly.
+        g_notes.clear();
+        g_path.clear();
+        g_loaded = false;
+        return;
+    }
+    if (g_loaded && path == g_path)
+        return;
+    // Path changed (different character/account) — Load() clears the map
+    // before reading, so the new character never inherits the old one's notes.
+    g_path = std::move(path);
+    Load();
+    g_loaded = true;
+}
+
+} // namespace
+
+const char *Get(uint64_t guid) {
+    if (guid == 0)
+        return nullptr;
+    EnsureLoaded();
+    auto it = g_notes.find(guid);
+    if (it == g_notes.end() || it->second.note.empty())
+        return nullptr;
+    return it->second.note.c_str();
+}
+
+bool Set(uint64_t guid, const char *name, const char *note) {
+    if (guid == 0)
+        return false;
+    EnsureLoaded();
+    if (g_path.empty())
+        return false; // no realm/account yet — nowhere to persist
+
+    std::string text = (note != nullptr) ? note : "";
+    Sanitize(&text);
+    if (static_cast<int>(text.size()) > MAX_NOTE_LEN)
+        text.resize(MAX_NOTE_LEN);
+
+    if (text.empty()) {
+        if (g_notes.erase(guid) == 0)
+            return false; // nothing to clear
+    } else {
+        Entry e;
+        e.name = (name != nullptr) ? name : "";
+        Sanitize(&e.name);
+        e.note = std::move(text);
+        g_notes[guid] = std::move(e);
+    }
+    Save();
+    return true;
+}
+
+} // namespace FriendList::Notes

src/friendlist/Notes.h

@@ -0,0 +1,40 @@
+// 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 friend notes. Vanilla 1.12 has no server-side note field
+// (TBC added it), so we persist notes ourselves — the same pattern the
+// equipment manager uses for its sets. Backing file:
+//   WTF\Account\<acct>\<realm>\<char>\ClassicAPI_FriendNotes.txt
+// Per-character, because the friends list itself is per-character in
+// vanilla (each character keeps its own friends). GUID-keyed within that
+// file — a friend's GUID is stable and unique on the realm.
+
+namespace FriendList::Notes {
+
+// Longest stored note. Longer input is truncated on Set.
+constexpr int MAX_NOTE_LEN = 128;
+
+// The note for a friend GUID, or nullptr if none. Loads the per-realm store
+// on first use. The pointer is valid until the next Set or realm switch.
+const char *Get(uint64_t guid);
+
+// Set the note for a friend GUID, or clear it when `note` is null/empty.
+// `name` is stored alongside so the file stays human-readable. Persists to
+// disk immediately. Returns true if the store changed.
+bool Set(uint64_t guid, const char *name, const char *note);
+
+} // namespace FriendList::Notes

src/friendlist/SetNotes.cpp

@@ -0,0 +1,89 @@
+// 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_FriendList.SetFriendNotes(name, notes)` / `SetFriendNotesByIndex(index,
+// notes)` — write a client-side note for a friend (see `Notes.h`). Passing an
+// empty / nil note clears it. Matches retail: the target must already be on
+// the friends list, and there is no return value. Fires FRIENDLIST_UPDATE on
+// change so the friends UI and note-aware addons refresh.
+
+#include "FriendList.h"
+#include "Notes.h"
+
+#include "Game.h"
+#include "event/Custom.h"
+
+#include <cstdint>
+#include <cstring>
+
+namespace FriendList::SetNotes {
+
+namespace {
+
+// The friend entry whose name matches (case-insensitive), or null.
+const uint8_t *FindByName(const char *name) {
+    if (name == nullptr || *name == '\0')
+        return nullptr;
+    const int count = FriendList::Count();
+    for (int i = 0; i < count; ++i) {
+        const uint8_t *entry = FriendList::EntryByIndex(i);
+        if (entry == nullptr)
+            break;
+        const char *fname = *reinterpret_cast<const char *const *>(
+            entry + FriendList::OFF_FRIEND_NAME);
+        if (fname != nullptr && _stricmp(fname, name) == 0)
+            return entry;
+    }
+    return nullptr;
+}
+
+void ApplyNote(const uint8_t *entry, const char *note) {
+    if (entry == nullptr)
+        return;
+    const uint64_t guid = *reinterpret_cast<const uint64_t *>(
+        entry + FriendList::OFF_FRIEND_GUID);
+    const char *name = *reinterpret_cast<const char *const *>(
+        entry + FriendList::OFF_FRIEND_NAME);
+    if (Notes::Set(guid, name, note))
+        Event::Custom::Fire(Event::Custom::LookupByName("FRIENDLIST_UPDATE"), "");
+}
+
+int __fastcall Script_SetFriendNotes(void *L) {
+    const char *name = Game::Lua::IsString(L, 1) ? Game::Lua::ToString(L, 1) : nullptr;
+    const char *note = Game::Lua::IsString(L, 2) ? Game::Lua::ToString(L, 2) : nullptr;
+    ApplyNote(FindByName(name), note);
+    return 0;
+}
+
+int __fastcall Script_SetFriendNotesByIndex(void *L) {
+    if (!Game::Lua::IsNumber(L, 1))
+        return 0;
+    const int index = static_cast<int>(Game::Lua::ToNumber(L, 1)); // 1-based
+    const char *note = Game::Lua::IsString(L, 2) ? Game::Lua::ToString(L, 2) : nullptr;
+    if (index >= 1 && index <= FriendList::Count())
+        ApplyNote(FriendList::EntryByIndex(index - 1), note);
+    return 0;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_FriendList", "SetFriendNotes",
+                                     &Script_SetFriendNotes);
+    Game::Lua::RegisterTableFunction("C_FriendList", "SetFriendNotesByIndex",
+                                     &Script_SetFriendNotesByIndex);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace FriendList::SetNotes

src/friendlist/Who.cpp

@@ -121,7 +121,7 @@ using SendQuery_t = void(__thiscall *)(void *self, const char *queryStr);
 
 bool SendQueryInternal(const char *fullQuery) {
     auto *system = *reinterpret_cast<void *const *>(
-        static_cast<uintptr_t>(Offsets::VAR_WHO_SYSTEM));
+        static_cast<uintptr_t>(Offsets::VAR_SOCIAL_SYSTEM));
     if (system == nullptr)
         return false;
     auto fn = reinterpret_cast<SendQuery_t>(Offsets::FUN_WHO_SYSTEM_SEND_QUERY);

src/friendlist/WhoInfo.cpp

@@ -0,0 +1,113 @@
+// 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_FriendList.GetWhoInfo(index)` — the modern table form of vanilla's
+// `GetWhoInfo(index)`. The vanilla global returns positional values and, most
+// notably, no class *token* — only the localized class name. This returns a
+// table that includes `filename` (the "MAGE"/"WARRIOR" token), so a /who list
+// can be class-colored via RAID_CLASS_COLORS without reverse-mapping the
+// localized name.
+//
+// Reads the same /who result buffer the engine's Script_GetWhoInfo
+// (0x005AD6E0) reads (see the WHO_RESULT_* offsets in Offsets.h): an array of
+// stride-0xA0 entries with inline name/guild strings and race/class/zone DBC
+// indices. `C_FriendList.GetNumWhoResults()` is the companion count.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "dbc/Names.h"
+
+#include <cstdint>
+
+namespace FriendList::WhoInfo {
+
+namespace {
+
+int WhoResultCount() {
+    return *reinterpret_cast<const int *>(
+        static_cast<uintptr_t>(Offsets::VAR_WHO_RESULT_COUNT));
+}
+
+// `C_FriendList.GetNumWhoResults()` → `numWhos, totalCount`. The first is the
+// number of entries you can index with GetWhoInfo; the second is the server's
+// total-match count (it can exceed the displayed list). Mirrors the vanilla
+// global's two returns.
+int __fastcall Script_GetNumWhoResults(void *L) {
+    const int displayed = WhoResultCount();
+    const int total = *reinterpret_cast<const int *>(
+        static_cast<uintptr_t>(Offsets::VAR_WHO_RESULT_COUNT) + 4);
+    Game::Lua::PushNumber(L, static_cast<double>(displayed));
+    Game::Lua::PushNumber(L, static_cast<double>(total));
+    return 2;
+}
+
+// `C_FriendList.GetWhoInfo(index)` → WhoInfo table, or nil for a bad index.
+int __fastcall Script_GetWhoInfo(void *L) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+    const int index = static_cast<int>(Game::Lua::ToNumber(L, 1)); // 1-based
+    if (index < 1 || index > WhoResultCount()) {
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+
+    const uint8_t *entry = reinterpret_cast<const uint8_t *>(
+        static_cast<uintptr_t>(Offsets::VAR_WHO_RESULTS) +
+        static_cast<size_t>(index - 1) * Offsets::WHO_RESULT_STRIDE);
+
+    const char *name = reinterpret_cast<const char *>(entry + Offsets::OFF_WHO_NAME);
+    const char *guild = reinterpret_cast<const char *>(entry + Offsets::OFF_WHO_GUILD);
+    const int level = *reinterpret_cast<const int *>(entry + Offsets::OFF_WHO_LEVEL);
+    const uint32_t raceID =
+        *reinterpret_cast<const uint32_t *>(entry + Offsets::OFF_WHO_RACE);
+    const uint32_t classID =
+        *reinterpret_cast<const uint32_t *>(entry + Offsets::OFF_WHO_CLASS);
+    const uint32_t zoneID =
+        *reinterpret_cast<const uint32_t *>(entry + Offsets::OFF_WHO_ZONE);
+
+    Game::Lua::NewTable(L);
+    Game::Lua::SetFieldString(L, "fullName", name);       // inline; "" if empty
+    Game::Lua::SetFieldString(L, "fullGuildName", guild); // "" when guildless
+    Game::Lua::SetFieldNumber(L, "level", static_cast<double>(level));
+    // Optional strings stay nil (unset) when the DBC id doesn't resolve, so an
+    // `if info.filename then` check works — SetFieldString would coerce null
+    // to "" (truthy).
+    if (const char *raceStr = DBC::RaceName(raceID))
+        Game::Lua::SetFieldString(L, "raceStr", raceStr);
+    if (const char *classStr = DBC::ClassName(classID))
+        Game::Lua::SetFieldString(L, "classStr", classStr);
+    if (const char *filename = DBC::ClassToken(classID))
+        Game::Lua::SetFieldString(L, "filename", filename);
+    // /who zones are already zone-level, so use the area's own name (no parent
+    // walk) — matches the engine's own GetWhoInfo.
+    if (const char *area = DBC::AreaName(zoneID, /*resolveToParent=*/false))
+        Game::Lua::SetFieldString(L, "area", area);
+    // No `gender`: vanilla's /who result carries no sex field (the entry ends
+    // at the zone index), so modern's gender return has no source here.
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_FriendList", "GetWhoInfo",
+                                     &Script_GetWhoInfo);
+    Game::Lua::RegisterTableFunction("C_FriendList", "GetNumWhoResults",
+                                     &Script_GetNumWhoResults);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace FriendList::WhoInfo

src/gameobject/Tooltip.cpp

@@ -14,6 +14,7 @@
 #include "Game.h"
 #include "Offsets.h"
 #include "guid/Guid.h"
+#include "object/Resolve.h"
 
 #include <cstdint>
 
@@ -28,9 +29,6 @@ namespace GameObject::Tooltip {
 // on every subsequent `SetX` call — same gating pattern Has/GetUnitGUID,
 // Has/GetItem, and Has/GetSpell use.
 
-using ObjectResolveByGUID_t = void *(__fastcall *)(int type, const char *debugName,
-                                                   uint32_t guidLo, uint32_t guidHi,
-                                                   int priority);
 using GameObjectGetName_t = const char *(__fastcall *)(void *gameObject);
 
 // `GameTooltip:GetGameObject()` → (name, id, guid) for whichever gameobject
@@ -72,10 +70,9 @@ static int __fastcall Script_GameTooltipGetGameObject(void *L) {
     if (guidLo == 0 && guidHi == 0)
         return 0;
 
-    auto resolve = reinterpret_cast<ObjectResolveByGUID_t>(
-        Offsets::FUN_OBJECT_RESOLVE_BY_GUID);
-    void *obj = resolve(Offsets::OBJ_TYPE_GAMEOBJECT, "GameTooltip:GetGameObject",
-                        guidLo, guidHi, 0x172);
+    void *obj = Object::ByGuid(Offsets::TYPEMASK_GAMEOBJECT,
+                               (static_cast<uint64_t>(guidHi) << 32) | guidLo,
+                               "GameTooltip:GetGameObject", 0x172);
     if (obj == nullptr)
         return 0;
 

src/glue/Session.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_Glue` session helpers.
+//
+// `C_Glue.IsFirstLoadThisSession()` — glue-only. Returns true only while the
+// FIRST glue screen since the process launched is showing, and false on
+// every return to glue after a world login (a genuine world→glue logout;
+// login↔character-select stays within the first glue session). Retail uses
+// it so the login UI runs one-time startup (intro cinematic, news) only on
+// the initial launch, not on each relog.
+//
+// Backed by a process-static boot counter, no engine state needed: the glue
+// registration callback fires exactly once per glue boot
+// (FUN_LOAD_GLUE_SCRIPT_FUNCTIONS — initial launch + each world→glue return),
+// so the counter equals "how many glue screens this session" and the first
+// one is boot #1. The glue Lua state is recreated per boot, so C_Glue is
+// re-registered each time; the counter is process-static and survives that.
+//
+// `C_Glue.IsOnGlueScreen()` — true when a GlueXML screen is showing (no
+// character logged in), false in the world. Registered on BOTH Lua states,
+// and the answer is a compile-time constant per state: the glue and in-game
+// Lua states are mutually exclusive (glue exists only when no character is in
+// the world), so the glue registration returns true and the in-game one
+// returns false — no runtime flag to consult. Available in both states so
+// shared code that runs in either environment can branch on it.
+
+#include "Game.h"
+
+namespace Glue::Session {
+
+namespace {
+
+// Glue-screen boots since process start. 1 during the very first glue screen.
+int g_glueBootCount = 0;
+
+int __fastcall Script_IsFirstLoadThisSession(void *L) {
+    Game::Lua::PushBool(L, g_glueBootCount <= 1);
+    return 1;
+}
+
+int __fastcall Script_IsOnGlueScreen_True(void *L) {
+    Game::Lua::PushBool(L, true);
+    return 1;
+}
+
+int __fastcall Script_IsOnGlueScreen_False(void *L) {
+    Game::Lua::PushBool(L, false);
+    return 1;
+}
+
+void RegisterGlue() {
+    ++g_glueBootCount; // one glue boot per callback invocation
+    Game::Lua::RegisterTableFunction("C_Glue", "IsFirstLoadThisSession",
+                                     &Script_IsFirstLoadThisSession);
+    Game::Lua::RegisterTableFunction("C_Glue", "IsOnGlueScreen",
+                                     &Script_IsOnGlueScreen_True);
+}
+
+void RegisterInGame() {
+    // In-world: only IsOnGlueScreen makes sense (and it's always false).
+    // IsFirstLoadThisSession is a glue concept, so it's not registered here.
+    Game::Lua::RegisterTableFunction("C_Glue", "IsOnGlueScreen",
+                                     &Script_IsOnGlueScreen_False);
+}
+
+const Game::GlueModuleAutoRegister _autoregGlue{&RegisterGlue};
+const Game::ModuleAutoRegister _autoreg{&RegisterInGame};
+
+} // namespace
+
+} // namespace Glue::Session

src/item/Arg.cpp

@@ -21,7 +21,7 @@
 namespace Item::Arg {
 
 Resolved Resolve(void *L, int idx) {
-    Resolved out{0, nullptr};
+    Resolved out{0, 0, nullptr};
     if (Game::Lua::IsNumber(L, idx)) {
         out.itemID = static_cast<int>(Game::Lua::ToNumber(L, idx));
         return out;
@@ -34,7 +34,18 @@ Resolved Resolve(void *L, int idx) {
         return out;
     }
     if (const char *m = std::strstr(s, "item:")) {
-        out.itemID = std::atoi(m + 5);
+        m += 5;
+        out.itemID = std::atoi(m);
+        // Random suffix is the 3rd colon-separated field: itemID:enchant:suffix.
+        // Walk to the 2nd ':' (stopping at the link boundary), read the number
+        // after it. Bare "item:N" (no colons) leaves suffix 0.
+        int colons = 0;
+        for (const char *p = m; *p != '\0' && *p != '|'; ++p) {
+            if (*p == ':' && ++colons == 2) {
+                out.suffix = std::atoi(p + 1);
+                break;
+            }
+        }
         return out;
     }
     // Plain string — try numeric, otherwise expose as a name for

src/item/Arg.h

@@ -22,6 +22,7 @@ namespace Item::Arg {
 // can ignore `name` and treat `itemID == 0` as "no usable input".
 struct Resolved {
     int itemID;
+    int suffix; // random-property / suffix ID (3rd `item:` field), 0 if none
     const char *name;
 };
 

src/item/AverageLevel.cpp

@@ -55,6 +55,8 @@
 #include "item/Data.h"
 #include "item/ID.h"
 #include "item/Location.h"
+#include "item/Record.h"
+#include "object/Resolve.h"
 #include "unit/Identity.h"
 
 #include <algorithm>
@@ -65,10 +67,6 @@ namespace Item::AverageLevel {
 
 namespace {
 
-using GetItemRecord_t = const uint8_t *(__thiscall *)(void *cache, uint32_t itemID,
-                                                      const uint64_t *guid, void *callback,
-                                                      void *userData, int unused);
-
 // 1-based slot range used by both walks.
 constexpr int kFirstSlot = 1;
 constexpr int kLastSlot = 19;
@@ -119,13 +117,6 @@ constexpr uint32_t kSlotMaskByInvType[29] = {
 constexpr int kInvTypeMax = static_cast<int>(sizeof(kSlotMaskByInvType) /
                                               sizeof(kSlotMaskByInvType[0])) - 1;
 
-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);
-}
-
 // Returns (itemLevel, inventoryType) for the CGItem, or (0, 0) if
 // the itemID is unresolvable or the cache record hasn't loaded.
 struct ItemInfo {
@@ -139,7 +130,7 @@ ItemInfo ReadItemInfo(const uint8_t *cgItem) {
     const int itemID = Item::ID::FromCGItem(cgItem);
     if (itemID <= 0)
         return {0, 0};
-    const uint8_t *record = PeekItemRecord(static_cast<uint32_t>(itemID));
+    const uint8_t *record = Item::PeekRecord(static_cast<uint32_t>(itemID));
     if (record == nullptr) {
         // Equipped or bagged item with no cache record yet — queue a
         // warmup so the next call gets populated data. Cheap on cache
@@ -154,22 +145,11 @@ ItemInfo ReadItemInfo(const uint8_t *cgItem) {
 // Bank-walk helpers — bypass the bank-window gate on `GetItemBySlot`
 // by reading the player's invMgr GUID array directly. Same shape as
 // `C_Item.GetItemCount`'s bank path.
-using ResolveObjectByGuid_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<ResolveObjectByGuid_t>(
-        Offsets::FUN_OBJECT_RESOLVE_BY_GUID);
     return static_cast<const uint8_t *>(
-        fn(type, "AverageLevel",
-           static_cast<uint32_t>(guid),
-           static_cast<uint32_t>(guid >> 32),
-           0x172));
+        Object::ByGuid(type, guid, "AverageLevel", 0x172));
 }
 
 // Collects a single CGItem into `candidates` if it could equip in
@@ -209,7 +189,7 @@ void WalkGuidArrayRange(const uint8_t *invMgr, int firstSlot, int lastSlot,
     if (guidArray == nullptr)
         return;
     for (int slot = firstSlot; slot <= lastSlot; ++slot) {
-        const uint8_t *item = ResolveByGuid(Offsets::OBJ_TYPE_ITEM, guidArray[slot]);
+        const uint8_t *item = ResolveByGuid(Offsets::TYPEMASK_ITEM, guidArray[slot]);
         if (item == nullptr)
             continue;
         CollectBagOrBankItem(item, candidates);
@@ -229,7 +209,7 @@ void WalkBankBags(std::vector<Candidate> &candidates) {
         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,
+        const uint8_t *bag = ResolveByGuid(Offsets::TYPEMASK_CONTAINER,
                                             playerGuidArray[slot]);
         if (bag == nullptr)
             continue;

src/item/Bound.cpp

@@ -13,6 +13,7 @@
 
 #include "Game.h"
 #include "Offsets.h"
+#include "item/CGItem.h"
 #include "item/Location.h"
 
 #include <cstdint>
@@ -20,8 +21,7 @@
 namespace Item::Bound {
 
 static bool ItemIsSoulbound(const uint8_t *item) {
-    auto *descriptor = *reinterpret_cast<const uint8_t *const *>(
-        item + Offsets::OFF_ITEM_DESCRIPTOR);
+    auto *descriptor = Item::ObjectFields(item);
     if (descriptor == nullptr)
         return false;
     const uint32_t flags = *reinterpret_cast<const uint32_t *>(

src/item/CGItem.cpp

@@ -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/>.
+
+#include "CGItem.h"
+
+#include "Offsets.h"
+
+namespace Item {
+
+const uint8_t *InstanceBlock(const uint8_t *cgItem) {
+    if (cgItem == nullptr)
+        return nullptr;
+    return *reinterpret_cast<const uint8_t *const *>(
+        cgItem + Offsets::OFF_ITEM_INSTANCE_BLOCK);
+}
+
+const uint8_t *ObjectFields(const uint8_t *cgItem) {
+    if (cgItem == nullptr)
+        return nullptr;
+    return *reinterpret_cast<const uint8_t *const *>(
+        cgItem + Offsets::OFF_ITEM_DESCRIPTOR);
+}
+
+} // namespace Item

src/item/CGItem.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>
+
+// Accessors for a `CGItem`'s two descriptor-like pointers (see the "Item
+// lookups" notes in CLAUDE.md). Every item module used to spell out the same
+// `*reinterpret_cast<const uint8_t *const *>(cgItem + OFF_...)` deref; these
+// name it once.
+
+namespace Item {
+
+// The item's **instance block** (`CGItem + 0x08` dereferenced): a `uint64`
+// item GUID at `+0x00` and the `uint32` itemID at `+0x0C`. This is the block
+// the canonical inventory→cache path reads the itemID from. Returns nullptr
+// for a null `cgItem`; the stored pointer itself may still be null (callers
+// null-check the result before reading fields).
+const uint8_t *InstanceBlock(const uint8_t *cgItem);
+
+// The item's **m_objectFields descriptor** (`CGItem + 0x114` dereferenced):
+// the UpdateField block holding stack count (`+0x20`), flags (`+0x3C`),
+// spell charges (`+0x28`), durability (`+0xA0`), enchantments, etc. Distinct
+// from the instance block. Returns nullptr for a null `cgItem`.
+const uint8_t *ObjectFields(const uint8_t *cgItem);
+
+} // namespace Item

src/item/Charges.cpp

@@ -15,6 +15,7 @@
 
 #include "../Game.h"
 #include "../Offsets.h"
+#include "CGItem.h"
 
 #include <cstdlib>
 
@@ -23,8 +24,7 @@ namespace Item::Charges {
 int PushChargesForItem(void *L, const uint8_t *item) {
     if (item == nullptr)
         return 0;
-    auto *descriptor = *reinterpret_cast<const uint8_t *const *>(
-        item + Offsets::OFF_ITEM_DESCRIPTOR);
+    auto *descriptor = Item::ObjectFields(item);
     if (descriptor == nullptr)
         return 0;
     const int32_t stack = static_cast<int32_t>(*reinterpret_cast<const uint32_t *>(

src/item/Consumable.cpp

@@ -34,6 +34,7 @@
 #include "Game.h"
 #include "Offsets.h"
 #include "item/Arg.h"
+#include "item/Record.h"
 
 #include <cstdint>
 
@@ -41,17 +42,6 @@ namespace Item::Consumable {
 
 namespace {
 
-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);
-}
-
 constexpr uint32_t kItemClassConsumable = 0;
 constexpr uint32_t kInvTypeAmmo = 24;   // INVTYPE_AMMO
 constexpr uint32_t kInvTypeThrown = 25; // INVTYPE_THROWN
@@ -62,7 +52,7 @@ int __fastcall Script_C_Item_IsConsumableItem(void *L) {
         Game::Lua::PushBoolean(L, 0);
         return 1;
     }
-    const uint8_t *record = PeekItemRecord(static_cast<uint32_t>(itemID));
+    const uint8_t *record = Item::PeekRecord(static_cast<uint32_t>(itemID));
     if (record == nullptr) {
         Game::Lua::PushBoolean(L, 0);
         return 1;

src/item/Count.cpp

@@ -16,8 +16,10 @@
 #include "Game.h"
 #include "Offsets.h"
 #include "item/Arg.h"
+#include "item/CGItem.h"
 #include "item/ID.h"
 #include "item/Location.h"
+#include "object/Resolve.h"
 #include "unit/Identity.h"
 
 #include <cstdint>
@@ -32,8 +34,7 @@ namespace {
 int GetStackCount(const uint8_t *cgItem) {
     if (cgItem == nullptr)
         return 0;
-    auto *descriptor = *reinterpret_cast<const uint8_t *const *>(
-        cgItem + Offsets::OFF_ITEM_DESCRIPTOR);
+    auto *descriptor = Item::ObjectFields(cgItem);
     if (descriptor == nullptr)
         return 0;
     return static_cast<int>(*reinterpret_cast<const uint32_t *>(
@@ -51,8 +52,7 @@ int GetStackCount(const uint8_t *cgItem) {
 int GetUsesPerItem(const uint8_t *cgItem) {
     if (cgItem == nullptr)
         return 1;
-    auto *descriptor = *reinterpret_cast<const uint8_t *const *>(
-        cgItem + Offsets::OFF_ITEM_DESCRIPTOR);
+    auto *descriptor = Item::ObjectFields(cgItem);
     if (descriptor == nullptr)
         return 1;
     const int32_t raw = *reinterpret_cast<const int32_t *>(
@@ -97,22 +97,11 @@ int CountInBag(void *L, int bagID, int targetItemID, bool includeUses) {
 // object resolver `FUN_OBJECT_RESOLVE_BY_GUID` (the same function
 // `GetItemBySlot` would call internally if the gate let us through).
 
-using ResolveObjectByGuid_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<ResolveObjectByGuid_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));
+        Object::ByGuid(type, guid, "ItemMgr", 0x172));
 }
 
 // Walks linear slots `[firstSlot, lastSlot]` of `invMgr`'s GUID array
@@ -130,7 +119,7 @@ int CountInGuidArray(const uint8_t *invMgr, int firstSlot, int lastSlot,
         return 0;
     int total = 0;
     for (int slot = firstSlot; slot <= lastSlot; slot++) {
-        const uint8_t *item = ResolveByGuid(Offsets::OBJ_TYPE_ITEM, guidArray[slot]);
+        const uint8_t *item = ResolveByGuid(Offsets::TYPEMASK_ITEM, guidArray[slot]);
         if (item == nullptr)
             continue;
         if (Item::ID::FromCGItem(item) != targetItemID)
@@ -159,7 +148,7 @@ int CountInBankBags(int targetItemID, bool includeUses) {
     int total = 0;
     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,
+        const uint8_t *bag = ResolveByGuid(Offsets::TYPEMASK_CONTAINER,
                                            playerGuidArray[slot]);
         if (bag == nullptr)
             continue;

src/item/Cursor.cpp

@@ -16,6 +16,7 @@
 #include "Game.h"
 #include "Offsets.h"
 #include "cursor/Info.h"
+#include "item/CGItem.h"
 #include "item/Location.h"
 
 #include <cstdint>
@@ -44,8 +45,7 @@ bool ItemLocked(const uint8_t *item) {
 // Reads a CGItem's 64-bit instance GUID into lo/hi. False if the instance
 // block pointer is absent.
 bool ReadItemGuid(const uint8_t *item, uint32_t *lo, uint32_t *hi) {
-    auto *instance = *reinterpret_cast<const uint8_t *const *>(
-        item + Offsets::OFF_ITEM_INSTANCE_BLOCK);
+    auto *instance = Item::InstanceBlock(item);
     if (instance == nullptr)
         return false;
     *lo = *reinterpret_cast<const uint32_t *>(instance + Offsets::OFF_INSTANCE_BLOCK_GUID);

src/item/Data.cpp

@@ -15,6 +15,7 @@
 #include "Offsets.h"
 #include "event/Custom.h"
 #include "item/Arg.h"
+#include "item/CGItem.h"
 #include "item/Data.h"
 #include "item/Location.h"
 #include "tick/WorldTick.h"
@@ -119,8 +120,7 @@ static int ResolveLocationToItemID(void *L, int idx) {
     const uint8_t *item = Item::Location::Resolve(L, idx);
     if (item == nullptr)
         return 0;
-    auto *instance = *reinterpret_cast<const uint8_t *const *>(
-        item + Offsets::OFF_ITEM_INSTANCE_BLOCK);
+    auto *instance = Item::InstanceBlock(item);
     if (instance == nullptr)
         return 0;
     return static_cast<int>(*reinterpret_cast<const uint32_t *>(

src/item/Durability.cpp

@@ -15,6 +15,7 @@
 
 #include "Game.h"
 #include "Offsets.h"
+#include "item/CGItem.h"
 #include "item/Location.h"
 
 #include <cstdint>
@@ -34,8 +35,7 @@ namespace Item::Durability {
 int PushDurabilityForItem(void *L, const uint8_t *item) {
     if (item == nullptr)
         return 0;
-    auto *descriptor = *reinterpret_cast<const uint8_t *const *>(
-        item + Offsets::OFF_ITEM_DESCRIPTOR);
+    auto *descriptor = Item::ObjectFields(item);
     if (descriptor == nullptr)
         return 0;
     const uint32_t cur = *reinterpret_cast<const uint32_t *>(

src/item/Equipment.cpp

@@ -17,6 +17,7 @@
 #include "item/Cursor.h"
 #include "item/ID.h"
 #include "item/Location.h"
+#include "item/Record.h"
 #include "item/Swap.h"
 
 #include <cstdint>
@@ -25,20 +26,6 @@ namespace Item::Equipment {
 
 namespace {
 
-using GetItemRecord_t = const uint8_t *(__thiscall *)(void *cache, uint32_t itemID,
-                                                      const uint64_t *guid, void *callback,
-                                                      void *userData, int unused);
-
-// Same item-cache peek pattern as `Item::Bag::PeekItemRecord` — we
-// don't share because each caller is one-line-different and the
-// helper isn't worth a header.
-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);
-}
-
 // `OffhandHasWeapon()` — true iff the player has a one-handed
 // weapon (or off-hand-only weapon) equipped in the off-hand slot.
 // Returns false for empty off-hand, shields, and held items
@@ -64,7 +51,7 @@ int __fastcall Script_OffhandHasWeapon(void *L) {
         return 1;
     }
 
-    auto *record = PeekItemRecord(static_cast<uint32_t>(itemID));
+    auto *record = Item::PeekRecord(static_cast<uint32_t>(itemID));
     if (record == nullptr) {
         Game::Lua::PushBoolean(L, 0);
         return 1;
@@ -102,7 +89,7 @@ int __fastcall Script_C_Item_IsEquippableItem(void *L) {
         Game::Lua::PushBoolean(L, 0);
         return 1;
     }
-    auto *record = PeekItemRecord(static_cast<uint32_t>(itemID));
+    auto *record = Item::PeekRecord(static_cast<uint32_t>(itemID));
     if (record == nullptr) {
         Game::Lua::PushBoolean(L, 0);
         return 1;

src/item/GUID.cpp

@@ -14,6 +14,7 @@
 #include "Game.h"
 #include "Offsets.h"
 #include "guid/Guid.h"
+#include "item/CGItem.h"
 #include "item/Location.h"
 
 #include <cstdint>
@@ -27,8 +28,7 @@ namespace {
 uint64_t ReadItemGuid(const uint8_t *cgItem) {
     if (cgItem == nullptr)
         return 0;
-    auto *instance = *reinterpret_cast<const uint8_t *const *>(
-        cgItem + Offsets::OFF_ITEM_INSTANCE_BLOCK);
+    auto *instance = Item::InstanceBlock(cgItem);
     if (instance == nullptr)
         return 0;
     return *reinterpret_cast<const uint64_t *>(

src/item/GetData.cpp

@@ -27,6 +27,7 @@
 #include "item/Arg.h"
 #include "item/ID.h"
 #include "item/Location.h"
+#include "item/Record.h"
 #include "item/Spell.h"
 
 #include <cstdint>
@@ -36,17 +37,6 @@ namespace Item::GetData {
 
 namespace {
 
-using GetItemRecord_t = const uint8_t *(__thiscall *)(void *cache, uint32_t itemID,
-                                                      const uint64_t *guid, void *callback,
-                                                      void *userData, bool requestIfMissing);
-
-const uint8_t *FetchItemRecord(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, false);
-}
-
 int CurrentLocaleIndex() {
     return *reinterpret_cast<int *>(Offsets::VAR_LOCALE_INDEX);
 }
@@ -377,7 +367,7 @@ int PushDataForItemID(void *L, int itemID) {
         Game::Lua::PushNil(L);
         return 1;
     }
-    const uint8_t *record = FetchItemRecord(static_cast<uint32_t>(itemID));
+    const uint8_t *record = Item::PeekRecord(static_cast<uint32_t>(itemID));
     if (record == nullptr) {
         Game::Lua::PushNil(L);
         return 1;

src/item/ID.cpp

@@ -13,6 +13,7 @@
 
 #include "Game.h"
 #include "Offsets.h"
+#include "item/CGItem.h"
 #include "item/ID.h"
 #include "item/Location.h"
 
@@ -23,8 +24,7 @@ namespace Item::ID {
 int FromCGItem(const uint8_t *item) {
     if (item == nullptr)
         return 0;
-    auto *instance = *reinterpret_cast<const uint8_t *const *>(
-        item + Offsets::OFF_ITEM_INSTANCE_BLOCK);
+    auto *instance = Item::InstanceBlock(item);
     if (instance == nullptr)
         return 0;
     return static_cast<int>(*reinterpret_cast<const uint32_t *>(

src/item/Info.cpp

@@ -20,6 +20,7 @@
 #include "item/ID.h"
 #include "item/Link.h"
 #include "item/Location.h"
+#include "item/Record.h"
 
 #include <cstdint>
 #include <cstdio>
@@ -27,21 +28,10 @@
 
 namespace Item::Info {
 
-using GetItemRecord_t = const uint8_t *(__thiscall *)(void *cache, uint32_t itemID,
-                                                       const uint64_t *guid, void *callback,
-                                                       void *userData, bool requestIfMissing);
-
 static const char *PushedOrEmpty(const char *s) { return (s != nullptr && s[0] != 0) ? s : ""; }
 
 static int CurrentLocaleIndex() { return *reinterpret_cast<int *>(Offsets::VAR_LOCALE_INDEX); }
 
-static const uint8_t *FetchItemRecord(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, false);
-}
-
 static const char *LookupItemClassName(uint32_t classID) {
     return PushedOrEmpty(DBC::LocalizedField(
         Offsets::VAR_ITEMCLASS_RECORDS, Offsets::VAR_ITEMCLASS_COUNT,
@@ -114,7 +104,7 @@ static int __fastcall Script_GetItemInfoInstant(void *L) {
 
     Game::Lua::PushNumber(L, static_cast<double>(itemID));
 
-    const uint8_t *record = FetchItemRecord(static_cast<uint32_t>(itemID));
+    const uint8_t *record = Item::PeekRecord(static_cast<uint32_t>(itemID));
     if (record == nullptr) {
         for (int i = 0; i < 6; ++i)
             Game::Lua::PushNil(L);
@@ -150,7 +140,7 @@ static int __fastcall Script_GetItemInfoInstant(void *L) {
 static int PushIconForItemID(void *L, int itemID) {
     if (itemID <= 0)
         return 0;
-    const uint8_t *record = FetchItemRecord(static_cast<uint32_t>(itemID));
+    const uint8_t *record = Item::PeekRecord(static_cast<uint32_t>(itemID));
     if (record == nullptr)
         return 0;
     const uint32_t displayInfoID = *reinterpret_cast<const uint32_t *>(
@@ -229,7 +219,7 @@ static int __fastcall Script_C_Item_GetItemFamily(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));
+    const uint8_t *record = Item::PeekRecord(static_cast<uint32_t>(itemID));
     if (record == nullptr) {
         Item::Data::WarmCache(static_cast<uint32_t>(itemID));
         return 0;
@@ -259,11 +249,12 @@ static int __fastcall Script_C_Item_GetItemFamily(void *L) {
 // 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);
+    const Item::Arg::Resolved arg = Item::Arg::Resolve(L, 1);
+    const int itemID = arg.itemID;
     if (itemID <= 0)
         return 0;
 
-    const uint8_t *record = FetchItemRecord(static_cast<uint32_t>(itemID));
+    const uint8_t *record = Item::PeekRecord(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
@@ -288,14 +279,24 @@ static int __fastcall Script_C_Item_GetItemInfo(void *L) {
     const char *description = *reinterpret_cast<const char *const *>(
         record + Offsets::OFF_ITEMSTATS_DESCRIPTION);
 
+    // Apply the link's random suffix ("... of the Owl") to both the name and
+    // the reconstructed link when the input carried one (arg.suffix); with no
+    // suffix these reduce to the base name / plain `item:N:0:0:0` link.
+    char suffixedName[128];
+    const char *displayName =
+        Item::Link::NameFromIDSuffix(static_cast<uint32_t>(itemID), arg.suffix,
+                                     suffixedName, sizeof(suffixedName))
+            ? suffixedName
+            : name;
+
     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));
+    const bool haveLink = Item::Link::BasicFromIDSuffix(static_cast<uint32_t>(itemID),
+                                                        arg.suffix, link, sizeof(link));
 
-    Game::Lua::PushString(L, PushedOrEmpty(name));                    // 1  itemName
+    Game::Lua::PushString(L, PushedOrEmpty(displayName));             // 1  itemName
     if (haveLink)
         Game::Lua::PushString(L, link);                              // 2  itemLink
     else

src/item/InventoryID.cpp

@@ -13,6 +13,7 @@
 
 #include "Game.h"
 #include "Offsets.h"
+#include "item/CGItem.h"
 #include "unit/Flags.h"
 
 #include <cstdint>
@@ -41,8 +42,7 @@ int ItemIDForLocalPlayer(void *playerPtr, int slot1Based) {
     auto *item = static_cast<uint8_t *>(getBySlot(invMgr, slot1Based - 1));
     if (item == nullptr)
         return 0;
-    auto *instance = *reinterpret_cast<uint8_t *const *>(
-        item + Offsets::OFF_ITEM_INSTANCE_BLOCK);
+    auto *instance = Item::InstanceBlock(item);
     if (instance == nullptr)
         return 0;
     return static_cast<int>(*reinterpret_cast<const uint32_t *>(
@@ -106,14 +106,17 @@ static int __fastcall Script_GetInventoryItemID(void *L) {
     int itemID = 0;
     if (unitPtr == playerPtr) {
         itemID = ItemIDForLocalPlayer(playerPtr, slot);
-    } else if (Unit::Flags::IsPlayerControlled(
+    } else if (Unit::Flags::IsPlayerObject(
                    static_cast<const uint8_t *>(unitPtr))) {
         itemID = ItemIDForOtherUnit(unitPtr, slot);
     } else {
-        // NPC / creature — no visible-items array. Returning nil here
-        // also matches `GetInventoryItemLink`'s practical behavior on
-        // NPCs (it crashes the client without this gate; addons that
-        // don't pre-filter the unit don't typically reach this path).
+        // Non-player object — no CGPlayer visible-items array at +0xE68.
+        // Gate on the object being a player, not merely player-controlled:
+        // a pet/totem/MC'd creature sets UNIT_FLAG_PLAYER_CONTROLLED but
+        // has no sub-struct there, so IsPlayerControlled would let it
+        // through and `ItemIDForOtherUnit` would deref garbage and crash
+        // (same root cause as pfUI issue #34). Returning nil also matches
+        // `GetInventoryItemLink`'s practical behavior on non-players.
         return 0;
     }
     if (itemID == 0)

src/item/InventoryItemsForSlot.cpp

@@ -46,6 +46,7 @@
 #include "item/ID.h"
 #include "item/Link.h"
 #include "item/Location.h"
+#include "item/Record.h"
 
 #include <cstdint>
 #include <vector>
@@ -54,10 +55,6 @@ namespace Item::InventoryItemsForSlot {
 
 namespace {
 
-using GetItemRecord_t = const uint8_t *(__thiscall *)(void *cache, uint32_t itemID,
-                                                      const uint64_t *guid, void *callback,
-                                                      void *userData, int unused);
-
 // invType → slot bitmask. Bit N (0-based) means "this item type fits
 // 1-based slot N+1". Values 0..28 cover every InventoryType
 // vanilla's Item.dbc emits. Indices outside this range read as 0
@@ -146,18 +143,11 @@ bool PlayerCanEquip(const uint8_t *record) {
     return PlayerHasProficiency(classCode, subclass);
 }
 
-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);
-}
-
 const uint8_t *ItemRecordForCGItem(const uint8_t *cgItem) {
     const int itemID = Item::ID::FromCGItem(cgItem);
     if (itemID <= 0)
         return nullptr;
-    return PeekItemRecord(static_cast<uint32_t>(itemID));
+    return Item::PeekRecord(static_cast<uint32_t>(itemID));
 }
 
 uint32_t ReadInventoryType(const uint8_t *record) {

src/item/InventoryType.cpp

@@ -17,6 +17,7 @@
 #include "item/Data.h"
 #include "item/ID.h"
 #include "item/Location.h"
+#include "item/Record.h"
 
 #include <cstdint>
 
@@ -24,21 +25,10 @@ namespace Item::InventoryType {
 
 namespace {
 
-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 PushInventoryTypeForItemID(void *L, int itemID) {
     if (itemID <= 0)
         return 0;
-    const uint8_t *record = PeekItemRecord(static_cast<uint32_t>(itemID));
+    const uint8_t *record = Item::PeekRecord(static_cast<uint32_t>(itemID));
     if (record == nullptr) {
         Item::Data::WarmCache(static_cast<uint32_t>(itemID));
         return 0;

src/item/Level.cpp

@@ -17,6 +17,7 @@
 #include "item/Data.h"
 #include "item/ID.h"
 #include "item/Location.h"
+#include "item/Record.h"
 
 #include <cstdint>
 
@@ -24,21 +25,10 @@ namespace Item::Level {
 
 namespace {
 
-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 PushItemLevelForItemID(void *L, int itemID) {
     if (itemID <= 0)
         return 0;
-    const uint8_t *record = PeekItemRecord(static_cast<uint32_t>(itemID));
+    const uint8_t *record = Item::PeekRecord(static_cast<uint32_t>(itemID));
     if (record == nullptr) {
         Item::Data::WarmCache(static_cast<uint32_t>(itemID));
         return 0;

src/item/Link.cpp

@@ -17,6 +17,7 @@
 #include "Offsets.h"
 #include "item/Location.h"
 #include "item/QualityColor.h"
+#include "item/Record.h"
 
 #include <cstdint>
 #include <cstdio>
@@ -30,19 +31,9 @@ using BuildItemLink_t = const char *(__fastcall *)(const void *cgItem);
 using BuildInstanceName_t = void(__thiscall *)(const void *cgItem, char *out,
                                                unsigned outSize);
 
-// Cached ItemStats record lookup. Same `_GetRecord` pattern the rest of
-// the codebase uses; passes a noop NULL callback so no SMSG fires for
-// uncached items — caller treats "not cached" as a clean failure.
-using GetItemRecord_t = const uint8_t *(__thiscall *)(void *cache, uint32_t itemID,
-                                                       const uint64_t *guid, void *callback,
-                                                       void *userData, int dedupFlag);
-
-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);
-}
+// Inner name builder, no CGItem needed: (out, outSize, itemID, suffixID).
+using BuildNameFromID_t = void(__fastcall *)(char *out, unsigned outSize,
+                                             uint32_t itemID, int suffixID);
 
 } // namespace
 
@@ -63,25 +54,45 @@ bool NameFromCGItem(const uint8_t *cgItem, char *out, size_t outSize) {
     return out[0] != '\0';
 }
 
-bool BasicFromItemID(uint32_t itemID, char *out, size_t outSize) {
+bool NameFromIDSuffix(uint32_t itemID, int suffixID, char *out, size_t outSize) {
     if (out == nullptr || outSize == 0)
         return false;
-    const uint8_t *record = PeekItemRecord(itemID);
+    out[0] = '\0';
+    auto fn = reinterpret_cast<BuildNameFromID_t>(
+        Offsets::FUN_ITEM_BUILD_NAME_FROM_ID);
+    fn(out, static_cast<unsigned>(outSize), itemID, suffixID);
+    return out[0] != '\0';
+}
+
+bool BasicFromIDSuffix(uint32_t itemID, int suffixID, char *out, size_t outSize) {
+    if (out == nullptr || outSize == 0)
+        return false;
+    const uint8_t *record = Item::PeekRecord(itemID);
     if (record == nullptr)
         return false;
-    const char *name = *reinterpret_cast<const char *const *>(
-        record + Offsets::OFF_ITEMSTATS_NAME);
-    if (name == nullptr || *name == '\0')
-        return false;
+    char name[128];
+    if (!NameFromIDSuffix(itemID, suffixID, name, sizeof(name))) {
+        // Suffix builder yielded nothing (e.g. suffix row missing) — fall back
+        // to the base record name so we at least produce a valid link.
+        const char *base = *reinterpret_cast<const char *const *>(
+            record + Offsets::OFF_ITEMSTATS_NAME);
+        if (base == nullptr || *base == '\0')
+            return false;
+        std::snprintf(name, sizeof(name), "%s", base);
+    }
     const uint32_t quality = *reinterpret_cast<const uint32_t *>(
         record + Offsets::OFF_ITEMSTATS_QUALITY);
     const int n = std::snprintf(out, outSize,
-        "%s|Hitem:%u:0:0:0|h[%s]|h|r",
+        "%s|Hitem:%u:0:%d:0|h[%s]|h|r",
         Item::QualityColor::Prefix(static_cast<int>(quality)),
-        itemID, name);
+        itemID, suffixID, name);
     return n > 0 && static_cast<size_t>(n) < outSize;
 }
 
+bool BasicFromItemID(uint32_t itemID, char *out, size_t outSize) {
+    return BasicFromIDSuffix(itemID, 0, out, outSize);
+}
+
 namespace {
 
 // `C_Item.GetItemLink(itemLocation)` — returns the fully-decorated

src/item/Link.h

@@ -51,4 +51,18 @@ bool NameFromCGItem(const uint8_t *cgItem, char *out, size_t outSize);
 // possible link (`item:` payload + colored prefix + bracketed name).
 bool BasicFromItemID(uint32_t itemID, char *out, size_t outSize);
 
+// Writes the suffix-decorated display name for `(itemID, suffixID)` into
+// `out` WITHOUT a live item instance — the by-string analog of
+// NameFromCGItem. `suffixID` is the 3rd `item:` field (random property /
+// suffix); 0 = base name. Applies the "... of the Owl" suffix via the
+// engine's inner builder (FUN_ITEM_BUILD_NAME_FROM_ID) when the item is
+// cached and the suffix is a valid ItemRandomProperties row. Returns false
+// (out empty) if the item isn't cached or has no name — warm and retry.
+bool NameFromIDSuffix(uint32_t itemID, int suffixID, char *out, size_t outSize);
+
+// Like BasicFromItemID but preserves the random `suffixID` in both the
+// `item:` payload (`item:N:0:suffix:0`) and the bracketed, suffix-decorated
+// name. `suffixID` 0 reduces exactly to BasicFromItemID.
+bool BasicFromIDSuffix(uint32_t itemID, int suffixID, char *out, size_t outSize);
+
 } // namespace Item::Link

src/item/Location.cpp

@@ -16,10 +16,13 @@
 #include "../Game.h"
 #include "../Offsets.h"
 #include "../guid/Guid.h"
+#include "../object/Resolve.h"
 #include "../unit/Identity.h"
 #include "Arg.h"
+#include "CGItem.h"
 #include "ID.h"
 #include "Link.h"
+#include "Record.h"
 
 #include <cstring>
 
@@ -30,9 +33,6 @@ namespace {
 using GetItemBySlot_t = void *(__thiscall *)(void *thisInvMgr, int slot);
 using PackBagSlot_t = int(__fastcall *)(void *L, void **outInvMgr, int *outLinearSlot,
                                          int *outUnused);
-using GetItemRecord_t = const uint8_t *(__thiscall *)(void *cache, uint32_t itemID,
-                                                      const uint64_t *guid, void *callback,
-                                                      void *userData, int unused);
 
 // Reads `loc.fieldName` and returns it as an int. Returns false via the
 // boolean result if the field is missing or non-numeric. Always leaves the
@@ -56,16 +56,8 @@ const uint8_t *ResolveBagSlot(void *L, int bagID, int slotIndex) {
 
 // --- GUID-walk helpers ---------------------------------------------------
 
-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);
-}
-
 uint64_t ReadCGItemGUID(const uint8_t *item) {
-    auto *instance = *reinterpret_cast<const uint8_t *const *>(
-        item + Offsets::OFF_ITEM_INSTANCE_BLOCK);
+    auto *instance = Item::InstanceBlock(item);
     if (instance == nullptr)
         return 0;
     return *reinterpret_cast<const uint64_t *>(
@@ -105,12 +97,8 @@ void *EquippedBagInventory(int bagID) {
     const uint64_t bagGuid = getBagGuid(static_cast<uint32_t>(bagID - 1));
     if (bagGuid == 0)
         return nullptr; // no bag equipped in that slot
-    using ResolveByGUID_t = void *(__fastcall *)(int, const char *, uint32_t,
-                                                  uint32_t, int);
-    auto resolve = reinterpret_cast<ResolveByGUID_t>(Offsets::FUN_OBJECT_RESOLVE_BY_GUID);
     auto *container = static_cast<const uint8_t *>(
-        resolve(Offsets::OBJ_TYPE_CONTAINER, "ItemMgr", static_cast<uint32_t>(bagGuid),
-                static_cast<uint32_t>(bagGuid >> 32), 0x172));
+        Object::ByGuid(Offsets::TYPEMASK_CONTAINER, bagGuid, "ItemMgr", 0x172));
     return ContainerInventory(container);
 }
 
@@ -128,7 +116,7 @@ int GetBagSlotCount(int bagID) {
     const int bagItemID = Item::ID::FromCGItem(bagItem);
     if (bagItemID == 0)
         return 0;
-    auto *record = PeekItemRecord(static_cast<uint32_t>(bagItemID));
+    auto *record = Item::PeekRecord(static_cast<uint32_t>(bagItemID));
     if (record == nullptr)
         return 0;
     return static_cast<int>(*reinterpret_cast<const uint32_t *>(
@@ -170,13 +158,8 @@ bool ParseGUIDString(const char *s, uint64_t *out) {
 const uint8_t *ResolveByGUID(uint64_t guid) {
     if (guid == 0)
         return nullptr;
-    using ResolveByGUID_t = void *(__fastcall *)(int, const char *, uint32_t,
-                                                  uint32_t, int);
-    auto fn = reinterpret_cast<ResolveByGUID_t>(Offsets::FUN_OBJECT_RESOLVE_BY_GUID);
-    return static_cast<const uint8_t *>(fn(Offsets::OBJ_TYPE_ITEM, "ItemMgr",
-                                            static_cast<uint32_t>(guid),
-                                            static_cast<uint32_t>(guid >> 32),
-                                            0x172));
+    return static_cast<const uint8_t *>(
+        Object::ByGuid(Offsets::TYPEMASK_ITEM, guid, "ItemMgr", 0x172));
 }
 
 bool FindByItemID(void *L, int itemID, ByGUIDResult *out) {

src/item/Location.h

@@ -70,7 +70,7 @@ const uint8_t *ResolveEquipmentSlot(int slot1Based);
 int GetBagSlotCount(int bagID);
 
 // Given a `CGContainer*` (an equipped bag or bank bag, resolved by GUID via
-// `FUN_OBJECT_RESOLVE_BY_GUID` with `OBJ_TYPE_CONTAINER`), returns its own
+// `FUN_OBJECT_RESOLVE_BY_GUID` with `TYPEMASK_CONTAINER`), returns its own
 // inventory-manager object via the container's vtable method at
 // `+OFF_CONTAINER_GET_INVENTORY`. The returned object has the same layout as
 // the player inventory manager: slot count at `+0x00`, flat GUID array at

src/item/Lock.cpp

@@ -32,6 +32,7 @@
 #include "Game.h"
 #include "Offsets.h"
 #include "guid/Guid.h"
+#include "item/CGItem.h"
 #include "item/Location.h"
 
 #include <cstdint>
@@ -54,8 +55,7 @@ using UnlockAll_t = void(__cdecl *)();
 bool ReadItemGuid(const uint8_t *item, uint32_t *lo, uint32_t *hi) {
     if (item == nullptr)
         return false;
-    auto *inst = *reinterpret_cast<const uint8_t *const *>(
-        item + Offsets::OFF_ITEM_INSTANCE_BLOCK);
+    auto *inst = Item::InstanceBlock(item);
     if (inst == nullptr)
         return false;
     *lo = *reinterpret_cast<const uint32_t *>(inst + Offsets::OFF_INSTANCE_BLOCK_GUID);

src/item/MaxStackSize.cpp

@@ -17,6 +17,7 @@
 #include "item/Data.h"
 #include "item/ID.h"
 #include "item/Location.h"
+#include "item/Record.h"
 
 #include <cstdint>
 
@@ -24,21 +25,10 @@ namespace Item::MaxStackSize {
 
 namespace {
 
-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 PushMaxStackSizeForItemID(void *L, int itemID) {
     if (itemID <= 0)
         return 0;
-    const uint8_t *record = PeekItemRecord(static_cast<uint32_t>(itemID));
+    const uint8_t *record = Item::PeekRecord(static_cast<uint32_t>(itemID));
     if (record == nullptr) {
         Item::Data::WarmCache(static_cast<uint32_t>(itemID));
         return 0;

src/item/Name.cpp

@@ -18,6 +18,7 @@
 #include "item/ID.h"
 #include "item/Link.h"
 #include "item/Location.h"
+#include "item/Record.h"
 
 #include <cstdint>
 
@@ -25,17 +26,6 @@ namespace Item::Name {
 
 namespace {
 
-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);
-}
-
 // Reads `m_name[0]` directly off a cached record. Items only ever
 // populate the first name slot — the array shape (`char *m_name[4]`
 // per VanillaHelpers's `ItemStats_C`) is a client-internal layout, not
@@ -44,7 +34,7 @@ const uint8_t *PeekItemRecord(uint32_t itemID) {
 int PushNameForItemID(void *L, int itemID) {
     if (itemID <= 0)
         return 0;
-    const uint8_t *record = PeekItemRecord(static_cast<uint32_t>(itemID));
+    const uint8_t *record = Item::PeekRecord(static_cast<uint32_t>(itemID));
     if (record == nullptr) {
         Item::Data::WarmCache(static_cast<uint32_t>(itemID));
         return 0;
@@ -94,8 +84,27 @@ static int __fastcall Script_C_Item_GetItemName(void *L) {
 // for `itemID`, firing a background cache fill on miss. Accepts the
 // same input shapes as `GetItemInfoInstant` (number, `"item:NNN..."`
 // string, or any string containing a parseable `item:NN` chunk).
+//
+// When the input is an item link carrying a random suffix
+// (`item:12022:0:769:0`), the returned name is suffix-decorated
+// ("Iridium Chain of the Owl") — the 3rd `item:` field is parsed and
+// applied via the engine's own name builder, so it matches the global
+// `GetItemInfo`'s name. A bare itemID (number or `item:N`) has no suffix
+// and yields the base name.
 static int __fastcall Script_C_Item_GetItemNameByID(void *L) {
-    return PushNameForItemID(L, Item::Arg::ResolveItemID(L, 1));
+    const Item::Arg::Resolved r = Item::Arg::Resolve(L, 1);
+    if (r.itemID <= 0)
+        return 0;
+    char buf[128];
+    if (Item::Link::NameFromIDSuffix(static_cast<uint32_t>(r.itemID), r.suffix,
+                                     buf, sizeof(buf))) {
+        Game::Lua::PushString(L, buf);
+        return 1;
+    }
+    // Not cached yet — fire a background fill and return nil (same miss
+    // behavior as the base-name path).
+    Item::Data::WarmCache(static_cast<uint32_t>(r.itemID));
+    return 0;
 }
 
 static void RegisterLuaFunctions() {