fix(loader): install hooks off the loader lock to survive VanillaFixes' 10s injection deadline

DllMain enabled ~90 hooks individually, and every MH_EnableHook freezes all process threads (CreateToolhelp32Snapshot + SuspendThread each) under the Windows loader lock. On machines whose security stack intercepts thread suspension, 90 serialized freezes ran past VanillaFixes' 10-second remote-LoadLibrary deadline, so VF read the still-running injection thread as STILL_ACTIVE (259) and showed its generic "compatible client" error — a false diagnosis of a slow load that blocked launch entirely for affected users. Move the whole install off the loader lock. DllMain now only spawns a worker thread and returns immediately. Hooks install via a latched EnsureInitialized() reached from two triggers: VanillaFixes' `Load` export (called on the game's main thread after injection — VF's sanctioned extension point) or the fallback worker (for any non-VF injector). Whichever arrives first installs; the other observes the cached result. All hooks are queued and activated in a single MH_ApplyQueued, so ~90 thread-freezes collapse to one. - src/DllMain.cpp: minimal DllMain + InstallHooks/EnsureInitialized/Load export - src/Game.cpp: RunHookRegistrations queues instead of enabling - src/ClassicAPI.def + CMake /DEF: export `Load` undecorated - src/Common.h: drop the now-dead HOOK_FUNCTION/UNHOOK_FUNCTION macros
docs: trim internal implementation detail from FontString entries
2026-11-12 12:57:37 +00:00 · 2026-08-19 17:46:59 -05:00 · 2026-08-19 17:04:02 -05:00 · 2026-08-19 16:58:56 -05:00 · 2026-08-19 16:48:38 -05:00 · 2026-08-19 16:46:55 -05:00
231 changed files with 15317 additions and 3277 deletions
@@ -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
@@ -45,4 +45,6 @@
 # debug information files
 *.dwo

-CLAUDE.md
+CLAUDE.md
+
+/AddOns/!!!ClassicAPI/.classicapi-dev
@@ -45,3 +45,4 @@ Util\Vector4D.lua
 Util\UIParent.lua
 Util\AuraDurationModifiers.lua
 Util\SecureUnitMenu.lua
+Util\TextureUtil.lua
@@ -58,3 +58,26 @@ if C_AddOns.DoesAddOnExist("ShaguTweaks") then
        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
@@ -7,46 +7,16 @@
 -- 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 C_UnitAuras.RegisterAuraDurationModifier mirrors the server's edit
-- off that trigger.
+-- cast, so a registered rule mirrors the server's edit off that trigger.
 --
-- A trigger is matched by exact spellID (stable across ranks -- these are the
-- IDs the server binds its spell script to); the affected aura by
-- SpellFamilyName + a family-flag overlap (rank-proof, exactly how the server
-- scripts locate it). Flags below are from the client's Spell.dbc. When the
-- trigger is a whole class of spells rather than a named ability,
-- RegisterAuraDurationModifierByTrigger matches it by SpellFamilyName + school
-- index instead (see Shadow Weaving below).
--
-- NOT included on purpose: Carnage's Rip/Rake refresh fires behind a
-- server-side probability roll on Ferocious Bite. The client can't know the
-- roll's outcome, so inferring it would show wrong timers. If you accept that,
-- register it yourself, e.g. (DRUID = 7):
--   C_UnitAuras.RegisterAuraDurationModifier(<ferociousBiteID>, 7, tonumber("800000",16), 108, "refresh") -- Rip
--   C_UnitAuras.RegisterAuraDurationModifier(<ferociousBiteID>, 7, tonumber("1000",16),   494, "refresh") -- Rake
-- Conflagrate's *full*-consume variant (other servers) removes Immolate
-- outright; that clears the aura slot and ClassicAPI evicts it via the normal
-- removal path, so the reduce rule below is harmless there and correct on
-- Turtle (where Immolate keeps ticking with 3s shaved off).
+-- 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).

-if TURTLE_WOW_VERSION then
-    local WARLOCK, SHAMAN = 5, 11
-    -- Lua 5.0 has no 0x hex literals; tonumber(hex, 16) keeps the flags readable.
-    local IMMOLATE_FLAG   = tonumber("4", 16)        -- CF_WARLOCK_IMMOLATE  (bit 2)
-    local FLAMESHOCK_FLAG = tonumber("10000000", 16) -- CF_SHAMAN_FLAME_SHOCK (bit 28)
-
-    -- Conflagrate (all ranks) -> shave 3s off the caster's Immolate.
-    local CONFLAGRATE = { 17962, 18930, 18931, 18932 }
-    for i = 1, table.getn(CONFLAGRATE) do
-        C_UnitAuras.RegisterAuraDurationModifier(CONFLAGRATE[i], WARLOCK, IMMOLATE_FLAG, 0, "reduce", 3)
-    end
-
-    -- Molten Blast (all ranks) -> refresh the caster's Flame Shock to full.
-    local MOLTEN_BLAST = { 36916, 36917, 36918, 36919, 36920, 36921 }
-    for i = 1, table.getn(MOLTEN_BLAST) do
-        C_UnitAuras.RegisterAuraDurationModifier(MOLTEN_BLAST[i], SHAMAN, FLAMESHOCK_FLAG, 0, "refresh")
-    end
-end
 -- 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
@@ -132,4 +132,9 @@ INSCRIPTION_AVAILABLE = false;
 EQUIPPED_FIRST = 1;
 EQUIPPED_LAST = 19;

-BASE_MOVEMENT_SPEED = 7;
+BASE_MOVEMENT_SPEED = 7;
+
+UPPER_LEFT_VERTEX = 1;
+LOWER_LEFT_VERTEX = 2;
+UPPER_RIGHT_VERTEX = 3;
+LOWER_RIGHT_VERTEX = 4;
@@ -2,12 +2,15 @@
 -- 1.12 / Lua 5.0.
 --
 -- 5.0 notes: no `#`/`%`/string-method syntax — uses string.*, math.mod.
-- The currency/cost helpers (C_CurrencyInfo etc.) are omitted. GetMoneyString
-- uses text symbols, not coin texture markup (markup doesn't render in 1.12).
+-- GetMoneyString gives the text-symbol form ("12g 34s 56c"). The coin-icon form
+-- (GetCoinTextureString / C_CurrencyInfo.GetCoinTextureString) is provided by the
+-- ClassicAPI DLL in C++ (src/currency/CoinText.cpp) — like retail, where it's a
+-- C function — now that the inline-texture backport renders |T markup in 1.12.
 --
 -- The FrameXML format-string globals these functions consume
-- (LARGE_NUMBER_SEPERATOR, PERCENTAGE_STRING, GOLD_AMOUNT_SYMBOL, …) are
-- defined in the locale layer (locales/enUS.lua), which loads first.
+-- (LARGE_NUMBER_SEPERATOR, PERCENTAGE_STRING, GOLD_AMOUNT_SYMBOL,
+-- GOLD_AMOUNT_TEXTURE, …) are defined in the locale layer (locales/enUS.lua),
+-- which loads first.

 COPPER_PER_SILVER = 100;
 SILVER_PER_GOLD = 100;
@@ -73,10 +76,9 @@ function SplitTextIntoHeaderAndNonHeader(text)
 end

 -- (money, separateThousands [, checkGoldThreshold, showZeroAsGold])
-- Text-symbol form ("12g 34s 56c"); the coin-texture form from the
-- reference is dropped since texture markup doesn't render in 1.12. The
-- checkGoldThreshold arg is accepted for signature compatibility but not
-- applied (it relied on modern Constants tables).
+-- Text-symbol form ("12g 34s 56c"); for the coin-icon form use
+-- GetCoinTextureString below. The checkGoldThreshold arg is accepted for
+-- signature compatibility but not applied (it relied on modern Constants tables).
 function GetMoneyString(money, separateThousands, checkGoldThreshold, showZeroAsGold)
    local gold = math.floor(money / COPPER_PER_GOLD);
    local silver = math.floor(math.mod(money, COPPER_PER_GOLD) / COPPER_PER_SILVER);
@@ -90,31 +90,3 @@ function GameTooltip_ShowCompareItem(self, shift)
 		end
 	end
 end
-
-- Guard the stock GameTooltip UPDATE_MOUSEOVER_UNIT handler (issue #12).
--
-- ClassicAPI's DLL now fires UPDATE_MOUSEOVER_UNIT on mouseover LOSS too (retail
-- parity), not just on gain. The stock inline handler in FrameXML/GameTooltip.xml
-- recolors the name unconditionally:
--     _G[this:GetName().."TextLeft1"]:SetTextColor(GameTooltip_UnitColor("mouseover"))
-- and GameTooltip_UnitColor returns white (1,1,1) when "mouseover" doesn't exist.
-- So the loss fire (and the transient clear that happens when clicking a unit)
-- repaints the still-visible/fading name white before it disappears -- reported
-- as NPC and PvP-flagged-player names flashing white.
--
-- We wrap the stock handler instead of replacing its body: swallow the event
-- only when there is no mouseover unit to color, otherwise delegate to the
-- original untouched. During the loss window the name simply keeps its last
-- color instead of going white; when a mouseover resolves again it recolors
-- normally. (1.12 OnEvent handlers read the `event`/`this` globals the engine
-- sets before invoking us, so calling the original as a plain function works.)
-local originalOnEvent = GameTooltip:GetScript("OnEvent")
-GameTooltip:SetScript("OnEvent", function()
-	if ( event == "UPDATE_MOUSEOVER_UNIT" and not UnitExists("mouseover") ) then
-		return;
-	end
-
-	if ( originalOnEvent ) then
-		originalOnEvent();
-	end
-end)
@@ -7,19 +7,46 @@
 -- 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.
+-- 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. 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.
+-- 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");
@@ -42,18 +69,57 @@ local function ResolveMenu(unit)
    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 name;
-    if which == "RAID_TARGET_ICON" then
-        name = RAID_TARGET_ICON;
-    end
    local dd = EnsureDropdown();
-    dd.initialize = function()
-        UnitPopup_ShowMenu(dd, which, unit, name);
+    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
@@ -0,0 +1,94 @@
+TextureUtil = {};
+
+function SetClampedTextureRotation(texture, rotationDegrees)
+    if (rotationDegrees ~= 0 and rotationDegrees ~= 90 and rotationDegrees ~= 180 and rotationDegrees ~= 270) then
+        error("SetRotation: rotationDegrees must be 0, 90, 180, or 270");
+        return;
+    end
+
+    if not (texture.rotationDegrees) then
+        texture.origTexCoords = {texture:GetTexCoord()};
+        texture.origWidth = texture:GetWidth();
+        texture.origHeight = texture:GetHeight();
+    end
+
+    if (texture.rotationDegrees == rotationDegrees) then
+        return;
+    end
+
+    texture.rotationDegrees = rotationDegrees;
+
+    if (rotationDegrees == 0 or rotationDegrees == 180) then
+        texture:SetWidth(texture.origWidth);
+        texture:SetHeight(texture.origHeight);
+    else
+        texture:SetWidth(texture.origHeight);
+        texture:SetHeight(texture.origWidth);
+    end
+
+    if (rotationDegrees == 0) then
+        texture:SetTexCoord( texture.origTexCoords[1], texture.origTexCoords[2],
+                             texture.origTexCoords[3], texture.origTexCoords[4],
+                             texture.origTexCoords[5], texture.origTexCoords[6],
+                             texture.origTexCoords[7], texture.origTexCoords[8] );
+    elseif (rotationDegrees == 90) then
+        texture:SetTexCoord( texture.origTexCoords[3], texture.origTexCoords[4],
+                             texture.origTexCoords[7], texture.origTexCoords[8],
+                             texture.origTexCoords[1], texture.origTexCoords[2],
+                             texture.origTexCoords[5], texture.origTexCoords[6] );
+    elseif (rotationDegrees == 180) then
+        texture:SetTexCoord( texture.origTexCoords[7], texture.origTexCoords[8],
+                             texture.origTexCoords[5], texture.origTexCoords[6],
+                             texture.origTexCoords[3], texture.origTexCoords[4],
+                             texture.origTexCoords[1], texture.origTexCoords[2] );
+    elseif (rotationDegrees == 270) then
+        texture:SetTexCoord( texture.origTexCoords[5], texture.origTexCoords[6],
+                             texture.origTexCoords[1], texture.origTexCoords[2],
+                             texture.origTexCoords[7], texture.origTexCoords[8],
+                             texture.origTexCoords[3], texture.origTexCoords[4] );
+    end
+end
+
+function ClearClampedTextureRotation(texture)
+    if (texture.rotationDegrees) then
+        SetClampedTextureRotation(texture, 0);
+        texture.origTexCoords = nil;
+        texture.origWidth = nil;
+        texture.origHeight = nil;
+        texture.rotationDegrees = nil;
+    end
+end
+
+function GetTexCoordsByGrid(xOffset, yOffset, textureWidth, textureHeight, gridWidth, gridHeight)
+    local widthPerGrid = gridWidth / textureWidth;
+    local heightPerGrid = gridHeight / textureHeight;
+    return (xOffset - 1) * widthPerGrid, (xOffset) * widthPerGrid, (yOffset - 1) * heightPerGrid, (yOffset) * heightPerGrid;
+end
+
+-- left/right/top/bottom are normalized [0..1] coords within the file (the
+-- markup's texel fields are produced by multiplying back up by the file size).
+function CreateTextureMarkup(file, fileWidth, fileHeight, width, height, left, right, top, bottom, xOffset, yOffset)
+    return string.format("|T%s:%d:%d:%d:%d:%d:%d:%d:%d:%d:%d|t",
+          file
+        , height
+        , width
+        , xOffset or 0
+        , yOffset or 0
+        , fileWidth
+        , fileHeight
+        , left * fileWidth
+        , right * fileWidth
+        , top * fileHeight
+        , bottom * fileHeight
+    );
+end
+
+function CreateSimpleTextureMarkup(file, width, height, xOffset, yOffset)
+    return string.format("|T%s:%d:%d:%d:%d|t",
+          file
+        , height or width
+        , width
+        , xOffset or 0
+        , yOffset or 0
+    );
+end
@@ -754,8 +754,8 @@ local function ShowTradeSkillLink(link, text)
 	frame.bar:SetMinMaxValues(0, (max and max > 0) and max or 1);
 	frame.bar:SetValue(cur or 0);
 	frame.barName:SetText(prof);
-	frame.barRank:SetText(string.format("%d/%d", cur or 0, max or 0));
-	frame.summary:SetText(string.format("%d of %d recipes known", known, total));
+	frame.barRank:SetFormattedText("%d/%d", cur or 0, max or 0);
+	frame.summary:SetFormattedText("%d of %d recipes known", known, total);
 	frame.recipes = knownList;
 	frame.subclassFilter = nil;

@@ -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";
@@ -1,11 +1,44 @@
 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";
+COPPER_AMOUNT_TEXTURE = "%d|TInterface\\MoneyFrame\\UI-MoneyIcons:%d:%d:0:0:4:1:2:3:0:1|t";
+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";
+GOLD_AMOUNT_TEXTURE = "%d|TInterface\\MoneyFrame\\UI-MoneyIcons:%d:%d:0:0:4:1:0:1:0:1|t";
+GOLD_AMOUNT_TEXTURE_STRING = "%s|TInterface\\MoneyFrame\\UI-MoneyIcons:%d:%d:0:0:4:1:0:1:0:1|t";
 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,8 +72,13 @@ 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";
+SILVER_AMOUNT_TEXTURE = "%d|TInterface\\MoneyFrame\\UI-MoneyIcons:%d:%d:0:0:4:1:1:2:0:1|t";
 SLASH_CLEARFOCUS1 = "/clearfocus";
 SLASH_CLEARFOCUS2 = "/clearfocus";
 SLASH_EQUIP_SET1 = "/equipset";
@@ -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";
@@ -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";
@@ -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 = "/сбросфокуса";
@@ -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";
@@ -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 = "/清除專注目標";
@@ -1018,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
@@ -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,13 @@ 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.)
+    # /DEF exports `Load` (VanillaFixes' post-injection entry point) undecorated
+    # so its GetProcAddress(module, "Load") resolves. See src/ClassicAPI.def and
+    # the loader-lock rationale in src/DllMain.cpp.
+    "/OPT:REF /OPT:ICF /MERGE:.rdata=.text /MERGE:.pdata=.text /SECTION:.text,EWR /NODEFAULTLIB:MSVCRT /MAP /DEF:${CMAKE_CURRENT_SOURCE_DIR}/src/ClassicAPI.def"
 )
@@ -20,6 +20,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | [Action](docs/API.md#action) | `GetActionInfo` |
 | [AddOns](docs/API.md#addons) | `C_AddOns.DoesAddOnExist`, `C_AddOns.GetAddOnName`, `C_AddOns.GetAddOnNotes`, `C_AddOns.GetAddOnOptionalDependencies`, `C_AddOns.GetAddOnSecurity`, `C_AddOns.GetAddOnTitle`, `C_AddOns.IsAddOnLoadable`, `C_AddOns.IsAddOnLoaded` |
 | [AuctionHouse](docs/API.md#auctionhouse) | `C_AuctionHouse.PostItem` |
+| [Bindings](docs/API.md#bindings) | `SetBindingSpell`, `SetBindingItem`, `SetBindingMacro`, `SetBindingClick`, `SetOverrideBinding`, `SetOverrideBindingSpell`, `SetOverrideBindingItem`, `SetOverrideBindingMacro`, `SetOverrideBindingClick`, `ClearOverrideBindings` |
 | [Chat](docs/API.md#chat) | `GetCurrentChatGUID` |
 | [ChatBubbles](docs/API.md#chatbubbles) | `C_ChatBubbles.GetAllChatBubbles` |
 | [Class](docs/API.md#class) | `FillLocalizedClassList` |
@@ -29,14 +30,15 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | [Cursor](docs/API.md#cursor) | `GetCursorInfo` |
 | [Container](docs/API.md#container) | `C_Container.CalculateTotalNumberOfFreeBagSlots`, `C_Container.GetContainerItemCharges`, `C_Container.GetContainerItemDurability`, `C_Container.GetContainerItemID`, `C_Container.GetContainerItemInfo`, `C_Container.GetContainerItemRepairCost`, `C_Container.GetContainerNumFreeSlots`, `C_Container.GetItemCooldown`, `C_Container.HasContainerItem`, `C_Container.IsContainerItemOpenable`, `C_Container.MoveItem`, `C_Container.PlayerHasHearthstone`, `C_Container.SwapItems`, `C_Container.UseHearthstone`, `GetItemCooldown` |
 | [Creature](docs/API.md#creature) | `C_CreatureInfo.GetCreatureID`, `C_CreatureInfo.GetCreatureInfoByID`, `C_CreatureInfo.RequestLoadCreatureByID`, `C_CreatureInfo.GetRaceInfo`, `C_CreatureInfo.GetClassInfo`, `C_CreatureInfo.GetCreatureFamilyInfo`, `C_CreatureInfo.GetCreatureFamilyIDs`, `C_CreatureInfo.GetFactionInfo`, `C_CreatureInfo.GetCreatureTypeInfo`, `C_CreatureInfo.GetCreatureTypeIDs` |
+| [Currency](docs/API.md#currency) | `GetCoinTextureString`, `C_CurrencyInfo.GetCoinTextureString` |
 | EncodingUtil | `C_EncodingUtil.CompressString`, `C_EncodingUtil.DecompressString`, `C_EncodingUtil.EncodeBase64`, `C_EncodingUtil.DecodeBase64`, `C_EncodingUtil.EncodeHex`, `C_EncodingUtil.DecodeHex`, `C_EncodingUtil.SerializeJSON`, `C_EncodingUtil.DeserializeJSON`, `C_EncodingUtil.SerializeCBOR`, `C_EncodingUtil.DeserializeCBOR` |
 | [EquipmentSet](docs/API.md#equipmentset) | `C_EquipmentSet.CanUseEquipmentSets`, `C_EquipmentSet.ClearIgnoredSlotsForSave`, `C_EquipmentSet.CreateEquipmentSet`, `C_EquipmentSet.DeleteEquipmentSet`, `C_EquipmentSet.EquipmentSetContainsLockedItems`, `C_EquipmentSet.GetEquipmentSetID`, `C_EquipmentSet.GetEquipmentSetIDs`, `C_EquipmentSet.GetEquipmentSetInfo`, `C_EquipmentSet.GetIgnoredSlots`, `C_EquipmentSet.GetItemIDs`, `C_EquipmentSet.GetItemLocations`, `C_EquipmentSet.GetNumEquipmentSets`, `C_EquipmentSet.IgnoreSlotForSave`, `C_EquipmentSet.IsSlotIgnoredForSave`, `C_EquipmentSet.ModifyEquipmentSet`, `C_EquipmentSet.SaveEquipmentSet`, `C_EquipmentSet.UnignoreSlotForSave`, `C_EquipmentSet.UseEquipmentSet` |
 | [Events](docs/API.md#events) | `C_EventUtils.IsEventValid`, `GetFramesRegisteredForEvent` |
 | [Expansion](docs/API.md#expansion) | `ClassicExpansionAtLeast`, `ClassicExpansionAtMost`, `GetClassicExpansionLevel` |
 | [Faction](docs/API.md#faction) | `C_Reputation.GetFactionDataByIndex`, `C_Reputation.GetFactionStandings`, `C_Reputation.GetLastStandingChange`, `C_Reputation.GetWatchedFactionData`, `C_Reputation.SetWatchedFactionByID`, `GetFactionIDByIndex`, `GetFactionInfoByID`, `GetFactionParentID` |
 | [Focus](docs/API.md#focus) | `ClearFocus`, `FocusUnit` |
-| [Frame](docs/API.md#frame) | `region:SetPoint("point")` (one-arg form), `region:SetSize`, `region:GetSize`, `region:IsMouseOver`, `region:GetRect`, `region:IsDragging`, `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.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`, `fontstring:GetStringHeight`, `texture:SetRotation`, `texture:GetRotation`, `texture:SetVertexOffset`, `texture:GetVertexOffset`, `texture:SetColorTexture`, `fontstring:SetRotation`, `fontstring:GetRotation`, `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` |
@@ -49,7 +51,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | [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` |
@@ -59,8 +61,8 @@ 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` |
-| [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` |
+| [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.GetSpellBookItemInfo`, `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`, `IsIndoors`, `IsInGroup`, `IsInRaid`, `IsLoggedIn`, `IsMounted`, `IsOutdoors`, `IsStealthed`, `IsSwimming` |
 | [System](docs/API.md#system) | `CopyToClipboard`, `GetPhysicalScreenSize` |
 | [Talent](docs/API.md#talent) | `GetTalentIDByIndex`, `GetTalentSpellID` |
@@ -70,8 +72,8 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | [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`, `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.RegisterAuraDurationModifier`, `C_UnitAuras.RegisterAuraDurationModifierByTrigger`, `C_UnitAuras.RegisterComboDuration` |
+| [Unit](docs/API.md#unit) | `ClosestUnitPosition`, `GetUnitSpeed`, `UnitClassBase`, `UnitCreatureFamilyID`, `UnitCreatureID`, `UnitCreatureTypeID`, `UnitDistanceSquared`, `UnitGUID`, `UnitHealthMissing`, `UnitInLineOfSight`, `UnitInRange`, `UnitIsAFK`, `UnitIsDND`, `UnitIsFeignDeath`, `UnitIsInMyGuild`, `UnitIsMinion`, `UnitIsOtherPlayersPet`, `UnitIsPet`, `UnitIsPossessed`, `UnitOwnerGUID`, `UnitPosition`, `UnitPower`, `UnitPowerMax`, `UnitPowerMissing`, `UnitPowerType`, `UnitRaceBase`, `UnitSpellHaste`, `UnitSpellTargetName`, `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` |

@@ -188,6 +190,8 @@ when launching with `-console`), not as Lua functions. See the
 | Inventory type | `Enum.InventoryType.Index*Type` (0–34, e.g. `IndexHeadType`=1 … `IndexRelicType`=28) |
 | Item class | `Enum.ItemClass.{Consumable,Container,Weapon,Gem,Armor,Reagent,Projectile,Tradegoods,ItemEnhancement,Recipe,Quiver,Questitem,Key,Miscellaneous,…}` (0–19) |
 | Item quality | `Enum.ItemQuality.{Poor,Common,Uncommon,Rare,Epic,Legendary,Artifact}` (0–6) |
+| Spellbook bank | `Enum.SpellBookSpellBank.{Player,Pet}` (0–1) |
+| Spellbook item type | `Enum.SpellBookItemType.{None,Spell,FutureSpell,PetAction,Flyout}` (0–4; 1.12 only yields `Spell`/`PetAction`) |

 ### Unit tokens

@@ -199,6 +203,17 @@ when launching with `-console`), not as Lua functions. See the

 ### Bindings

+ClassicAPI backports the later-client direct-action and temporary override
+binding families. Permanent bindings use the standard `SPELL`, `ITEM`,
+`MACRO`, and `CLICK` command strings and can be saved normally. Overrides are
+session-only, frame-owned, and support the usual priority flag.
+
+See the [Bindings API reference](docs/API.md#bindings) for signatures,
+precedence, execution behavior, macro-text usage, and 1.12 compatibility
+notes.
+
+#### Predefined focus bindings
+
 Injected into the engine's **Targeting Functions** group at FrameXML
 Bindings.xml load time, so they appear in the keybind UI alongside
 native targeting bindings instead of orphaned at the bottom.
@@ -208,7 +223,8 @@ native targeting bindings instead of orphaned at the bottom.
 | `FOCUSTARGET` | `FocusUnit("target")` — pin current target as focus |
 | `TARGETFOCUS` | `TargetUnit("focus")` — switch target to the focus |

-See [Focus / Bindings](docs/API.md#bindings-focustarget--targetfocus) for the implementation note.
+See [Predefined focus bindings](docs/API.md#predefined-focus-bindings-focustarget--targetfocus)
+for the implementation note.

 ### Behaviors

@@ -217,6 +233,7 @@ Transparent engine tweaks — no API to call, they just fix a vanilla limitation
 | Tweak | Effect |
 |-------|--------|
 | Tooltip line cap | Lifts `GameTooltip`'s hard 30-line limit to 60 for every `GameTooltipTemplate` frame (`GameTooltip`, `ShoppingTooltip1/2`, `ItemRefTooltip`, AtlasLoot, …). Stat-heavy tooltips and comparison blocks (e.g. pfUI's eqcompare) no longer have their extra lines silently dropped. Done in pure C++ by growing the engine's FontString pool at tooltip-creation time. |
+| Inline textures | Draws inline texture markup (`\|T…\|t`) as icons in FontStrings, chat, and tooltips, the way 4.3.4+ clients do. Vanilla 1.12 shows the raw escape as literal text instead. This covers item and spell icons, raid-target markers, and the coin icons in money strings. `GetStringWidth` and `GetStringHeight` count the icons, so measured width and text wrapping stay correct. Done in pure C++ by hooking the engine's text pipeline — no addon. |

 ## Installation

@@ -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")

@@ -0,0 +1,761 @@
+# Backporting inline `|T…|t` texture escape sequences to 1.12
+
+The 1.12 text engine shows `|Tpath:height:width:…|t` markup as literal text.
+This project makes it draw the icon inline in FontStrings, chat, and tooltips —
+the way 4.3.4 and later clients do. The feature is complete and shipped
+([src/text/InlineTexture.cpp](../src/text/InlineTexture.cpp),
+[src/text/InlineTexturePool.cpp](../src/text/InlineTexturePool.cpp)).
+
+This file is the reverse-engineering map. **Current design** below states what
+ships today. Everything from **Goal & spec** down is the historical RE trail —
+the 4.3.4 study, the 1.12 injection map, and the bring-up plan. It is kept for
+the addresses and the reasoning, not as a description of the current code.
+
+## Current design (shipped)
+
+Each icon renders as an **engine-managed region** (a pooled `CSimpleTexture`)
+anchored to its owning FontString. The engine draws the region every frame and
+moves it with its line, so texture residency and scroll tracking are correct by
+construction. (A raw-GxU-quad renderer existed during bring-up and was removed
+in `56c2670`; its RE is the "REMOVED" section below.)
+
+The DLL hooks the engine's own text pipeline — no companion addon:
+
+- **Positioning** — a co-hook on the glyph emitter `FUN_005ccbe0` records each
+  icon at its pen position and delegates the plain text runs to the engine
+  (segmented delegation, below). The pen read-back needed a fix: the engine's
+  pen is lazy and omits the last glyph's own advance, so a coin sat on its
+  digits; the emitter now adds the true terminal advance from the engine's own
+  glyph-advance helpers (`550cf5e`).
+- **Rendering** — the paint-pass co-hook `FUN_005c8fe0` walks the icon records
+  and queues each to `Text::InlineTexturePool`, which places the region on the
+  next frame tick (never mid-render).
+- **Placement coordinates** — text pen space IS render-target pixels. The
+  engine stores node positions NORMALIZED (fs-local anchor ÷
+  `[0x832A44]`/`[0x832A48]` per axis, `FUN_0041ade0`), and the origin finalize
+  `FUN_005cdf70` multiplies by the integer raster dimensions
+  `[0xC2B9A4]`/`[0xC2B9A0]` (rounded, with the justify shift and vertical
+  align folded in). So the flush converts pen → fs-relative anchor with
+  `K = raster ÷ anchorExtent`, **per axis**, from those four live globals — no
+  calibration, no cache, correct at every resolution and UI scale (`968335d`).
+  Two earlier forms both failed: an empirical K (`origin ÷ rect edge`) that
+  chat could never self-derive (its rect edge sits near screen x = 0 and
+  failed the divide guard) and so rode a global cache seeded by whichever
+  fontstring derived first — right only at the layout it was calibrated on;
+  then a closed form built from the SetPoint px factor, which used the wrong
+  global pair. Full derivation chain at `VAR_TEXT_RASTER_X/Y` in `Offsets.h`.
+- **Fade / parent alpha** — icons fade with their line (the pool mirrors the
+  fs's folded colour alpha per frame, `3ca3b7e`), and segmented GLYPHS do too:
+  a bit-3 (standalone FontString) node's baked per-glyph colours never re-bake
+  on an alpha change (the engine's colour-change invalidate `FUN_005ccb40`
+  skips bit-3 nodes), so the flush mirrors the node's live alpha byte
+  (node+0x2c — SetTextColor alpha × frame-chain alpha, kept folded by the
+  engine) into every baked colour, change-detected per page (`bd14a93`). An
+  earlier `0xFF` alpha force at emit was a misdiagnosis of a bubble that built
+  while faded out; it froze icon-line text fully opaque while everything
+  around it faded.
+- **Outlined fonts** — outline ink extends past the glyph advances; the
+  engine itself grows line height by exactly 4.0 / 2.0 pen px for thick / thin
+  outline (`face+0x180` bits 3 / 0, `.rdata` constants). `OutlineInkPen` reads
+  the same flags and constants, and half the ink leads each icon, half trails
+  — threaded through the shared advance helper so the emitter advance, the
+  justify pre-shift, and the wrap-stepper probes all agree. Without it, coins
+  clipped into outlined digits the moment the exact K removed the old
+  miscalibration's accidental slack (`968335d`).
+- **Measure** — three cold FontString-level co-hooks make measure match the
+  drawn result: width (`FUN_00772890`), height (`FUN_007729B0`), and wrap
+  (`FUN_005C7260`). `GetStringWidth`, `fontstring:GetStringHeight`, wrap
+  breaks, and line height all count the icon.
+- **Tall icons** — an icon taller than the font grows its line height, so it
+  does not overlap its neighbors, and it centers in the grown line. A hyperlink
+  that contains a tall icon is hoverable across the whole icon
+  (`49934b0`, `b9d0705`).
+- **Chat fade** — icons fade in lockstep with their chat line (`3ca3b7e`).
+- **Editboxes** — an editbox keeps the raw markup, so the caret stays aligned
+  (two complementary signals, below).
+- **Payload** — the full
+  `|Tpath:height:width:offsetX:offsetY:texW:texH:left:right:top:bottom:r:g:b|t`:
+  size, pen offset, sprite-sheet crop, and vertex tint. BLP and uncompressed
+  TGA.
+- **Anti-spoof** — chat strips player-injected `|T` icons.
+
+Every fs-level measure path now counts icons: width (`FUN_00772890`), height
+(`FUN_007729B0`), wrap (`FUN_005C7260`), and the substring measure
+(`FUN_00772AE0` — an earlier note claimed nothing consumed it; its xrefs
+refute that: the GameTooltip auto-size measures each WRAPPED SEGMENT of a
+wrap-enabled line through it, so icon-bearing wrapped tooltip lines
+undersized their tooltip until it was hooked too). The Lua control surface is
+one kill switch, `_classicapi_InlineTexEnable` (the SEH latch trips it on a
+flush fault); the bring-up tune / stat / probe functions were removed
+(`5e5677b`, `6800a9a`).
+
+## REMOVED (bring-up record) — the raw-GxU-quad rendering primitive
+
+This was the FIRST renderer: each icon drawn as a raw textured quad through the
+text VB path. It shipped, then was removed in `56c2670` for the engine-region
+model (regions are resident by construction; the quad path needed the texture-
+residency machinery below and still flickered on VRAM pressure — see
+`docs/InlineTextureResidency.md`). This section is the address record for the
+removed code, not a description of the current renderer. `LoadTextureByPath`,
+`DrawTexturedQuad`, and the GxU device offsets it names are gone from
+`Offsets.h`; the values live here and in git history.
+
+An arbitrary texture draws through the text VB path as a coloured, alpha-blended
+quad. The end-to-end recipe:
+
+1. **Load by path** — `LoadTextureByPath` replicates `FUN_00770200`'s load: build
+   flags via `FUN_0058a980(&flags, DAT_00878cf0, 0,0, 0,0,0, 1, 0)`, then
+   `FUN_00449d90(path, &desc, flags, 0, 1)` with a byte-identical 5-dword desc
+   (`{PTR_FUN_007ffa10, 8, &self8, (&self8)|1, 0}`). Returns the **HTEXTURE**
+   (0x15c-byte struct; path@+0xc, flags@+0x110, refcount@+4).
+2. **THE KEY — residency + correct bind via `FUN_0044acf0(HTEXTURE, 1, 0)`.**
+   This is the engine's own "get renderable texture" call (what the widget
+   render uses every frame). It returns the bindable **CGxTexture** at
+   `[HTEXTURE+0x140]` and, with force=1, drives the streaming load
+   (`FUN_0044ad50` submits/prioritises it via `[HTEXTURE+0x138]`). **Calling it
+   every frame is the live reference that makes the texture resident** — no
+   hidden widget, no manual BLP decode. This was the entire multi-session
+   blocker: WoW streams textures and only loads ones a live frame references; a
+   standalone `FUN_00449d90` texture never loads on its own. Binding the raw
+   HTEXTURE is `SetTexture([HTEXTURE+0x48]=0)` = a **white** quad; the D3D
+   handle lives on the CGxTexture (`[CGxTexture+0x48]`), not the HTEXTURE.
+   Dead ends that wasted time: manually invoking the decode callback
+   `FUN_0044a260` (fills `[+0x120]` but not the bindable `+0x140`, and faults);
+   binding `[HTEXTURE+0x48]` or `[HTEXTURE+0x120]` (both wrong offsets); forcing
+   the streamable flag `tex[0x3c]|=0x80` (crashes in d3d9 — the bind's stream-in
+   vfunc corrupts the resource).
+3. **Bind** — `FUN_00589e80(0x17, cgxTex)` (selector 0x17 = text texture stage).
+4. **Colour** — the font stage's default stage-0 COLOROP is already MODULATE, so
+   `texture.rgb × diffuse(white)` = the icon's true colours; texture alpha works
+   too. No colorop override is needed for a plain white vertex. (If a tint is
+   wanted later: COLOROP is D3DTSS internal state `0x42` via `FUN_005a2570`; the
+   engine leaves COLORARG1 at the D3D default = TEXTURE. Do NOT poke it directly
+   mid-draw — it leaks `MODULATE` to the whole UI when a fault skips the restore.
+   Use the engine's selector `0x1f` (value→COLOROP/ALPHAOP preset table at
+   `DAT_0080a25c`/`DAT_0080a274`; value 1 = MODULATE/MODULATE).)
+5. **Quad** — lock the shared dynamic VB `FUN_0058a140(0, 0x18, 0x800)`, get the
+   write ptr `FUN_0058a080`, write **4 verts** of the format
+   `{float x,y,z; u32 colorBGRA; float u,v}` (stride 0x18) in corner order
+   **TL, TR, BL, BR** (matches the shared quad index buffer `{0,1,2, 2,1,3}` and
+   the device cull winding), submit `FUN_005c8f40(&handle, 4)`, unlock
+   `FUN_0058a0a0(handle, 0)`.
+6. **Where** — co-hook the text paint pass `FUN_005c8fe0` and draw after the
+   original glyph flush (device is in the correct textured-UI state there).
+   Coordinate space is **per-layout pixels, y-down**; glyph verts live at small
+   local coords (a probed glyph was at ~(9,33)–(17,50)). Draw coords must be
+   within the layout's rendered area (a fixed (100,100) test lands in chat).
+
+The build-side gotcha: the D3D device (default backend, `FUN_0058dd70`) is
+actually **OpenGL** (`glMaterialfv`/`glFogi`) — the D3D backend is `FUN_0058ba70`
+(`FUN_00598ce0`, vtable `PTR_FUN_00809ef8`); its state applier is `vtable[1]` =
+`FUN_005a2f00`, which maps engine selectors to D3D via `FUN_005a2570`
+(SetRenderState `+0xe4`, SetTextureStageState `+0x10c`, SetSamplerState `+0x114`,
+SetTexture `+0x104`). Selector map (shared across GL/D3D backends): 7=blend,
+0x10=depthtest, 0x14=cullface, 0x17-0x1e=texture bind (8 units),
+0x1f-0x26=colorop/alphaop preset (unit 0-7).
+
+## SOLVED — positioning, measure/wrap, editbox exclusion, texcoords
+
+The primitive draws at arbitrary coords; the rest is knowing WHERE and WHEN.
+Everything is in [src/text/InlineTexture.cpp](../src/text/InlineTexture.cpp);
+offsets under the "Inline texture escape" + positioning blocks in
+[Offsets.h](../src/Offsets.h).
+
+### The text render hierarchy (verified)
+
+```
+frame → renderNode [frame+0x118] → group [renderNode+0x18]
+      → node [group+0x18]        → line [node+0x24]  ← the emitter's `this`
+```
+
+- Main UI render `FUN_007657d0(DAT_00cf0bd8)` walks strata → frames, calls
+  `FUN_0076fb00(renderNode)` per frame's render node.
+- `FUN_0076fb00` draws the frame's Texture regions then `FUN_005c1ef0(group)` →
+  `FUN_005c8b70(group)` → `FUN_005c8fe0(node)` per node.
+- `FUN_005c8fe0(node)` = the **paint pass** we co-hook: ensures each line built
+  (`FUN_005cd6a0` → `FUN_005cdc20` → the emitter), then binds each font page and
+  copies the line's per-page glyph batches into the dynamic VB, translated by the
+  line origin `[line+0x70]/[+0x74]`.
+- The **emitter** `FUN_005ccbe0(line, text, len, colorState, penXYZ, pageMask,
+  linkState)` builds one wrapped line's glyph quads. `this` (the "line"/node the
+  icon list keys on) owns batches `[+0xa0+page*4]` and origin `[+0x70]`. **Note
+  the render node the emitter sees has NO back-pointer up to the frame** — the
+  editbox discriminator had to be found another way (see below).
+
+### Positioning — segmented delegation (co-hook the emitter)
+
+We do NOT reimplement the emitter's intricate glyph vertex math. Instead, in the
+`FUN_005ccbe0` co-hook, for a line containing an inline texture:
+
+1. Split the line at icon boundaries. Render each **plain run** by calling the
+   ORIGINAL emitter on just that substring — the engine still draws every glyph.
+2. Thread the pen across runs: on return the emitter leaves the final node-local
+   pen x in **`linkState[4]`**, stored with `FSTP dword` — a **FLOAT bit
+   pattern**, not an int. Read it as a float (`*(float*)&linkState[4]`); an
+   int-cast yields garbage (this bug hid the icon off-screen and dropped the
+   trailing text).
+3. Record an `IconRecord` at the pen (node-local `x`,`y`) into `g_nodeIcons[line]`
+   and advance the pen by the icon width. No draw runs during the build — icons
+   are recorded and **flushed** in the `FUN_005c8fe0` paint co-hook, which
+   computes each icon's pen-space position (line origin `[line+0x70]/[+0x74]`
+   maps node-local → pen, the same translate the glyph copy `FUN_005c8710`
+   applies), converts pen → anchor with the per-axis K (see **Placement
+   coordinates** in Current design), and queues it to `Text::InlineTexturePool`
+   as a placement RELATIVE TO THE OWNING FONTSTRING. The pool applies
+   placements on the next frame tick.
+4. Restore `penXYZ[0]` on exit (the original never writes it; the draw builder
+   does NOT reset it between left-justified lines, so leaving it mutated
+   cascade-shifts every following line).
+
+### FontString pipe-doubling — the escape arrives as `||T…||t`
+
+The FontString text sanitizer **doubles any pipe that doesn't begin a recognized
+escape** so it renders as a literal `|`. 1.12 doesn't know `|T`, so a caller's
+`|Tpath:h|t` reaches the emitter as `||Tpath:h||t` (verified: emitter text length
+2, pipes doubled). The detector therefore matches BOTH the doubled form (the
+real-world case) and a clean `|T` (should one ever arrive undoubled). Normal
+doubled pipes (`|| `) never match because the next char must be `T`.
+
+### bit-3 batch-clear mode
+
+The emitter clears the line's page batches at its top only when node flag
+`[line+0x5c] & 0x08` is set (the FontString/static case). Calling the original
+per segment would then wipe all but the last run. Handled by doing the clear
+ONCE per build (a `len==0` original call with bit 3 still set), then clearing
+bit 3 so the per-segment calls APPEND, restoring flags on exit. Bit 5 (shadow)
+isn't set for these nodes, so the only added work is a harmless colour append.
+
+Clearing bit 3 has one more consequence: it switches the engine from the
+UNIFORM colour path (node+0x2c, consulted live at every paint) to baked
+PER-GLYPH colours the paint uses verbatim. The build-time alpha in colorState
+is already correct (the engine folds SetTextColor alpha × frame-chain alpha
+into node+0x2c on every alpha change), but the baked copies never refresh —
+the flush's alpha mirror keeps them tracking later fades. See **Fade / parent
+alpha** in Current design.
+
+### Multi-line / multi-icon accumulation
+
+The draw builder walks a node's wrapped lines by calling the emitter repeatedly
+on the SAME node, advancing the text pointer. So the icon list is cleared ONCE
+per build — on the first wrapped line, detected by `text == [node+0x48]` (the
+node's text start) — and icons ACCUMULATE across lines. Multiple icons per line
+fall out of the segmentation loop naturally.
+
+### Vertical centring — font-relative
+
+`penXYZ[1]` sits near the text TOP, so the icon centre = `penY + fontHeight *
+g_centerFrac` (0.6, calibrated in-game across chat + pfUI's bubble). Font height
+comes from the engine's own `FUN_005c6fa0(flag, [node+0x1c])` (the emitter's
+glyph-sizing call), so centring holds across font sizes without a fixed pixel
+nudge. A TALL icon (height > font) centres in its GROWN line (see the tall-icon
+sections in Current design) — the string-height co-hook adds the overflow, so
+the extra room sits half above and half below the text.
+
+### Measure / wrap — co-hook the tokenizer
+
+Line wrap is decided by the measure/fit functions (`FUN_005c6940`, `FUN_005c7470`
+via `FUN_005c7260`), which all share the `|`-tokenizer `FUN_005c2810`. Left
+alone, they count the hidden path text and wrap early. Fix: co-hook the
+tokenizer — when it's at an inline-texture span, consume the whole span as ONE
+near-zero-width token so every measure/fit caller ignores the path characters.
+The emitter detects icons independently (it scans the raw bytes), so the draw
+path is unaffected.
+
+### Measure width: FIXED at the fs-level choke (`GetStringWidth` counts icons)
+
+The tokenizer reports an icon span as a **near-zero-width** token, so at the
+gxu loop level every measure caller counts the icon as ~0 pixels wide. (The
+emitter still reserves the render width, so text after an icon positions
+correctly.) An earlier version of this doc concluded that the gap could not
+be closed cleanly, because the gxu engine has **no single cold choke**:
+
+- `FUN_005c6940` (width), `FUN_005c7470`/`FUN_005c7260` (wrap), and the
+  hit-test loop each tokenize and accrue width independently.
+- The token contract has no width field.
+- The per-glyph helpers (`FUN_005cabd0`/`FUN_005c6b70`) are the hottest text
+  functions in the engine.
+
+That analysis was right about the gxu level. The choke sits ONE LEVEL UP:
+**`FUN_00772890` = `CSimpleFontString::GetStringWidthInternal`**
+(`Offsets::FUN_FONTSTRING_STRING_WIDTH`) is cold, MinHook-safe, and the single
+funnel for exactly 4 callers:
+
+- `Script_GetStringWidth` (0x0079E510)
+- the GameTooltip auto-size (0x00530640)
+- the editbox caret positioner (0x0077DE70)
+- the layout effective-width vmethod (`FUN_00772930` = fs+0x24 vtbl +0x1C,
+  which feeds auto-width fontstring layout)
+
+It lazily computes into the `fs+0xFC` cache (anchor units, 0.0 sentinel) via
+the measure core `FUN_0044D670`, then divides the pen-space result by
+`fs+0x7C`.
+
+The co-hook lives in `src/text/InlineTexture.cpp`. It calls the original,
+then adds `SumIconAdvances(text) / K` when two gates pass:
+
+- `InlineInterceptActive(text)` is true — the **same predicate** the tokenizer
+  hook stands down on, factored into one function so measure and render can
+  never disagree.
+- The fs is not an editbox: `fs+0x120 & 0x1000` is clear (the fs-level bit
+  `FUN_0044D670` translates into the gxu editbox flag 0x40).
+
+The icon sum is computed in TRUE PEN PX — the exact numbers the emitter
+reserves — and bridged into the getter's return space by the font height
+known in both spaces: `sumPen × (fontHInt / fontHPen)`. `ResolveFsPenFont`
+replicates the render chain: `fontHPen = round((fontHInt × fs+0x7C, floored
+at [0x801628]/rasterY) × rasterY)` (the rebuild's node fontSize + the node
+ctor's min clamp + the emitter's own height helper), and the outline ink
+resolves through `face = [[fs+0xE0]+0x20]` — the same object the node stores
+at +0x44. fs-built nodes are always in snap mode (no fs-flag maps to node
+bit 7), so the snap-truncated advances are exact. The per-icon advance comes
+from `IconAdvancePen`, the **same helper** the emitter reserves with — so the
+measured width matches the rendered width by construction, outline ink and
+pixel snapping included. (An earlier bridge used the SetPoint push factor
+`div×1024/mul ≈ 1468` as the intermediate — the units cancelled for `:0`
+icons, but it couldn't express the truncation or the ink.)
+
+Unit trap (hit on first flight): escape sizes are UI PIXELS. Do NOT divide
+the icon sum by `fs+0x7C` — that field is the layout UI *scale* (~0.68–1.0).
+The original's own `out / fs+0x7C` applies to a value the measure core
+already ran through the `FUN_0041AD80` gxu→internal converter, not to raw
+pixels. The `/0x7C` version measured a 16px icon as +44k px.
+
+The hook NEVER writes the `fs+0xFC` cache: the original can serve the cached
+value, so the icon sum is re-derived and re-added per call (idempotent).
+
+The same hook also fixes two layout consumers for free: tooltips auto-size
+wide enough for icon-bearing lines, and auto-width fontstrings lay out at
+their true rendered width.
+
+### Wrap: FIXED at the shared stepper (`FUN_TEXT_WRAP_STEPPER` = 0x005C7260)
+
+Wrap decisions also measured icons as ~0, so a chat line with prefix icons
+broke as if the icons were not there and the emitter's real advances ran past
+the right edge. The choke is the wrap-stepper dispatcher `FUN_005C7260`: it
+lays out one wrapped line per call, and its exactly 4 callers are EVERY wrap
+consumer — the draw builder `FUN_005CDC20` (render breaks), the height
+measure `FUN_005C2070`, the chars-that-fit counter `FUN_005C21C0` (ellipsis),
+and the break-array computer `FUN_005C2430` (behind `FUN_00772B60`).
+
+The co-hook shrinks the `wrapWidth` argument by a **minimal feasible
+shrink**, gated on the same `InlineInterceptActive` predicate plus the flags
+editbox bit 0x40 the dispatcher already carries. The stepper reports each
+probe's measured (icons-at-zero) line width in `outWidth`, which gives a
+direct feasibility check: the line renders inside the frame iff its icons
+fit in the shrink plus the spare the break left (`iconSum ≤ s + (probeW −
+outWidth)`). The hook probes sandboxed (local out-params plus a COPY of the
+`p10` in/out state byte, so the caller's first-line state is not consumed):
+s = 0 first (feasible → no shrink at all — the common short-message case),
+escalate by the measured deficit when infeasible, bisect down after the
+first feasible hit; ≤8 probes, and with no feasible hit the last escalation
+target wins (wraps early rather than overflowing). The feasibility check
+carries a HALF-GLYPH tolerance: an auto-width fontstring (single anchor, no
+width — e.g. pfUI's addon-list labels) wraps at the icon-inclusive string
+width our GetStringWidth hook feeds the effective-width vmethod, so its line
+fits with exactly zero slack, and cross-computation drift between the two
+hooks' unit chains (plus OUTLINE extras and the trailing-glyph quirk) read
+"fits exactly" as "1px over" — shrinking a zero-slack line forces a wrap
+that had no business existing. Genuine icon overflow is ≥ a full icon, so
+half a glyph separates drift from real overflow. `outBreak` and
+`outNext − text` are byte counts; `outBreak == len` means the whole text
+fit. Two rejected earlier schemes, for the record: a naive whole-remaining-
+text sum shredded an 8-icon line to one word per line, and a fixed-point
+iteration on the icon count oscillated (a ~55-byte zero-width escape makes
+the break↔icon-count coupling discontinuous — no fixed point exists).
+`text` always points at the REMAINING text, so a continuation line whose
+icons are behind it gets sum = 0. Because all four consumers share the hook,
+render breaks, `GetStringHeight`, truncation, and break arrays shift
+together. (A `_classicapi_InlineTexWrap(n)` ring dumped the last 8
+icon-bearing calls during bring-up; removed with the other diagnostics in
+`5e5677b`.)
+
+Unit trap #2 (hit TWICE): the stepper's inputs are gxu-normalized, PER AXIS —
+fontH is normalized-Y (× rasterY = pen px) and wrapWidth/outWidth are
+normalized-X (× rasterX = pen px). Both caller flavors land there: the draw
+builder passes node+0x1C/+0x3C (normalized at block creation), and the
+fs-level callers (the path chat wraps through) x-normalize their widths
+inside `FUN_0044d670` before gxu. First flight subtracted raw pixels and
+annihilated the small normalized widths (2-glyph chat fragments). The second
+converted with `fontH / fontHPx` — a Y-AXIS factor applied to an X-axis
+width — overshrinking the budget by the render aspect (×1.33 at 4:3, ×2.37
+at 2560×1080): icon-bearing chat lines wrapped a word or two early, worse per
+icon and per aspect. The correct pen-x → width-units factor is `1/rasterX`,
+and the glyph-relative tolerances use `fontHPx/rasterX` so "half a glyph"
+means an actual glyph width.
+
+**Chat hyperlink hover over inline icons works (verified).** An emote wrapped in a
+hyperlink — `|Htel:name|h|T…|t|h`, the TwitchEmotes pattern — pops its tooltip when
+you hover the *icon*, not just adjacent text. The hover region is NOT re-measured
+on hover: the engine records each hyperlink's screen rect at layout time into a
+`GXUFONTHYPERLINKINFO` array (32-byte entries: rect + link data) via `FUN_005cd310`,
+called from the draw builder `FUN_005cdc20` — the same layout pass that runs the
+line through our co-hooked tokenizer (`FUN_005c2810`) and wrap-stepper
+(`FUN_005c7260`). So the recorded rect rides the same icon-aware position
+accounting the wrap fix installs; the icon lands inside the hover region for free,
+and hovering it fires the frame's `OnHyperlinkEnter`. This is a consequence of the
+wrap fix, not a separate feature. (Ghidra caveat: the decompile of the
+`FUN_005cd310` call args is mangled — a pointer-as-float + an uninitialized temp —
+so this is confirmed by the call path plus in-game test, not the byte-level
+formula.)
+
+**Still icon-blind (accepted residuals):**
+
+- Sub-pixel only for a string-final icon: the width hooks report its INK edge
+  (advance minus the trail half-pad/ink — `TrailingIconTrimPen`), matching the
+  engine's own last-glyph convention (the gxu width loop ends on ink, not
+  advance — the source of the old −0.8px measurement, whose previous-glyph
+  advance treatment is semantically CORRECT once an icon renders after it).
+  What remains is the icon region's ±0.5px placement rounding and the base
+  loop's ~0 contribution for the payload-0 icon token.
+- An fs whose `fs+0xFC` cache was filled while the feature was toggled
+  differently (`_classicapi_InlineTexEnable`) keeps its old base width until
+  the next `SetText`/font change re-dirties it. Debug-toggle-only.
+
+**Editbox measure stays raw (by design).** The caret/measure path reads the
+focused editbox's INPUT buffer in place, and the tokenizer stands down on it
+per-editbox (`TextInFocusedEditbox` pointer-range test — not a global focus
+check), so caret math measures the raw `|T…|t` literal the editbox renders.
+The width hook mirrors that with the `fs+0x120 & 0x1000` editable gate. One
+marginal wobble: the focused single-line chat editbox's display fontstring
+carries editable=0 (only multi-line editors set the bit), so the caret
+positioner's line-boundary branch (multi-line-only in practice) can see an
+icon-adjusted `FUN_00772890` on it. Closing that costs a per-token content
+compare, which is not worth it.
+
+### Editbox exclusion — two COMPLEMENTARY signals (bit 6 + focus global)
+
+Editable text must show raw, editable `|T…|t` markup, not rendered icons — you
+edit macros, tweak icon fields, copy/paste texture strings. **This is
+retail-correct, verified in-game on a modern client:** typing
+`|TInterface\Icons\INV_Misc_Coin_01:16|t` into the chat entry box OR a macro body
+shows it **raw** (no icon) — Blizzard neutralizes player-*typed* escape sequences
+as anti-abuse — while addon/system text (`AddMessage`, `GetCoinTextureString`)
+renders. Retail's discriminator is the text's SOURCE (trusted vs player-typed),
+not editbox-vs-display; a shift-clicked item link renders in the chat box because
+it's inserted through the trusted path, but a typed `|T`/`|c` does not. Our
+editbox-raw + display-renders split reproduces the same observable outcome. (One
+mechanism-level divergence we accept: our editbox-raw uses the GLOBAL focus signal
+below, so while an editbox is focused OTHER display text that rebuilds also
+briefly shows raw; retail suppresses per-source. Cosmetic, and a per-editbox fix
+would need hot-path text-buffer matching — not worth it.) 1.12's tokenizer,
+unlike 4.3.4's, has no per-render texture-disable bit (4.3.4 uses tokenizer flag
+**0x1000** to kill only `|T`, **0x800** to kill all escapes), and editbox text
+nodes are NOT distinguishable by class from the render node — the emitter can't
+reach the owning frame. It takes **two signals together**, not one (an earlier
+version of this note wrongly called the focus global a redundant "belt-and-
+suspenders fallback" — removing it renders the chat/copy boxes' `|T` as icons):
+
+- **Node flag `[node+0x5c]` bit 6 (0x40) = EDITABLE** — catches the **macro
+  editor** (`MacroFrameText`, flags `0x4D`), which builds its layout once,
+  **un-focused**, so the focus global never sees it. But single-line inputs
+  (chat entry box, `pfChatCopyBox`) have bit 6 **CLEAR** — their nodes are
+  `0x0D`/`0x20D`, identical to display FontStrings — so bit 6 can't catch them.
+- **Focused-editbox global `DAT_00cf4dc8`** (`InputFocused()`; holds the editbox
+  with keyboard focus, cleared by `ClearFocus` = `FUN_0077e410`) — catches those
+  single-line inputs. It's GLOBAL (true UI-wide, not per-node), which is why,
+  while an editbox is focused, other display text that *rebuilds* also briefly
+  renders raw. That's an accepted tradeoff: there is no per-node signal for
+  single-line inputs, and when you're in an editbox seeing raw markup is what you
+  want anyway.
+
+**Why the tokenizer's bit-6 gate is load-bearing for RENDER, not just measure:**
+when the emitter suppresses an editbox it delegates to the ORIGINAL emitter,
+which **re-enters the tokenizer** to lay out glyphs (`FUN_005ccbe0` →
+`FUN_005c2810`). On that render path `flags` is the node's own flags, so bit
+0x40 makes the tokenizer stand down and the `|T` draws as literal text. Drop the
+bit-6 gate and the (un-focused) macro editor draws **BLANK** — the tokenizer eats
+the span as a zero-width token and the original emitter renders nothing (verified
+in-game). Focused single-line inputs get the same "don't intercept" via
+`Suppressed()` → `InputFocused()`. So both the emitter and the tokenizer consult
+`Suppressed() || bit-6`; the two must agree or you get blank-vs-raw mismatches.
+
+(Dead end: **monochrome render flag `DAT_00c2b9dc`** (`FUN_005c8b70` sets it per
+group) — un-set at MacroFrameText's build time and flickered as a flush gate.
+Dropped. The editbox class vtable is `0x0081c8c0`, its script-slot resolver
+`FUN_0077a310` with focus slots at `+0x438`/`+0x440` — useful if a frame-level
+hook is ever needed.)
+
+### Descriptor fields + the vertical flip
+
+`ParseIcon` handles the full positional payload
+`path:height:width:offsetX:offsetY:texW:texH:left:right:top:bottom:r:g:b`.
+Texcoords crop a sprite sheet to one cell: `u = left/texW, right/texW`,
+`v = top/texH, bottom/texH` — e.g. `UI-RaidTargetingIcons` is a 256×256 sheet,
+4×2 grid of 64×64, so marker N's cell is `256:256:<col*64>:<+64>:<row*64>:<+64>`.
+
+**Vertex colour (`r:g:b`, 0-255):** the last three positional fields tint the
+icon. They pack to `0xFFrrggbb` — the same `0xAARRGGBB` order the tokenizer's
+`|cAARRGGBB` colour path builds (verified from `FUN_005c2810`'s colour branch),
+so the value flows straight into the quad's vertex colour and the font stage's
+default MODULATE COLOROP multiplies `texture.rgb × tint`. White (`255:255:255`,
+the default) = untinted. Because parsing is positional, a tint needs all the
+preceding fields present; the `TintIcon` helper passes `0`s for width..bottom
+(texW/texH `0` disables the texcoord crop → full texture) so the colour lands in
+the trailing slots.
+
+**Texcoord order:** the region's 4-float texcoord setter
+(`FUN_SIMPLETEXTURE_SET_TEXCOORD`) takes the rect **Y-FIRST INTERLEAVED**
+(`{v0, u0, v1, u1}`), matching the engine's `{yA, left, yB, right}` rect
+convention — diagnosed in-game when `{u0,v0,u1,v1}` rendered a raid-mark crop as
+the wrong cell. v is top-down, same as the `|T` payload's top/bottom fields.
+(The removed quad path had the inverse concern: the OpenGL backend put v=0 at
+the bottom, so the quad mapped the TOP screen corners to v1 — kept here as the
+backend note.)
+
+### Build / deploy / test cadence
+
+- `set -o pipefail; cmake --build build --config Release 2>&1 | tail -5 && cp build/Release/ClassicAPI.dll "C:/WoW/Octo/dll/ClassicAPI.dll"`
+  — `pipefail` stops a failed build from deploying a stale DLL.
+- **The client must be fully EXITED to relink** (it loads a symlink to the
+  linker's output). DLL changes need a full restart, not `/reload`.
+- **The embedded `!!!ClassicAPI` addon is symlinked**, so Lua-only changes (the
+  `TextureTest()` harness in `Util/AddOnCompat.lua`) need only `/reload`.
+
+### Remaining / optional
+
+- **Measure width, height, wrap** — all DONE (the three fs-level co-hooks in
+  Current design). Vertex-colour tint (`:r:g:b`) — DONE. The bring-up
+  diagnostics (`_classicapi_InlineTexSuppress/Tune/Stats/ProbeFS/RegionCal/Wrap`
+  and the capture globals) were REMOVED (`5e5677b`); only
+  `_classicapi_InlineTexEnable` remains.
+- **Animated emotes** — no DLL work is needed: a TwitchEmotes-style animator
+  re-`SetText`s each line ~30fps and rewrites the `|T` texcoords to crop the
+  current film-strip frame. That is addon Lua. RLE-compressed TGAs do not
+  decode in 1.12 (uncompressed only) — convert with
+  `magick in.tga -compress none in.tga` (no `-orient`/`-flip`: the region
+  renderer's texcoord order shows the frame right-side-up).
+- **Still icon-blind** (accepted): the hyperlink hit-test past a tall icon
+  OUTSIDE the link on the same line. The substring measure `FUN_00772AE0` was
+  hooked once its real consumer surfaced (the tooltip auto-size measures
+  wrapped SEGMENTS with it), and the trailing-icon width residual is trimmed
+  to sub-pixel (`TrailingIconTrimPen` — a string-final icon reports its ink
+  edge, not its advance, per the engine's own last-glyph convention).
+
+## Goal & spec
+
+Render the modern inline-texture escape (warcraft.wiki.gg/wiki/UI_escape_sequences#Textures):
+
+```
+|Tpath:height[:width[:offsetX:offsetY[:texWidth:texHeight:left:right:top:bottom[:rV:gV:bV]]]]|t
+```
+
+Atlas markup (`|A:atlas:…|a`) is Legion+ (needs an atlas DB 1.12 lacks) — out
+of scope. FileDataID paths are Legion+ — 1.12 resolves texture PATH strings
+only.
+
+## Confirmed: 1.12 has ZERO inline-texture support
+
+In-game test on the target client — all of these render as literal text, no
+icon:
+
+```
+|TInterface\Icons\INV_Misc_Coin_01:16|t
+|TInterface\Icons\INV_Misc_Coin_01:16:16|t
+|TInterface\Icons\INV_Misc_Coin_01:16:16:0:0|t
+```
+
+Root cause (see 1.12 map below): the shared escape tokenizer has no `T`/`t`
+case, so `|T` falls through to "literal `|` + ordinary glyphs".
+
+## Reference: 4.3.4 (`C:\WoW\Proudmoore\apwow.exe`, build 15595)
+
+4.3.4's text pipeline is a shared `|`-tokenizer feeding per-purpose loops that
+`switch` on the returned token type. It DOES support `|T`.
+
+- **Tokenizer `FUN_00613980`** — reads one token, returns a type code, bytes
+  consumed (`*param2`), payload char (`*param5`). `|`-switch token types:
+  `1`=color(`|c`+8 hex), `2`=reset(`|r`), `3`=break(`|n`/newline), `4`=`||`,
+  `5`=`|H`, `6`=`|h`, **`7`=texture(`|T`…`|t`)**, `8`=`|t`, `9`/`10`=`|K`/`|k`
+  callback, `0xb`/`0xc`=`|W`/`|w`, `0`=ordinary glyph. The `T` case scans
+  forward to the closing `|t` and returns 7 with the whole span's byte length.
+- **Field parser `FUN_00617ba0(tokenStart, &desc, size)`** — splits the `|T`
+  payload on `:` (helpers: `FUN_0040fa50`=strchr, `FUN_004b3d00`=atof,
+  `FUN_004b3480`=atoi) into a **0x40-byte descriptor**:
+
+  | off | field |
+  |----|-------|
+  | `+0x10`/`+0x14` | path ptr / length (up to first `:`) |
+  | `+0x18` | height (font-scaled) — required |
+  | `+0x1C` | width (defaults to height) |
+  | `+0x20`/`+0x24` | offsetX / offsetY |
+  | `+0x28`–`+0x34` | 4 normalized texcoords (texel ÷ texW/texH) |
+  | `+0x3C` | hasTexCoords flag |
+  | `+0x38`–`+0x3B` | vertex B/G/R/A |
+  | `+0x3D` | hasColor flag |
+
+- **Measure loop `FUN_00618430`** — walks tokens; `case 7` calls
+  `FUN_00617ba0` and adds the texture width to the pen.
+- **Draw emitter `FUN_0061ea10`** (analog of 1.12 `FUN_005ccbe0`) — its
+  `case 7` is the texture draw:
+  1. `FUN_00617ba0(tokenStart, &desc)` — parse fields into the descriptor
+     (stored inline on the line-state struct at `param7+0xb`, 0x10 dwords).
+  2. Compute pen x, width (`desc.width[+0x18 dword = param7[0x12]] * scale`),
+     and y from the justify mode `[obj+0x58]` (0=baseline, 1=center, 2=top).
+  3. Copy the descriptor to a stack struct and call **`FUN_0061e820`** — the
+     inline-texture quad emit. (`FUN_0061dd50` handles a region-state 1→2
+     transition when a texture interrupts a hyperlink capture.)
+- **`FUN_0061e820`** — normalizes the 4 quad corners (÷ screen w/h from
+  `DAT_00dd9ea0`/`DAT_00dd9ea4`) and calls `FUN_0061e410(1, &verts)`.
+- **`FUN_0061e410(count=1, &verts)`** (`__thiscall`, ECX = a vertex-buffer
+  object) — appends `count` quads of **0x40 bytes** (one quad = pos + texcoords)
+  to a **dedicated inline-texture vertex buffer**, growing it as needed
+  (`FUN_0061db40`). So inline textures accumulate in their OWN batch, separate
+  from the per-font-page glyph batches, each quad carrying its own texture
+  (bound at flush). This is the concrete confirmation of the "separate quad
+  path" — the backport must add such a batch + flush on the 1.12 side.
+
+## Target: 1.12 (`C:\WoW\Octo\WoW.exe`, build 5875) injection map
+
+Same architecture as 4.3.4, different addresses and token numbering. Reached
+from `Script_GetStringWidth` (`FUN_0079e510`) → `FUN_00772890` →
+`FUN_0044d670` → `FUN_005c2050` → the loops.
+
+- **Shared tokenizer `FUN_005c2810`** — `~11 callers`. `|`-switch token types:
+  `0`=color(`|c`), `1`=reset(`|r`), `2`=break(`|n`/newline), `3`=`||`,
+  `4`=`|H`, `5`=`|h`, `6`=ordinary glyph. **No `T`/`t` case** → `|T` hits the
+  fall-through (`*param5=0x7c; return 6`) = literal `|` then glyphs. Adding a
+  texture token means picking an unused code (e.g. `7`).
+- **Measure loop `FUN_005c6940`** — `switch`: `0/1/4/5` zero-width, `2` break,
+  default glyph (advance via `FUN_005c6b70`; kerning `FUN_005ca2d0`/
+  `FUN_005ca4b0`). No texture case.
+- **Fit/width loops** `FUN_005c6c50` (chars-into-width + per-char x, for
+  cursor/wrap) and `FUN_005c7470` (truncation/ellipsis). Same switch shape.
+- **Draw builder `FUN_005cdc20`** — reads the layout object's text at `[+0x48]`,
+  handles line-wrap / justify (`[+0x54]`) / color state, per line calls the
+  glyph emitter and `FUN_005cd310` (hyperlink rect registration).
+- **Glyph emitter `FUN_005ccbe0`** — the real quad emitter. Per glyph:
+  `FUN_005cabd0(fontFace,char)` → glyph record (atlas **page** at `rec[10]`,
+  advance `rec[0x12]`, texcoords `rec[0x18..0x1b]`), then appends 4 verts to a
+  **per-atlas-page** batch at `[obj + page*4 + 0xa0]`. `case 0/1` set/reset
+  color, `4/5` open/close hyperlink region, default = glyph.
+
+### The architectural wrinkle
+
+Glyph quads batch **per font-atlas page**. An inline `|T` texture is an
+arbitrary texture, not a font page, so it cannot join that batch — it needs a
+**separate textured-quad draw** (its own draw call, correctly ordered against
+the glyph batches so it appears inline). This is the substantive work, not the
+tokenizing. 4.3.4 solves it exactly this way — captured below: its draw `case 7`
+appends the quad to a dedicated inline-texture vertex buffer at
+`renderObject+0x9c`, separate from the per-font-page glyph batches (see the
+`FUN_0061ea10` / `FUN_0061e820` items under Open items).
+
+## Strategy
+
+The tokenizer is shared by ~11 callers, so DON'T just make it return a new
+type — the other callers' `switch`es would hit `default` and mis-handle it.
+Instead:
+
+1. **Reimplement (co-hook) the measure loop `FUN_005c6940` and the draw
+   builder `FUN_005cdc20`/emitter `FUN_005ccbe0`** — copy existing logic
+   (fully decompiled), delegate every non-texture token to the original
+   handling, and add an inline `|T…|t` case: measure → advance pen by texture
+   width; draw → emit the arbitrary-texture quad.
+2. **Port `FUN_00617ba0`** (field parse → 0x40 descriptor). Standalone, safe to
+   write now from the 4.3.4 decompilation; needs 1.12 equivalents of strchr/
+   atof/atoi (trivial or already in `Offsets.h`).
+3. **Leave the shared tokenizer `FUN_005c2810` and the other ~9 callers
+   untouched** — they keep rendering `|T` literally (wrap/cursor math slightly
+   off inside a texture in v1 — cosmetic, extend later).
+4. **Texture load by path** — reuse the engine's `Texture:SetTexture` loader;
+   **quad emit** — the primitive 4.3.4's draw case uses (to pin).
+
+Risk: the hot text path (every string every frame). But these are
+deterministic C functions, NOT the contended nampower/SuperWoW targets, so the
+MinHook-collision concern is low. Reimplementing two complex loops faithfully
+is the real cost.
+
+## Incremental slices
+
+1. Fixed-size `|Tpath:height|t` — render + width only (ignore width/offset/
+   texcoord/color). Proves the end-to-end quad path.
+2. width, offsetX/Y.
+3. texcoords (`texW:texH:l:r:t:b`).
+4. vertex color.
+5. correct wrap/cursor (extend `FUN_005c6c50`/`FUN_005c7470`).
+
+## Open items / next steps
+
+- [x] **4.3.4 draw-side `case 7`** — captured: `FUN_0061ea10` case 7 →
+      `FUN_00617ba0` (parse) + `FUN_0061e820`→`FUN_0061e410` (append quad to a
+      dedicated inline-texture vertex buffer). Separate batch, per-quad texture.
+- [x] **4.3.4 inline-texture buffer located** — `FUN_0061e820` (`RET 0x40`,
+      i.e. a 0x40-byte quad struct by value) does `ADD ECX,0x9c` before
+      `FUN_0061e410`, so the dedicated inline-texture vertex buffer is at
+      **renderObject+0x9c** (glyph batches are the `+0xa0 + page*4` array — the
+      two are adjacent but distinct). Quad struct: positions at `+0x8..+0x14`,
+      texcoords at `+0x20..+0x2c` (rest = z / texture handle / color). Appended
+      one quad at a time via `FUN_0061e410(this=buf@+0x9c, count, &quad)`.
+- [x] **Flush + path→texture load** — NOT traced on the 4.3.4 side by design;
+      its purpose (the flush + per-quad texture bind + path→load mechanism) is
+      fully answered on the **1.12 side** below: paint/flush `FUN_005c8fe0`,
+      bind `FUN_00589e80(0x17,tex)` + draw `FUN_005c8f40`, load `FUN_00449d90`.
+      4.3.4's own `+0x9c`-buffer flush is not needed — we implement against 1.12.
+- [x] **1.12 path→texture loader** — `FUN_00770200(textureObj, path, flag,
+      blend=DAT_00878cf0, flag)`. It's the string-path branch of
+      `Script_Texture_SetTexture` (`FUN_0079bb40`, method-table entry at
+      `0x0087c1a0`). This is how a `|T` path becomes a bound texture.
+- [x] **1.12 batch render + textured-quad GPU primitive — FOUND.** The paint
+      pass is `FUN_005c8fe0(layoutObj)`: it ensures each line built
+      (`FUN_005cd6a0`), then per font page (stride 0x18, indices 0..7 over
+      `[obj+0x18c+page*0x18]` = the page's texture object) does:
+      - **bind texture:** `FUN_00589e80(0x17, texturePage)` (0x17 = the texture
+        render-state selector),
+      - **lock dynamic VB:** `FUN_0058a140(0, stride=0x18, 0x800)` → handle;
+        `FUN_0058a080(handle)` → vertex data ptr,
+      - copy the page's built verts from the per-page batch at
+        `[lineObj + 0xa0 + page*4]` (`FUN_005ce090`=count, `FUN_005ce0c0`=copy),
+      - **draw:** `FUN_005c8f40(&handle, vertCount)` (flush/submit),
+      - **unlock:** `FUN_0058a0a0(handle, 0)`.
+
+      **Vertex stride = 0x18** (24 bytes = pos + uv + packed color). So an inline
+      `|T` quad = 4 (or 6) such verts, bound to its own texture. Reuse path for
+      the `|T` draw: `FUN_00589e80(0x17, inlineTex)` → write quad verts →
+      `FUN_005c8f40`. **`FUN_005c8fe0` is the co-hook site for strategy B** —
+      after the glyph batches are drawn, draw the frame's collected `|T` quads.
+- [x] **Path → bindable texture handle — RESOLVED.** `FUN_00770200`
+      (SetTexture-by-path) internally calls **`FUN_00449d90(path, &desc, flags,
+      0, 1)`** — the general path→CGxTexture loader (normalizes path, by-name
+      cache, creates on miss via `FUN_0044a140`/`FUN_0044a310`, returns a
+      **fallback texture on failure so never null**) — and stores the handle at
+      `textureObj+0xcc`. That handle is the SAME CGxTexture type
+      `FUN_00589e80(0x17, tex)` binds (the `tex[0x3c]` streamable flag +
+      non-null `*tex` that `FUN_00593840` checks are CGxTexture fields; font
+      pages and Texture widgets bind identically). So a `|T` draws as:
+      `tex = FUN_00449d90(path,&desc,flags,0,1)` → `FUN_00589e80(0x17,tex)` →
+      write 4 verts (stride 0x18) → `FUN_005c8f40(&vb,n)`. No scratch widget
+      needed if we replicate `FUN_00770200`'s descriptor setup
+      (`FUN_0058a980(&desc, blend, …)` then `FUN_00449d90`); or, simplest, keep
+      one scratch Texture object, `FUN_00770200(scratch,path,…)`, read
+      `[scratch+0xcc]`. The internal by-name cache makes repeats cheap.
+
+Two implementation strategies once the primitive is pinned:
+- **A (mirror 4.3.4):** own a separate inline-texture vertex buffer, flush it
+  in the paint pass alongside the glyph batches. Faithful, more integration.
+- **B (immediate):** at paint time, draw each collected `|T` quad immediately
+  via the GxU primitive (bind `FUN_00770200`'d texture, draw one quad). Simpler;
+  inline textures are few, so per-quad draw calls are fine. Likely the better
+  first cut.
+- [ ] Confirm 1.12's tokenizer flag bits (`param4 & 0x100/0x200/0x400/0x800`)
+      that gate color/escape handling, so the reimplemented loops pass them
+      through unchanged.
+
+## Reality check on scope — how it actually landed
+
+The plan above feared reimplementing 1.12's glyph emitter `FUN_005ccbe0` (a
+long, intricate function) and the measure loop. It did not come to that. The
+shipped design avoids both:
+
+- **Positioning** does NOT reimplement the emitter — it SEGMENTS the line at
+  icon boundaries and delegates each plain run to the ORIGINAL emitter, so the
+  engine still lays out every glyph. We only track where the icons go.
+- **Rendering** does NOT stand up a separate quad batch — icons are
+  engine-managed regions anchored to their FontString (the removed quad batch
+  was strategy B; regions replaced it).
+- **Measure** does NOT reimplement the loops — three cold co-hooks on the
+  fs-level width / height / wrap functions add the icons' contribution and call
+  the originals.
+
+The result is the largest feature in the project, but built from co-hooks that
+delegate to the engine rather than from reimplemented layout code. It was
+verified by in-game iteration over many build/test rounds, as expected.
@@ -0,0 +1,115 @@
+# Why inline icons render as engine regions
+
+Inline `|T…|t` icons render as pooled `CSimpleTexture` regions
+([src/text/InlineTexturePool.cpp](../src/text/InlineTexturePool.cpp)) — one per
+visible icon, anchored to the icon's owning FontString. The engine draws each
+region every frame like any UI texture, so the icon is resident by construction
+and moves with its line for free. This is 4.3.4's `CSimpleEmbeddedTexture`
+model, built from the parts 1.12 ships.
+
+This file records why that design was chosen and the RE behind it. A raw-GxU-
+quad renderer came first and was removed (`56c2670`).
+
+## History — a residency misdiagnosis, corrected
+
+The quad renderer flickered: a random subset of chat icons blanked on scroll,
+and a second client showed no icons at all. The first diagnosis was **texture
+residency** — the theory that a raw quad bound a texture the VRAM manager had
+evicted, because a raw quad is owned by no frame object.
+
+That diagnosis was wrong. The real cause was the Large-Address-Aware pointer
+bound (`dc61f77`): a 2GB cap in the flush's `LooksReadable` check rejected valid
+heap pointers above `0x80000000`, and the flush's node walk BREAKS on a rejected
+node. So one high node truncated the walk, and every node after it lost its
+icon. That is the "random subset blanks" pattern, and a second client shows none
+because it grows the heap past 2GB sooner. With the bound fixed, the raw quads
+did not flicker either.
+
+So engine regions are kept for **4.3.4 parity**, not necessity. They are
+resident by construction, which closes the residency question for good — but the
+question was never the real bug. Do not re-open the residency investigation; the
+D3D notes at the end are the record of what was ruled out.
+
+## The region the pool builds
+
+1.12 ships `CSimpleTexture` — the ordinary `Texture` widget
+(`frame:CreateTexture()`). It is a managed, reference-counted, `CGxTexCache`-
+backed, engine-drawn texture. The only thing 3.3.5's `CSimpleEmbeddedTexture`
+adds is automatic inline layout inside the FontString, and the emitter already
+computes the icon positions — so the pool supplies them. (`CSimpleEmbeddedTexture`
+is compiled into 3.3.5 only; RTTI confirms it is absent from 1.12.)
+
+Per icon, the pool takes a pooled region and sets the texture, texcoords,
+colour, and two anchor points relative to the owning FontString's bottom-left.
+The engine then owns load, residency, managed-pool reload, clipping, and draw.
+
+### 1.12 entry points (used by the pool)
+
+RTTI name strings: `.?AVCSimpleTexture@@` @ `0x00846588`,
+`.?AVCSimpleFontString@@` @ `0x00846544`.
+
+Create a `CSimpleTexture` from C (mirrors `Tooltip::LinePool`'s FontString path):
+
+```
+void* mem = FUN_00760450(&DAT_00cf4ce0, 0, /*rtti*/0x00846588, 0xFFFFFFFE); // pool alloc
+void* tex = FUN_0076fc40(mem, parentFrame, /*drawLayer*/2, /*sublayer*/1);   // ctor
+```
+
+Set the texture path (loads through the engine's own loader, owns the handle):
+
+```
+FUN_00770200(tex, path, 0, DAT_00878cf0, 0);  // CSimpleTexture::SetTexture(path)
+```
+
+`FUN_00770200` builds GxTexFlags (`FUN_0058a980`), loads via `FUN_00449d90`,
+stores the HTEXTURE at `tex+0xCC` (owned ref), releases the old one
+(`FUN_0041aed0`), and marks the region dirty. This ownership is the whole
+residency story — the engine holds the texture and reloads it on eviction.
+
+Region methods the pool calls directly:
+
+| method | C++ target |
+|---|---|
+| SetTexCoord | `FUN_00770410(tex, &{v0,u0,v1,u1})` — Y-FIRST interleaved |
+| SetColor | `FUN_0077F750(tex, &BGRA)` — also the chat-fade alpha mirror |
+| SetPoint | `FUN_00767C70` — internal units (see LinePool `PixelToInternal`) |
+| Show / Hide | `FUN_0077FCB0` / `FUN_0077FC60` (desired-shown `+0xC4`, realized `+0xC8`) |
+
+`CSimpleTexture` layout (from ctor `FUN_0076fc40`): vtable `0x0081c718`;
+region-render vtable at `+0x24`; HTEXTURE `+0xCC`; blend `+0xD0`; per-corner
+quad position/texcoord arrays `+0xD4..+0x100` (`OFF_SIMPLETEXTURE_CORNERS`);
+`+0x128` a flag. The region-render vtable slot 0 (`0x00770670`) computes the
+screen rect and calls `FUN_007705b0` to STORE the quad corners; the GPU draw is
+deferred to the engine's batched region paint.
+
+## The pen↔anchor bridge
+
+The emitter computes icon positions in PEN units; the pool stores region
+`SetPoint` offsets in ANCHOR units, relative to the FontString's rect. The
+bridge is one scale `K` (pen units per anchor unit) plus the FontString's own
+rect: the flush reads the FontString rect and derives `K` per node, converts
+each icon's screen rect to FontString-relative anchor offsets, and queues that.
+The pool applies the queued placement on the next frame tick — never mid-render.
+`K` derivation and the FontString-relative store are in `FlushLayout`
+([src/text/InlineTexture.cpp](../src/text/InlineTexture.cpp)); the
+convergence pass in `Maintain`
+([src/text/InlineTexturePool.cpp](../src/text/InlineTexturePool.cpp)) self-heals
+any residual scale from the region's own frame-scale chain.
+
+## What was ruled out during the residency chase (do not re-investigate)
+
+The blank icons had zero CPU-side signature — records present, node chain
+contiguous, geometry sane, index buffer ready at submit, batched draw, z-buffer
+excluded twice. The full D3D9 render state at the true draw point was benign:
+`zFunc=8` always, `aBlend=1`, `colorW=0xF`, scissor and stencil off, texture
+stage MODULATE with a valid bound texture every draw. All of this was consistent
+with the LAA-bound truncation (the node never reached the draw), not with a lost
+texture surface.
+
+D3D9 device access, if it is ever needed again:
+
+- `IDirect3DDevice9* = *(void**)(*(void**)0x00C0ED38 + 0x38a8)` (CGxDeviceD3d).
+- `GetRenderState` = device vtable `+0xE8`; `SetRenderState` `+0xE4`.
+- The GxU re-applies its cached render states before every draw (`FUN_005a1b20`),
+  so a raw `SetRenderState` for a GxU-managed state is overwritten; `ZENABLE` is
+  not in that path, so a direct set survives.
@@ -0,0 +1,9 @@
+; Exports for ClassicAPI.dll.
+;
+; `Load` is VanillaFixes' post-injection entry point: after the launcher
+; injects each dlls.txt DLL, the VanillaFixes runtime calls the DLL's `Load`
+; export on the game's MAIN thread (GetProcAddress(module, "Load")), outside
+; the loader lock and with no timeout. Listing it here exports it undecorated
+; as "Load" so GetProcAddress finds it regardless of calling convention.
+EXPORTS
+    Load
@@ -13,26 +13,6 @@

 namespace Common {

-#define HOOK_FUNCTION(offset, hook, original)                                                      \
-    {                                                                                              \
-        auto *target = reinterpret_cast<LPVOID>(offset);                                           \
-        if (MH_CreateHook(target, reinterpret_cast<LPVOID>(hook),                                  \
-                          reinterpret_cast<LPVOID *>(&original)) != MH_OK)                         \
-            return FALSE;                                                                          \
-        if (MH_EnableHook(target) != MH_OK)                                                        \
-            return FALSE;                                                                          \
-    }
-
-#define UNHOOK_FUNCTION(offset, original)                                                          \
-    {                                                                                              \
-        auto *target = reinterpret_cast<LPVOID>(offset);                                           \
-        if (MH_DisableHook(target) != MH_OK)                                                       \
-            return FALSE;                                                                          \
-        if (MH_RemoveHook(target) != MH_OK)                                                        \
-            return FALSE;                                                                          \
-        (original) = nullptr;                                                                      \
-    }
-
 bool PatchBytes(void *dst, const void *src, size_t len);

 } // namespace Common
@@ -16,8 +16,12 @@
 #include "MinHook.h"
 #include "Offsets.h"
 #include "event/Custom.h"
+#include "model/DisplayInfo.h"
 #include "nameplate/Walk.h"
 #include "player/NameCache.h"
+#include "text/InlineTexture.h"
+#include "text/InlineTexturePool.h"
+#include "texture/Transform.h"

 static Game::FrameScript_Initialize_t FrameScript_Initialize_o = nullptr;
 static Game::LoadScriptFunctions_t LoadScriptFunctions_o = nullptr;
@@ -47,6 +51,20 @@ static bool __fastcall FrameScript_Initialize_h() {
    // cache to clear here.
    NamePlate::Events::PrepareForReload();

+    // The reload teardown destroys every icon pool texture, fontstring,
+    // and text node — forget all inline-icon pointers now so nothing
+    // touches them (see InlineTexture.h / InlineTexturePool.h).
+    Text::InlineTexture::PrepareForReload();
+    Text::InlineTexturePool::PrepareForReload();
+
+    // Drop per-region corner transforms (SetRotation / SetVertexOffset) — the
+    // reload destroys every addon texture and the region pool reuses their pointers.
+    Texture::Transform::PrepareForReload();
+
+    // Drop pending character-dress jobs and their engine compositors — the
+    // reload destroys every Model frame the jobs point at.
+    Model::DisplayInfo::PrepareForReload();
+
    // Persist the name cache before the engine starts tearing down.
    // This hook fires on both `/reload` and `/logout` (the engine
    // re-initializes Lua state in both cases), giving us a clean
@@ -71,6 +89,13 @@ static void __fastcall LoadScriptFunctions_h() {
 static void __stdcall LoadGlueScriptFunctions_h() {
    LoadGlueScriptFunctions_o();
    Game::RunGlueModuleRegistrations();
+    // World→glue teardown destroyed every world fontstring and text node the
+    // inline-icon maps reference; forget them now that the glue UI is booting.
+    // (Glue→world is covered by FrameScript_Initialize_h; the node-free hook
+    // handles individual deaths, but bulk teardown paths may bypass it.)
+    Text::InlineTexture::PrepareForReload();
+    Text::InlineTexturePool::PrepareForReload();
+    Texture::Transform::PrepareForReload();
 }

 // Every Lua-side `frame:RegisterEvent(...)` is a chance to claim a slot
@@ -86,47 +111,134 @@ static void __fastcall FrameRegisterEvent_h(void *frame, void *edx,
    FrameRegisterEvent_o(frame, edx, eventName);
 }

+// ---------------------------------------------------------------------------
+// Hook install — kept OFF the Windows loader lock.
+//
+// Every MH_EnableHook freezes all process threads (CreateToolhelp32Snapshot +
+// SuspendThread/GetThreadContext each). Doing ~90 of those from DllMain, under
+// the loader lock, is the pattern MinHook documents as unsafe: on machines
+// whose security stack intercepts thread suspension it stalled the remote
+// LoadLibrary thread past VanillaFixes' 10-second injection deadline, so VF
+// read the still-running thread as STILL_ACTIVE (259) and showed its generic
+// "compatible client" error — a false diagnosis of a slow load.
+//
+// So DllMain installs nothing. The install runs later, on a thread that does
+// NOT hold the loader lock, via one of two triggers that both funnel through
+// the latched EnsureInitialized():
+//   * VanillaFixes' `Load` export, called on the game's main thread after
+//     injection (the sanctioned VF extension point), or
+//   * a fallback worker thread we spawn from DllMain, for any other injector
+//     that never calls `Load`.
+// Whichever arrives first installs; the other observes the cached result.
+// ---------------------------------------------------------------------------
+
+static volatile LONG g_initClaimed = 0;    // 0 until a thread takes the installer role
+static volatile LONG g_initDone = 0;       // 0 until the install has finished
+static volatile LONG g_initResult = 1;     // 0 = success, 1 = failure (until proven)
+static volatile LONG g_mhInitialized = 0;  // MH_Initialize succeeded (gates detach teardown)
+
+static bool CreateAndQueue(uintptr_t offset, void *hook, void **original) {
+    auto *target = reinterpret_cast<LPVOID>(offset);
+    if (MH_CreateHook(target, hook, original) != MH_OK)
+        return false;
+    // Queue only — a single MH_ApplyQueued below applies the whole batch in
+    // one thread-freeze.
+    if (MH_QueueEnableHook(target) != MH_OK)
+        return false;
+    return true;
+}
+
+static bool InstallHooks() {
+    if (MH_Initialize() != MH_OK)
+        return false;
+    InterlockedExchange(&g_mhInitialized, 1);
+
+    if (!CreateAndQueue(Offsets::FUN_INVALID_FUNCTION_PTR_CHECK,
+                        reinterpret_cast<void *>(InvalidFunctionPtrCheck_h), nullptr))
+        return false;
+
+    // Four core init hooks — each runs glue logic (PrepareForReload,
+    // RunModuleRegistrations, RunGlueModuleRegistrations, EnableWrites,
+    // RetryClaims) tightly coupled to DllMain state, so a declarative
+    // HookAutoRegister wouldn't simplify them.
+    if (!CreateAndQueue(Offsets::FUN_FRAME_SCRIPT_INITIALIZE,
+                        reinterpret_cast<void *>(FrameScript_Initialize_h),
+                        reinterpret_cast<void **>(&FrameScript_Initialize_o)))
+        return false;
+    if (!CreateAndQueue(Offsets::FUN_LOAD_SCRIPT_FUNCTIONS,
+                        reinterpret_cast<void *>(LoadScriptFunctions_h),
+                        reinterpret_cast<void **>(&LoadScriptFunctions_o)))
+        return false;
+    if (!CreateAndQueue(Offsets::FUN_LOAD_GLUE_SCRIPT_FUNCTIONS,
+                        reinterpret_cast<void *>(LoadGlueScriptFunctions_h),
+                        reinterpret_cast<void **>(&LoadGlueScriptFunctions_o)))
+        return false;
+    if (!CreateAndQueue(Offsets::FUN_FRAME_REGISTER_EVENT,
+                        reinterpret_cast<void *>(FrameRegisterEvent_h),
+                        reinterpret_cast<void **>(&FrameRegisterEvent_o)))
+        return false;
+
+    // All feature hooks declared via `Game::HookAutoRegister` at file scope
+    // in their respective modules (create + queue-enable, no apply yet).
+    if (!Game::RunHookRegistrations())
+        return false;
+
+    // One thread-freeze that activates every queued hook at once.
+    return MH_ApplyQueued() == MH_OK;
+}
+
+// Runs InstallHooks exactly once. Returns 0 on success, 1 on failure. If a
+// second caller arrives while the install is in flight, it blocks briefly so
+// both callers observe the real result.
+static DWORD EnsureInitialized() {
+    if (InterlockedCompareExchange(&g_initClaimed, 1, 0) == 0) {
+        g_initResult = InstallHooks() ? 0 : 1;
+        InterlockedExchange(&g_initDone, 1);
+    } else {
+        while (InterlockedCompareExchange(&g_initDone, 0, 0) == 0)
+            Sleep(1);
+    }
+    return static_cast<DWORD>(g_initResult);
+}
+
+static DWORD WINAPI InitWorker(LPVOID) {
+    EnsureInitialized();
+    return 0;
+}
+
+// VanillaFixes calls this on the game's MAIN thread after injection
+// (InitAdditionalDLLs -> GetProcAddress(module, "Load")), outside the loader
+// lock and with no timeout — the sanctioned VF extension point. Returns 0 on
+// success; VF reports any non-zero result to the user. Exported undecorated
+// as "Load" via src/ClassicAPI.def.
+extern "C" DWORD Load() { return EnsureInitialized(); }
+
 BOOL APIENTRY DllMain(HMODULE hModule, DWORD reason, LPVOID lpReserved) {
    if (reason == DLL_PROCESS_ATTACH) {
        DisableThreadLibraryCalls(hModule);

-        if (MH_Initialize() != MH_OK)
-            return FALSE;
-
-        auto *target = reinterpret_cast<LPVOID>(Offsets::FUN_INVALID_FUNCTION_PTR_CHECK);
-        if (MH_CreateHook(target, reinterpret_cast<LPVOID>(InvalidFunctionPtrCheck_h), nullptr) != MH_OK)
-            return FALSE;
-        if (MH_EnableHook(target) != MH_OK)
-            return FALSE;
-
-        // Four core init hooks stay here — each runs glue logic
-        // (PrepareForReload, RunModuleRegistrations,
-        // RunGlueModuleRegistrations, EnableWrites, RetryClaims)
-        // that's tightly coupled to DllMain state, so a declarative
-        // HookAutoRegister wouldn't simplify them.
-        HOOK_FUNCTION(Offsets::FUN_FRAME_SCRIPT_INITIALIZE, FrameScript_Initialize_h,
-                      FrameScript_Initialize_o);
-        HOOK_FUNCTION(Offsets::FUN_LOAD_SCRIPT_FUNCTIONS, LoadScriptFunctions_h,
-                      LoadScriptFunctions_o);
-        HOOK_FUNCTION(Offsets::FUN_LOAD_GLUE_SCRIPT_FUNCTIONS,
-                      LoadGlueScriptFunctions_h, LoadGlueScriptFunctions_o);
-        HOOK_FUNCTION(Offsets::FUN_FRAME_REGISTER_EVENT, FrameRegisterEvent_h,
-                      FrameRegisterEvent_o);
-
-        // All feature hooks declared via `Game::HookAutoRegister` at
-        // file scope in their respective modules.
-        if (!Game::RunHookRegistrations())
-            return FALSE;
+        // Install nothing here (loader lock — see the block comment above).
+        // Spawn a worker that installs off the lock; the new thread cannot
+        // run its body until DllMain returns and the loader lock releases,
+        // and we never wait on it. Under VanillaFixes the `Load` export
+        // usually wins the latch first; this worker covers every other
+        // injector. DisableThreadLibraryCalls suppressed its THREAD_ATTACH.
+        HANDLE worker = CreateThread(nullptr, 0, InitWorker, nullptr, 0, nullptr);
+        if (worker != nullptr)
+            CloseHandle(worker);
    } else if (reason == DLL_PROCESS_DETACH) {
-        // Clean /quit path. Flush before MH_Uninitialize — the cache's
-        // file I/O uses Win32 directly (no MinHook involvement), so
-        // either order works in practice, but flushing first lets us
-        // bail early if the hook teardown ever grows side effects.
-        // Hard process termination (task manager kill) bypasses this
-        // path; that's an inherent OS limitation, and the 5-minute
-        // backstop flush in Remember() covers the worst case there.
-        Player::NameCache::Flush();
-        MH_Uninitialize();
+        // Clean /quit path — only tear down if we actually initialized.
+        // Flush before MH_Uninitialize — the cache's file I/O uses Win32
+        // directly (no MinHook involvement), so either order works in
+        // practice, but flushing first lets us bail early if the hook
+        // teardown ever grows side effects. Hard process termination (task
+        // manager kill) bypasses this path; that's an inherent OS
+        // limitation, and the 5-minute backstop flush in Remember() covers
+        // the worst case there.
+        if (g_mhInitialized) {
+            Player::NameCache::Flush();
+            MH_Uninitialize();
+        }
    }
    return TRUE;
 }
@@ -73,7 +73,7 @@ using RegisterFrameMethods_t = void(__fastcall *)(const FrameMethodEntry *table,
 } // namespace

 void *State() {
-    return *reinterpret_cast<void **>(static_cast<uintptr_t>(Offsets::VAR_LUA_STATE));
+    return Game::Read<void *>(Offsets::VAR_LUA_STATE);
 }

 namespace {
@@ -320,7 +320,12 @@ bool RunHookRegistrations() {
        if (MH_CreateHook(targetPtr, node->hook,
                          reinterpret_cast<LPVOID *>(node->original)) != MH_OK)
            return false;
-        if (MH_EnableHook(targetPtr) != MH_OK)
+        // Queue, don't enable. The caller (InstallHooks) applies every
+        // queued hook with a single MH_ApplyQueued, so all ~90 hooks share
+        // ONE thread-freeze instead of one freeze per hook. This is the
+        // difference that keeps install cheap on machines whose security
+        // stack intercepts SuspendThread / VirtualProtect per call.
+        if (MH_QueueEnableHook(targetPtr) != MH_OK)
            return false;
    }
    return true;
@@ -17,6 +17,46 @@

 namespace Game {

+// --- Typed engine-memory access ---------------------------------------------
+//
+// The canonical way to read/write an engine object field or a fixed-VA global,
+// replacing the `*reinterpret_cast<const T *>(base + Offsets::OFF_X)` idiom
+// (and its double-cast variant when `base` isn't a byte pointer). Offsets stay
+// in Offsets.h per the single-source-of-truth rule — these only centralize the
+// cast noise, they add no checking.
+//
+//   Game::Read<int>(obj, Offsets::OFF_FIELD)      field read
+//   Game::Ref<uint32_t>(obj, Offsets::OFF_FIELD)  writable field lvalue
+//   Game::Ptr<float>(obj, Offsets::OFF_FIELD)     pointer TO a field (arrays,
+//                                                 out-params for engine calls)
+//   Game::Read<float>(Offsets::VAR_GLOBAL)        fixed-VA global read
+//   Game::Ref<int>(Offsets::VAR_GLOBAL)           fixed-VA global lvalue
+
+template <typename T>
+inline const T *Ptr(const void *base, uintptr_t offset) {
+    return reinterpret_cast<const T *>(reinterpret_cast<const uint8_t *>(base) + offset);
+}
+template <typename T>
+inline T *Ptr(void *base, uintptr_t offset) {
+    return reinterpret_cast<T *>(reinterpret_cast<uint8_t *>(base) + offset);
+}
+template <typename T>
+inline T Read(const void *base, uintptr_t offset) {
+    return *Ptr<T>(base, offset);
+}
+template <typename T>
+inline T &Ref(void *base, uintptr_t offset) {
+    return *Ptr<T>(base, offset);
+}
+template <typename T>
+inline T Read(uintptr_t address) {
+    return *reinterpret_cast<const T *>(address);
+}
+template <typename T>
+inline T &Ref(uintptr_t address) {
+    return *reinterpret_cast<T *>(address);
+}
+
 using FrameScript_Initialize_t = bool(__fastcall *)();
 using LoadScriptFunctions_t = void(__fastcall *)();

@@ -341,19 +381,24 @@ void RunGlueModuleRegistrations();

 // Declarative MinHook registration. Each feature module declares a
 // file-scope `static const Game::HookAutoRegister _hookreg{target,
-// &hook_fn, reinterpret_cast<void**>(&original_fn)};` and DllMain's
-// `RunHookRegistrations` walks the list once after `MH_Initialize`,
-// installing each hook with `MH_CreateHook` + `MH_EnableHook`.
+// &hook_fn, reinterpret_cast<void**>(&original_fn)};` and the installer
+// (`InstallHooks` in DllMain.cpp) walks the list once after
+// `MH_Initialize`, creating each hook and QUEUE-enabling it; a single
+// `MH_ApplyQueued` then activates them all in one thread-freeze.
+//
+// The install runs OFF the loader lock (via the `Load` export or the
+// fallback worker thread — see DllMain.cpp), never inside DllMain, so
+// the thread-freeze can't deadlock or stall the loader.
 //
 // Same lifetime rules as ModuleAutoRegister: constructors chain onto
 // a static-init list before DllMain runs, the linker keeps the OBJ
 // because the constructor has side effects, and order across TUs is
 // undefined but doesn't matter here (hooks are independent).
 //
-// Use only for feature hooks. The three core engine-init hooks in
+// Use only for feature hooks. The four core engine-init hooks in
 // DllMain (FrameScript_Initialize / LoadScriptFunctions /
-// Frame::RegisterEvent) have inline logic that interleaves with the
-// hook chain and stays in DllMain.
+// LoadGlueScriptFunctions / Frame::RegisterEvent) have inline logic that
+// interleaves with the hook chain and stays with the installer.
 struct HookAutoRegister {
    HookAutoRegister(uintptr_t target, void *hook, void **original);
    uintptr_t target;
@@ -362,8 +407,9 @@ struct HookAutoRegister {
    HookAutoRegister *next;
 };

-// Installs every registered hook. Returns `false` and stops on first
-// failure — caller (DllMain) should propagate by returning FALSE.
+// Creates and QUEUE-enables every registered hook (no `MH_ApplyQueued`
+// here — the caller applies the whole batch at once). Returns `false`
+// and stops on first failure.
 bool RunHookRegistrations();

 } // namespace Game
@@ -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);
@@ -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,30 +99,18 @@ 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);
+    return Game::Read<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);
+    return Game::Read<uint64_t>(inst, Offsets::OFF_INSTANCE_BLOCK_GUID);
 }

 struct SlotInfo {
@@ -145,18 +135,18 @@ SlotInfo ReadSlot(void *L, int bag, int slot) {
 // --- auction-house globals ----------------------------------------------

 uint64_t AuctioneerGuid() {
-    const uint32_t lo = *reinterpret_cast<const uint32_t *>(
+    const uint32_t lo = Game::Read<uint32_t>(
        Offsets::VAR_AUCTION_AUCTIONEER_GUID_LO);
-    const uint32_t hi = *reinterpret_cast<const uint32_t *>(
+    const uint32_t hi = Game::Read<uint32_t>(
        Offsets::VAR_AUCTION_AUCTIONEER_GUID_HI);
    return (static_cast<uint64_t>(hi) << 32) | lo;
 }
 bool AHOpen() { return AuctioneerGuid() != 0; }

 void SetSellGuid(uint64_t guid) {
-    *reinterpret_cast<uint32_t *>(Offsets::VAR_AUCTION_SELL_GUID_LO) =
+    Game::Ref<uint32_t>(Offsets::VAR_AUCTION_SELL_GUID_LO) =
        static_cast<uint32_t>(guid);
-    *reinterpret_cast<uint32_t *>(Offsets::VAR_AUCTION_SELL_GUID_HI) =
+    Game::Ref<uint32_t>(Offsets::VAR_AUCTION_SELL_GUID_HI) =
        static_cast<uint32_t>(guid >> 32);
 }

@@ -188,11 +178,11 @@ 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 *>(
-               rec + Offsets::OFF_ITEMSTATS_BAG_FAMILY) == 0;
+    return Game::Read<uint32_t>(
+               rec, Offsets::OFF_ITEMSTATS_BAG_FAMILY) == 0;
 }

 bool FindFreeGeneralSlot(void *L, int *outBag, int *outSlot) {
@@ -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;
 }
@@ -23,6 +23,7 @@
 #include "net/PacketReader.h"
 #include "net/SendObserver.h"
 #include "spell/Mod.h"
+#include "time/Clock.h"
 #include "unit/Identity.h"

 #include <cstdint>
@@ -32,12 +33,7 @@ namespace Aura::ComboDuration {
 namespace {

 using Net::CDataStore;
-
-uint32_t NowMs() {
-    using TickCount_t = uint32_t(__fastcall *)();
-    return reinterpret_cast<TickCount_t>(
-        static_cast<uintptr_t>(Offsets::FUN_OS_TICKCOUNT_MS))();
-}
+using Time::Clock::NowMs;

 // ---- Combo-point snapshot (NetClient send co-hook) ------------------------

@@ -57,28 +53,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
@@ -94,7 +114,7 @@ void OnSend(uint32_t opcode, Net::CDataStore *packet) {
        return;
    const uint32_t spellId = Net::Read<uint32_t>(packet);
    if (spellId != 0)
-        g_capture = {spellId, CurrentComboPoints(), NowMs()};
+        RememberCapture(spellId, CurrentComboPoints(), NowMs());
 }

 const Net::SendObserver::AutoSubscribe _sendSub{&OnSend};
@@ -19,6 +19,9 @@
 #include "dbc/Lookup.h"
 #include "group/MemberStats.h"
 #include "guid/Guid.h"
+#include "spell/CrowdControl.h"
+#include "spell/IsSelfBuff.h"
+#include "time/Clock.h"
 #include "unit/Identity.h"

 #include <cstdint>
@@ -28,13 +31,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 +68,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 *);
@@ -149,12 +145,10 @@ double PlayerBuffExpirationSeconds(const uint8_t *entry) {
    // Permanent auras (paladin auras, passives, racials) carry an infinite
    // Spell.dbc duration (SpellDuration base -1); the server stores the fixed
    // cast-time in this slot for them, so it's always "already elapsed" and the
-    // engine shows no countdown. The signed `(int)` compare also absorbs the
-    // ~24.86-day GetTickCount wrap (both operands wrap together).
-    using TickCount_t = uint32_t(__fastcall *)();
-    const uint32_t nowMs = reinterpret_cast<TickCount_t>(
-        static_cast<uintptr_t>(Offsets::FUN_OS_TICKCOUNT_MS))();
-    if (static_cast<int32_t>(nowMs - expirationMs) >= 0)
+    // engine shows no countdown. `Time::Clock::Reached` takes the signed diff, so
+    // it also absorbs the ~24.86-day GetTickCount wrap (both operands wrap
+    // together).
+    if (Time::Clock::Reached(expirationMs))
        return 0.0; // expiration reached/passed → permanent or no timer
    return static_cast<double>(expirationMs) * 0.001;
 }
@@ -209,6 +203,13 @@ 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) { return Time::Clock::Reached(expMs); }
+
 int PlayerLevel(const uint8_t *player) {
    auto *desc = Descriptor(player);
    if (desc == nullptr)
@@ -217,6 +218,35 @@ int PlayerLevel(const uint8_t *player) {
        desc + Offsets::OFF_UNIT_FIELD_LEVEL);
 }

+// Caster + timing attributed to ONE aura instance — the aura `spellID` sitting
+// in absolute descriptor `slot` on `guid` (`Aura::Source::SLOT_UNBOUND` when
+// the caller has no slot: the out-of-range group array, the cache fallback).
+// The slot is what tells two casters' copies of one spell apart; without it
+// they are indistinguishable from a spell ID alone.
+//
+// The caster is the observed one 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), else 0. 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.
+struct Attribution {
+    uint64_t caster;
+    uint32_t expirationMs;
+    uint32_t durationMs;
+};
+
+Attribution Attribute(uint64_t guid, uint32_t spellID, int slot) {
+    Attribution a = {0, 0, 0};
+    if (guid == 0 || spellID == 0)
+        return a;
+    Aura::Source::Get(guid, spellID, slot, &a.caster, &a.expirationMs,
+                      &a.durationMs);
+    if (a.caster == 0 && Spell::IsSelfBuff::IsSelfBuff(spellID))
+        a.caster = guid; // self-only-target aura → cast by the unit itself
+    return a;
+}
+
 } // namespace

 uint32_t ReadSpellID(const uint8_t *unit, int slot) {
@@ -250,16 +280,68 @@ 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 && Attribute(UnitGuid(unit), spellID, slot).caster == 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 member has no descriptor, so there is
+// no slot to attribute by and the cache is consulted by (guid, spellID) alone.
+// 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 &&
+           Attribute(guid, spellID, Aura::Source::SLOT_UNBOUND).caster == 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 +354,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 +363,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 +377,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 +385,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 +400,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;
    }
@@ -450,10 +532,21 @@ static void BuildTable(void *L, uint32_t spellID, int applications,
 // buff table (gated on `isPlayer`); for everyone else it, the caster, and the
 // applied (caster-modified) duration come from the `Aura::Source` SMSG_SPELL_GO
 // cache when it observed the cast — a miss leaves the modern-truthful defaults
-// (expiration 0, no sourceUnit/GUID).
+// (expiration 0, no sourceUnit/GUID). `slot` is the absolute descriptor slot
+// the aura occupies, which is what attributes it to the right caster when two
+// of them hold the same spell on the unit; `Aura::Source::SLOT_UNBOUND` for the
+// paths with no descriptor to read one from.
+//
+// `known` short-circuits the by-(guid,spell,slot) resolve: the cache-fallback
+// paths already hold the exact entry's attribution (Enumerate copied it out),
+// so they pass it straight through. Re-resolving there would call `Get` a second
+// time and, for an unbound entry sharing its spell with another caster's entry,
+// return a miss — dropping a caster Enumerate already knew. Null for the
+// descriptor / group-array paths, which have no per-entry attribution in hand.
 static void PushEnriched(void *L, uint64_t guid, uint32_t spellID,
                         bool isHelpful, int applications, int unitLevel,
-                         bool isPlayer) {
+                         bool isPlayer, int slot,
+                         const Attribution *known = nullptr) {
    double duration = 0.0;
    double expirationTime = 0.0;
    uint64_t casterGuid = 0;
@@ -465,27 +558,42 @@ static void PushEnriched(void *L, uint64_t guid, uint32_t spellID,
            expirationTime = PlayerBuffExpirationSeconds(entry);
    }
    if (spellID != 0 && guid != 0) {
-        uint64_t c = 0;
-        uint32_t expMs = 0;
-        uint32_t durMs = 0;
-        if (Aura::Source::Get(guid, spellID, &c, &expMs, &durMs)) {
-            if (expirationTime == 0.0 && expMs != 0)
-                expirationTime = static_cast<double>(expMs) * 0.001;
-            if (durMs != 0)
-                duration = static_cast<double>(durMs) * 0.001;
-            casterGuid = c;
-        }
+        // Caster (sourceGUID/sourceUnit) and timing resolved together, so a
+        // self-buff both shows a source and matches HELPFUL|PLAYER instead of
+        // the two paths disagreeing.
+        Attribution a = (known != nullptr) ? *known : Attribute(guid, spellID, slot);
+        // Self-buff inference for a pre-resolved entry whose caster the cache
+        // never learned (idempotent on the Attribute() path, which already
+        // applied it — the caster is nonzero there when it matched).
+        if (a.caster == 0 && Spell::IsSelfBuff::IsSelfBuff(spellID))
+            a.caster = guid;
+        // 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 && a.expirationMs != 0 &&
+            !ExpirationElapsed(a.expirationMs))
+            expirationTime = static_cast<double>(a.expirationMs) * 0.001;
+        if (a.durationMs != 0)
+            duration = static_cast<double>(a.durationMs) * 0.001;
+        casterGuid = a.caster;
    }
    BuildTable(L, spellID, applications, isHelpful, duration, expirationTime,
               casterGuid);
 }

+// Attribution held directly by an `Aura::Source` cache entry (from `Enumerate`),
+// for the cache-fallback push paths to hand to `PushEnriched` as `known`.
+static Attribution CachedAttribution(const Aura::Source::CachedAura &c) {
+    return {c.casterGuid, c.expirationMs, c.durationMs};
+}
+
 void Push(void *L, const uint8_t *unit, int slot) {
    const uint32_t spellID = ReadSpellID(unit, slot);
    const bool isHelpful = slot < Offsets::UNIT_AURA_BUFF_COUNT;
    const int unitLevel = (unit != nullptr) ? PlayerLevel(unit) : 0;
    PushEnriched(L, UnitGuid(unit), spellID, isHelpful, ReadStacks(unit, slot),
-                 unitLevel, unit != nullptr && unit == LocalPlayer());
+                 unitLevel, unit != nullptr && unit == LocalPlayer(), slot);
 }

 namespace {
@@ -496,12 +604,15 @@ namespace {
 // applied (caster-modified) ms when known, else the Spell.dbc base.
 void PushFromCache(void *L, const uint8_t *unit,
                   const Aura::Source::CachedAura &c, bool isHelpful) {
-    // `PushEnriched` re-reads the same cache entry `c` came from (by
-    // guid+spellID) to fill caster / expiration / applied duration, so the
-    // result is identical to reading `c`'s fields directly. Stacks aren't in
-    // SMSG_SPELL_GO, so `applications` is 1.
+    // `c` already carries this exact instance's caster + timing (Enumerate
+    // copied it out), so hand it to `PushEnriched` as `known` rather than
+    // re-resolving by (guid, spell, slot) — an unbound entry sharing its spell
+    // with another caster's would otherwise resolve to a miss and drop the
+    // caster. Stacks aren't in SMSG_SPELL_GO, so `applications` is 1.
    const int unitLevel = (unit != nullptr) ? PlayerLevel(unit) : 0;
-    PushEnriched(L, UnitGuid(unit), c.spellId, isHelpful, 1, unitLevel, false);
+    const Attribution a = CachedAttribution(c);
+    PushEnriched(L, UnitGuid(unit), c.spellId, isHelpful, 1, unitLevel, false,
+                 c.slot, &a);
 }

 // Reconciles the `Aura::Source` cache against `unit`'s descriptor: when the
@@ -518,15 +629,9 @@ void ReconcileCache(const uint8_t *unit) {
    if (unit == nullptr)
        return;
    uint32_t present[Offsets::UNIT_AURA_TOTAL];
-    int n = 0;
-    for (int slot = 0; slot < Offsets::UNIT_AURA_TOTAL; ++slot) {
-        const uint32_t id = ReadSpellID(unit, slot);
-        if (id != 0)
-            present[n++] = id;
-    }
-    if (n == 0)
-        return;
-    Aura::Source::EvictAbsent(UnitGuid(unit), present, n);
+    for (int slot = 0; slot < Offsets::UNIT_AURA_TOTAL; ++slot)
+        present[slot] = ReadSpellID(unit, slot);
+    Aura::Source::EvictAbsent(UnitGuid(unit), present);
 }

 // True if `unit`'s descriptor currently exposes any visible aura in either
@@ -548,8 +653,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 +666,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 +676,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 +698,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 +707,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 +718,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 +729,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 +742,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 +773,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 +814,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,17 +828,18 @@ 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) {
+            const Attribution a = CachedAttribution(buf[i]);
            PushEnriched(L, guid, buf[i].spellId, filter == Filter::Helpful, 1,
-                         GroupMemberLevel(guid), false);
+                         GroupMemberLevel(guid), false, buf[i].slot, &a);
            return true;
        }
    }
@@ -748,18 +848,19 @@ 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++));
+        const Attribution a = CachedAttribution(buf[i]);
        PushEnriched(L, guid, buf[i].spellId, filter == Filter::Helpful, 1, level,
-                     false);
+                     false, buf[i].slot, &a);
        Game::Lua::SetTable(L, outerIdx);
    }
 }
@@ -768,7 +869,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,10 +880,11 @@ 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;
+        const Attribution a = CachedAttribution(buf[i]);
        PushEnriched(L, guid, buf[i].spellId, !harmful, 1, GroupMemberLevel(guid),
-                     false);
+                     false, buf[i].slot, &a);
        return true;
    }
    return false;
@@ -791,7 +893,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,24 +904,24 @@ 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),
                         filter == Filter::Helpful, 1, GroupMemberLevel(guid),
-                         false);
+                         false, Aura::Source::SLOT_UNBOUND);
            return true;
        }
    }
    // 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,28 +937,28 @@ 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);
+                     GroupMemberLevel(guid), false, Aura::Source::SLOT_UNBOUND);
        return true;
    }
    if (!GroupArrayHasVisibleAura(arr)) {
        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,27 +978,27 @@ 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);
+                     GroupMemberLevel(guid), false, Aura::Source::SLOT_UNBOUND);
        return true;
    }
    if (!GroupArrayHasVisibleAura(arr)) {
        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,16 +1010,17 @@ 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),
-                     filter == Filter::Helpful, 1, level, false);
+                     filter == Filter::Helpful, 1, level, false,
+                     Aura::Source::SLOT_UNBOUND);
        Game::Lua::SetTable(L, outerIdx);
    }
    // Empty array (server delta-resend gap): supplement from the cache.
    if (!GroupArrayHasVisibleAura(arr))
-        AppendGroupCacheFallbacks(L, guid, arr, filter, playerOnly, outerIdx,
+        AppendGroupCacheFallbacks(L, guid, arr, filter, match, outerIdx,
                                  nextKey);
 }

@@ -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
@@ -21,10 +21,12 @@
 #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 "time/Clock.h"
 #include "totem/Tracker.h"
 #include "unit/Identity.h"

@@ -53,11 +55,7 @@ bool SpellAppliesAura(const uint8_t *spellRecord) {
    return false;
 }

-uint32_t NowMs() {
-    using TickCount_t = uint32_t(__fastcall *)();
-    return reinterpret_cast<TickCount_t>(
-        static_cast<uintptr_t>(Offsets::FUN_OS_TICKCOUNT_MS))();
-}
+using Time::Clock::NowMs;

 // Server-authoritative duration (ms). When the local player is the caster
 // we let the engine fold in the player's duration modifiers (skipMod = 0);
@@ -124,61 +122,304 @@ bool WasRecentPlayerCast(uint32_t spellId) {
 // application hook fires for the same aura.
 enum Kind : int8_t { KIND_UNKNOWN = -1, KIND_HELPFUL = 0, KIND_HARMFUL = 1 };

+// An entry is one AURA INSTANCE, identified the way the server identifies one:
+// `(target, spell, caster)`. Two same-class raiders' Corruption on one boss are
+// two auras occupying two descriptor slots, so a `(target, spell)` identity
+// collapses them into one entry — the later cast overwrites the earlier
+// caster's timing, and `OnAuraRemoved` for either copy evicts both.
+//
+// The descriptor only stores spell IDs, so recovering WHICH instance a slot
+// holds needs the slot bound to its entry. SpellGo knows the caster but no
+// slot; `OnAuraAdded` knows the slot but no caster. They arrive in that order
+// (SpellGo, then the SMSG_UPDATE_OBJECT that seats the aura), so the
+// application hook binds the cast capture it belongs to — the newest entry for
+// this `(target, spell)` still awaiting a slot.
 struct Entry {
    uint64_t targetGuid;
    uint64_t casterGuid;
    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)
+    int16_t slot;          // absolute descriptor slot, SLOT_UNBOUND until bound
    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, caster) 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.) Per-caster identity adds one entry per
+// extra caster of the same spell on one target, which is bounded by the 16
+// debuff slots that can hold them.
+constexpr int kCacheSize = 2048;
 Entry g_cache[kCacheSize];
-int g_writeCursor = 0;

-// `fromCast` true: the SpellGo hook — authoritative caster + caster-modified
-// (talented) timing. False: the OnAuraAdded application hook — timing only,
-// no caster, and it must not clobber an entry SpellGo already owns (that
-// would replace talented timing with the unmodified base), so it skips
-// entries that already carry a caster.
-void Store(uint64_t targetGuid, uint32_t spellId, uint64_t casterGuid,
-           uint32_t expirationMs, uint32_t durationMs, bool fromCast,
-           int8_t kind) {
+// One past the highest slot ever claimed since the last flush — the active
+// prefix `[0, g_usedHigh)`. Every used entry lives below it (Claim is the sole
+// allocator and extends it; FlushAll resets it), so all lookups scan only this
+// prefix instead of the full 2048. Outside a raid the working set is a handful
+// of auras, so this is the difference between a ~30-entry scan and a 2048-entry
+// one on the per-aura query path. Never lowered on eviction — an over-estimate
+// only costs a few extra skipped (!used) slots, never a missed live entry.
+int g_usedHigh = 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;
+}
+
+// ---- Entry lookup --------------------------------------------------------
+
+// The exact aura instance `caster` has on `targetGuid` — the server's own
+// identity for one aura, and what a repeat cast refreshes.
+Entry *FindByCaster(uint64_t targetGuid, uint32_t spellId, uint64_t casterGuid) {
+    for (int i = 0; i < g_usedHigh; ++i) {
+        Entry &e = g_cache[i];
+        if (e.used && e.targetGuid == targetGuid && e.spellId == spellId &&
+            e.casterGuid == casterGuid)
+            return &e;
+    }
+    return nullptr;
+}
+
+// The instance seated in descriptor slot `slot`.
+Entry *FindBySlot(uint64_t targetGuid, uint32_t spellId, int slot) {
+    if (slot < 0)
+        return nullptr;
+    for (int i = 0; i < g_usedHigh; ++i) {
+        Entry &e = g_cache[i];
+        if (e.used && e.targetGuid == targetGuid && e.spellId == spellId &&
+            e.slot == slot)
+            return &e;
+    }
+    return nullptr;
+}
+
+// The newest cast capture for this aura still awaiting a descriptor slot —
+// what an `OnAuraAdded` for `(target, spell)` is seating. Newest wins because
+// SpellGo precedes the application by a packet, so the freshest unbound entry
+// is the cast that just landed; an older one is a capture that never seated
+// (fully resisted, immune) and is left to expire on its own. "Newest" is the
+// smallest `Time::Clock::Elapsed(stamp, now)` — a wrap-safe signed difference;
+// a raw `stampMs >` compare inverts across the 2^32 ms tick wrap.
+Entry *FindFreshestUnbound(uint64_t targetGuid, uint32_t spellId, uint32_t now) {
+    Entry *best = nullptr;
+    uint32_t bestElapsed = 0;
+    for (int i = 0; i < g_usedHigh; ++i) {
+        Entry &e = g_cache[i];
+        if (!e.used || e.targetGuid != targetGuid || e.spellId != spellId ||
+            e.slot != SLOT_UNBOUND)
+            continue;
+        const uint32_t elapsed = Time::Clock::Elapsed(e.stampMs, now);
+        if (best == nullptr || elapsed < bestElapsed) {
+            best = &e;
+            bestElapsed = elapsed;
+        }
+    }
+    return best;
+}
+
+// The one entry for `(target, spell)`, or null when there are none or several.
+// Several means two casters and no way to tell their instances apart from a
+// spell ID alone, which is exactly when guessing is what produces a wrong
+// caster and a wrong timer.
+Entry *FindSole(uint64_t targetGuid, uint32_t spellId) {
+    Entry *found = nullptr;
+    for (int i = 0; i < g_usedHigh; ++i) {
+        Entry &e = g_cache[i];
+        if (!e.used || e.targetGuid != targetGuid || e.spellId != spellId)
+            continue;
+        if (found != nullptr)
+            return nullptr;
+        found = &e;
+    }
+    return found;
+}
+
+// The instance a slot-bearing query means: the entry seated in `slot`, else the
+// unit's sole entry for the spell — every single-caster case and the slotless
+// (out-of-range group array, cache fallback) paths. Two casters' entries with
+// no slot binding resolve to null (see FindSole), never to a coin flip. This is
+// the read-side identity rule; both `Get` and `Evict` resolve through it so they
+// can't drift into naming different instances for the same query.
+Entry *FindInstance(uint64_t targetGuid, uint32_t spellId, int slot) {
+    Entry *e = FindBySlot(targetGuid, spellId, slot);
+    return e != nullptr ? e : FindSole(targetGuid, spellId);
+}
+
+// Marks the slot `e` occupies as within the active prefix, so later lookups
+// reach it. Every new entry passes through here (Claim is the only allocator),
+// which is what keeps the `[0, g_usedHigh)` invariant true for all writers.
+Entry *Register(Entry *e) {
+    const int idx = static_cast<int>(e - g_cache);
+    if (idx >= g_usedHigh)
+        g_usedHigh = idx + 1;
+    return e;
+}
+
+// Takes 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 evicts. Scans the full array — as the allocator it
+// must be able to hand out slots beyond the current active prefix (that is how
+// the prefix grows), so it can't bound itself by g_usedHigh.
+Entry *Claim(uint32_t now) {
+    for (auto &e : g_cache) {
+        if (!e.used ||
+            (e.expirationMs != 0 && now >= e.expirationMs &&
+             !DescriptorListsAura(e.targetGuid, e.spellId)))
+            return Register(&e);
+    }
+    // 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;
+    }
+    return Register((orphan != nullptr) ? orphan : lru);
+}
+
+// ---- Writes --------------------------------------------------------------
+
+// The SpellGo hook: authoritative caster + caster-modified (talented) timing.
+// Identity is `(target, spell, caster)`, so a second caster of the same spell
+// opens its own entry instead of overwriting the first's, and a recast by the
+// same caster refreshes theirs — keeping the descriptor slot already bound to
+// it.
+void StoreFromCast(uint64_t targetGuid, uint32_t spellId, uint64_t casterGuid,
+                   uint32_t expirationMs, uint32_t durationMs) {
    if (targetGuid == 0 || spellId == 0)
        return;
-
-    // Update an existing entry for this exact aura instance.
-    for (auto &e : g_cache) {
-        if (e.used && e.targetGuid == targetGuid && e.spellId == spellId) {
-            // Learn the classification whenever a slot-derived kind arrives —
-            // independent of caster/timing ownership, and never downgrade a
-            // known kind back to unknown.
-            if (kind != KIND_UNKNOWN)
-                e.kind = kind;
-            if (!fromCast && e.casterGuid != 0)
-                return; // SpellGo owns this entry; keep its caster + timing
-            if (casterGuid != 0)
-                e.casterGuid = casterGuid;
-            e.expirationMs = expirationMs;
-            e.durationMs = durationMs;
-            return;
-        }
-    }
-    // Take a free slot, else an expired one, else evict round-robin.
    const uint32_t now = NowMs();
-    for (auto &e : g_cache) {
-        if (!e.used || (e.expirationMs != 0 && now >= e.expirationMs)) {
-            e = {targetGuid, casterGuid, spellId, expirationMs, durationMs,
-                 kind, true};
-            return;
-        }
+    Entry *e = FindByCaster(targetGuid, spellId, casterGuid);
+    // A lone unattributed entry for this aura is the same instance seen without
+    // a caster (seated by an application hook while we were out of view, or a
+    // group-array guess), so claim it rather than opening a second entry for
+    // one aura — the same adoption `ApplyDurationModifiers` does. Only when
+    // it's the unit's only entry for the spell: with several, "the one this
+    // cast refreshes" is a guess, and guessing wrong writes this caster's timer
+    // onto another's aura.
+    if (e == nullptr) {
+        Entry *sole = FindSole(targetGuid, spellId);
+        if (sole != nullptr && sole->casterGuid == 0)
+            e = sole;
    }
-    Entry &slot = g_cache[g_writeCursor];
-    g_writeCursor = (g_writeCursor + 1) % kCacheSize;
-    slot = {targetGuid, casterGuid, spellId, expirationMs, durationMs, kind,
-            true};
+    if (e == nullptr) {
+        e = Claim(now);
+        *e = {targetGuid, casterGuid, spellId, expirationMs, durationMs,
+              now,        SLOT_UNBOUND, KIND_UNKNOWN, true};
+        return;
+    }
+    e->stampMs = now; // refresh EvictAbsent grace on any touch
+    e->casterGuid = casterGuid;
+    e->expirationMs = expirationMs;
+    e->durationMs = durationMs;
+}
+
+// The OnAuraAdded / OnAuraStacksChanged application hooks: a descriptor slot,
+// a classification, and base timing — but no caster (except the local player's
+// own recent cast, which `StampApplication` resolves). Seats the slot on the
+// cast capture it belongs to, and must not clobber the caster + talented
+// timing SpellGo already owns for that instance.
+//
+// `slot` is SLOT_UNBOUND for the out-of-range group-array path, which has no
+// descriptor at all; there the only available identity is `(target, spell)`.
+void StoreFromApplication(uint64_t targetGuid, uint32_t spellId,
+                          uint64_t casterGuid, uint32_t expirationMs,
+                          uint32_t durationMs, int slot, int8_t kind) {
+    if (targetGuid == 0 || spellId == 0)
+        return;
+    const uint32_t now = NowMs();
+    // Anything outside the descriptor's slot range can't index it, so it binds
+    // nothing — `EvictAbsent` indexes the array by a bound entry's slot.
+    if (slot < 0 || slot >= Offsets::UNIT_AURA_TOTAL)
+        slot = SLOT_UNBOUND;
+
+    Entry *e = FindBySlot(targetGuid, spellId, slot);
+    if (e == nullptr)
+        e = FindFreshestUnbound(targetGuid, spellId, now);
+    if (e == nullptr && slot < 0)
+        e = FindSole(targetGuid, spellId);
+    if (e == nullptr) {
+        e = Claim(now);
+        *e = {targetGuid, casterGuid, spellId, expirationMs, durationMs, now,
+              static_cast<int16_t>(slot), kind, true};
+        return;
+    }
+
+    e->stampMs = now;
+    if (slot >= 0)
+        e->slot = static_cast<int16_t>(slot);
+    // Learn the classification whenever a slot-derived kind arrives —
+    // independent of caster/timing ownership, and never downgrade a known kind
+    // back to unknown.
+    if (kind != KIND_UNKNOWN)
+        e->kind = kind;
+    if (e->casterGuid != 0)
+        return; // SpellGo owns this entry; keep its caster + talented timing
+    if (casterGuid != 0)
+        e->casterGuid = casterGuid;
+    e->expirationMs = expirationMs;
+    e->durationMs = durationMs;
 }

 // ---- Out-of-range group-member aura snapshots ---------------------------
@@ -216,25 +457,27 @@ void StampGroupGuess(uint64_t guid, uint16_t spellId, int8_t kind, uint32_t now)
    const uint32_t base = SpellDurationMs(rec, /*casterIsPlayer*/ false);
    if (base == 0)
        return;
-    Store(guid, spellId, /*casterGuid*/ 0, now + base, base, /*fromCast*/ false,
-          kind);
+    StoreFromApplication(guid, spellId, /*casterGuid*/ 0, now + base, base,
+                         SLOT_UNBOUND, kind);
 }

-// Evict the entry for an aura the engine reports gone. Keyed by (target,
-// spell) like the rest of the cache. Without this, the GetAuraDataByIndex
-// fallback would keep surfacing a dropped aura until its computed expiry —
-// e.g. a Rank 1 buff replaced by Rank 2 (engine drops Rank 1 from the
-// descriptor) would show as a phantom second aura, or a dispelled buff would
-// linger.
-void Evict(uint64_t targetGuid, uint32_t spellId) {
+// Evict the entry for an aura the engine reports gone, identified by the
+// descriptor slot it vacated. Without this, the GetAuraDataByIndex fallback
+// would keep surfacing a dropped aura until its computed expiry — e.g. a Rank
+// 1 buff replaced by Rank 2 (engine drops Rank 1 from the descriptor) would
+// show as a phantom second aura, or a dispelled buff would linger.
+//
+// The slot is what makes this safe when two casters hold the same spell on one
+// target: only the instance that actually fell off goes. Falling back to a
+// spell-ID match when nothing is bound to the slot keeps the pre-binding
+// behaviour, but only while the match is unambiguous — dropping one of two
+// casters' entries at random would take a live aura's caster with it.
+void Evict(uint64_t targetGuid, uint32_t spellId, int slot) {
    if (targetGuid == 0 || spellId == 0)
        return;
-    for (auto &e : g_cache) {
-        if (e.used && e.targetGuid == targetGuid && e.spellId == spellId) {
-            e.used = false;
-            return;
-        }
-    }
+    Entry *e = FindInstance(targetGuid, spellId, slot);
+    if (e != nullptr)
+        e->used = false;
 }

 // ---- Server-side duration modifiers (trigger-driven inference) -----------
@@ -245,15 +488,18 @@ void Evict(uint64_t targetGuid, uint32_t spellId) {
 // 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 come from Lua
-// (`C_UnitAuras.RegisterAuraDurationModifier`), so the server-specific set
-// lives in the addon, not the DLL. Turtle examples:
+// 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 by exact spellID (from the server's script binding,
-// stable across ranks); 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
+// 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
@@ -275,23 +521,24 @@ constexpr int kMaxMods = 128;
 DurationMod g_mods[kMaxMods];
 int g_modCount = 0;

-bool AffectedMatches(const uint8_t *rec, const DurationMod &m) {
-    if (rec == nullptr)
+// 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 (*reinterpret_cast<const uint32_t *>(
-            rec + Offsets::OFF_SPELL_RECORD_FAMILY_NAME) != m.affectedFamily)
-        return false;
-    const uint64_t flags = *reinterpret_cast<const uint64_t *>(
-        rec + Offsets::OFF_SPELL_RECORD_FAMILY_FLAGS);
-    if ((flags & m.affectedMask) == 0)
-        return false;
-    if (m.affectedIcon != 0 &&
+    if (icon != 0 &&
        *reinterpret_cast<const uint32_t *>(
-            rec + Offsets::OFF_SPELL_RECORD_ICON_ID) != m.affectedIcon)
+            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
@@ -312,26 +559,62 @@ bool TriggerMatches(const DurationMod &m, uint32_t triggerSpellId,
    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)
+        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))
+            if (e.expirationMs > now + static_cast<uint32_t>(m.valueMs)) {
                e.expirationMs -= static_cast<uint32_t>(m.valueMs);
-            else
+                SignalAuraChanged(e.targetGuid);
+            } else {
                e.used = false; // shaved to/past now → server removes it
+            }
        }
        break;
    case MOD_REMOVE:
-        e.used = false;
+        e.used = false; // removal — OnAuraRemoved / descriptor path fires UNIT_AURA
        break;
    }
 }
@@ -352,7 +635,8 @@ void ApplyDurationModifiers(uint32_t triggerSpellId, uint64_t caster,
        if (!TriggerMatches(m, triggerSpellId, triggerRec))
            continue;
        for (int t = 0; t < numTargets; ++t) {
-            for (auto &e : g_cache) {
+            for (int i = 0; i < g_usedHigh; ++i) {
+                Entry &e = g_cache[i];
                if (!e.used || e.targetGuid != targets[t])
                    continue;
                // The mechanic acts on the trigger-caster's own aura. Cast-applied
@@ -414,40 +698,6 @@ int OpFromString(const char *s) {
    return -1;
 }

-// `C_UnitAuras.RegisterAuraDurationModifier(triggerSpellID, affectedFamily,
-//     affectedFamilyFlags, affectedIcon, op [, valueSeconds])` -> bool.
-// op: "refresh" | "reduce" | "set" | "remove". valueSeconds used by
-// reduce/set. affectedIcon 0 = match any icon. Re-registering an identical
-// (trigger, family, flags, icon) tuple replaces its op/value.
-int __fastcall Script_RegisterAuraDurationModifier(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::IsString(L, 5)) {
-        Game::Lua::Error(
-            L, "Usage: C_UnitAuras.RegisterAuraDurationModifier(triggerSpellID, "
-               "affectedFamily, affectedFamilyFlags, affectedIcon, op[, "
-               "valueSeconds])");
-        return 0;
-    }
-    const auto trigger = static_cast<uint32_t>(Game::Lua::ToNumber(L, 1));
-    const auto family = static_cast<uint32_t>(Game::Lua::ToNumber(L, 2));
-    const auto mask = static_cast<uint64_t>(Game::Lua::ToNumber(L, 3));
-    const auto icon = static_cast<uint32_t>(Game::Lua::ToNumber(L, 4));
-    const int op = OpFromString(Game::Lua::ToString(L, 5));
-    const int32_t valueMs =
-        Game::Lua::IsNumber(L, 6)
-            ? static_cast<int32_t>(Game::Lua::ToNumber(L, 6) * 1000.0)
-            : 0;
-    if (op < 0) {
-        Game::Lua::PushBool(L, false);
-        return 1;
-    }
-    Game::Lua::PushBool(L, RegisterDurationMod(trigger, /*triggerFamily*/ 0,
-                                               /*triggerSchool*/ -1, family, mask,
-                                               icon, op, valueMs));
-    return 1;
-}
-
 // `C_UnitAuras.RegisterAuraDurationModifierByTrigger(triggerFamily,
 //     triggerSchool, affectedFamily, affectedFamilyFlags, affectedIcon, op
 //     [, valueSeconds])` -> bool. Like the above, but the trigger is matched
@@ -485,8 +735,6 @@ int __fastcall Script_RegisterAuraDurationModifierByTrigger(void *L) {
 }

 void RegisterDurationModLua() {
-    Game::Lua::RegisterTableFunction("C_UnitAuras", "RegisterAuraDurationModifier",
-                                     &Script_RegisterAuraDurationModifier);
    Game::Lua::RegisterTableFunction("C_UnitAuras",
                                     "RegisterAuraDurationModifierByTrigger",
                                     &Script_RegisterAuraDurationModifierByTrigger);
@@ -496,8 +744,9 @@ const Game::ModuleAutoRegister _autoregDurationMod{&RegisterDurationModLua};

 // Wipe the whole cache. Used on a map transition (see OnWorldTick).
 void FlushAll() {
-    for (auto &e : g_cache)
-        e.used = false;
+    for (int i = 0; i < g_usedHigh; ++i)
+        g_cache[i].used = false;
+    g_usedHigh = 0; // active prefix is empty again
    // Reset transition baselines too: post-transition group auras re-sync and
    // should be treated as first-sight (unknown age), not diffed as new.
    for (auto &s : g_groupSnaps)
@@ -533,9 +782,20 @@ void OnWorldTick() {
    }

    const uint32_t now = NowMs();
-    for (auto &e : g_cache) {
-        if (e.used && e.expirationMs != 0 && now >= e.expirationMs)
-            e.used = false;
+    for (int i = 0; i < g_usedHigh; ++i) {
+        Entry &e = g_cache[i];
+        if (!e.used || e.expirationMs == 0 || !Time::Clock::Reached(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.
@@ -543,6 +803,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};
@@ -608,13 +871,11 @@ void HandleSpellGo(uint64_t caster, uint32_t spellId, const uint64_t *targets,

    if (numTargets == 0) {
        // No explicit hit list (self-cast with caster-implicit target).
-        Store(caster, spellId, caster, expirationMs, durationMs, true,
-              KIND_UNKNOWN);
+        StoreFromCast(caster, spellId, caster, expirationMs, durationMs);
        return;
    }
    for (int i = 0; i < numTargets; ++i)
-        Store(targets[i], spellId, caster, expirationMs, durationMs, true,
-              KIND_UNKNOWN);
+        StoreFromCast(targets[i], spellId, caster, expirationMs, durationMs);
 }

 // SMSG_SPELL_GO parse (funnel subscriber). At the leaf handler the engine has
@@ -647,12 +908,19 @@ const Net::PacketDispatch::AutoSubscribe _spellGoSub{&SpellGoSub};

 // ---- Aura-application co-hooks (timing for proc / triggered auras) -------

-// Stamp expiration for an aura that just landed/refreshed on `unit`. Used by
-// both the add and stack-change hooks. No caster is available from these
-// paths, so it stamps timing only with `fromCast=false` — Store skips any
-// entry SpellGo already owns, so a directly-cast aura keeps its talented
-// timing. Base (unmodified) duration is the best estimate without a caster.
-void StampApplication(void *unit, uint32_t spellId, int8_t kind) {
+// Classify by the absolute aura slot: 0..BUFF_COUNT-1 = buff (helpful),
+// BUFF_COUNT..TOTAL-1 = debuff (harmful).
+int8_t KindForSlot(int slot) {
+    return slot >= Offsets::UNIT_AURA_BUFF_COUNT ? KIND_HARMFUL : KIND_HELPFUL;
+}
+
+// Stamp expiration for an aura that just landed/refreshed in `slot` on `unit`.
+// Used by both the add and stack-change hooks. No caster is available from
+// these paths, so it stamps timing only — StoreFromApplication keeps whatever
+// SpellGo already owns, so a directly-cast aura keeps its talented timing.
+// Base (unmodified) duration is the best estimate without a caster. The slot
+// is what binds this application to the cast capture behind it.
+void StampApplication(void *unit, uint32_t spellId, int slot) {
    if (spellId == 0)
        return;
    const uint8_t *rec = Spell::Lookup::RecordForID(static_cast<int>(spellId));
@@ -669,14 +937,8 @@ void StampApplication(void *unit, uint32_t spellId, int8_t kind) {
    const uint32_t durationMs = SpellDurationMs(rec, byPlayer);
    const uint64_t caster = byPlayer ? Unit::Identity::PlayerGuid() : 0;
    const uint32_t expirationMs = durationMs > 0 ? NowMs() + durationMs : 0;
-    Store(unitGuid, spellId, caster, expirationMs, durationMs,
-          /*fromCast*/ false, kind);
-}
-
-// Classify by the absolute aura slot: 0..BUFF_COUNT-1 = buff (helpful),
-// BUFF_COUNT..TOTAL-1 = debuff (harmful).
-int8_t KindForSlot(int slot) {
-    return slot >= Offsets::UNIT_AURA_BUFF_COUNT ? KIND_HARMFUL : KIND_HELPFUL;
+    StoreFromApplication(unitGuid, spellId, caster, expirationMs, durationMs,
+                         slot, KindForSlot(slot));
 }

 // Bump the player-stat-inputs signal when an aura change hits the LOCAL
@@ -696,7 +958,7 @@ OnAuraAdded_t g_origOnAuraAdded = nullptr;
 void __fastcall OnAuraAdded_h(void *unit, void *edx, uint32_t slot,
                              uint32_t spellId) {
    g_origOnAuraAdded(unit, edx, slot, spellId);
-    StampApplication(unit, spellId, KindForSlot(static_cast<int>(slot)));
+    StampApplication(unit, spellId, static_cast<int>(slot));
    NotifyIfPlayer(unit);
 }

@@ -716,8 +978,7 @@ void __fastcall OnAuraStacksChanged_h(void *unit, void *edx, int slot,
    g_origOnAuraStacksChanged(unit, edx, slot, stackCount);
    StampApplication(
        unit,
-        Aura::Data::ReadSpellID(static_cast<const uint8_t *>(unit), slot),
-        KindForSlot(slot));
+        Aura::Data::ReadSpellID(static_cast<const uint8_t *>(unit), slot), slot);
    NotifyIfPlayer(unit);
 }

@@ -746,8 +1007,7 @@ OnAuraRemoved_t g_origOnAuraRemoved = nullptr;
 void __fastcall OnAuraRemoved_h(void *unit, void *edx, uint32_t slot,
                                uint32_t spellId) {
    g_origOnAuraRemoved(unit, edx, slot, spellId);
-    (void)slot;
-    Evict(Unit::Identity::GuidForObject(unit), spellId);
+    Evict(Unit::Identity::GuidForObject(unit), spellId, static_cast<int>(slot));
    NotifyIfPlayer(unit);
 }

@@ -757,33 +1017,99 @@ const Game::HookAutoRegister _hookAuraRemoved{

 } // namespace

-bool Get(uint64_t unitGuid, uint32_t spellId, uint64_t *outCaster,
+bool Get(uint64_t unitGuid, uint32_t spellId, int slot, uint64_t *outCaster,
         uint32_t *outExpirationMs, uint32_t *outDurationMs) {
    if (unitGuid == 0 || spellId == 0)
        return false;
-    for (const auto &e : g_cache) {
-        if (e.used && e.targetGuid == unitGuid && e.spellId == spellId) {
-            *outCaster = e.casterGuid;
-            *outExpirationMs = e.expirationMs;
-            *outDurationMs = e.durationMs;
-            return true;
-        }
-    }
-    return false;
+    // Slot first, then the sole entry (see FindInstance): several entries and no
+    // slot binding is a genuine ambiguity, so reporting the miss leaves the
+    // caller its unknown-caster defaults instead of one caster's timer on the
+    // other's aura.
+    const Entry *e = FindInstance(unitGuid, spellId, slot);
+    if (e == nullptr)
+        return false;
+    *outCaster = e->casterGuid;
+    *outExpirationMs = e->expirationMs;
+    *outDurationMs = e->durationMs;
+    return true;
 }

-void EvictAbsent(uint64_t unitGuid, const uint32_t *presentSpellIds, int count) {
-    if (unitGuid == 0 || presentSpellIds == nullptr || count <= 0)
-        return;
-    for (auto &e : g_cache) {
+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 (int i = 0; i < g_usedHigh; ++i) {
+        Entry &e = g_cache[i];
        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 *slotSpellIds) {
+    if (unitGuid == 0 || slotSpellIds == nullptr)
+        return;
+    bool anyPresent = false;
+    for (int s = 0; s < Offsets::UNIT_AURA_TOTAL; ++s)
+        if (slotSpellIds[s] != 0) {
+            anyPresent = true;
+            break;
+        }
+    if (!anyPresent)
+        return; // out of range vs genuinely buffless — see the header
+    const uint32_t now = NowMs();
+    for (int i = 0; i < g_usedHigh; ++i) {
+        Entry &e = g_cache[i];
+        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) {
-                present = true;
-                break;
-            }
+        if (e.slot != SLOT_UNBOUND) {
+            // A bound entry is only backed by the slot it was seated in, so a
+            // slot now holding a different spell (or nothing) leaves it stale
+            // even when another caster's copy keeps the spell ID on the unit.
+            present = slotSpellIds[e.slot] == e.spellId;
+        } else {
+            for (int s = 0; s < Offsets::UNIT_AURA_TOTAL; ++s)
+                if (slotSpellIds[s] == e.spellId) {
+                    present = true;
+                    break;
+                }
+        }
        if (!present)
            e.used = false;
    }
@@ -795,14 +1121,14 @@ int Enumerate(uint64_t unitGuid, bool harmful, CachedAura *out, int maxOut) {
    const int8_t want = harmful ? KIND_HARMFUL : KIND_HELPFUL;
    const uint32_t now = NowMs();
    int n = 0;
-    for (const auto &e : g_cache) {
-        if (n >= maxOut)
-            break;
+    for (int i = 0; i < g_usedHigh && n < maxOut; ++i) {
+        const Entry &e = g_cache[i];
        if (!e.used || e.targetGuid != unitGuid || e.kind != want)
            continue;
        if (e.expirationMs != 0 && now >= e.expirationMs)
            continue; // expired (infinite-duration entries pass)
-        out[n++] = {e.spellId, e.casterGuid, e.expirationMs, e.durationMs};
+        out[n++] = {e.spellId, e.casterGuid, e.expirationMs, e.durationMs,
+                    e.slot};
    }
    return n;
 }
@@ -19,7 +19,15 @@
 // the client ever sees the caster + a server-authoritative duration is the
 // `SMSG_SPELL_GO` packet at cast time. We parse it (the same packet
 // nampower parses for its `AURA_CAST_ON_*` events) and remember, per
-// `(targetGuid, spellId)`, who cast it and when it should expire.
+// `(targetGuid, spellId, casterGuid)`, who cast it and when it should expire.
+//
+// The caster belongs in that key because it belongs in the server's: two
+// same-class raiders' Corruption on one boss are two auras in two descriptor
+// slots, and a `(target, spell)` cache holds one entry for both — the second
+// cast overwrites the first caster's timing, and either copy falling off
+// evicts the survivor's entry too. The descriptor stores only spell IDs, so
+// each entry additionally records the slot its aura was seated in
+// (`OnAuraAdded`), which is what lets a per-slot query name the right instance.
 //
 // `Aura::Data::Push` consults this to fill `sourceUnit` (caster, resolved
 // to a unit token) and `expirationTime` for non-player units. The cache is
@@ -31,36 +39,82 @@

 namespace Aura::Source {

-// Looks up the cached caster + timing for the aura `spellId` currently on
-// the unit identified by `unitGuid`. Returns true and fills the out params
-// on a hit. `*outExpirationMs` is an absolute `GetTickCount`-epoch timestamp
-// (0 = unknown / infinite-duration aura); `*outDurationMs` is the applied
-// duration including the caster's modifiers (talents etc.; 0 = none) — use
-// it for the `duration` field so it stays consistent with `expirationTime`;
-// `*outCaster` is the caster's 64-bit GUID (never 0 on a hit). Returns false
-// on a miss or for zero inputs.
-bool Get(uint64_t unitGuid, uint32_t spellId, uint64_t *outCaster,
+// `slot` value for a query with no descriptor slot to go on (out-of-range
+// group array, cache fallback) and for an entry not yet seated in one.
+constexpr int SLOT_UNBOUND = -1;
+
+// Looks up the cached caster + timing for the aura `spellId` occupying
+// absolute descriptor `slot` on the unit identified by `unitGuid`. Returns
+// true and fills the out params on a hit. `*outExpirationMs` is an absolute
+// `GetTickCount`-epoch timestamp (0 = unknown / infinite-duration aura);
+// `*outDurationMs` is the applied duration including the caster's modifiers
+// (talents etc.; 0 = none) — use it for the `duration` field so it stays
+// consistent with `expirationTime`; `*outCaster` is the caster's 64-bit GUID
+// (0 when the aura was seen applied but its cast never observed). Returns
+// false on a miss or for zero inputs.
+//
+// Pass `SLOT_UNBOUND` when the caller has no slot. Resolution is by slot
+// first, then by spell ID when the unit carries only one entry for it; two
+// casters' entries with no slot binding resolve to a miss rather than to a
+// coin flip between them.
+bool Get(uint64_t unitGuid, uint32_t spellId, int slot, 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;
    uint64_t casterGuid;   // 0 = caster unknown (application hook, no SpellGo)
    uint32_t expirationMs; // 0 = infinite / unknown
    uint32_t durationMs;   // applied duration (incl. caster mods); 0 = none
+    int slot;              // descriptor slot the aura was seated in; feed it
+                           // back to `Get` to reach this exact entry again
 };

-// Evicts every cached entry for `unitGuid` whose spellId is NOT present in
-// `presentSpellIds[0..count)`. Used to reconcile the cache against a unit's
-// authoritative descriptor when it is back in view (a populated aura array
-// means the unit is fully synced): an entry the descriptor no longer lists
-// was removed while we couldn't observe it — e.g. a buff the owner cancelled
-// while out of our range, whose `OnAuraRemoved` we never received — so drop
-// it before the descriptor-drop fallback resurfaces it as a phantom. The
-// caller must only invoke this when the descriptor is populated (count > 0);
-// an empty array can't distinguish "out of range" from "genuinely buffless",
-// so reconciling then would wrongly wipe still-valid out-of-range entries.
-void EvictAbsent(uint64_t unitGuid, const uint32_t *presentSpellIds, int count);
+// Evicts every cached entry for `unitGuid` the unit's descriptor contradicts.
+// `slotSpellIds` is the raw `UNIT_FIELD_AURA` array — exactly
+// `Offsets::UNIT_AURA_TOTAL` spell IDs indexed by absolute slot, 0 for empty.
+// Used to reconcile the cache against a unit's authoritative descriptor when
+// it is back in view (a populated aura array means the unit is fully synced):
+// an entry the descriptor no longer backs was removed while we couldn't
+// observe it — e.g. a buff the owner cancelled while out of our range, whose
+// `OnAuraRemoved` we never received — so drop it before the descriptor-drop
+// fallback resurfaces it as a phantom.
+//
+// An entry seated in a slot is checked against THAT slot, so one caster's
+// copy going away retires its own entry even while another caster keeps the
+// spell ID present on the unit. Entries never seated are checked against the
+// whole array. An all-empty array is ignored: it can't distinguish "out of
+// range" from "genuinely buffless", and reconciling then would wrongly wipe
+// still-valid out-of-range entries.
+void EvictAbsent(uint64_t unitGuid, const uint32_t *slotSpellIds);

 // Fills `out` with up to `maxOut` cached, non-expired auras on `unitGuid`
 // whose helpful/harmful classification matches `harmful`. Returns the count
@@ -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
@@ -0,0 +1,620 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under
+// the terms of the GNU General Public License as published by the Free Software
+// Foundation, either version 3 of the License, or (at your option) any later
+// version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+// A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// Backports the direct-action and override binding APIs introduced in 2.0.
+// Normal bindings are stored by vanilla's SetBinding implementation using the
+// later-client SPELL/ITEM/MACRO/CLICK command strings. The resolved-command
+// hook executes those four command families; every native binding command is
+// passed through unchanged.
+//
+// Override bindings live in a separate owner-scoped layer in front of the
+// native key lookup. They are deliberately never written to the saved binding
+// table, so clearing an owner immediately reveals the next override or the
+// unchanged native binding underneath it.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "macro/Execute.h"
+
+#include <algorithm>
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+namespace Bindings::Api {
+
+namespace {
+
+constexpr const char kSpellPrefix[] = "SPELL ";
+constexpr const char kItemPrefix[] = "ITEM ";
+constexpr const char kMacroPrefix[] = "MACRO ";
+constexpr const char kClickPrefix[] = "CLICK ";
+constexpr const char kDefaultMouseButton[] = "LeftButton";
+
+using ScriptSetBinding_t = int(__fastcall *)(void *L);
+using KeyDispatch_t = int(__thiscall *)(void *mgr, const char *key, int isDown);
+using CommandExecute_t = int(__thiscall *)(void *mgr, const char *cmd, int isDown);
+
+KeyDispatch_t KeyDispatch_o = nullptr;
+CommandExecute_t CommandExecute_o = nullptr;
+
+enum class CommandType {
+    None,
+    Spell,
+    Item,
+    Macro,
+    Click,
+};
+
+struct ParsedCommand {
+    CommandType type = CommandType::None;
+    const char *argument = nullptr;
+};
+
+struct OverrideEntry {
+    const void *owner = nullptr;
+    std::string key;
+    std::string command;
+    bool priority = false;
+    uint64_t sequence = 0;
+};
+
+std::vector<OverrideEntry> g_overrides;
+std::unordered_map<std::string, std::string> g_activeOverrides;
+uint64_t g_nextSequence = 0;
+
+// Normalizes a binding key to the engine's own canonical form so a stored
+// override matches the string FUN_BINDING_KEY_DISPATCH builds at keypress. The
+// engine's key-string builder (FUN_004b6630) always emits modifiers in the
+// fixed order ALT-CTRL-SHIFT- ahead of the base key, regardless of the order
+// the caller passed them; vanilla SetBinding never reorders, so the override
+// layer does it here. Both the store and the lookup run through this, so they
+// stay consistent while also matching the engine's keypress form.
+std::string CanonicalKey(const char *key) {
+    std::string result = key ? key : "";
+    for (char &character : result) {
+        if (character >= 'a' && character <= 'z')
+            character = static_cast<char>(character - 'a' + 'A');
+    }
+
+    // Strip the three modifier prefixes in whatever order/repetition they
+    // appear, then re-emit them in the engine's fixed order. Prefix-stripping
+    // (rather than splitting on '-') keeps the minus base key correct, e.g.
+    // "SHIFT--" -> modifier SHIFT + base "-".
+    bool alt = false, ctrl = false, shift = false;
+    size_t base = 0;
+    for (bool matched = true; matched;) {
+        matched = false;
+        if (result.compare(base, 4, "ALT-") == 0) {
+            alt = true;
+            base += 4;
+            matched = true;
+        } else if (result.compare(base, 5, "CTRL-") == 0) {
+            ctrl = true;
+            base += 5;
+            matched = true;
+        } else if (result.compare(base, 6, "SHIFT-") == 0) {
+            shift = true;
+            base += 6;
+            matched = true;
+        }
+    }
+
+    if (!alt && !ctrl && !shift)
+        return result;
+
+    std::string canonical;
+    if (alt)
+        canonical += "ALT-";
+    if (ctrl)
+        canonical += "CTRL-";
+    if (shift)
+        canonical += "SHIFT-";
+    canonical += result.substr(base);
+
+    return canonical;
+}
+
+std::string MakeCommand(const char *prefix, const char *arg) {
+    std::string cmd = prefix;
+    cmd += arg;
+    return cmd;
+}
+
+std::string MakeClickCommand(const char *btnName, const char *mouseBtn) {
+    std::string cmd = MakeCommand(kClickPrefix, btnName);
+    if (mouseBtn != nullptr) {
+        cmd += ':';
+        cmd += mouseBtn;
+    }
+
+    return cmd;
+}
+
+ParsedCommand ParseCommand(const char *cmd) {
+    if (cmd == nullptr)
+        return {};
+
+    struct PrefixEntry {
+        const char *prefix;
+        size_t length;
+        CommandType type;
+    };
+
+    static constexpr PrefixEntry prefixes[] = {
+        {kSpellPrefix, sizeof(kSpellPrefix) - 1, CommandType::Spell},
+        {kItemPrefix, sizeof(kItemPrefix) - 1, CommandType::Item},
+        {kMacroPrefix, sizeof(kMacroPrefix) - 1, CommandType::Macro},
+        {kClickPrefix, sizeof(kClickPrefix) - 1, CommandType::Click},
+    };
+
+    for (const PrefixEntry &entry : prefixes) {
+        if (std::strncmp(cmd, entry.prefix, entry.length) == 0)
+            return {entry.type, cmd + entry.length};
+    }
+
+    return {};
+}
+
+bool CallGlobalString(void *L, const char *func, const char *arg) {
+    const int top = Game::Lua::GetTop(L);
+    if (!Game::Lua::PushGlobalFunction(L, func)) {
+        Game::Lua::SetTop(L, top);
+        return false;
+    }
+
+    Game::Lua::PushString(L, arg);
+    const bool ok = Game::Lua::PCall(L, 1, 0, 0) == 0;
+    Game::Lua::SetTop(L, top);
+
+    return ok;
+}
+
+bool CallTableString(void *L, const char *table, const char *func, const char *arg) {
+    const int top = Game::Lua::GetTop(L);
+
+    Game::Lua::PushString(L, table);
+    Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX);
+    if (Game::Lua::Type(L, -1) != Game::Lua::TYPE_TABLE) {
+        Game::Lua::SetTop(L, top);
+        return false;
+    }
+
+    const int tableIndex = Game::Lua::GetTop(L);
+
+    Game::Lua::PushString(L, func);
+    Game::Lua::GetTable(L, tableIndex);
+    if (Game::Lua::Type(L, -1) != Game::Lua::TYPE_FUNCTION) {
+        Game::Lua::SetTop(L, top);
+        return false;
+    }
+
+    Game::Lua::PushString(L, arg);
+    const bool ok = Game::Lua::PCall(L, 1, 0, 0) == 0;
+    Game::Lua::SetTop(L, top);
+
+    return ok;
+}
+
+void InvokeButtonClick(void *L, const char *btnName, size_t btnNameLength, const char *mouseBtn) {
+    const int top = Game::Lua::GetTop(L);
+
+    Game::Lua::PushLString(L, btnName, static_cast<unsigned int>(btnNameLength));
+    Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX);
+    if (Game::Lua::Type(L, -1) != Game::Lua::TYPE_TABLE) {
+        Game::Lua::SetTop(L, top);
+        return;
+    }
+
+    const int frameIndex = Game::Lua::GetTop(L);
+    Game::Lua::PushString(L, "Click");
+    Game::Lua::GetTable(L, frameIndex);
+    if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_FUNCTION) {
+        Game::Lua::PushValue(L, frameIndex);
+        Game::Lua::PushString(L, mouseBtn);
+        Game::Lua::PCall(L, 2, 0, 0);
+    }
+
+    Game::Lua::SetTop(L, top);
+}
+
+void ExecuteClick(void *L, const char *arg) {
+    const char *separator = std::strrchr(arg, ':');
+    if (separator == arg || (separator != nullptr && separator[1] == '\0'))
+        return;
+
+    const char *mouseBtn = kDefaultMouseButton;
+    size_t btnNameLength = std::strlen(arg);
+    if (separator != nullptr) {
+        btnNameLength = static_cast<size_t>(separator - arg);
+        mouseBtn = separator + 1;
+    }
+
+    if (btnNameLength == 0)
+        return;
+
+    InvokeButtonClick(L, arg, btnNameLength, mouseBtn);
+}
+
+// Returns true for every recognized direct-action command, including malformed
+// or stale commands. Vanilla cannot execute these namespaces, so a bad command
+// is consumed as a no-op instead of falling through to an unrelated handler.
+bool ExecuteSpecialCommand(const char *cmd, int isDown) {
+    const ParsedCommand parsed = ParseCommand(cmd);
+    if (parsed.type == CommandType::None)
+        return false;
+
+    if (!isDown || parsed.argument == nullptr || *parsed.argument == '\0')
+        return true;
+
+    void *L = Game::Lua::State();
+    if (L == nullptr)
+        return true;
+
+    switch (parsed.type) {
+    case CommandType::Spell:
+        CallGlobalString(L, "CastSpellByName", parsed.argument);
+        break;
+    case CommandType::Item:
+        CallTableString(L, "C_Item", "UseItemByName", parsed.argument);
+        break;
+    case CommandType::Macro:
+        Macro::Execute::Saved(L, parsed.argument);
+        break;
+    case CommandType::Click:
+        ExecuteClick(L, parsed.argument);
+        break;
+    default:
+        break;
+    }
+
+    return true;
+}
+
+const OverrideEntry *FindEffectiveOverride(const std::string &key) {
+    const OverrideEntry *best = nullptr;
+    for (const OverrideEntry &entry : g_overrides) {
+        if (entry.key != key)
+            continue;
+
+        if (best == nullptr || entry.priority > best->priority ||
+            (entry.priority == best->priority && entry.sequence > best->sequence))
+            best = &entry;
+    }
+
+    return best;
+}
+
+void SetOverride(const void *owner, bool priority, const std::string &key, const std::string &cmd) {
+    auto existing =
+        std::find_if(g_overrides.begin(), g_overrides.end(),
+                     [&](const OverrideEntry &entry) {
+                         return entry.owner == owner && entry.key == key;
+                     });
+
+    if (existing == g_overrides.end()) {
+        g_overrides.push_back(
+            {owner, key, cmd, priority, ++g_nextSequence});
+        return;
+    }
+
+    existing->command = cmd;
+    existing->priority = priority;
+    existing->sequence = ++g_nextSequence;
+}
+
+void RemoveOverride(const void *owner, const std::string &key) {
+    g_overrides.erase(std::remove_if(g_overrides.begin(), g_overrides.end(),
+                                     [&](const OverrideEntry &entry) {
+                                         return entry.owner == owner &&
+                                                entry.key == key;
+                                     }),
+                      g_overrides.end());
+}
+
+int ExecuteCommand(void *mgr, const char *cmd, int isDown) {
+    if (ExecuteSpecialCommand(cmd, isDown))
+        return 1;
+
+    return CommandExecute_o(mgr, cmd, isDown);
+}
+
+int __fastcall CommandExecute_h(void *mgr, void *, const char *cmd, int isDown) {
+    return ExecuteCommand(mgr, cmd, isDown);
+}
+
+// Runs an override-resolved command with the same execution context the engine
+// wraps around a native keypress. FUN_BINDING_KEY_DISPATCH saves the frame-
+// script exec-context, zeroes it for the nested command, marks the manager as
+// mid-command (`+0xD8`), then restores the context and floors the nesting
+// depth. Native-table bindings already run inside this (the engine sets it up
+// before calling FUN_BINDING_COMMAND_EXECUTE, which we co-hook); overrides
+// bypass that path, so we mirror it here. Without it, a native Bindings.xml
+// command dispatched through an override would run without the context its
+// handler expects. Special SPELL/ITEM/MACRO/CLICK commands run harmlessly
+// inside the same wrapper.
+int DispatchOverrideCommand(void *mgr, const char *cmd, int isDown) {
+    volatile uint32_t *context =
+        reinterpret_cast<volatile uint32_t *>(Offsets::VAR_FRAMESCRIPT_EXEC_CONTEXT);
+    volatile uint32_t *depth = reinterpret_cast<volatile uint32_t *>(
+        Offsets::VAR_FRAMESCRIPT_EXEC_CONTEXT_DEPTH);
+    volatile uint32_t *executing =
+        Game::Ptr<volatile uint32_t>(mgr, Offsets::OFF_BINDING_MANAGER_EXECUTING);
+
+    const uint32_t savedContext = *context;
+    *depth = *depth + 1;
+    if (*depth != 0)
+        *context = 0;
+
+    *executing = 1;
+    const int result = ExecuteCommand(mgr, cmd, isDown);
+    *executing = 0;
+
+    if (*depth != 0)
+        *context = savedContext;
+    if (static_cast<int32_t>(*depth) - 1 > 0)
+        *depth = *depth - 1;
+    else
+        *depth = 0;
+
+    return result;
+}
+
+int __fastcall KeyDispatch_h(void *mgr, void *, const char *key, int isDown) {
+    const std::string canonicalKey = CanonicalKey(key);
+
+    // Keep a key-down paired with its override command even if that override is
+    // cleared while the command executes. The newly revealed native binding
+    // must not receive only the key-up half of the same physical press.
+    if (!isDown) {
+        auto active = g_activeOverrides.find(canonicalKey);
+        if (active != g_activeOverrides.end()) {
+            DispatchOverrideCommand(mgr, active->second.c_str(), 0);
+            g_activeOverrides.erase(active);
+            return 1;
+        }
+    }
+
+    const OverrideEntry *entry = FindEffectiveOverride(canonicalKey);
+    if (entry == nullptr)
+        return KeyDispatch_o(mgr, key, isDown);
+
+    if (isDown)
+        g_activeOverrides[canonicalKey] = entry->command;
+
+    return DispatchOverrideCommand(mgr, entry->command.c_str(), isDown);
+}
+
+int SetBindingCommand(void *L, const char *prefix, const char *usage) {
+    if (!Game::Lua::IsString(L, 1) || !Game::Lua::IsString(L, 2)) {
+        Game::Lua::Error(L, usage);
+        return 0;
+    }
+
+    const std::string key = Game::Lua::ToString(L, 1);
+    const std::string command = MakeCommand(prefix, Game::Lua::ToString(L, 2));
+
+    // Preserve the stock SetBinding return value, binding-set selection,
+    // key normalization, UPDATE_BINDINGS event, and SaveBindings behavior.
+    Game::Lua::SetTop(L, 0);
+    Game::Lua::PushString(L, key.c_str());
+    Game::Lua::PushString(L, command.c_str());
+    auto setBinding =
+        reinterpret_cast<ScriptSetBinding_t>(Offsets::FUN_SCRIPT_SET_BINDING);
+
+    return setBinding(L);
+}
+
+const char *OptionalMouseButton(void *L, int index, const char *usage) {
+    if (Game::Lua::GetTop(L) < index || Game::Lua::Type(L, index) == Game::Lua::TYPE_NIL)
+        return nullptr;
+
+    if (!Game::Lua::IsString(L, index)) {
+        Game::Lua::Error(L, usage);
+        return nullptr;
+    }
+
+    return Game::Lua::ToString(L, index);
+}
+
+int __fastcall Script_SetBindingSpell(void *L) {
+    return SetBindingCommand(L, kSpellPrefix, "Usage: SetBindingSpell(key, spell)");
+}
+
+int __fastcall Script_SetBindingItem(void *L) {
+    return SetBindingCommand(L, kItemPrefix, "Usage: SetBindingItem(key, item)");
+}
+
+int __fastcall Script_SetBindingMacro(void *L) {
+    return SetBindingCommand(L, kMacroPrefix, "Usage: SetBindingMacro(key, macro)");
+}
+
+int __fastcall Script_SetBindingClick(void *L) {
+    constexpr const char *usage = "Usage: SetBindingClick(key, buttonName [, mouseButton])";
+    if (!Game::Lua::IsString(L, 1) || !Game::Lua::IsString(L, 2)) {
+        Game::Lua::Error(L, usage);
+        return 0;
+    }
+
+    const std::string key = Game::Lua::ToString(L, 1);
+    const char *buttonName = Game::Lua::ToString(L, 2);
+    const char *mouseButton = OptionalMouseButton(L, 3, usage);
+    const std::string command = MakeClickCommand(buttonName, mouseButton);
+
+    Game::Lua::SetTop(L, 0);
+    Game::Lua::PushString(L, key.c_str());
+    Game::Lua::PushString(L, command.c_str());
+    auto setBinding =
+        reinterpret_cast<ScriptSetBinding_t>(Offsets::FUN_SCRIPT_SET_BINDING);
+
+    return setBinding(L);
+}
+
+bool ReadOverrideHeader(void *L, const char *usage, const void **owner,
+                        bool *priority, std::string *key) {
+    *owner = Game::Lua::ResolveObject(L, 1);
+    if (*owner == nullptr || Game::Lua::Type(L, 2) != Game::Lua::TYPE_BOOLEAN ||
+        !Game::Lua::IsString(L, 3)) {
+        Game::Lua::Error(L, usage);
+        return false;
+    }
+
+    *priority = Game::Lua::ToBoolean(L, 2) != 0;
+    *key = CanonicalKey(Game::Lua::ToString(L, 3));
+    return true;
+}
+
+int SetOverrideBindingCommand(void *L, const char *prefix, const char *usage) {
+    const void *owner = nullptr;
+    bool priority = false;
+
+    std::string key;
+    if (!ReadOverrideHeader(L, usage, &owner, &priority, &key))
+        return 0;
+
+    if (!Game::Lua::IsString(L, 4)) {
+        Game::Lua::Error(L, usage);
+        return 0;
+    }
+
+    SetOverride(owner, priority, key,
+                MakeCommand(prefix, Game::Lua::ToString(L, 4)));
+
+    return 0;
+}
+
+int __fastcall Script_SetOverrideBinding(void *L) {
+    constexpr const char *usage = "Usage: SetOverrideBinding(owner, isPriority, key [, command])";
+    const void *owner = nullptr;
+    bool priority = false;
+
+    std::string key;
+    if (!ReadOverrideHeader(L, usage, &owner, &priority, &key))
+        return 0;
+
+    if (Game::Lua::GetTop(L) < 4 ||
+        Game::Lua::Type(L, 4) == Game::Lua::TYPE_NIL) {
+        RemoveOverride(owner, key);
+        return 0;
+    }
+
+    if (!Game::Lua::IsString(L, 4)) {
+        Game::Lua::Error(L, usage);
+        return 0;
+    }
+
+    SetOverride(owner, priority, key, Game::Lua::ToString(L, 4));
+    return 0;
+}
+
+int __fastcall Script_SetOverrideBindingSpell(void *L) {
+    return SetOverrideBindingCommand(
+        L, kSpellPrefix,
+        "Usage: SetOverrideBindingSpell(owner, isPriority, key, spell)");
+}
+
+int __fastcall Script_SetOverrideBindingItem(void *L) {
+    return SetOverrideBindingCommand(
+        L, kItemPrefix,
+        "Usage: SetOverrideBindingItem(owner, isPriority, key, item)");
+}
+
+int __fastcall Script_SetOverrideBindingMacro(void *L) {
+    return SetOverrideBindingCommand(
+        L, kMacroPrefix,
+        "Usage: SetOverrideBindingMacro(owner, isPriority, key, macro)");
+}
+
+int __fastcall Script_SetOverrideBindingClick(void *L) {
+    constexpr const char *usage =
+        "Usage: SetOverrideBindingClick(owner, "
+        "isPriority, key, buttonName [, mouseButton])";
+
+    const void *owner = nullptr;
+    bool priority = false;
+
+    std::string key;
+    if (!ReadOverrideHeader(L, usage, &owner, &priority, &key))
+        return 0;
+
+    if (!Game::Lua::IsString(L, 4)) {
+        Game::Lua::Error(L, usage);
+        return 0;
+    }
+
+    const char *buttonName = Game::Lua::ToString(L, 4);
+    const char *mouseButton = OptionalMouseButton(L, 5, usage);
+    SetOverride(owner, priority, key,
+                MakeClickCommand(buttonName, mouseButton));
+
+    return 0;
+}
+
+int __fastcall Script_ClearOverrideBindings(void *L) {
+    const void *owner = Game::Lua::ResolveObject(L, 1);
+    if (owner == nullptr) {
+        Game::Lua::Error(L, "Usage: ClearOverrideBindings(owner)");
+        return 0;
+    }
+
+    g_overrides.erase(std::remove_if(g_overrides.begin(), g_overrides.end(),
+                                     [&](const OverrideEntry &entry) {
+                                         return entry.owner == owner;
+                                     }),
+                      g_overrides.end());
+    return 0;
+}
+
+void RegisterLuaFunctions() {
+    // A fresh FrameScript state makes every owner pointer from the previous
+    // state stale. Permanent bindings remain in vanilla's binding table.
+    g_overrides.clear();
+    g_activeOverrides.clear();
+    g_nextSequence = 0;
+
+    Game::Lua::RegisterGlobalFunction("SetBindingSpell", &Script_SetBindingSpell);
+    Game::Lua::RegisterGlobalFunction("SetBindingItem", &Script_SetBindingItem);
+    Game::Lua::RegisterGlobalFunction("SetBindingMacro", &Script_SetBindingMacro);
+    Game::Lua::RegisterGlobalFunction("SetBindingClick", &Script_SetBindingClick);
+    Game::Lua::RegisterGlobalFunction("SetOverrideBinding",
+                                      &Script_SetOverrideBinding);
+    Game::Lua::RegisterGlobalFunction("SetOverrideBindingSpell",
+                                      &Script_SetOverrideBindingSpell);
+    Game::Lua::RegisterGlobalFunction("SetOverrideBindingItem",
+                                      &Script_SetOverrideBindingItem);
+    Game::Lua::RegisterGlobalFunction("SetOverrideBindingMacro",
+                                      &Script_SetOverrideBindingMacro);
+    Game::Lua::RegisterGlobalFunction("SetOverrideBindingClick",
+                                      &Script_SetOverrideBindingClick);
+    Game::Lua::RegisterGlobalFunction("ClearOverrideBindings",
+                                      &Script_ClearOverrideBindings);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+const Game::HookAutoRegister _hookKeyDispatch{
+    Offsets::FUN_BINDING_KEY_DISPATCH, reinterpret_cast<void *>(&KeyDispatch_h),
+    reinterpret_cast<void **>(&KeyDispatch_o)};
+
+const Game::HookAutoRegister _hookCommandExecute{
+    Offsets::FUN_BINDING_COMMAND_EXECUTE,
+    reinterpret_cast<void *>(&CommandExecute_h),
+    reinterpret_cast<void **>(&CommandExecute_o)};
+
+} // namespace
+
+} // namespace Bindings::Api
@@ -18,29 +18,19 @@
 // against an internal cache to identify the player. With this we
 // just read the GUID directly.
 //
-// Implementation: the SMSG_MESSAGECHAT handler at FUN_0049D560 reads
-// the senderGUID from the packet (offsets `[ebp-0x10]` / `[ebp-0xC]`
-// in that function's stack frame) and forwards it as args 9-10 to
-// the chat dispatcher at FUN_0049A870. The dispatcher in turn fires
-// the appropriate CHAT_MSG_* event during its execution. We hook the
-// dispatcher's entry, stash the GUID into a file-scope global, call
-// the original (which fires the event synchronously), then clear the
-// global on return. Inside the addon's OnEvent, `GetCurrentChatGUID`
-// reads the global.
-//
-// Why not hook the SMSG handler directly: the GUID isn't in argument
-// registers/stack at the handler's entry — it's read mid-function
-// into locals. Hooking the dispatcher (which receives the GUID as
-// args) is structurally simpler. The trade-off: the dispatcher is
-// also called for synthetic chat (system notifications, arena team
-// events, etc.) with GUID = 0; for those, `GetCurrentChatGUID()`
-// returns nil — matches the modern API's behavior of nil GUID for
-// non-player-sourced chat.
+// The GUID is published for the duration of a chat dispatch by a
+// `DispatchScope` (see the header), which Chat::Dispatch — the single
+// owner of the FUN_0049A870 chat-dispatch hook — constructs around the
+// original call. The engine fires the CHAT_MSG_* event synchronously
+// inside that call, so `GetCurrentChatGUID` reads the right GUID from
+// the addon's OnEvent. The dispatcher is also called for synthetic chat
+// (system notifications, arena team events, etc.) with GUID = 0; for
+// those `GetCurrentChatGUID()` returns nil — matching the modern API's
+// behavior of a nil GUID for non-player-sourced chat.

 #include "CurrentGUID.h"

 #include "Game.h"
-#include "Offsets.h"
 #include "guid/Guid.h"

 #include <cstdint>
@@ -69,39 +59,17 @@ void RegisterLuaFunctions() {

 } // namespace

-ChatDispatch_t ChatDispatch_o = nullptr;
+DispatchScope::DispatchScope(uint32_t guidLo, uint32_t guidHi)
+    : prevLo_(g_currentGuidLo), prevHi_(g_currentGuidHi) {
+    g_currentGuidLo = guidLo;
+    g_currentGuidHi = guidHi;
+}

-void __fastcall ChatDispatch_h(
-    const char *sender, int chatType,
-    int arg3, int arg4, int arg5, int arg6, int arg7,
-    int targetGuidLo, int targetGuidHi, int arg10,
-    int senderGuidLo, int senderGuidHi)
-{
-    // Save before original — the engine's chat event fires DURING
-    // origCall, and the addon's OnEvent runs synchronously inside
-    // that window. The GUID must be readable at that point.
-    const uint32_t prevLo = g_currentGuidLo;
-    const uint32_t prevHi = g_currentGuidHi;
-    g_currentGuidLo = static_cast<uint32_t>(senderGuidLo);
-    g_currentGuidHi = static_cast<uint32_t>(senderGuidHi);
-
-    ChatDispatch_o(sender, chatType, arg3, arg4, arg5, arg6, arg7,
-                   targetGuidLo, targetGuidHi, arg10,
-                   senderGuidLo, senderGuidHi);
-
-    // Restore prior value rather than clearing to 0, so nested
-    // dispatch (one chat event firing during another's OnEvent —
-    // e.g. an addon calling SendChatMessage from its handler) leaves
-    // the outer context's GUID intact when the inner returns.
-    g_currentGuidLo = prevLo;
-    g_currentGuidHi = prevHi;
+DispatchScope::~DispatchScope() {
+    g_currentGuidLo = prevLo_;
+    g_currentGuidHi = prevHi_;
 }

 static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};

-static const Game::HookAutoRegister _hookreg{
-    Offsets::FUN_CHAT_DISPATCH,
-    reinterpret_cast<void *>(&ChatDispatch_h),
-    reinterpret_cast<void **>(&ChatDispatch_o)};
-
 } // namespace Chat::CurrentGUID
@@ -13,55 +13,28 @@

 #pragma once

+#include <cstdint>
+
 namespace Chat::CurrentGUID {

-// Hook for FUN_CHAT_DISPATCH (0x0049A870). Saves the senderGUID into
-// a file-scope global for the duration of the original call, then
-// clears it on return. Inside that window the engine fires the
-// appropriate CHAT_MSG_* event, so `GetCurrentChatGUID()` called from
-// the addon's OnEvent sees the GUID for the message that triggered it.
-//
-// 12-arg __fastcall signature. The function has a stack-probe
-// prologue (`mov eax, 0x1F0C; call _chkstk`) — its frame is ~8KB.
-// Verified by disassembling 0x0049A870 in 1.12.1: stack-arg access
-// reaches `[ebp+0x2C]` (= param 12) and the function exits with
-// `ret 0x28` (cleans 40 bytes = 10 stack args + 2 register args).
-//
-//   ECX  = arg1 (sender name string)
-//   EDX  = arg2 (chat type byte)
-//   [esp+ 4] = arg3
-//   [esp+ 8] = arg4
-//   [esp+ c] = arg5
-//   [esp+10] = arg6
-//   [esp+14] = arg7
-//   [esp+18] = arg8 — target GUID lo (for whisper/channel target)
-//   [esp+1c] = arg9 — target GUID hi
-//   [esp+20] = arg10
-//   [esp+24] = arg11 — sender GUID lo     ← captured
-//   [esp+28] = arg12 — sender GUID hi     ← captured
-//
-// Identified args 11/12 as senderGUID by tracing the AFK auto-reply
-// path at 0x0049AB39: reads params 11/12, OR's them to check for
-// non-zero, pushes them onto the packet stream via FUN_00418370
-// (the "write u64" helper). That's the GUID the AFK whisper-back is
-// addressed to — i.e. the original message sender.
-//
-// An earlier 10-arg signature derived from Ghidra (on the wrong
-// binary) had `ret 0x20` cleanup. The 8-byte cleanup mismatch with
-// the engine's `ret 0x28`-shaped call left 8 bytes of stack
-// uncleaned per chat-dispatch invocation, corrupting the engine's
-// stack frame and crashing on a later indirect call. See the
-// commit message for the full diagnosis.
-using ChatDispatch_t = void(__fastcall *)(
-    const char *sender, int chatType,
-    int arg3, int arg4, int arg5, int arg6, int arg7,
-    int targetGuidLo, int targetGuidHi, int arg10,
-    int senderGuidLo, int senderGuidHi);
-extern ChatDispatch_t ChatDispatch_o;
-void __fastcall ChatDispatch_h(
-    const char *sender, int chatType,
-    int arg3, int arg4, int arg5, int arg6, int arg7,
-    int targetGuidLo, int targetGuidHi, int arg10,
-    int senderGuidLo, int senderGuidHi);
+// RAII scope that publishes the sender GUID of the chat message currently being
+// dispatched, for `GetCurrentChatGUID()` to read. Chat::Dispatch constructs one
+// around the original chat-dispatch call: the engine fires the CHAT_MSG_* event
+// synchronously inside that call, so an addon's OnEvent sees the GUID of the
+// message that triggered it. Restores the prior value on destruction rather than
+// clearing to 0, so nested dispatch (a chat event firing during another's
+// OnEvent — e.g. an addon calling SendChatMessage from its handler) leaves the
+// outer context's GUID intact when the inner returns.
+class DispatchScope {
+public:
+    DispatchScope(uint32_t guidLo, uint32_t guidHi);
+    ~DispatchScope();
+    DispatchScope(const DispatchScope &) = delete;
+    DispatchScope &operator=(const DispatchScope &) = delete;
+
+private:
+    uint32_t prevLo_;
+    uint32_t prevHi_;
+};

 } // namespace Chat::CurrentGUID
@@ -0,0 +1,105 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// Single owner of the chat-dispatch hook (FUN_0049A870).
+//
+// The engine routes every server-delivered chat message — say/yell/whisper/
+// channel/emote and synthetic system notifications — through this one function.
+// (Addon `print`/`AddMessage` does NOT pass through it.) Several independent
+// concerns need to observe or transform a dispatched message, but MinHook allows
+// only ONE hook per target, so this module owns the hook and orchestrates them,
+// mirroring Net::PacketDispatch (one hook, fanned out to independent concerns):
+//
+//   - Chat::IconFilter::Sanitize — strip player-injected `|T` icon spoofs from
+//     the message before the engine builds the chat line AND the speech bubble
+//     (both come from the same buffer, so one sanitize covers both).
+//   - Chat::RaidMarkers::Substitute — expand `{rt1}`/`{skull}`/… raid-target
+//     tokens into inline marker icons. Runs AFTER Sanitize so a player gets the
+//     fixed marker icons but still can't inject an arbitrary `|T` path.
+//   - Chat::CurrentGUID::DispatchScope — publish the sender GUID for the
+//     synchronous CHAT_MSG_* event so `GetCurrentChatGUID()` can read it.
+//
+// Signature — `__fastcall`, `RET 0x28`:
+//   ECX  = arg1  — the MESSAGE text (verified from the call site in FUN_0049D560:
+//                  `MOV ECX,[EBP-0x10]` = the raw/processed message. An older
+//                  note mislabeled this "sender name".) Copied into one buffer
+//                  fed to both the chat frame and the bubble spawn FUN_00608AC0.
+//   EDX  = arg2  — chat type byte
+//   [esp+04] = arg3      [esp+08] = arg4      [esp+0c] = arg5
+//   [esp+10] = arg6      [esp+14] = arg7
+//   [esp+18] = arg8  — target GUID lo (whisper/channel target)
+//   [esp+1c] = arg9  — target GUID hi
+//   [esp+20] = arg10
+//   [esp+24] = arg11 — sender GUID lo   ← published
+//   [esp+28] = arg12 — sender GUID hi   ← published
+//
+// The `RET 0x28` cleanup (40 bytes = 10 stack args) MUST match the declared
+// signature exactly; an earlier 10-arg / `ret 0x20` version left 8 bytes
+// uncleaned per call and crashed the engine on a later indirect call.
+
+#include "CurrentGUID.h"
+#include "IconFilter.h"
+#include "RaidMarkers.h"
+
+#include "Game.h"
+#include "Offsets.h"
+
+#include <cstdint>
+
+namespace Chat::Dispatch {
+
+namespace {
+
+using ChatDispatch_t = void(__fastcall *)(
+    const char *message, int chatType,
+    int arg3, int arg4, int arg5, int arg6, int arg7,
+    int targetGuidLo, int targetGuidHi, int arg10,
+    int senderGuidLo, int senderGuidHi);
+
+ChatDispatch_t g_original = nullptr;
+
+void __fastcall ChatDispatch_h(
+    const char *message, int chatType,
+    int arg3, int arg4, int arg5, int arg6, int arg7,
+    int targetGuidLo, int targetGuidHi, int arg10,
+    int senderGuidLo, int senderGuidHi)
+{
+    // Strip player-injected `|T` icon escapes (covers chat line + speech bubble;
+    // both build from this message). The 0x800 buffer matches the engine's own
+    // message-buffer cap.
+    char iconBuf[0x800];
+    const char *msg = Chat::IconFilter::Sanitize(message, iconBuf, sizeof iconBuf);
+
+    // Expand raid-target tokens ({rt1}/{skull}/…) into inline marker icons —
+    // after the sanitize, so only these fixed, safe escapes are added.
+    char markerBuf[0x800];
+    msg = Chat::RaidMarkers::Substitute(msg, markerBuf, sizeof markerBuf);
+
+    // Publish the sender GUID for the CHAT_MSG_* event the original fires
+    // synchronously; restored when this scope ends (after the original returns).
+    Chat::CurrentGUID::DispatchScope guid(static_cast<uint32_t>(senderGuidLo),
+                                          static_cast<uint32_t>(senderGuidHi));
+
+    g_original(msg, chatType, arg3, arg4, arg5, arg6, arg7,
+               targetGuidLo, targetGuidHi, arg10,
+               senderGuidLo, senderGuidHi);
+}
+
+static const Game::HookAutoRegister _hookreg{
+    Offsets::FUN_CHAT_DISPATCH,
+    reinterpret_cast<void *>(&ChatDispatch_h),
+    reinterpret_cast<void **>(&g_original)};
+
+} // namespace
+
+} // namespace Chat::Dispatch
@@ -0,0 +1,85 @@
+// 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/>.
+
+// Inline-texture (`|T`) chat anti-spoof.
+//
+// Vanilla neutralizes player-*typed* escapes in chat (a typed `|cff…|r`,
+// `|Hitem…|h` or `|T…|t` shows as raw text) — only *trusted* text renders them
+// (addon `AddMessage`, shift-clicked links). Our Text::InlineTexture backport
+// breaks that parity for `|T` alone: it detects the neutralized `||T` form and
+// draws the icon anyway, so a player could `/say` `|Tpath|t` and have a real
+// icon appear in everyone's chat AND in the speech bubble over their head.
+//
+// This restores vanilla's behavior for `|T` by defanging it in the chat path,
+// while leaving `|c`/`|r`/`|H`/`|h` exactly as vanilla (already raw for typed
+// input). It CANNOT be done in the text emitter: addon `|T` and player `|T`
+// reach the emitter as byte-identical `||T` (vanilla doubles the unrecognized
+// `|T` for both), so the only place they're distinguishable is the source —
+// server-delivered chat flows through the chat dispatcher, addon `print` does
+// not. Chat::Dispatch owns that hook and calls this on the message.
+//
+// Defang = replace the `|` of each `|T` with a space, breaking the pipe→T
+// adjacency the inline-texture detector keys on (`|T` and `||T` both contain the
+// `|T` substring, so this catches the doubled form too). The path text stays
+// readable, the closer `|t` is inert without an opener, and every other escape
+// is untouched.
+
+#include "IconFilter.h"
+
+namespace Chat::IconFilter {
+
+namespace {
+
+// True if `s` contains an inline-texture opener (`|T`) anywhere.
+bool HasIconEscape(const char *s) {
+    for (; *s != '\0'; ++s)
+        if (s[0] == '|' && s[1] == 'T')
+            return true;
+    return false;
+}
+
+} // namespace
+
+const char *Sanitize(const char *msg, char *buf, size_t bufSize) {
+    if (msg == nullptr || !HasIconEscape(msg))
+        return msg; // common case: forward untouched, no copy
+
+    // NEVER write `msg` in place: several of the chat handler's ~50 callers pass
+    // read-only `.rdata` literals (system notifications), so an in-place edit
+    // would fault. We copy only when a `|T` is actually present.
+    //
+    // Defanging must not leave a LONE `|` followed by a non-escape char — that's
+    // an invalid escape, which the chat frame tolerates but the speech-bubble
+    // text setter chokes on, producing an empty bubble (verified in-game). By the
+    // time chat reaches us the escape is usually the doubled `||T` (vanilla's own
+    // neutralization of typed escapes), where `||` is a VALID literal-pipe escape.
+    // So: keep the pipe(s) and blank the `T` when the pipe completes a `||`; blank
+    // BOTH chars for a lone `|T`. Either way no dangling `|` remains, and no `|T`
+    // opener survives for the inline-texture detector to fire on.
+    size_t j = 0;
+    for (size_t i = 0; msg[i] != '\0' && j + 1 < bufSize;) {
+        if (msg[i] == '|' && msg[i + 1] == 'T') {
+            const bool doubledPipe = (i > 0 && msg[i - 1] == '|');
+            buf[j++] = doubledPipe ? '|' : ' '; // keep pipe only if it completes `||`
+            if (j + 1 < bufSize)
+                buf[j++] = ' '; // blank the `T`
+            i += 2;             // consumed `|T`
+        } else {
+            buf[j++] = msg[i++];
+        }
+    }
+    buf[j] = '\0';
+    return buf;
+}
+
+} // namespace Chat::IconFilter
@@ -0,0 +1,28 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <cstddef>
+
+namespace Chat::IconFilter {
+
+// Strips player-injected inline-texture (`|T…|t`) escapes from a chat message.
+// Returns `msg` unchanged when it contains no `|T` (the common case — no copy),
+// otherwise a sanitized copy written into `buf`. Called by Chat::Dispatch on the
+// message the engine's chat handler is about to display. See IconFilter.cpp for
+// the anti-spoof rationale and why sanitizing here (not in the text emitter) is
+// the only place player-typed and addon `|T` are distinguishable.
+const char *Sanitize(const char *msg, char *buf, size_t bufSize);
+
+} // namespace Chat::IconFilter
@@ -0,0 +1,154 @@
+// 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/>.
+
+// Raid-target marker chat substitutions ({rt1}..{rt8} / {star} / {skull} / ...).
+//
+// Modern WoW lets players type `{skull}` (etc.) in chat and everyone sees the
+// raid-target icon. Vanilla 1.12 has no such substitution. We backport it onto
+// the inline-texture (`|T…|t`) renderer: each recognized token is rewritten into
+// a `|T` escape that crops the shared raid-target sprite sheet
+// `Interface\TargetingFrame\UI-RaidTargetingIcons` to the matching 64×64 cell.
+//
+// Runs in Chat::Dispatch AFTER Chat::IconFilter::Sanitize. Order is deliberate:
+// sanitize first defangs any player-typed raw `|T` spoof, then we add ONLY the
+// fixed, known-safe marker escapes — so players get the markers without a path to
+// inject arbitrary textures.
+//
+// Icon→texcoord mapping verified against the client's own UnitPopup.lua
+// (RAID_TARGET_1..8): the sheet is 256×256 with 64-pixel cells, marker N at
+// column (N-1)%4, row (N-1)/4. So RT1(star) is the top-left cell and RT8(skull)
+// is row 1, column 3. The inline renderer's OpenGL v-flip already draws this sheet
+// right-side-up (it's the sheet that flip was verified against), so top<bottom
+// pixel coords render correctly.
+
+#include "RaidMarkers.h"
+
+#include <cstdio>
+#include <cstring>
+
+namespace Chat::RaidMarkers {
+
+namespace {
+
+// On-screen pixel size of an inline marker. The default chat font is ~14px, so 14
+// keeps a marker about one line tall. Fixed (the substitution is a static string
+// rewrite and can't see the target font); tunable here if it reads too small/large.
+constexpr int kMarkerSizePx = 14;
+
+struct Token {
+    const char *name; // lowercase alias, no braces
+    int marker;       // raid-target index 1..8
+};
+
+// Aliases per the modern client, all case-insensitive. `{coin}` is a colloquial
+// alias for `{circle}` (RT2) and `{x}` for `{cross}` (RT7) — both shown in the
+// in-game substitution help.
+constexpr Token kTokens[] = {
+    {"rt1", 1}, {"star", 1},
+    {"rt2", 2}, {"circle", 2}, {"coin", 2},
+    {"rt3", 3}, {"diamond", 3},
+    {"rt4", 4}, {"triangle", 4},
+    {"rt5", 5}, {"moon", 5},
+    {"rt6", 6}, {"square", 6},
+    {"rt7", 7}, {"cross", 7}, {"x", 7},
+    {"rt8", 8}, {"skull", 8},
+};
+
+char LowerAscii(char c) { return (c >= 'A' && c <= 'Z') ? static_cast<char>(c + 32) : c; }
+
+// Case-insensitive match of the n-char token body [s, s+n) against a lowercase
+// literal — true only when `lit` is exactly n chars long.
+bool EqCI(const char *s, size_t n, const char *lit) {
+    for (size_t i = 0; i < n; ++i)
+        if (lit[i] == '\0' || LowerAscii(s[i]) != lit[i])
+            return false;
+    return lit[n] == '\0';
+}
+
+// Raid-target index (1..8) for the token body [name, name+n), or 0 if unknown.
+int MatchMarker(const char *name, size_t n) {
+    for (const Token &t : kTokens)
+        if (EqCI(name, n, t.name))
+            return t.marker;
+    return 0;
+}
+
+bool HasBrace(const char *s) {
+    for (; *s != '\0'; ++s)
+        if (*s == '{')
+            return true;
+    return false;
+}
+
+} // namespace
+
+const char *Substitute(const char *msg, char *buf, size_t bufSize) {
+    if (msg == nullptr || !HasBrace(msg))
+        return msg; // common case: forward untouched, no copy
+
+    // A token inflates ~28x (a 3-char `{rtN}` -> ~85-byte `|T` markup), so a
+    // marker-dense message can exceed `buf`. Never DROP message content to fit:
+    // only expand a token when the expansion AND the whole remaining input (worst
+    // case copied 1:1 as literal text) still fit. Past that point later tokens
+    // stay literal `{rtN}`, so the full message text is always preserved — a DLL
+    // user never sees a shorter line than a non-DLL user, just fewer icons.
+    const size_t msgLen = std::strlen(msg);
+
+    size_t j = 0;
+    for (size_t i = 0; msg[i] != '\0' && j + 1 < bufSize;) {
+        if (msg[i] == '{') {
+            // Scan the token body to the closing brace (bounded — longest alias
+            // is 8 chars, so a `{` with no nearby `}` is just literal text).
+            size_t k = i + 1;
+            while (msg[k] != '\0' && msg[k] != '}' && k - i <= 12)
+                ++k;
+            if (msg[k] == '}') {
+                const int marker = MatchMarker(msg + i + 1, k - (i + 1));
+                if (marker != 0) {
+                    const int col = (marker - 1) % 4;
+                    const int row = (marker - 1) / 4;
+                    const int l = col * 64, r = l + 64, t = row * 64, b = t + 64;
+                    // Emit the pipe-DOUBLED form `||T…||t`. The inline emitter
+                    // renders both `|T` and `||T`, but the vanilla speech-bubble
+                    // text builder (FUN_004b1600) TRUNCATES at a lone `|T` while
+                    // PRESERVING `||` — so the doubled form is what survives into
+                    // the bubble's FontString (which pfUI's bubble reskin copies
+                    // and renders). Anti-spoof Sanitize runs before this, so these
+                    // are the only `||T` openers a player can produce.
+                    char markup[128];
+                    const int m = std::snprintf(
+                        markup, sizeof markup,
+                        "||TInterface\\TargetingFrame\\UI-RaidTargetingIcons:%d:%d:0:0:256:256:"
+                        "%d:%d:%d:%d||t",
+                        kMarkerSizePx, kMarkerSizePx, l, r, t, b);
+                    // Reserve room for the literal tail after this token
+                    // (msg[k+1..]) so the rest of the message always fits.
+                    const size_t tail = msgLen - (k + 1);
+                    if (m > 0 && j + static_cast<size_t>(m) + tail + 1 <= bufSize) {
+                        std::memcpy(buf + j, markup, static_cast<size_t>(m));
+                        j += static_cast<size_t>(m);
+                        i = k + 1; // consume through the closing `}`
+                        continue;
+                    }
+                    // No room for the expansion — fall through and copy the
+                    // literal `{` so the message is never left truncated mid-token.
+                }
+            }
+        }
+        buf[j++] = msg[i++];
+    }
+    buf[j] = '\0';
+    return buf;
+}
+
+} // namespace Chat::RaidMarkers
@@ -0,0 +1,30 @@
+// 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 <cstddef>
+
+namespace Chat::RaidMarkers {
+
+// Expands raid-target marker tokens in a chat message into inline raid-target
+// icon textures — the modern `{rt1}`..`{rt8}` / `{star}` / `{circle}` / `{skull}`
+// (etc.) chat substitutions, backported onto the inline-texture renderer. Returns
+// `msg` unchanged when it contains no `{` (the common case — no copy), otherwise a
+// rewritten copy in `buf`. Called by Chat::Dispatch AFTER the `|T` anti-spoof
+// sanitize, so a player can use the fixed, safe marker icons but still can't
+// inject an arbitrary texture path. See RaidMarkers.cpp for the token table and
+// the icon→texcoord mapping.
+const char *Substitute(const char *msg, char *buf, size_t bufSize);
+
+} // namespace Chat::RaidMarkers
@@ -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);
@@ -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};

@@ -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>
@@ -78,13 +80,12 @@ bool BuildIconPath(uint32_t displayInfoID, char *out, size_t outSize) {
 // readable-text id is non-zero (letters / server-authored notes).
 bool ItemReadable(const uint8_t *item, const uint8_t *record) {
    if (record != nullptr &&
-        *reinterpret_cast<const uint32_t *>(record + Offsets::OFF_ITEMSTATS_PAGE_TEXT) != 0)
+        Game::Read<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;
+           Game::Read<uint32_t>(
+               descriptor, Offsets::OFF_DESCRIPTOR_READABLE_TEXT_ID) != 0;
 }

 int __fastcall Script_C_Container_GetContainerItemInfo(void *L) {
@@ -107,23 +108,22 @@ 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) {
-        stackCount = *reinterpret_cast<const int *>(
-            descriptor + Offsets::OFF_DESCRIPTOR_STACK_COUNT);
-        isBound = (*reinterpret_cast<const uint32_t *>(
-                       descriptor + Offsets::OFF_DESCRIPTOR_FLAGS) &
+        stackCount = Game::Read<int>(
+            descriptor, Offsets::OFF_DESCRIPTOR_STACK_COUNT);
+        isBound = (Game::Read<uint32_t>(
+                       descriptor, Offsets::OFF_DESCRIPTOR_FLAGS) &
                   Offsets::ITEM_FLAG_SOULBOUND) != 0;
    }
-    const bool isLocked = (*reinterpret_cast<const uint32_t *>(
-                               item + Offsets::OFF_ITEM_CLIENT_LOCK) &
+    const bool isLocked = (Game::Read<uint32_t>(
+                               item, Offsets::OFF_ITEM_CLIENT_LOCK) &
                           Offsets::ITEM_CLIENT_LOCK_BIT) != 0;
    const bool isReadable = ItemReadable(item, record);

@@ -135,17 +135,17 @@ int __fastcall Script_C_Container_GetContainerItemInfo(void *L) {
    bool hasLoot = false;
    bool hasNoValue = false;
    if (record != nullptr) {
-        const uint32_t displayInfoID = *reinterpret_cast<const uint32_t *>(
-            record + Offsets::OFF_ITEMSTATS_DISPLAY_INFO_ID);
+        const uint32_t displayInfoID = Game::Read<uint32_t>(
+            record, Offsets::OFF_ITEMSTATS_DISPLAY_INFO_ID);
        haveIcon = BuildIconPath(displayInfoID, iconPath, sizeof(iconPath));
-        quality = *reinterpret_cast<const uint32_t *>(
-            record + Offsets::OFF_ITEMSTATS_QUALITY);
+        quality = Game::Read<uint32_t>(
+            record, Offsets::OFF_ITEMSTATS_QUALITY);
        haveQuality = true;
-        const uint32_t flags = *reinterpret_cast<const uint32_t *>(
-            record + Offsets::OFF_ITEMSTATS_FLAGS);
+        const uint32_t flags = Game::Read<uint32_t>(
+            record, Offsets::OFF_ITEMSTATS_FLAGS);
        hasLoot = (flags & Offsets::ITEM_FLAG_LOOTABLE) != 0;
-        hasNoValue = *reinterpret_cast<const uint32_t *>(
-                         record + Offsets::OFF_ITEMSTATS_SELL_PRICE) == 0;
+        hasNoValue = Game::Read<uint32_t>(
+                         record, Offsets::OFF_ITEMSTATS_SELL_PRICE) == 0;
    }

    const char *hyperlink = Item::Link::FromCGItem(item);
@@ -155,8 +155,8 @@ int __fastcall Script_C_Container_GetContainerItemInfo(void *L) {
    if (Item::Link::NameFromCGItem(item, nameBuf, sizeof(nameBuf))) {
        itemName = nameBuf;
    } else if (record != nullptr) {
-        const char *baseName = *reinterpret_cast<const char *const *>(
-            record + Offsets::OFF_ITEMSTATS_NAME);
+        const char *baseName = Game::Read<const char *>(
+            record, Offsets::OFF_ITEMSTATS_NAME);
        if (baseName != nullptr && baseName[0] != '\0')
            itemName = baseName;
    }
@@ -53,7 +53,9 @@
 #include "Game.h"
 #include "Offsets.h"
 #include "cache/QueryLoad.h"
+#include "creature/Info.h"
 #include "dbc/Lookup.h"
+#include "dbc/Names.h"
 #include "event/Custom.h"

 #include <cstdint>
@@ -93,14 +95,14 @@ int __fastcall Script_GetCreatureInfoByID(void *L) {
    if (rec == nullptr)
        return 0; // not cached -> nil

-    const char *name = *reinterpret_cast<const char *const *>(rec + Offsets::OFF_CREATURE_NAME);
+    const char *name = Game::Read<const char *>(rec, Offsets::OFF_CREATURE_NAME);
    const char *subName =
-        *reinterpret_cast<const char *const *>(rec + Offsets::OFF_CREATURE_SUBNAME);
-    const uint32_t type = *reinterpret_cast<const uint32_t *>(rec + Offsets::OFF_CREATURE_TYPE);
-    const uint32_t family = *reinterpret_cast<const uint32_t *>(rec + Offsets::OFF_CREATURE_FAMILY);
-    const uint32_t rank = *reinterpret_cast<const uint32_t *>(rec + Offsets::OFF_CREATURE_RANK);
+        Game::Read<const char *>(rec, Offsets::OFF_CREATURE_SUBNAME);
+    const uint32_t type = Game::Read<uint32_t>(rec, Offsets::OFF_CREATURE_TYPE);
+    const uint32_t family = Game::Read<uint32_t>(rec, Offsets::OFF_CREATURE_FAMILY);
+    const uint32_t rank = Game::Read<uint32_t>(rec, Offsets::OFF_CREATURE_RANK);
    const uint32_t displayID =
-        *reinterpret_cast<const uint32_t *>(rec + Offsets::OFF_CREATURE_DISPLAYID);
+        Game::Read<uint32_t>(rec, Offsets::OFF_CREATURE_DISPLAYID);

    Game::Lua::NewTable(L);
    Game::Lua::SetFieldNumber(L, "creatureID", creatureID);
@@ -143,17 +145,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 +164,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 ""
@@ -225,7 +213,7 @@ int __fastcall Script_GetCreatureFamilyIDs(void *L) {
    Game::Lua::NewTable(L);

    const int count =
-        *reinterpret_cast<const int *>(Offsets::VAR_CREATUREFAMILY_COUNT);
+        Game::Read<int>(Offsets::VAR_CREATUREFAMILY_COUNT);
    int n = 0;
    for (int id = 1; id <= count; ++id) {
        const char *name = DBC::LocalizedField(Offsets::VAR_CREATUREFAMILY_RECORDS,
@@ -262,8 +250,8 @@ int __fastcall Script_GetFactionInfo(void *L) {
                                       static_cast<uint32_t>(raceID));
    if (crRec == nullptr)
        return 0; // unknown race
-    const int ftId = *reinterpret_cast<const int *>(
-        crRec + Offsets::OFF_CHRRACES_FACTION_TEMPLATE);
+    const int ftId = Game::Read<int>(
+        crRec, Offsets::OFF_CHRRACES_FACTION_TEMPLATE);
    if (ftId <= 0)
        return 0;

@@ -272,31 +260,31 @@ int __fastcall Script_GetFactionInfo(void *L) {
                                       static_cast<uint32_t>(ftId));
    if (ftRec == nullptr)
        return 0;
-    const uint32_t mask = *reinterpret_cast<const uint32_t *>(
-        ftRec + Offsets::OFF_FACTIONTEMPLATE_GROUP_MASK);
+    const uint32_t mask = Game::Read<uint32_t>(
+        ftRec, Offsets::OFF_FACTIONTEMPLATE_GROUP_MASK);

    // FactionGroup is stored contiguously (records-base + i*stride), not as a
    // pointer array — iterate by hand rather than via DBC::Record.
-    auto *fgBase = *reinterpret_cast<const uint8_t *const *>(
+    auto *fgBase = Game::Read<const uint8_t *>(
        Offsets::VAR_FACTIONGROUP_RECORDS);
    const int fgCount =
-        *reinterpret_cast<const int *>(Offsets::VAR_FACTIONGROUP_COUNT);
-    const int locale = *reinterpret_cast<const int *>(Offsets::VAR_LOCALE_INDEX);
+        Game::Read<int>(Offsets::VAR_FACTIONGROUP_COUNT);
+    const int locale = Game::Read<int>(Offsets::VAR_LOCALE_INDEX);
    if (fgBase == nullptr)
        return 0;

    for (int i = 0; i < fgCount; ++i) {
        const uint8_t *row = fgBase + i * Offsets::FACTIONGROUP_STRIDE;
-        const int bit = *reinterpret_cast<const int *>(
-            row + Offsets::OFF_FACTIONGROUP_BIT);
+        const int bit = Game::Read<int>(
+            row, Offsets::OFF_FACTIONGROUP_BIT);
        if ((mask & (1u << (bit & 0x1F))) == 0)
            continue;
-        const char *loc = *reinterpret_cast<const char *const *>(
-            row + Offsets::OFF_FACTIONGROUP_NAMES + locale * 4);
+        const char *loc = Game::Read<const char *>(
+            row, Offsets::OFF_FACTIONGROUP_NAMES + locale * 4);
        if (loc == nullptr || *loc == '\0')
            continue; // "Player" / "Monster" have empty localized names
-        const char *eng = *reinterpret_cast<const char *const *>(
-            row + Offsets::OFF_FACTIONGROUP_ENGLISH);
+        const char *eng = Game::Read<const char *>(
+            row, Offsets::OFF_FACTIONGROUP_ENGLISH);

        Game::Lua::NewTable(L);
        Game::Lua::SetFieldString(L, "name", loc);
@@ -336,7 +324,7 @@ int __fastcall Script_GetCreatureTypeIDs(void *L) {
    Game::Lua::NewTable(L);

    const int count =
-        *reinterpret_cast<const int *>(Offsets::VAR_CREATURETYPE_COUNT);
+        Game::Read<int>(Offsets::VAR_CREATURETYPE_COUNT);
    int n = 0;
    for (int id = 1; id <= count; ++id) {
        const char *name = DBC::LocalizedField(Offsets::VAR_CREATURETYPE_RECORDS,
@@ -380,4 +368,15 @@ const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};

 } // namespace

+// Public accessor for Model::DisplayInfo's SetCreature — the same peek
+// GetCreatureInfoByID uses, reduced to the display-ID field. 0 = uncached.
+uint32_t DisplayID(uint32_t creatureID) {
+    if (creatureID == 0)
+        return 0;
+    const uint8_t *rec = PeekCreature(creatureID);
+    if (rec == nullptr)
+        return 0;
+    return Game::Read<uint32_t>(rec, Offsets::OFF_CREATURE_DISPLAYID);
+}
+
 } // namespace Creature::Info
@@ -0,0 +1,27 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <cstdint>
+
+namespace Creature::Info {
+
+// The cached model display ID for a creature/NPC entry, or 0 when the creature
+// is not in the client creature cache (creaturecache.wdb, or queried this
+// session). A synchronous peek — no network query. Backs `Model:SetCreature`:
+// the cache being keyed by entry ID and carrying a display ID is exactly the
+// entry-ID → model mapping vanilla has no DBC for.
+uint32_t DisplayID(uint32_t creatureID);
+
+} // namespace Creature::Info
@@ -0,0 +1,144 @@
+// 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/>.
+
+// `GetCoinTextureString` / `C_CurrencyInfo.GetCoinTextureString` — the coin-icon
+// money string (e.g. "12<gold> 34<silver> 56<copper>"), a C++ backport of the
+// retail C function.
+//
+// Behaviour derived from 3.3.5's `Script_GetCoinTextureString` (FUN_00510d00 →
+// formatter FUN_007e7e10): split the copper amount into gold / silver / copper,
+// emit only the non-zero denominations in that order, space-separated; a zero
+// amount shows "0" copper. Each denomination is built from a localized
+// GlobalString — `GOLD_AMOUNT_TEXTURE` / `SILVER_AMOUNT_TEXTURE` /
+// `COPPER_AMOUNT_TEXTURE` — exactly as the engine does (its formatter
+// `FUN_0076f070` is a C-format over the same GlobalString). Those strings don't
+// exist in stock 1.12, so they're backported in `locales/enUS.lua`
+// (language-independent, so the enUS base covers every locale); the embedded
+// `!!!ClassicAPI` addon guarantees they're loaded.
+//
+// 1.12 has no separate UI-GoldIcon / UI-SilverIcon / UI-CopperIcon textures
+// (those are a later-expansion split); vanilla uses ONE sprite sheet
+// `Interface\MoneyFrame\UI-MoneyIcons` cropped per coin (gold 0-0.25, silver
+// 0.25-0.5, copper 0.5-0.75 across a 4-cell strip — from CoinPickupFrame.xml).
+// So the format carries the inline-texture texcoord fields (texW=4 texH=1, then
+// the per-coin left:right cell). The `|T` markup renders as real coin icons via
+// ClassicAPI's inline-texture backport (`Text::InlineTexture`).
+
+#include "Game.h"
+
+#include <cstdio>
+#include <string>
+
+namespace Currency::CoinText {
+
+namespace {
+
+// Icon size. Retail defaults fontHeight to 0 = "use the display font's height",
+// and the inline-texture renderer now honours 0 (it resolves the coin to the
+// line's font height at draw time), so coins match the surrounding text instead
+// of a fixed size. Callers may still pass an explicit height.
+constexpr int kDefaultHeight = 0;
+
+// Fallbacks byte-identical to the backported GlobalStrings, used only if the
+// locale layer somehow isn't loaded when this is first called.
+// Format: count |T sheet : height=0 : width=0 : offsetX=0 : offsetY=0 : texW=4 :
+// texH=1 : left : right : top=0 : bottom=1 |t  (left:right selects the coin cell).
+// height/width 0 = size to the font. offsetX stays 0: the inline-texture
+// renderer's font-relative pad spaces the coin from its digits (the historical
+// "coin sits on the digit" bug was the emitter's lazy pen read-back, fixed in
+// the DLL). Never grow a per-coin offset here.
+constexpr const char *kGoldFallback =
+    "%d|TInterface\\MoneyFrame\\UI-MoneyIcons:%d:%d:0:0:4:1:0:1:0:1|t";
+constexpr const char *kSilverFallback =
+    "%d|TInterface\\MoneyFrame\\UI-MoneyIcons:%d:%d:0:0:4:1:1:2:0:1|t";
+// The three coin arts occupy IDENTICAL pixels within their sheet cells (x 0-14,
+// y 1-14 of 16 — confirmed by decoding the DXT3 alpha of the exported
+// UI-MoneyIcons.blp); only the left:right cell select differs (gold 0:1,
+// silver 1:2, copper 2:3).
+constexpr const char *kCopperFallback =
+    "%d|TInterface\\MoneyFrame\\UI-MoneyIcons:%d:%d:0:0:4:1:2:3:0:1|t";
+
+// Formats one denomination from its localized GlobalString and appends it to
+// `out`. Reads `_G[globalName]` the way retail reads the coin GlobalStrings; the
+// format consumes (count, iconHeight, iconWidth). No separator between
+// denominations — the renderer's symmetric per-icon pad already spaces each coin
+// from the surrounding digits, so a space here would double the gap.
+void AppendDenom(void *L, std::string &out, const char *globalName, const char *fallback,
+                 int count, int height) {
+    const int top = Game::Lua::GetTop(L);
+    Game::Lua::PushLocalizedString(L, globalName, fallback); // [.., fmt]
+    const char *fmt = Game::Lua::ToString(L, -1);
+    char piece[256];
+    piece[0] = '\0';
+    if (fmt != nullptr)
+        std::snprintf(piece, sizeof piece, fmt, count, height, height);
+    Game::Lua::SetTop(L, top); // pop the format string
+    out += piece;
+}
+
+// GetCoinTextureString(amount [, fontHeight]) -> string
+int __fastcall Script_GetCoinTextureString(void *L) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, "Usage: GetCoinTextureString(amount [, fontHeight])");
+        return 0; // unreachable — Error long-jumps
+    }
+    const double amt = Game::Lua::ToNumber(L, 1);
+    long long amount = static_cast<long long>(amt < 0.0 ? amt - 0.5 : amt + 0.5); // round
+    if (amount < 0)
+        amount = 0;
+    // Vanilla money is a uint32 copper field, so 0xFFFFFFFF copper (~429,496
+    // gold) is the most the game can represent. Clamp to it: an unclamped huge
+    // input (e.g. 1e15) makes `gold` exceed INT_MAX, and the cast below truncates
+    // it to the low 32 bits, printing a garbage count through the "%d" format.
+    constexpr long long kMaxCopper = 0xFFFFFFFFLL;
+    if (amount > kMaxCopper)
+        amount = kMaxCopper;
+
+    int height = kDefaultHeight;
+    if (Game::Lua::IsNumber(L, 2)) {
+        const int h = static_cast<int>(Game::Lua::ToNumber(L, 2));
+        if (h > 0)
+            height = h;
+    }
+
+    const int gold = static_cast<int>(amount / 10000);
+    const int silver = static_cast<int>((amount % 10000) / 100);
+    const int copper = static_cast<int>(amount % 100);
+
+    std::string out;
+    if (amount == 0) {
+        AppendDenom(L, out, "COPPER_AMOUNT_TEXTURE", kCopperFallback, 0, height);
+    } else {
+        if (gold > 0)
+            AppendDenom(L, out, "GOLD_AMOUNT_TEXTURE", kGoldFallback, gold, height);
+        if (silver > 0)
+            AppendDenom(L, out, "SILVER_AMOUNT_TEXTURE", kSilverFallback, silver, height);
+        if (copper > 0)
+            AppendDenom(L, out, "COPPER_AMOUNT_TEXTURE", kCopperFallback, copper, height);
+    }
+
+    Game::Lua::PushString(L, out.c_str());
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterGlobalFunction("GetCoinTextureString", &Script_GetCoinTextureString);
+    Game::Lua::RegisterTableFunction("C_CurrencyInfo", "GetCoinTextureString",
+                                     &Script_GetCoinTextureString);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace Currency::CoinText
@@ -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);
@@ -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
@@ -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
@@ -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));
 }

@@ -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 *>(
@@ -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 =
@@ -13,6 +13,7 @@

 #include "Storage.h"

+#include "Game.h"
 #include "Offsets.h"

 #include <cstdint>
@@ -25,7 +26,7 @@ namespace EquipmentSet::Storage {
 namespace {

 const char *ReadAccountName() {
-    return *reinterpret_cast<const char *const *>(Offsets::VAR_ACCOUNT_NAME_PTR);
+    return Game::Read<const char *>(Offsets::VAR_ACCOUNT_NAME_PTR);
 }

 const char *ReadCharacterName() {
@@ -34,10 +35,10 @@ const char *ReadCharacterName() {
 }

 const char *ReadRealmName() {
-    auto *info = *reinterpret_cast<uint8_t **>(Offsets::VAR_REALM_INFO_PTR);
+    auto *info = Game::Read<uint8_t *>(Offsets::VAR_REALM_INFO_PTR);
    if (info == nullptr)
        return nullptr;
-    return *reinterpret_cast<const char *const *>(info + Offsets::OFF_REALM_INFO_NAME);
+    return Game::Read<const char *>(info, Offsets::OFF_REALM_INFO_NAME);
 }

 // Removes trailing CR/LF/whitespace. Names from the engine are ASCII
@@ -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,13 +205,13 @@ int __fastcall Script_GameTooltipSetEquipmentSet(void *L) {
            unnamedMissing++;
            continue;
        }
-        auto *record = PeekItemRecord(id);
+        auto *record = Item::PeekRecord(id);
        if (record == nullptr) {
            unnamedMissing++;
            continue;
        }
-        const char *name = *reinterpret_cast<const char *const *>(
-            record + Offsets::OFF_ITEMSTATS_NAME);
+        const char *name = Game::Read<const char *>(
+            record, Offsets::OFF_ITEMSTATS_NAME);
        if (name == nullptr || name[0] == '\0') {
            unnamedMissing++;
            continue;
@@ -112,13 +112,13 @@ void SMemFree(void *ptr) {
 int TryClaim(const char *eventName) {
    if (!g_writesEnabled)
        return -1;
-    auto *base = *reinterpret_cast<uint8_t **>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
-    const int count = *reinterpret_cast<int *>(Offsets::VAR_EVENT_TABLE_COUNT);
+    auto *base = Game::Read<uint8_t *>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
+    const int count = Game::Read<int>(Offsets::VAR_EVENT_TABLE_COUNT);
    if (base == nullptr || count <= 0)
        return -1;
    for (int i = 0; i < count; ++i) {
-        auto **namePtr = reinterpret_cast<const char **>(
-            base + i * Offsets::EVENT_ENTRY_STRIDE +
+        auto **namePtr = Game::Ptr<const char *>(
+            base + i * Offsets::EVENT_ENTRY_STRIDE,
            Offsets::OFF_EVENT_ENTRY_NAME);
        if (*namePtr == nullptr) {
            char *copy = SStrDup(eventName);
@@ -169,15 +169,15 @@ void Grow() {
        return;
    g_growLatched = true; // one attempt per build, whether or not it grows

-    const int count = *reinterpret_cast<int *>(Offsets::VAR_EVENT_TABLE_COUNT);
-    auto *base = *reinterpret_cast<uint8_t **>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
+    const int count = Game::Read<int>(Offsets::VAR_EVENT_TABLE_COUNT);
+    auto *base = Game::Read<uint8_t *>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
    if (base == nullptr || count <= 0 || g_reservedCount <= 0)
        return;

    int nulls = 0;
    for (int i = 0; i < count; ++i)
-        if (*reinterpret_cast<const char *const *>(
-                base + i * Offsets::EVENT_ENTRY_STRIDE +
+        if (Game::Read<const char *>(
+                base + i * Offsets::EVENT_ENTRY_STRIDE,
                Offsets::OFF_EVENT_ENTRY_NAME) == nullptr)
            ++nulls;

@@ -193,8 +193,8 @@ void Grow() {
    // moving the buffer would corrupt their subscription). Abort if so and
    // fall back to claim-NULL.
    for (int i = 0; i < count; ++i) {
-        const uint32_t head = *reinterpret_cast<const uint32_t *>(
-            base + i * Offsets::EVENT_ENTRY_STRIDE + Offsets::OFF_EVENT_ENTRY_HEAD);
+        const uint32_t head = Game::Read<uint32_t>(
+            base + i * Offsets::EVENT_ENTRY_STRIDE, Offsets::OFF_EVENT_ENTRY_HEAD);
        if (head != 0 && (head & 1) == 0) { // populated chain (not 0 / sentinel)
            Debug::Log::Printf(
                "[event] grow aborted — chain live at slot %d (not first-reg)", i);
@@ -231,9 +231,9 @@ void Grow() {
    // Publish base BEFORE count so the globals never advertise more entries
    // than the buffer holds. Then free the OLD buffer only — the name
    // strings live on in newBuf and are freed by the reload teardown.
-    *reinterpret_cast<uint8_t **>(Offsets::VAR_EVENT_TABLE_BASE_PTR) = newBuf;
-    *reinterpret_cast<int *>(Offsets::VAR_EVENT_TABLE_CAP) = newCount;
-    *reinterpret_cast<int *>(Offsets::VAR_EVENT_TABLE_COUNT) = newCount;
+    Game::Ref<uint8_t *>(Offsets::VAR_EVENT_TABLE_BASE_PTR) = newBuf;
+    Game::Ref<int>(Offsets::VAR_EVENT_TABLE_CAP) = newCount;
+    Game::Ref<int>(Offsets::VAR_EVENT_TABLE_COUNT) = newCount;
    SMemFree(base);

    Debug::Log::Printf("[event] grew table %d -> %d (%d NULL, %d reserved%s)",
@@ -268,13 +268,13 @@ int Lookup(const char *name) {
 int LookupByName(const char *name) {
    if (name == nullptr)
        return -1;
-    auto *base = *reinterpret_cast<uint8_t **>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
-    const int count = *reinterpret_cast<int *>(Offsets::VAR_EVENT_TABLE_COUNT);
+    auto *base = Game::Read<uint8_t *>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
+    const int count = Game::Read<int>(Offsets::VAR_EVENT_TABLE_COUNT);
    if (base == nullptr || count <= 0)
        return -1;
    for (int i = 0; i < count; ++i) {
-        const char *entryName = *reinterpret_cast<const char *const *>(
-            base + i * Offsets::EVENT_ENTRY_STRIDE +
+        const char *entryName = Game::Read<const char *>(
+            base + i * Offsets::EVENT_ENTRY_STRIDE,
            Offsets::OFF_EVENT_ENTRY_NAME);
        if (entryName != nullptr && std::strcmp(entryName, name) == 0)
            return i;
@@ -285,16 +285,16 @@ int LookupByName(const char *name) {
 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);
+    auto *base = Game::Read<uint8_t *>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
+    const int count = Game::Read<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);
+    const uint32_t head = Game::Read<uint32_t>(
+        base + slot * Offsets::EVENT_ENTRY_STRIDE, Offsets::OFF_EVENT_ENTRY_HEAD);
    return head != 0 && (head & 1) == 0;
 }

@@ -330,12 +330,12 @@ int __fastcall Script_DumpSlot(void *L) {
        return 0;
    }
    const int slot = static_cast<int>(Game::Lua::ToNumber(L, 1));
-    auto *base = *reinterpret_cast<uint8_t **>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
-    const int count = *reinterpret_cast<int *>(Offsets::VAR_EVENT_TABLE_COUNT);
+    auto *base = Game::Read<uint8_t *>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
+    const int count = Game::Read<int>(Offsets::VAR_EVENT_TABLE_COUNT);
    const char *name = nullptr;
    if (base != nullptr && slot >= 0 && slot < count) {
-        name = *reinterpret_cast<const char *const *>(
-            base + slot * Offsets::EVENT_ENTRY_STRIDE +
+        name = Game::Read<const char *>(
+            base + slot * Offsets::EVENT_ENTRY_STRIDE,
            Offsets::OFF_EVENT_ENTRY_NAME);
    }
    Debug::Log::Printf("[dumpslot] base=0x%08X count=%d slot=%d name='%s'",
@@ -345,16 +345,16 @@ int __fastcall Script_DumpSlot(void *L) {
 }

 int __fastcall Script_DumpAllEvents(void *) {
-    auto *base = *reinterpret_cast<uint8_t **>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
-    const int count = *reinterpret_cast<int *>(Offsets::VAR_EVENT_TABLE_COUNT);
+    auto *base = Game::Read<uint8_t *>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
+    const int count = Game::Read<int>(Offsets::VAR_EVENT_TABLE_COUNT);
    Debug::Log::Printf("[dumpall] base=0x%08X count=%d",
                       static_cast<unsigned>(reinterpret_cast<uintptr_t>(base)),
                       count);
    if (base == nullptr)
        return 0;
    for (int i = 0; i < count; ++i) {
-        const char *name = *reinterpret_cast<const char *const *>(
-            base + i * Offsets::EVENT_ENTRY_STRIDE +
+        const char *name = Game::Read<const char *>(
+            base + i * Offsets::EVENT_ENTRY_STRIDE,
            Offsets::OFF_EVENT_ENTRY_NAME);
        if (name != nullptr && *name != '\0')
            Debug::Log::Printf("[%d] %s", i, name);
@@ -50,22 +50,20 @@ int __fastcall Script_GetFramesRegisteredForEvent(void *L) {
    if (slot < 0)
        return 0;

-    auto *base = *reinterpret_cast<uint8_t **>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
+    auto *base = Game::Read<uint8_t *>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
    if (base == nullptr)
        return 0;

    const uint8_t *entry = base + slot * Offsets::EVENT_ENTRY_STRIDE;
-    const uintptr_t head = *reinterpret_cast<const uintptr_t *>(
-        entry + Offsets::OFF_EVENT_ENTRY_HEAD);
+    const uintptr_t head = Game::Read<uintptr_t>(entry, Offsets::OFF_EVENT_ENTRY_HEAD);

    // First pass: count subscribers so we can reserve stack up front — an
    // event with many registered frames would otherwise risk overflowing
    // the default Lua stack slack as we push.
    int count = 0;
    for (uintptr_t node = head; (node & 1) == 0 && node != 0;
-         node = *reinterpret_cast<const uintptr_t *>(
-             node + Offsets::OFF_EVENT_NODE_NEXT)) {
-        if (*reinterpret_cast<void *const *>(node + Offsets::OFF_EVENT_NODE_FRAME))
+         node = Game::Read<uintptr_t>(node + Offsets::OFF_EVENT_NODE_NEXT)) {
+        if (Game::Read<void *>(node + Offsets::OFF_EVENT_NODE_FRAME))
            ++count;
    }
    if (count == 0)
@@ -74,10 +72,8 @@ int __fastcall Script_GetFramesRegisteredForEvent(void *L) {

    int pushed = 0;
    for (uintptr_t node = head; (node & 1) == 0 && node != 0;
-         node = *reinterpret_cast<const uintptr_t *>(
-             node + Offsets::OFF_EVENT_NODE_NEXT)) {
-        void *frame = *reinterpret_cast<void *const *>(
-            node + Offsets::OFF_EVENT_NODE_FRAME);
+         node = Game::Read<uintptr_t>(node + Offsets::OFF_EVENT_NODE_NEXT)) {
+        void *frame = Game::Read<void *>(node + Offsets::OFF_EVENT_NODE_FRAME);
        if (frame != nullptr) {
            UI::FrameObject::Push(L, frame);
            ++pushed;
@@ -0,0 +1,409 @@
+// 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.
+
+// FontString metric backports.
+//
+// 1.12's FontString method table (32 entries at 0x0087C1D8, registry context
+// VAR_FONTSTRING_METHOD_REGISTRY) ships GetStringWidth but none of the later
+// metric bindings. The engine already has every internal getter — these are
+// the thin Lua bindings Blizzard never wrote for 1.12:
+//
+//   GetStringHeight()         — 2.3.0 binding; internal getter
+//                               FUN_FONTSTRING_STRING_HEIGHT (wrap-aware,
+//                               lines×fontH + (lines−1)×spacing, cache
+//                               fs+0x100, 0 for empty text).
+//   GetUnboundedStringWidth() — the substring measure with the WHOLE string
+//                               (FUN_FONTSTRING_MEASURE_SUBSTRING, len 0 =
+//                               strlen): the string's width with no wrap cap.
+//                               Icon-aware for free — the call routes through
+//                               text/InlineTexture.cpp's co-hook.
+//   GetWrappedWidth()         — the RENDERED width: the widest wrapped line
+//                               (the tooltip auto-size's own recipe — break
+//                               array + per-segment substring measures).
+//   GetNumLines()             — the node's built line count (render truth,
+//                               OFF_TEXT_NODE_BUILT_LINES) once painted; for
+//                               an unbuilt node, the engine's own break-array
+//                               computer (FUN_FONTSTRING_BREAK_ARRAY — also
+//                               icon-aware via the wrap-stepper co-hook).
+//   GetLineHeight()           — the fs font height via the same getter the
+//                               rebuild feeds the text node (FUN_007727b0);
+//                               excludes spacing, like retail (GetSpacing is
+//                               its own method).
+//   IsTruncated()             — did the engine cut the text off with an
+//                               ellipsis? Reads the render's own output: the
+//                               built text node's copy of the laid-out string
+//                               (OFF_TEXT_NODE_TEXT) vs the source. Same
+//                               "displayed vs full" comparison retail does; no
+//                               reconstruction of the fit/wrap/maxLines logic.
+//                               Reflects the last rendered layout (the display-
+//                               text resolver's rect is zero until a render, so
+//                               a Lua-time re-call cannot see the bound).
+//   SetMaxLines(n)/GetMaxLines() — cap the fontstring to n wrapped lines; text
+//                               past the cap is ellipsized. Writes the engine's
+//                               own per-fontstring maxLines field (fs+0x128,
+//                               already honored by the truncation resolver) and
+//                               re-invalidates the layout like SetText does.
+//                               1.12 has no SetWordWrap, so SetMaxLines(1) is
+//                               how you get a single-line, ellipsized label.
+//   SetFormattedText(fmt,...) — string.format + SetText convenience. The format
+//                               runs through the engine's OWN str_format C
+//                               function (FUN_LUA_STR_FORMAT) under pcall — NOT
+//                               _G.string.format, so an addon replacing
+//                               string.format can't hijack it (matches retail).
+//                               The set goes through FUN_FONTSTRING_SET_TEXT,
+//                               keeping the sanitizer/pipe handling identical to
+//                               SetText.
+//
+// Push conversion mirrors Script_GetStringWidth (0x0079E510): resolve self,
+// call the internal getter, convert anchor units → UI pixels, push.
+//
+// No inline-icon adjustment lives HERE: the width/height internal getters are
+// already icon-adjusted by their co-hooks (calling the hooked VA routes
+// through the detour), and icons never change GetLineHeight.
+
+#include "Game.h"
+#include "Offsets.h"
+
+#include <cstdint>
+#include <cstring>
+
+namespace FontString::Metrics {
+namespace {
+
+// FUN_FONTSTRING_STRING_HEIGHT — ECX = fs, no stack args, float in x87 ST0.
+using StringHeightInternal_t = float(__fastcall *)(void *fs);
+// FUN_FONTSTRING_MEASURE_SUBSTRING — __thiscall(fs, text, len); dummy-EDX form.
+using MeasureSubstring_t = float(__fastcall *)(void *fs, void *edx, const char *text, int len);
+// FUN_FONTSTRING_FONT_HEIGHT — __thiscall(fs, mode-on-stack); dummy-EDX form.
+using FsFontHeight_t = float(__fastcall *)(void *fs, void *edx, int mode);
+// FUN_FONTSTRING_BREAK_ARRAY — __thiscall(fs, text, wrapWidth, outBreaks, cap).
+using BreakArray_t = uint32_t(__fastcall *)(void *fs, void *edx, const char *text, float width,
+                                            int *outBreaks, int cap);
+// FUN_FONTSTRING_SET_TEXT — __thiscall(fs, text, flag = 0); dummy-EDX form.
+using FsSetText_t = void(__fastcall *)(void *fs, void *edx, const char *text, int flag);
+// FUN_HANDLE_RELEASE — DecRef a ref-counted handle. __fastcall(handle).
+using HandleRelease_t = void(__fastcall *)(void *handle);
+// FUN_FONTSTRING_LAYOUT_INVALIDATE — region layout invalidate. __thiscall(region,
+// int); dummy-EDX form.
+using LayoutInvalidate_t = void(__fastcall *)(void *region, void *edx, int arg);
+
+// Invalidate a fontstring's layout exactly as SetText (FUN_00771D80) does after
+// a content change, so a layout-affecting property change (max lines) takes
+// effect on the next draw: drop the cached measures, release the built node,
+// clear the layout-dirty bit, and notify the region to re-lay-out. Re-calling
+// SetText would NOT work — it early-outs when the text string is unchanged.
+void InvalidateLayout(void *fs) {
+    Game::Ref<float>(fs, Offsets::OFF_FONTSTRING_WIDTH_CACHE) = 0.0f;
+    Game::Ref<float>(fs, Offsets::OFF_FONTSTRING_HEIGHT_CACHE) = 0.0f;
+    void *block = Game::Read<void *>(fs, Offsets::OFF_FONTSTRING_TEXT_BLOCK);
+    if (block != nullptr) {
+        reinterpret_cast<HandleRelease_t>(Offsets::FUN_HANDLE_RELEASE)(block);
+        Game::Ref<void *>(fs, Offsets::OFF_FONTSTRING_TEXT_BLOCK) = nullptr;
+    }
+    Game::Ref<uint32_t>(fs, Offsets::OFF_FONTSTRING_DIRTY_FLAGS) &= ~1u;
+    void *region = reinterpret_cast<void *>(reinterpret_cast<uintptr_t>(fs) + 0x24);
+    reinterpret_cast<LayoutInvalidate_t>(Offsets::FUN_FONTSTRING_LAYOUT_INVALIDATE)(
+        region, nullptr, 0);
+}
+
+// Anchor units → UI pixels: `FUN_0041AE40(FUN_0041AD70() × DAT_007FFD68 × v)`
+// = v × [VAR_UI_COORD_SCALE_DIV] × 1024 / [VAR_UI_COORD_SCALE_MUL] — the exact
+// push chain Script_GetStringWidth uses (the inverse of
+// Tooltip::LinePool::PixelToInternal).
+double InternalToPixel(float v) {
+    const float mul = Game::Read<float>(Offsets::VAR_UI_COORD_SCALE_MUL);
+    const float div = Game::Read<float>(Offsets::VAR_UI_COORD_SCALE_DIV);
+    if (mul == 0.0f)
+        return 0.0;
+    return static_cast<double>(v) * div * Offsets::UI_COORD_SCALE_UNIT / mul;
+}
+
+// The fs's wrap budget in the units FUN_FONTSTRING_BREAK_ARRAY expects
+// (width-getter units — it multiplies by fs+0x7C itself before gxu, verified
+// decompile), or 0 when the rect is unresolved. rectWidth ÷ scale, calibrated
+// EMPIRICALLY against the render with a three-point probe (a 100px box at
+// scale ~0.91, text whose candidate lines measure 78.1 / 94.6 / 101.6px):
+//   raw rectW      → effective budget ~91px  → broke one word EARLY,
+//   rectW/scale²   → effective budget ~110px → broke one word LATE,
+//   rectW/scale    → effective budget 100px  → breaks exactly where the
+//                    render does (94.6 ≤ 100 < 101.6).
+// All three observations fit budget_px = pxOf(param) × scale, pinning the
+// single ÷scale. (A pure paper derivation from the rebuild's node budget
+// predicted /scale² — one hop of that chain models the live behaviour wrong;
+// the probe is the arbiter.)
+float WrapBudget(void *fs) {
+    const float *rc = Game::Ptr<const float>(fs, Offsets::OFF_REGION_RECT);
+    float width = (rc[3] > rc[1]) ? (rc[3] - rc[1]) : (rc[1] - rc[3]);
+    const float s = Game::Read<float>(fs, Offsets::OFF_LAYOUT_SCALE);
+    if (width > 0.0f && s > 0.0f)
+        width /= s;
+    return width;
+}
+
+// Shared self-resolve for every method here.
+void *ResolveSelf(void *L, const char *usage) {
+    void *fs = nullptr;
+    if (Game::Lua::Type(L, 1) == Game::Lua::TYPE_TABLE)
+        fs = Game::Lua::ResolveObject(L, 1);
+    if (fs == nullptr)
+        Game::Lua::Error(L, "%s", usage);
+    return fs;
+}
+
+int __fastcall Script_GetStringHeight(void *L) {
+    void *fs = ResolveSelf(L, "Usage: fontstring:GetStringHeight()");
+    if (fs == nullptr)
+        return 0;
+    const float h = reinterpret_cast<StringHeightInternal_t>(
+        Offsets::FUN_FONTSTRING_STRING_HEIGHT)(fs);
+    Game::Lua::PushNumber(L, InternalToPixel(h));
+    return 1;
+}
+
+int __fastcall Script_GetUnboundedStringWidth(void *L) {
+    void *fs = ResolveSelf(L, "Usage: fontstring:GetUnboundedStringWidth()");
+    if (fs == nullptr)
+        return 0;
+    const char *text = Game::Read<const char *>(fs, Offsets::OFF_FONTSTRING_TEXT);
+    if (text == nullptr || *text == '\0') {
+        Game::Lua::PushNumber(L, 0.0);
+        return 1;
+    }
+    const float w = reinterpret_cast<MeasureSubstring_t>(
+        Offsets::FUN_FONTSTRING_MEASURE_SUBSTRING)(fs, nullptr, text, 0);
+    Game::Lua::PushNumber(L, InternalToPixel(w));
+    return 1;
+}
+
+int __fastcall Script_GetNumLines(void *L) {
+    void *fs = ResolveSelf(L, "Usage: fontstring:GetNumLines()");
+    if (fs == nullptr)
+        return 0;
+    const char *text = Game::Read<const char *>(fs, Offsets::OFF_FONTSTRING_TEXT);
+    if (text == nullptr || *text == '\0') {
+        Game::Lua::PushNumber(L, 0.0);
+        return 1;
+    }
+    // Render truth first: the built node's line count. Zero until the node
+    // paints once (hidden fs, mid-rebuild) — fall back below.
+    void *block = Game::Read<void *>(fs, Offsets::OFF_FONTSTRING_TEXT_BLOCK);
+    if (block != nullptr) {
+        void *node = Game::Read<void *>(block, Offsets::OFF_TEXTBLOCK_NODE);
+        if (node != nullptr) {
+            const int built = Game::Read<int>(node, Offsets::OFF_TEXT_NODE_BUILT_LINES);
+            if (built > 0) {
+                Game::Lua::PushNumber(L, static_cast<double>(built));
+                return 1;
+            }
+        }
+    }
+    // Unbuilt: the engine's own break-array computer, fed the fs's wrap
+    // budget (see WrapBudget's scale note). An unresolved rect (0 width)
+    // means no wrap constraint exists yet — one line, like a fresh
+    // single-anchor fs.
+    const float width = WrapBudget(fs);
+    if (width <= 0.0f) {
+        Game::Lua::PushNumber(L, 1.0);
+        return 1;
+    }
+    int breaks[64];
+    uint32_t lines = reinterpret_cast<BreakArray_t>(Offsets::FUN_FONTSTRING_BREAK_ARRAY)(
+        fs, nullptr, text, width, breaks, 64);
+    if (lines > 64u)
+        lines = 64u;
+    if (lines == 0u)
+        lines = 1u;
+    Game::Lua::PushNumber(L, static_cast<double>(lines));
+    return 1;
+}
+
+int __fastcall Script_GetWrappedWidth(void *L) {
+    void *fs = ResolveSelf(L, "Usage: fontstring:GetWrappedWidth()");
+    if (fs == nullptr)
+        return 0;
+    const char *text = Game::Read<const char *>(fs, Offsets::OFF_FONTSTRING_TEXT);
+    if (text == nullptr || *text == '\0') {
+        Game::Lua::PushNumber(L, 0.0);
+        return 1;
+    }
+    auto measure =
+        reinterpret_cast<MeasureSubstring_t>(Offsets::FUN_FONTSTRING_MEASURE_SUBSTRING);
+    // The fs's wrap budget (see WrapBudget's scale note). Without one
+    // (unresolved rect) nothing wraps, and the rendered width IS the
+    // one-line width.
+    const float budget = WrapBudget(fs);
+    if (budget <= 0.0f) {
+        Game::Lua::PushNumber(L, InternalToPixel(measure(fs, nullptr, text, 0)));
+        return 1;
+    }
+    // The tooltip auto-size's own recipe (FUN_00530640): break positions from
+    // the break-array computer, then the widest per-segment measure. Both
+    // callees are icon-aware through their co-hooks, and a segment-final icon
+    // reports its ink edge — so this is the rendered width, wrap and icons
+    // included.
+    int breaks[64];
+    uint32_t segs = reinterpret_cast<BreakArray_t>(Offsets::FUN_FONTSTRING_BREAK_ARRAY)(
+        fs, nullptr, text, budget, breaks, 64);
+    if (segs > 64u)
+        segs = 64u;
+    if (segs <= 1u) {
+        Game::Lua::PushNumber(L, InternalToPixel(measure(fs, nullptr, text, 0)));
+        return 1;
+    }
+    int len = 0;
+    while (len < 0x4000 && text[len] != '\0')
+        ++len;
+    float widest = 0.0f;
+    for (uint32_t i = 0; i < segs; ++i) {
+        const int start = breaks[i];
+        int end = (i + 1 < segs) ? breaks[i + 1] : len;
+        if (start < 0 || start >= end || end > len)
+            continue;
+        // A segment runs to the NEXT segment's start, which includes the
+        // whitespace the wrap consumed — the render never draws it, and a
+        // trailing space also flips the last real letter from ink to
+        // full-advance treatment (+~1.5px, measured). Trim to what renders.
+        while (end > start && (text[end - 1] == ' ' || text[end - 1] == '\n' ||
+                               text[end - 1] == '\r' || text[end - 1] == '\t'))
+            --end;
+        if (start >= end)
+            continue;
+        const float w = measure(fs, nullptr, text + start, end - start);
+        if (w > widest)
+            widest = w;
+    }
+    Game::Lua::PushNumber(L, InternalToPixel(widest));
+    return 1;
+}
+
+int __fastcall Script_GetLineHeight(void *L) {
+    void *fs = ResolveSelf(L, "Usage: fontstring:GetLineHeight()");
+    if (fs == nullptr)
+        return 0;
+    const float h = reinterpret_cast<FsFontHeight_t>(Offsets::FUN_FONTSTRING_FONT_HEIGHT)(
+        fs, nullptr, 1);
+    Game::Lua::PushNumber(L, InternalToPixel(h));
+    return 1;
+}
+
+int __fastcall Script_IsTruncated(void *L) {
+    void *fs = ResolveSelf(L, "Usage: fontstring:IsTruncated()");
+    if (fs == nullptr)
+        return 0;
+    // Retail computes this by running the display-text resolver and strcmp'ing
+    // its result against the source (5.4.8 inner fn 0x0045E001). 1.12's resolver
+    // needs the LAID-OUT rect (fs+0x64), which is zero until a render pass, so a
+    // Lua-time re-call always sees an unbounded box and never truncates. Read the
+    // render's OWN output instead: the built text node keeps a copy of exactly
+    // the string it laid out (OFF_TEXT_NODE_TEXT) — the ellipsized "<prefix>..."
+    // form on truncation, else the source verbatim. So this reflects the last
+    // rendered layout (the fontstring must have drawn once), matching retail's
+    // "displayed vs full" semantics.
+    bool truncated = false;
+    void *block = Game::Read<void *>(fs, Offsets::OFF_FONTSTRING_TEXT_BLOCK);
+    const char *src = Game::Read<const char *>(fs, Offsets::OFF_FONTSTRING_TEXT);
+    if (block != nullptr && src != nullptr) {
+        void *node = Game::Read<void *>(block, Offsets::OFF_TEXTBLOCK_NODE);
+        const char *shown =
+            (node != nullptr) ? Game::Read<const char *>(node, Offsets::OFF_TEXT_NODE_TEXT)
+                              : nullptr;
+        if (shown != nullptr) {
+            // A truncated display is exactly <source-prefix> + "...". Require the
+            // "..." suffix, a length strictly shorter than the source, and a
+            // matching byte-prefix. This rejects a STALE node — one left from a
+            // previous, different text after a fresh SetText, not yet re-laid-out
+            // — which would otherwise read as a truncation of the new text.
+            const size_t nlen = std::strlen(shown);
+            const size_t slen = std::strlen(src);
+            if (nlen >= 3 && nlen < slen && shown[nlen - 3] == '.' &&
+                shown[nlen - 2] == '.' && shown[nlen - 1] == '.' &&
+                std::memcmp(shown, src, nlen - 3) == 0)
+                truncated = true;
+        }
+    }
+    Game::Lua::PushBool(L, truncated);
+    return 1;
+}
+
+int __fastcall Script_SetMaxLines(void *L) {
+    void *fs = ResolveSelf(L, "Usage: fontstring:SetMaxLines(maxLines)");
+    if (fs == nullptr)
+        return 0;
+    // <= 0 or a non-number means "no cap" — the engine treats 0 as unlimited.
+    int maxLines = 0;
+    if (Game::Lua::IsNumber(L, 2)) {
+        const double n = Game::Lua::ToNumber(L, 2);
+        if (n > 0.0)
+            maxLines = static_cast<int>(n);
+    }
+    if (maxLines != Game::Read<int>(fs, Offsets::OFF_FONTSTRING_MAX_LINES)) {
+        Game::Ref<int>(fs, Offsets::OFF_FONTSTRING_MAX_LINES) = maxLines;
+        InvalidateLayout(fs);
+    }
+    return 0;
+}
+
+int __fastcall Script_GetMaxLines(void *L) {
+    void *fs = ResolveSelf(L, "Usage: fontstring:GetMaxLines()");
+    if (fs == nullptr)
+        return 0;
+    Game::Lua::PushNumber(
+        L, static_cast<double>(Game::Read<int>(fs, Offsets::OFF_FONTSTRING_MAX_LINES)));
+    return 1;
+}
+
+int __fastcall Script_SetFormattedText(void *L) {
+    void *fs = nullptr;
+    if (Game::Lua::Type(L, 1) == Game::Lua::TYPE_TABLE)
+        fs = Game::Lua::ResolveObject(L, 1);
+    if (fs == nullptr || !Game::Lua::IsString(L, 2)) {
+        Game::Lua::Error(L, "Usage: fontstring:SetFormattedText(\"format\"[, ...])");
+        return 0;
+    }
+    const int top = Game::Lua::GetTop(L);
+    Game::Lua::CheckStack(L, top + 4);
+    Game::Lua::PushCClosure(
+        L, reinterpret_cast<Game::Lua::CFunction>(Offsets::FUN_LUA_STR_FORMAT), 0);
+    for (int i = 2; i <= top; ++i)
+        Game::Lua::PushValue(L, i);
+    if (Game::Lua::PCall(L, top - 1, 1, 0) != 0) {
+        const char *msg = Game::Lua::ToString(L, -1);
+        Game::Lua::Error(L, "%s", (msg != nullptr) ? msg : "SetFormattedText: format failed");
+        return 0;
+    }
+    const char *result = Game::Lua::ToString(L, -1);
+    reinterpret_cast<FsSetText_t>(Offsets::FUN_FONTSTRING_SET_TEXT)(
+        fs, nullptr, (result != nullptr) ? result : "", 0);
+    Game::Lua::SetTop(L, top);
+    return 0;
+}
+
+const Game::Lua::FrameMethodEntry g_methods[] = {
+    {"GetStringHeight", &Script_GetStringHeight},
+    {"GetUnboundedStringWidth", &Script_GetUnboundedStringWidth},
+    {"GetWrappedWidth", &Script_GetWrappedWidth},
+    {"GetNumLines", &Script_GetNumLines},
+    {"GetLineHeight", &Script_GetLineHeight},
+    {"IsTruncated", &Script_IsTruncated},
+    {"SetMaxLines", &Script_SetMaxLines},
+    {"GetMaxLines", &Script_GetMaxLines},
+    {"SetFormattedText", &Script_SetFormattedText},
+};
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterFrameMethods(
+        reinterpret_cast<void *>(Offsets::VAR_FONTSTRING_METHOD_REGISTRY), g_methods,
+        static_cast<int>(sizeof(g_methods) / sizeof(g_methods[0])));
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+} // namespace FontString::Metrics
@@ -58,9 +58,11 @@
 // 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`
+// `spell` attribute and casts it: with a `unit` attribute, on that 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 its feet;
+// with no `unit`, on the current target via the plain CastSpellByName), `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
@@ -96,7 +98,10 @@

 #include "Game.h"
 #include "Offsets.h"
+#include "baselib/Ascii.h"
 #include "cursor/Info.h"
+#include "macro/Execute.h"
+#include "object/Resolve.h"
 #include "spell/AtCursor.h"
 #include "spell/AtUnit.h"
 #include "tick/WorldTick.h"
@@ -147,15 +152,6 @@ void Compose3Lower(char *dst, size_t n, const char *a, const char *b, const char
    dst[i] = '\0';
 }

-// ASCII case-insensitive full-string equality.
-bool EqI(const char *a, const char *b) {
-    for (; *a && *b; ++a, ++b)
-        if (std::tolower(static_cast<unsigned char>(*a)) !=
-            std::tolower(static_cast<unsigned char>(*b)))
-            return false;
-    return *a == *b;
-}
-
 // 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
@@ -306,78 +302,6 @@ bool CallTableFunc2Str(void *L, const char *table, const char *method,
    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.
@@ -391,12 +315,11 @@ std::unordered_map<const void *, std::string> g_unitByFrame;
 uint64_t g_lastSet = 0;

 const void *CurrentMouseFocus() {
-    const void *ctx = *reinterpret_cast<const void *const *>(
+    const void *ctx = Game::Read<const void *>(
        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);
+    return Game::Read<const void *>(ctx, Offsets::OFF_UI_CONTEXT_MOUSE_FOCUS);
 }

 // The engine's real mouseover setter — `__stdcall(guidLo, guidHi, prevLo,
@@ -410,6 +333,50 @@ void CallEngineMouseover(uint64_t guid) {
        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 = Game::Read<void *>(
+        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 = Game::Read<int>(
+        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();

@@ -423,6 +390,11 @@ void MouseoverTick() {

    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;
    }
 }
@@ -455,10 +427,10 @@ void BuildModifierPrefix(void *L, char *buf, size_t n) {

 // Button name -> attribute suffix (retail's convention: the button number).
 const char *ButtonSuffix(const char *btn) {
-    if (EqI(btn, "RightButton"))  return "2";
-    if (EqI(btn, "MiddleButton")) return "3";
-    if (EqI(btn, "Button4"))      return "4";
-    if (EqI(btn, "Button5"))      return "5";
+    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
 }

@@ -546,10 +518,10 @@ bool CallGlobalNum2(void *L, const char *name, double a, double b) {
 // 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 (EqI(verb, "target")) {
+    if (Ascii::EqualCI(verb, "target")) {
        if (!unit) return false;
        // `unit="none"` clears the target (retail's SecureActionButton behavior).
-        if (EqI(unit, "none")) {
+        if (Ascii::EqualCI(unit, "none")) {
            Game::Lua::CallGlobal(L, "ClearTarget");
            return true;
        }
@@ -566,25 +538,32 @@ bool DispatchVerb(void *L, int fi, const char *prefix, const char *suffix,
            Game::Lua::CallGlobalString(L, "TargetUnit", unit);
        return true;
    }
-    if (EqI(verb, "assist")) {
+    if (Ascii::EqualCI(verb, "assist")) {
        if (!unit) return false;
        Game::Lua::CallGlobalString(L, "AssistUnit", unit);
        return true;
    }
-    if (EqI(verb, "focus")) {
+    if (Ascii::EqualCI(verb, "focus")) {
        if (!unit) return false;
        Unit::Focus::Set(Unit::Identity::GuidForToken(unit));
        return true;
    }
-    if (EqI(verb, "spell")) {
-        if (!unit) return false;
+    if (Ascii::EqualCI(verb, "spell")) {
        char spell[128];
        if (!ReadModAttr(L, fi, prefix, "spell", suffix, spell, sizeof spell))
            return false;
-        Spell::AtUnit::CastByName(spell, unit);
+        // With a `unit`, cast straight at it (GUID → dispatcher, no target
+        // juggling; a ground-target spell lands at its feet). With no `unit`,
+        // fall back to the plain global cast on the current target — a
+        // `type="spell"` button that sets no `unit` attribute (issue #18) now
+        // works like `/cast <spell>` instead of doing nothing.
+        if (unit)
+            Spell::AtUnit::CastByName(spell, unit);
+        else
+            Game::Lua::CallGlobalString(L, "CastSpellByName", spell);
        return true;
    }
-    if (EqI(verb, "item")) {
+    if (Ascii::EqualCI(verb, "item")) {
        char item[128];
        int bag, slot;
        if (ReadModAttr(L, fi, prefix, "item", suffix, item, sizeof item)) {
@@ -602,23 +581,64 @@ bool DispatchVerb(void *L, int fi, const char *prefix, const char *suffix,
        }
        return false;
    }
-    if (EqI(verb, "macro")) {
+    if (Ascii::EqualCI(verb, "macro")) {
+        // Give the macro a unit to act on. Vanilla macros have no `@unit`
+        // conditional, and unlike the `spell` verb (which feeds a GUID straight
+        // to the cast dispatcher) we can't inject a target into arbitrary macro
+        // text — so a plain `/cast Flash Heal` would hit the current target, not
+        // the clicked unit. Emulate the classic Clique click-heal: snapshot the
+        // current target, retarget the clicked unit, run the macro, then restore
+        // the previous target so the click doesn't leave the player retargeted.
+        // The macro's actions (/cast etc.) dispatch against the clicked unit
+        // synchronously while it's selected, so restoring the target afterward
+        // doesn't affect them.
+        uint64_t prevTarget = 0;
+        const bool swapped = unit != nullptr;
+        if (swapped) {
+            prevTarget =
+                (static_cast<uint64_t>(Game::Read<volatile uint32_t>(
+                     Offsets::VAR_CURRENT_SELECTION_GUID_HI))
+                 << 32) |
+                Game::Read<volatile uint32_t>(
+                    Offsets::VAR_CURRENT_SELECTION_GUID_LO);
+            Game::Lua::CallGlobalString(L, "TargetUnit", unit);
+        }
        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;
+        bool handled = false;
+        // `macrotext` is raw macro text (the modern default). Run it as text
+        // through the stock chat parser so each line dispatches via
+        // SlashCmdList — that routes /cast etc. through any addon slash hooks
+        // (e.g. SuperCleveRoidMacros' conditional /cast). A name-based RunMacro
+        // (which is what SuperCleveRoidMacros ships) can't interpret text and
+        // would silently resolve nothing.
+        if (ReadModAttr(L, fi, prefix, "macrotext", suffix, macro, sizeof macro)) {
+            Macro::Execute::Text(L, macro);
+            handled = true;
+        }
+        // Deprecated `macro` form: a saved-macro name/index. Prefer an
+        // addon-provided RunMacro (SuperCleveRoidMacros, pfUI, …) to run the
+        // named macro's body; fall back to the stock parser when none exists.
+        else if (ReadModAttr(L, fi, prefix, "macro", suffix, macro, sizeof macro)) {
+            handled = Macro::Execute::Saved(L, macro);
+        }
+        // Restore the target the click swapped away from. `FUN_TARGET_BY_GUID`
+        // validates the GUID resolves to a live unit and bails otherwise, so a
+        // target that despawned mid-macro is dropped cleanly rather than
+        // committed; a zero prior target means "no target" → ClearTarget.
+        if (swapped) {
+            if (prevTarget)
+                reinterpret_cast<void(__fastcall *)(const uint64_t *)>(
+                    Offsets::FUN_TARGET_BY_GUID)(&prevTarget);
+            else
+                Game::Lua::CallGlobal(L, "ClearTarget");
+        }
+        return handled;
    }
-    if (EqI(verb, "stop") || EqI(verb, "stopcasting")) {
+    if (Ascii::EqualCI(verb, "stop") || Ascii::EqualCI(verb, "stopcasting")) {
        Game::Lua::CallGlobal(L, "SpellStopCasting");
        return true;
    }
-    if (EqI(verb, "menu") || EqI(verb, "togglemenu")) {
+    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.
@@ -738,7 +758,7 @@ 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 (EqI(name, "onattributechanged"))
+    if (Ascii::EqualCI(name, "onattributechanged"))
        return reinterpret_cast<int>(AttrSlotFor(frame, /*create*/ true));
    return 0;
 }
@@ -131,8 +131,7 @@ int __fastcall Script_IsMouseOver(void *L) {
        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);
+    const float effScale = Game::Read<float>(obj, Offsets::OFF_REGION_EFFECTIVE_SCALE);

    double left, right, top, bottom;
    if (effScale == 0.0f ||
@@ -193,13 +192,10 @@ int __fastcall Script_GetRect(void *L) {
 // 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 *ctx = Game::Read<void *>(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)
+            ? Game::Read<void *>(ctx, Offsets::OFF_UI_CONTEXT_DRAG_TARGET)
            : nullptr;
    Game::Lua::PushBool(L, self != nullptr && self == dragTarget);
    return 1;
@@ -348,9 +344,9 @@ int __fastcall Script_HookScript(void *L) {
 using SStrCmpI_t = int(__stdcall *)(const char *a, const char *b, int n);

 bool FrameHasEvent(void *frame, const char *eventName) {
-    const uint32_t count = *reinterpret_cast<const uint32_t *>(
+    const uint32_t count = Game::Read<uint32_t>(
        static_cast<uintptr_t>(Offsets::VAR_EVENT_TABLE_COUNT));
-    auto *base = *reinterpret_cast<const uint8_t *const *>(
+    auto *base = Game::Read<const uint8_t *>(
        static_cast<uintptr_t>(Offsets::VAR_EVENT_TABLE_BASE_PTR));
    if (count == 0 || base == nullptr)
        return false;
@@ -360,21 +356,19 @@ bool FrameHasEvent(void *frame, const char *eventName) {

    for (uint32_t i = 0; i < count; ++i) {
        const uint8_t *entry = base + i * Offsets::EVENT_ENTRY_STRIDE;
-        const char *name = *reinterpret_cast<const char *const *>(
-            entry + Offsets::OFF_EVENT_ENTRY_NAME);
+        const char *name = Game::Read<const char *>(
+            entry, Offsets::OFF_EVENT_ENTRY_NAME);
        if (name == nullptr)
            continue;
        if (sstrcmpi(name, eventName, 0x7FFFFFFF) != 0)
            continue;
        // Names are unique, so this is the one entry — walk its chain.
-        uintptr_t node = *reinterpret_cast<const uintptr_t *>(
-            entry + Offsets::OFF_EVENT_ENTRY_HEAD);
+        uintptr_t node = Game::Read<uintptr_t>(
+            entry, Offsets::OFF_EVENT_ENTRY_HEAD);
        while ((node & 1) == 0 && node != 0) {
-            if (*reinterpret_cast<void *const *>(
-                    node + Offsets::OFF_EVENT_NODE_FRAME) == frame)
+            if (Game::Read<void *>(node + Offsets::OFF_EVENT_NODE_FRAME) == frame)
                return true;
-            node = *reinterpret_cast<const uintptr_t *>(
-                node + Offsets::OFF_EVENT_NODE_NEXT);
+            node = Game::Read<uintptr_t>(node + Offsets::OFF_EVENT_NODE_NEXT);
        }
        return false;
    }
@@ -0,0 +1,205 @@
+// 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 Game::Read<void *>(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 = Game::Read<float>(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 = Game::Read<void *>(ctx, Offsets::OFF_UI_CONTEXT_MOUSE_FOCUS);
+
+    const Cursor cur = ReadCursor(L);
+
+    std::vector<Hit> hits;
+    void *node = Game::Read<void *>(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 = Game::Read<void *>(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 = Game::Read<int>(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
@@ -29,8 +29,9 @@
 // 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
-// exact global save/set/restore and its message-handler errfunc; only the
-// final push+pcall differs.
+// 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
@@ -67,26 +68,19 @@ constexpr int kMaxArgs = 19;
 // 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);
-// luaL_ref(L, t) → int — pop the top, store it under a fresh int key in table
-// `t`, return the key. luaL_unref frees it.
-using LuaLRef_t = int(__fastcall *)(void *L, int t);
-using LuaLUnref_t = void(__fastcall *)(void *L, int t, 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);
-const auto LuaLRef = reinterpret_cast<LuaLRef_t>(Offsets::LUA_REF_REF);
-const auto LuaLUnref = reinterpret_cast<LuaLUnref_t>(Offsets::LUA_REF_UNREF);

 // 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)
+    if (Game::Read<int>(frame, 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);
+    return Game::Read<int>(frame, Offsets::OFF_COBJECT_LUA_REF);
 }

 // Writes "arg" + k (k in 1..19) into buf; buf must hold at least 6 bytes.
@@ -104,40 +98,93 @@ void ArgName(char *buf, int k) {
    }
 }

-// Sets _G[name] = <value currently on the stack top>, capturing the previous
-// _G[name] into *outOldRef (a luaL_ref for later restore). Stack-neutral:
-// consumes the value, leaves the stack as it was minus that value.
-void SetGlobalSaving(void *L, const char *name, int *outOldRef) {
-    using namespace Game::Lua;
-    PushString(L, name);        // [.., newVal, name]
-    GetTable(L, GLOBALS_INDEX); // [.., newVal, oldVal]
-    *outOldRef = LuaLRef(L, REGISTRY_INDEX); // [.., newVal]
-    PushString(L, name);        // [.., newVal, name]
-    Insert(L, -2);              // [.., name, newVal]
-    SetTable(L, GLOBALS_INDEX); // [..]
+// 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;
 }

-// Restores _G[name] to the value at oldRef, then frees the ref.
-void RestoreGlobal(void *L, const char *name, int oldRef) {
-    using namespace Game::Lua;
-    RawGetI(L, REGISTRY_INDEX, oldRef); // [.., oldVal]
-    PushString(L, name);                // [.., oldVal, name]
-    Insert(L, -2);                      // [.., name, oldVal]
-    SetTable(L, GLOBALS_INDEX);         // [..]
-    LuaLUnref(L, REGISTRY_INDEX, oldRef);
+// 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 globals (with save/restore), then invoke
-// the handler with modern positional args `(self, arg1..argN)` under the
-// engine's own message-handler errfunc. `fmt`/`vaPtr` are null for the no-arg
-// runner (N == 0).
-void RunModern(int handlerRef, void *frame, const char *fmt, const void *vaPtr) {
+// 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;
+        return false;
+    // Headroom for the saved-old block plus the transient set/call pushes.
+    if (CheckStack(L, 2 * kMaxArgs + 16) == 0)
+        return false;

-    // --- _G.this = frame -----------------------------------------------------
    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
@@ -145,68 +192,47 @@ void RunModern(int handlerRef, void *frame, const char *fmt, const void *vaPtr)
    // 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;
-    int selfRef = 0;
-    int oldThisRef = 0;
-    if (haveThis) {
-        selfRef = EnsureLuaRef(frame);
-        RawGetI(L, REGISTRY_INDEX, selfRef); // push frame object
-        SetGlobalSaving(L, "this", &oldThisRef);
-    }
+        Game::Read<int>(frame, Offsets::OFF_FRAME_ONEVENT_SLOT) == handlerRef;
+    const int selfRef = haveThis ? EnsureLuaRef(frame) : 0;

-    // --- _G.arg1..argN from the format --------------------------------------
-    int oldArgRefs[kMaxArgs];
-    char argNames[kMaxArgs][6];
-    int n = 0;
-    if (fmt != nullptr) {
-        const char *cur = static_cast<const char *>(vaPtr);
-        for (const char *p = fmt; *p != '\0' && n < kMaxArgs; ++p) {
-            if (*p != '%')
-                continue;
-            ++p;
-            if (*p == '\0')
-                break;
-            bool consumed = true;
-            switch (*p) {
-            case 'd':
-                PushNumber(L, static_cast<double>(*reinterpret_cast<const int *>(cur)));
-                cur += 4;
-                break;
-            case 'u':
-                PushNumber(L, static_cast<double>(
-                                  *reinterpret_cast<const unsigned int *>(cur)));
-                cur += 4;
-                break;
-            case 'f':
-                PushNumber(L, *reinterpret_cast<const double *>(cur));
-                cur += 8;
-                break;
-            case 's':
-                PushString(L, *reinterpret_cast<const char *const *>(cur));
-                cur += 4;
-                break;
-            default:
-                consumed = false; // unknown spec — skip, consume nothing
-                break;
-            }
-            if (!consumed)
-                continue;
-            ArgName(argNames[n], n + 1);
-            SetGlobalSaving(L, argNames[n], &oldArgRefs[n]);
-            ++n;
-        }
-    }
+    Arg args[kMaxArgs];
+    const int n = ParseArgs(fmt, vaPtr, args);

-    // --- call handler(self, arg1..argN) -------------------------------------
+    // --- 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);
-    const int errRef = *reinterpret_cast<const int *>(
+    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 = Game::Read<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 = base + 1;                  // absolute index of the errfunc
+        errIdx = callBase + 1;              // absolute index of the errfunc
    }
    RawGetI(L, REGISTRY_INDEX, handlerRef); // handler
    if (haveThis)
@@ -217,18 +243,24 @@ void RunModern(int handlerRef, void *frame, const char *fmt, const void *vaPtr)
        PushString(L, "event");
        GetTable(L, GLOBALS_INDEX);
    }
-    for (int k = 0; k < n; ++k) { // positional args, re-read from the globals
-        PushString(L, argNames[k]);
-        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, base); // drop the message handler + any leftover error object
+    SetTop(L, callBase); // drop the message handler + any leftover error object

-    // --- restore globals (reverse order) ------------------------------------
-    for (int k = n - 1; k >= 0; --k)
-        RestoreGlobal(L, argNames[k], oldArgRefs[k]);
-    if (haveThis)
-        RestoreGlobal(L, "this", oldThisRef);
+    // --- 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) ----------------
@@ -238,11 +270,10 @@ 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) {
-        g_origRunArgs(handlerRef, frame, fmt, vaPtr);
+    if (g_enabled && handlerRef != 0 && fmt != nullptr &&
+        RunModern(handlerRef, frame, fmt, vaPtr))
        return;
-    }
-    RunModern(handlerRef, frame, fmt, vaPtr);
+    g_origRunArgs(handlerRef, frame, fmt, vaPtr);
 }

 // --- FUN_FRAME_INVOKE_SCRIPT co-hook (no-arg scripts) -----------------------
@@ -252,11 +283,10 @@ 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) {
-        g_origInvoke(handlerRef, frame);
+    if (g_enabled && handlerRef != 0 && frame != nullptr &&
+        RunModern(handlerRef, frame, /*fmt*/ nullptr, /*vaPtr*/ nullptr))
        return;
-    }
-    RunModern(handlerRef, frame, /*fmt*/ nullptr, /*vaPtr*/ nullptr);
+    g_origInvoke(handlerRef, frame);
 }

 const Game::HookAutoRegister _runArgsHook{
@@ -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
@@ -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
@@ -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
@@ -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
@@ -0,0 +1,207 @@
+// 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 "Game.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 Game::Read<const char *>(Offsets::VAR_ACCOUNT_NAME_PTR);
+}
+
+const char *ReadRealmName() {
+    auto *info = Game::Read<uint8_t *>(Offsets::VAR_REALM_INFO_PTR);
+    if (info == nullptr)
+        return nullptr;
+    return Game::Read<const char *>(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
@@ -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
@@ -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
@@ -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);
@@ -0,0 +1,112 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `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 Game::Read<int>(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 = Game::Read<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 = Game::Ptr<const char>(entry, Offsets::OFF_WHO_NAME);
+    const char *guild = Game::Ptr<const char>(entry, Offsets::OFF_WHO_GUILD);
+    const int level = Game::Read<int>(entry, Offsets::OFF_WHO_LEVEL);
+    const uint32_t raceID =
+        Game::Read<uint32_t>(entry, Offsets::OFF_WHO_RACE);
+    const uint32_t classID =
+        Game::Read<uint32_t>(entry, Offsets::OFF_WHO_CLASS);
+    const uint32_t zoneID =
+        Game::Read<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
@@ -72,10 +72,10 @@ int __fastcall Script_GetGameObjectInfoByID(void *L) {
    if (rec == nullptr)
        return 0; // not cached -> nil

-    const uint32_t type = *reinterpret_cast<const uint32_t *>(rec + Offsets::OFF_GAMEOBJECT_TYPE);
+    const uint32_t type = Game::Read<uint32_t>(rec, Offsets::OFF_GAMEOBJECT_TYPE);
    const uint32_t displayID =
-        *reinterpret_cast<const uint32_t *>(rec + Offsets::OFF_GAMEOBJECT_DISPLAYID);
-    const char *name = *reinterpret_cast<const char *const *>(rec + Offsets::OFF_GAMEOBJECT_NAME);
+        Game::Read<uint32_t>(rec, Offsets::OFF_GAMEOBJECT_DISPLAYID);
+    const char *name = Game::Read<const char *>(rec, Offsets::OFF_GAMEOBJECT_NAME);

    Game::Lua::NewTable(L);
    Game::Lua::SetFieldNumber(L, "gameObjectID", goID);
@@ -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
@@ -65,17 +63,16 @@ static int __fastcall Script_GameTooltipGetGameObject(void *L) {
        return 0;

    const auto *base = static_cast<const uint8_t *>(tooltipObj);
-    const uint32_t guidLo = *reinterpret_cast<const uint32_t *>(
-        base + Offsets::OFF_TOOLTIP_GAMEOBJECT_GUID_LO);
-    const uint32_t guidHi = *reinterpret_cast<const uint32_t *>(
-        base + Offsets::OFF_TOOLTIP_GAMEOBJECT_GUID_HI);
+    const uint32_t guidLo =
+        Game::Read<uint32_t>(base, Offsets::OFF_TOOLTIP_GAMEOBJECT_GUID_LO);
+    const uint32_t guidHi =
+        Game::Read<uint32_t>(base, Offsets::OFF_TOOLTIP_GAMEOBJECT_GUID_HI);
    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;

@@ -114,10 +111,10 @@ static int __fastcall Script_GameTooltipHasGameObject(void *L) {
        return 1;
    }
    const auto *base = static_cast<const uint8_t *>(tooltipObj);
-    const uint32_t guidLo = *reinterpret_cast<const uint32_t *>(
-        base + Offsets::OFF_TOOLTIP_GAMEOBJECT_GUID_LO);
-    const uint32_t guidHi = *reinterpret_cast<const uint32_t *>(
-        base + Offsets::OFF_TOOLTIP_GAMEOBJECT_GUID_HI);
+    const uint32_t guidLo =
+        Game::Read<uint32_t>(base, Offsets::OFF_TOOLTIP_GAMEOBJECT_GUID_LO);
+    const uint32_t guidHi =
+        Game::Read<uint32_t>(base, Offsets::OFF_TOOLTIP_GAMEOBJECT_GUID_HI);
    Game::Lua::PushBool(L, guidLo != 0 || guidHi != 0);
    return 1;
 }
@@ -13,6 +13,7 @@

 #include "group/MemberStats.h"

+#include "Game.h"
 #include "Offsets.h"

 namespace Group::MemberStats {
@@ -23,7 +24,7 @@ namespace {
 using Lookup_t = const uint8_t *(__fastcall *)(uint64_t *guid);

 uint16_t U16(const uint8_t *p, int off) {
-    return *reinterpret_cast<const uint16_t *>(p + off);
+    return Game::Read<uint16_t>(p, off);
 }

 } // namespace
@@ -67,13 +68,13 @@ Stats Lookup(uint64_t guid) {
        s.level = U16(e, Offsets::OFF_RAID_SLOT_LEVEL);
        s.areaId = U16(e, Offsets::OFF_RAID_SLOT_AREA_ID);
        const uint32_t flags =
-            *reinterpret_cast<const uint32_t *>(e + Offsets::OFF_RAID_SLOT_FLAGS);
+            Game::Read<uint32_t>(e, Offsets::OFF_RAID_SLOT_FLAGS);
        s.online = (flags & Offsets::RAID_SLOT_FLAG_ONLINE) != 0;
        s.dead = (flags & Offsets::RAID_SLOT_FLAG_DEAD) != 0;
-        s.subgroup = static_cast<int>(*reinterpret_cast<const uint32_t *>(
-                         e + Offsets::OFF_RAID_SLOT_SUBGROUP)) + 1;
+        s.subgroup = static_cast<int>(Game::Read<uint32_t>(
+                         e, Offsets::OFF_RAID_SLOT_SUBGROUP)) + 1;
        s.rank = static_cast<int>(
-            *reinterpret_cast<const uint32_t *>(e + Offsets::OFF_RAID_SLOT_RANK));
+            Game::Read<uint32_t>(e, Offsets::OFF_RAID_SLOT_RANK));
        return s;
    }

@@ -93,8 +94,8 @@ const uint16_t *AuraArray(uint64_t guid) {
        if ((e[Offsets::OFF_GROUP_MEMBER_STATUS_FLAGS] &
             Offsets::GROUP_MEMBER_STATUS_ONLINE) == 0)
            return nullptr;
-        return reinterpret_cast<const uint16_t *>(
-            e + Offsets::OFF_GROUP_MEMBER_STATS_AURAS);
+        return Game::Ptr<const uint16_t>(
+            e, Offsets::OFF_GROUP_MEMBER_STATS_AURAS);
    }

    // Raid slot — auras at +0x64, no online gate (mirrors the engine's raid
@@ -102,8 +103,8 @@ const uint16_t *AuraArray(uint64_t guid) {
    auto slotFn = reinterpret_cast<Lookup_t>(
        static_cast<uintptr_t>(Offsets::FUN_GROUP_MEMBER_SLOT_LOOKUP));
    if (const uint8_t *e = slotFn(&guid)) {
-        return reinterpret_cast<const uint16_t *>(
-            e + Offsets::OFF_RAID_SLOT_AURAS);
+        return Game::Ptr<const uint16_t>(
+            e, Offsets::OFF_RAID_SLOT_AURAS);
    }

    return nullptr;
@@ -46,12 +46,9 @@ int __fastcall Script_GetCreatureID(void *L) {
        Game::Lua::PushNil(L);
        return 1;
    }
-    const Type type = Classify(guid);
-    if (type != Type::Creature && type != Type::Pet) {
-        Game::Lua::PushNil(L);
-        return 1;
-    }
-    const uint32_t entryID = static_cast<uint32_t>((guid >> 24) & 0xFFFFFFu);
+    // `Guid::CreatureEntry` handles the creature/pet type gate + the bits-24-47
+    // extraction, and returns 0 for players, non-creature types, and entry 0.
+    const uint32_t entryID = CreatureEntry(guid);
    if (entryID == 0) {
        Game::Lua::PushNil(L);
        return 1;
@@ -51,6 +51,13 @@ const char *FormatAsString(uint64_t guid, char *buf, std::size_t cap) {
    return buf;
 }

+uint32_t CreatureEntry(uint64_t guid) {
+    const Type type = Classify(guid);
+    if (type != Type::Creature && type != Type::Pet)
+        return 0;
+    return static_cast<uint32_t>((guid >> 24) & 0xFFFFFFu);
+}
+
 Type Classify(uint64_t guid) {
    if (guid == 0)
        return Type::Unknown;
@@ -76,6 +76,14 @@ inline bool IsGameObject(uint64_t guid)    { return Classify(guid) == Type::Game
 inline bool IsDynamicObject(uint64_t guid) { return Classify(guid) == Type::DynamicObject; }
 inline bool IsCorpse(uint64_t guid)        { return Classify(guid) == Type::Corpse; }

+// The creature-template / NPC entry ID packed into a creature or pet GUID
+// (bits 24-47). Vanilla puts the per-spawn counter in the low 24 bits and the
+// template entry above it. Returns 0 for any other GUID type (players,
+// gameobjects, items, the 0 sentinel) and when the field itself is 0 — the
+// engine never assigns entry 0, so 0 uniformly means "no creature template".
+// Shared by `C_CreatureInfo.GetCreatureID` and `UnitCreatureID`.
+uint32_t CreatureEntry(uint64_t guid);
+
 // Minimum buffer size for `FormatAsString`'s output — 16 hex digits +
 // the `"0x"` prefix + a NUL terminator.
 constexpr std::size_t STRING_SIZE = 19;
@@ -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
@@ -147,29 +138,18 @@ ItemInfo ReadItemInfo(const uint8_t *cgItem) {
        Item::Data::WarmCache(static_cast<uint32_t>(itemID));
        return {0, 0};
    }
-    return {*reinterpret_cast<const uint32_t *>(record + Offsets::OFF_ITEMSTATS_ITEM_LEVEL),
-            *reinterpret_cast<const uint32_t *>(record + Offsets::OFF_ITEMSTATS_INVENTORY_TYPE)};
+    return {Game::Read<uint32_t>(record, Offsets::OFF_ITEMSTATS_ITEM_LEVEL),
+            Game::Read<uint32_t>(record, Offsets::OFF_ITEMSTATS_INVENTORY_TYPE)};
 }

 // 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
@@ -204,12 +184,12 @@ void WalkGuidArrayRange(const uint8_t *invMgr, int firstSlot, int lastSlot,
                        std::vector<Candidate> &candidates) {
    if (invMgr == nullptr)
        return;
-    auto *guidArray = *reinterpret_cast<const uint64_t *const *>(
-        invMgr + Offsets::OFF_INVMGR_GUID_ARRAY);
+    auto *guidArray = Game::Read<const uint64_t *>(
+        invMgr, Offsets::OFF_INVMGR_GUID_ARRAY);
    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);
@@ -223,13 +203,13 @@ void WalkBankBags(std::vector<Candidate> &candidates) {
    auto *playerInvMgr = Unit::Identity::PlayerInventoryManager();
    if (playerInvMgr == nullptr)
        return;
-    auto *playerGuidArray = *reinterpret_cast<const uint64_t *const *>(
-        playerInvMgr + Offsets::OFF_INVMGR_GUID_ARRAY);
+    auto *playerGuidArray = Game::Read<const uint64_t *>(
+        playerInvMgr, Offsets::OFF_INVMGR_GUID_ARRAY);
    if (playerGuidArray == nullptr)
        return;
    for (int slot = Offsets::INVMGR_BANK_BAG_FIRST_SLOT;
         slot <= Offsets::INVMGR_BANK_BAG_LAST_SLOT; ++slot) {
-        const uint8_t *bag = ResolveByGuid(Offsets::OBJ_TYPE_CONTAINER,
+        const uint8_t *bag = ResolveByGuid(Offsets::TYPEMASK_CONTAINER,
                                            playerGuidArray[slot]);
        if (bag == nullptr)
            continue;
@@ -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 *>(
@@ -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
@@ -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
@@ -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 *>(
@@ -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;
@@ -42,16 +42,22 @@ namespace {
 // `uint *` (the ItemStats cache lookup uses the integer both as a
 // hash key and as the field-zero match target, which is how it
 // inherits the pointer typing in the decomp).
+//
+// `outDuration`/`outStart` are *unsigned* millisecond ticks (same OS counter
+// and epoch as `GetTime()`). Reading `outStart` into a signed `int` makes
+// every timestamp negative once the machine has been up past 2^31 ms
+// (~24.9 days), so `startTime + duration` lands in the past and every item
+// reads as off cooldown. Keep them unsigned; see `Time::Clock`.
 using QueryItemCooldown_t = bool(__fastcall *)(uint32_t itemID,
-                                                int *outDuration,
-                                                int *outStart,
+                                                uint32_t *outDuration,
+                                                uint32_t *outStart,
                                                uint32_t *outEnable);

 } // namespace

 void PushCooldown(void *L, int itemID) {
-    int durationMs = 0;
-    int startMs = 0;
+    uint32_t durationMs = 0;
+    uint32_t startMs = 0;
    uint32_t enable = 0;
    if (itemID > 0) {
        auto fn = reinterpret_cast<QueryItemCooldown_t>(
@@ -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;
@@ -16,6 +16,7 @@
 #include "Game.h"
 #include "Offsets.h"
 #include "cursor/Info.h"
+#include "item/CGItem.h"
 #include "item/Location.h"

 #include <cstdint>
@@ -38,18 +39,17 @@ constexpr int OFF_CONTAINER_GUID_LO = 0x08;
 constexpr int OFF_CONTAINER_GUID_HI = 0x0C;

 bool ItemLocked(const uint8_t *item) {
-    return (*reinterpret_cast<const uint32_t *>(item + Offsets::OFF_ITEM_CLIENT_LOCK) & 1) != 0;
+    return (Game::Read<uint32_t>(item, Offsets::OFF_ITEM_CLIENT_LOCK) & 1) != 0;
 }

 // 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);
-    *hi = *reinterpret_cast<const uint32_t *>(instance + Offsets::OFF_INSTANCE_BLOCK_GUID + 4);
+    *lo = Game::Read<uint32_t>(instance, Offsets::OFF_INSTANCE_BLOCK_GUID);
+    *hi = Game::Read<uint32_t>(instance, Offsets::OFF_INSTANCE_BLOCK_GUID + 4);
    return true;
 }

@@ -15,9 +15,13 @@
 #include "Offsets.h"
 #include "event/Custom.h"
 #include "item/Arg.h"
+#include "item/CGItem.h"
 #include "item/Data.h"
+#include "item/ID.h"
 #include "item/Location.h"
 #include "tick/WorldTick.h"
+#include "time/Clock.h"
+#include "unit/Identity.h"

 #include <cstdint>

@@ -63,21 +67,10 @@ static void FireItemDataLoadResult(int itemID, bool success) {
                                 itemID, success);
 }

-// Engine callback for **implicit** cache fills (transparent warmup
-// triggered by our `Script_GetItemInfo` hook or `SetItemByID`). Fires
-// only the broad `GET_ITEM_INFO_RECEIVED` event — `ITEM_DATA_LOAD_RESULT`
-// is reserved for explicit `RequestLoadItemData(ByID)` paths to match
-// modern API semantics.
-//
-// Calling convention is __stdcall, 2 args / 8 bytes — matching the
+// Item-load callbacks are __stdcall, 2 args / 8 bytes — matching the
 // callback at 0x004FDC30 (used by 4 sites in the binary) which ends in
-// `ret 8`. If the engine called us with a different convention, that
-// callback would crash the engine, so stdcall is verified by induction.
-static void __stdcall ItemLoadCallback_Implicit(void *userData, int success) {
-    const auto itemID = static_cast<int>(reinterpret_cast<uintptr_t>(userData));
-    FireGetItemInfoReceived(itemID, success != 0);
-}
-
+// `ret 8`. If the engine called us with a different convention it would
+// crash, so stdcall is verified by induction.
 using ItemLoadCallback_t = void(__stdcall *)(void *userData, int success);

 // Calls DBCache_ItemStats_C_GetRecord. With `callback=nullptr`,
@@ -119,12 +112,11 @@ 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 *>(
-        instance + Offsets::OFF_INSTANCE_BLOCK_ITEM_ID));
+    return static_cast<int>(Game::Read<uint32_t>(
+        instance, Offsets::OFF_INSTANCE_BLOCK_ITEM_ID));
 }

 static int __fastcall Script_IsItemDataCachedByID(void *L) {
@@ -191,10 +183,42 @@ constexpr int kMaxWaitTicks = 1200;
 // One-way latch; see the relog note in `WarmCache`.
 constexpr int kSettleTicks = 60;

+// Minimum spacing between outgoing *background* SMSG_ITEM_QUERY_SINGLE
+// requests. A single /reload can make addons (pfQuest / Questie / Bagnon)
+// look up hundreds of items in one frame. Unthrottled, every cache miss
+// fired its own packet at once: a reported burst of 1,325 requests in
+// ~14 ms exhausted a consumer router's NAT table and dropped the
+// machine's internet connectivity (issue #25). 50 ms caps the sustained
+// background rate at 20 requests / second. OnWorldTick is the single
+// point that issues queries, so this one floor governs the bulk path.
+constexpr uint32_t kMinRequestSpacingMs = 50;
+
+// Priority tier. The player's carried items (equipment + backpack +
+// equipped bags) are what the bag / paperdoll UI shows immediately on
+// login; behind the background floor they showed as "unknown" for a
+// second or two while a bulk addon scan drained ahead of them. These
+// are issued on a separate, more generous budget so they resolve fast.
+// The set is bounded (~120 items) and the engine prefetches inventory in
+// parallel, so a small per-tick cap keeps them near-instant without
+// re-introducing a burst: worst case is kOwnedPerTick + 1 packets per
+// frame (~7), far below the flood that broke connectivity.
+constexpr int kOwnedPerTick = 6;
+constexpr int kMaxOwned = 256;
+constexpr uint32_t kOwnedRefreshMs = 1000; // carried set changes slowly
+
 static Pending g_pending[kMaxPending];
 static int g_pendingCount = 0;
 static bool g_settled = false;
 static int g_worldTicks = 0;
+static uint32_t g_lastRequestMs = 0;
+
+// Snapshot of the itemIDs the player currently carries. Rebuilt by a
+// pure-C inventory walk (no Lua stack — safe at world-tick time) at most
+// once per kOwnedRefreshMs, and only while there is queued work.
+static uint32_t g_owned[kMaxOwned];
+static int g_ownedCount = 0;
+static uint32_t g_ownedBuiltMs = 0;
+static bool g_ownedEverBuilt = false;

 static int FindPending(uint32_t itemID) {
    for (int i = 0; i < g_pendingCount; ++i) {
@@ -335,69 +359,170 @@ static const Game::HookAutoRegister _hookCacheResponse{
    reinterpret_cast<void *>(&ItemStatsCacheResponse_h),
    reinterpret_cast<void **>(&ItemStatsCacheResponse_o)};

-// Escalation + timeout. The hook covers the happy path (engine fills
-// cache → we fire). This tick is only responsible for:
+// --- Owned-item priority set --------------------------------------------
+//
+// Determines which pending items are the player's carried inventory so
+// OnWorldTick can issue them ahead of background bulk lookups. The walk
+// reads the engine's GUID arrays directly (no Lua stack, no GetItemBySlot
+// bank gate) — the same pure-C pattern `item/Count` uses — so it is safe
+// to run at world-tick time.
+
+static void AddOwned(uint32_t itemID) {
+    if (itemID == 0)
+        return;
+    for (int i = 0; i < g_ownedCount; ++i)
+        if (g_owned[i] == itemID)
+            return; // dedup — stacks / duplicates collapse to one entry
+    if (g_ownedCount < kMaxOwned)
+        g_owned[g_ownedCount++] = itemID;
+}
+
+// Collects itemIDs from linear slots [first, last] of an inventory
+// manager's GUID array (invMgr+OFF_INVMGR_GUID_ARRAY). Empty slots hold a
+// zero GUID and are skipped.
+static void CollectOwnedFrom(const uint8_t *invMgr, int first, int last) {
+    if (invMgr == nullptr)
+        return;
+    auto *guids = Game::Read<const uint64_t *>(
+        invMgr, Offsets::OFF_INVMGR_GUID_ARRAY);
+    if (guids == nullptr)
+        return;
+    for (int slot = first; slot <= last; ++slot) {
+        const uint8_t *item = Item::Location::ResolveByGUID(guids[slot]);
+        if (item != nullptr)
+            AddOwned(static_cast<uint32_t>(Item::ID::FromCGItem(item)));
+    }
+}
+
+static void RebuildOwned() {
+    g_ownedCount = 0;
+    auto *invMgr = Unit::Identity::PlayerInventoryManager();
+    if (invMgr != nullptr) {
+        // Player invMgr linear slots 0..38: equipment + bag-slot items +
+        // backpack (bank starts at INVMGR_BANK_MAIN_FIRST_SLOT = 39).
+        CollectOwnedFrom(invMgr, 0,
+                         Offsets::BACKPACK_LINEAR_BASE + Offsets::BACKPACK_NUM_SLOTS - 1);
+        // Contents of each equipped bag (its own invMgr, slot count at +0).
+        for (int bagID = 1; bagID <= 4; ++bagID) {
+            auto *bagInv =
+                static_cast<const uint8_t *>(Item::Location::EquippedBagInventory(bagID));
+            if (bagInv == nullptr)
+                continue;
+            const int count = static_cast<int>(
+                Game::Read<uint32_t>(bagInv, Offsets::OFF_INVMGR_SLOT_COUNT));
+            if (count > 0)
+                CollectOwnedFrom(bagInv, 0, count - 1);
+        }
+    }
+    g_ownedEverBuilt = true;
+}
+
+static bool IsOwned(uint32_t itemID) {
+    for (int i = 0; i < g_ownedCount; ++i)
+        if (g_owned[i] == itemID)
+            return true;
+    return false;
+}
+
+// Escalation + timeout — and the ONE place any item query is issued, so
+// the rate limiter here governs every path into the cache. This tick is
+// responsible for:
 //   1. Latching the startup gate via a tick-count fallback, in case no
 //      engine response arrives early enough to latch it first.
-//   2. Issuing a query for items the engine doesn't naturally prefetch
-//      (e.g. quest rewards) — but only once `g_settled`, so we don't
-//      race the engine's startup-time state machine. The engine sends
-//      the SMSG, the response handler hook fires the event when the
-//      response lands.
+//   2. Issuing queries — for items the engine doesn't naturally prefetch
+//      (quest rewards) AND for every `WarmCache` miss — but only once
+//      `g_settled` (don't race the engine's startup state machine). The
+//      player's carried items go out first, up to `kOwnedPerTick` per
+//      tick; everything else is background, one per `kMinRequestSpacingMs`
+//      (don't flood the network; issue #25). The engine sends the SMSG;
+//      the response handler hook fires the event when the response lands.
 //   3. Firing failure immediately for items the server rejected (the
 //      escalation callback marked them `failed`), and as a last resort
-//      giving up after `kMaxWaitTicks` for items that never resolve at
-//      all (lost query, server silent) — fire failure.
+//      giving up after `kMaxWaitTicks` for items whose query was already
+//      sent but never resolved (lost query, server silent).
 static void OnWorldTick() {
    if (!g_settled && ++g_worldTicks >= kSettleTicks)
        g_settled = true;
+
+    const uint32_t now = Time::Clock::NowMs();
+
+    // Refresh the carried-item set while there is queued work, at most
+    // once per kOwnedRefreshMs — the set changes slowly and the walk is
+    // pointer-chasing, not free.
+    if (g_settled && g_pendingCount > 0 &&
+        (!g_ownedEverBuilt || Time::Clock::Elapsed(g_ownedBuiltMs, now) >= kOwnedRefreshMs)) {
+        RebuildOwned();
+        g_ownedBuiltMs = now;
+    }
+
+    // Two independent issue budgets this tick:
+    //   - owned (carried) items: up to kOwnedPerTick, no spacing floor —
+    //     bounded and player-visible, so they resolve fast.
+    //   - background items: one, and only once the spacing floor elapsed.
+    // World ticks fire once per frame (~10-16 ms), so the background floor
+    // is wall-clock, not a tick count, to bound its rate regardless of FPS.
+    int ownedBudget = g_settled ? kOwnedPerTick : 0;
+    bool bgAvailable =
+        g_settled && Time::Clock::Elapsed(g_lastRequestMs, now) >= kMinRequestSpacingMs;
+
    for (int i = 0; i < g_pendingCount;) {
-        if (!g_pending[i].requestIssued && g_settled) {
-            CacheFetch(g_pending[i].itemID, &ItemLoadCallback_Escalated);
-            g_pending[i].requestIssued = true;
+        if (g_settled && !g_pending[i].requestIssued) {
+            const bool owned = IsOwned(g_pending[i].itemID);
+            bool issue = false;
+            if (owned && ownedBudget > 0) {
+                issue = true;
+                --ownedBudget;
+            } else if (!owned && bgAvailable) {
+                issue = true;
+                bgAvailable = false;
+                g_lastRequestMs = now;
+            }
+            if (issue) {
+                CacheFetch(g_pending[i].itemID, &ItemLoadCallback_Escalated);
+                g_pending[i].requestIssued = true;
+            }
        }
-        // A server rejection (marked by the escalation callback) resolves
-        // the item as failure without waiting out the timeout.
+        // A fill (engine response) or a server rejection (escalation
+        // callback set `failed`) resolves the item either way.
        if (TryCompletePending(i))
            continue;
-        if (g_pending[i].ticksWaiting >= kMaxWaitTicks) {
-            const uint32_t itemID = g_pending[i].itemID;
-            const bool implicit = g_pending[i].implicit;
-            RemovePendingAt(i);
-            FireByTag(itemID, false, implicit);
-            continue;
+        // Only time out items whose query is actually in flight. Counting
+        // from track-time would fire spurious failures for items still
+        // waiting their turn behind the rate limiter.
+        if (g_pending[i].requestIssued) {
+            if (g_pending[i].ticksWaiting >= kMaxWaitTicks) {
+                const uint32_t itemID = g_pending[i].itemID;
+                const bool implicit = g_pending[i].implicit;
+                RemovePendingAt(i);
+                FireByTag(itemID, false, implicit);
+                continue;
+            }
+            ++g_pending[i].ticksWaiting;
        }
-        ++g_pending[i].ticksWaiting;
        ++i;
    }
 }

 static const Tick::WorldTick::AutoSubscribe _tickSub{&OnWorldTick};

-// Public C++ API — see Item/Data.h. Implicit (transparent) warmup
-// path used by the `Script_GetItemInfo` hook and `SetItemByID`. Fires
-// the cache request only if the item isn't already cached; uses the
-// implicit callback which fires only `GET_ITEM_INFO_RECEIVED` (not
-// `ITEM_DATA_LOAD_RESULT`), matching modern semantics for ambient
-// cache fills.
+// Public C++ API — see Item/Data.h. Implicit (transparent) warmup path
+// used by the `Script_GetItemInfo` hook and `SetItemByID`. Routes every
+// call through the pending queue so OnWorldTick's single rate-limited
+// issue point governs all outgoing item queries (issue #25). `Track`
+// resolves an already-cached item for free (a pure lookup, no SMSG) and
+// queues only a genuine miss; the response-handler sweep then fires
+// `GET_ITEM_INFO_RECEIVED` (implicit), never `ITEM_DATA_LOAD_RESULT`.
 void WarmCache(uint32_t itemID) {
-    // Post-settle (steady state): query immediately for lowest latency.
-    // The engine invokes our implicit callback when the data lands.
-    if (g_settled) {
-        CacheFetch(itemID, &ItemLoadCallback_Implicit);
-        return;
-    }
-    // Startup window: do NOT eagerly create the cache entry — that
-    // orphans it (the engine's prefetch skips already-existing entries,
-    // and our SMSG goes into a hole while dispatch isn't ready), leaving
-    // the item permanently nil for the session. This is the exact race
-    // that broke pfQuest/Questie scanning at PLAYER_ENTERING_WORLD. Defer
-    // through the pending set instead; OnWorldTick issues the query once
-    // settled and the response-handler sweep fires GET_ITEM_INFO_RECEIVED.
-    //
-    // NOTE: g_settled is a one-way latch per process. The race this
-    // guards is the initial-login cold-WDB window. On relog the WDB is
-    // already warm so cold-fetch pressure is minimal; we don't re-arm it.
+    // Do NOT issue the query here. Two reasons converge on the queue:
+    //   - Network: a post-settle immediate CacheFetch let a reload-time
+    //     lookup burst fire one SMSG per item in a single frame and flood
+    //     the network (issue #25). The queue's rate limiter prevents it.
+    //   - Startup race: eagerly creating the cache entry before the engine
+    //     settles orphans it — the engine's prefetch skips already-existing
+    //     entries and our SMSG goes into a hole while dispatch isn't ready,
+    //     leaving the item permanently nil. This broke pfQuest/Questie
+    //     scanning at PLAYER_ENTERING_WORLD. OnWorldTick issues only once
+    //     `g_settled`, so deferring here fixes that too.
    Track(itemID, /*implicit=*/true);
 }

@@ -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 *>(
@@ -83,8 +83,8 @@ int __fastcall Script_C_Item_GetEnchantInfo(void *L) {
    // Localized display name (8-slot locale array at +0x34). Clamp the
    // locale index to the array bounds — index 8 would read the locale
    // mask column that follows. enUS (0) fallback for empty slots.
-    auto names = reinterpret_cast<const char *const *>(rec + Offsets::OFF_SPELLITEMENCHANT_NAME);
-    int locale = *reinterpret_cast<const int *>(Offsets::VAR_LOCALE_INDEX);
+    auto names = Game::Ptr<const char *const>(rec, Offsets::OFF_SPELLITEMENCHANT_NAME);
+    int locale = Game::Read<int>(Offsets::VAR_LOCALE_INDEX);
    if (locale < 0 || locale >= kNumNameLocales)
        locale = 0;
    const char *name = names[locale];
@@ -93,9 +93,9 @@ int __fastcall Script_C_Item_GetEnchantInfo(void *L) {
    if (name == nullptr || name[0] == '\0')
        return 0; // unnamed record -> nil

-    auto type = reinterpret_cast<const int32_t *>(rec + Offsets::OFF_SPELLITEMENCHANT_TYPE);
-    auto amount = reinterpret_cast<const int32_t *>(rec + Offsets::OFF_SPELLITEMENCHANT_AMOUNT);
-    auto arg = reinterpret_cast<const int32_t *>(rec + Offsets::OFF_SPELLITEMENCHANT_ARG);
+    auto type = Game::Ptr<const int32_t>(rec, Offsets::OFF_SPELLITEMENCHANT_TYPE);
+    auto amount = Game::Ptr<const int32_t>(rec, Offsets::OFF_SPELLITEMENCHANT_AMOUNT);
+    auto arg = Game::Ptr<const int32_t>(rec, Offsets::OFF_SPELLITEMENCHANT_ARG);

    Game::Lua::NewTable(L);
    Game::Lua::SetFieldNumber(L, "enchantID", enchantID);
@@ -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;
@@ -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 *>(
@@ -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,19 +37,8 @@ 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);
+    return Game::Read<int>(Offsets::VAR_LOCALE_INDEX);
 }

 // Mirrors the lookup in `Item::Info`. ItemClass.dbc record `+0x0C` is
@@ -63,10 +53,10 @@ const char *LookupClassName(uint32_t classID) {
 // ItemSubClass.dbc walker — same fallback chain as Script_GetItemInfo
 // (verbose name first, short name on miss).
 const char *LookupSubClassName(uint32_t classID, uint32_t subClassID) {
-    const int count = *reinterpret_cast<int *>(Offsets::VAR_ITEMSUBCLASS_COUNT);
+    const int count = Game::Read<int>(Offsets::VAR_ITEMSUBCLASS_COUNT);
    if (count <= 0)
        return "";
-    auto *records = *reinterpret_cast<const uint8_t *const *>(Offsets::VAR_ITEMSUBCLASS_RECORDS);
+    auto *records = Game::Read<const uint8_t *>(Offsets::VAR_ITEMSUBCLASS_RECORDS);
    if (records == nullptr)
        return "";
    const int locale = CurrentLocaleIndex();
@@ -76,12 +66,12 @@ const char *LookupSubClassName(uint32_t classID, uint32_t subClassID) {
            continue;
        if (*reinterpret_cast<const uint32_t *>(record + 0x04) != subClassID)
            continue;
-        const char *verbose = *reinterpret_cast<const char *const *>(
-            record + Offsets::OFF_ITEMSUBCLASS_DISPLAY_NAME + locale * 4);
+        const char *verbose = Game::Read<const char *>(
+            record, Offsets::OFF_ITEMSUBCLASS_DISPLAY_NAME + locale * 4);
        if (verbose != nullptr && verbose[0] != '\0')
            return verbose;
-        const char *shortName = *reinterpret_cast<const char *const *>(
-            record + Offsets::OFF_ITEMSUBCLASS_NAME + locale * 4);
+        const char *shortName = Game::Read<const char *>(
+            record, Offsets::OFF_ITEMSUBCLASS_NAME + locale * 4);
        return (shortName != nullptr && shortName[0] != '\0') ? shortName : "";
    }
    return "";
@@ -182,10 +172,10 @@ void SetF32Array(void *L, const uint8_t *record, const char *key,
 void SetStatsMap(void *L, const uint8_t *record) {
    Game::Lua::PushString(L, "stats");
    Game::Lua::NewTable(L);
-    auto *types = reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_STAT_TYPE);
-    auto *values = reinterpret_cast<const int32_t *>(
-        record + Offsets::OFF_ITEMSTATS_STAT_VALUE);
+    auto *types = Game::Ptr<const uint32_t>(
+        record, Offsets::OFF_ITEMSTATS_STAT_TYPE);
+    auto *values = Game::Ptr<const int32_t>(
+        record, Offsets::OFF_ITEMSTATS_STAT_VALUE);
    for (int i = 0; i < Offsets::ITEMSTATS_STAT_SLOT_COUNT; ++i) {
        if (types[i] == 0 && values[i] == 0)
            continue;
@@ -203,18 +193,18 @@ void SetStatsMap(void *L, const uint8_t *record) {
 void SetSpellsArray(void *L, const uint8_t *record) {
    Game::Lua::PushString(L, "spells");
    Game::Lua::NewTable(L);
-    auto *ids = reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_SPELL_ID);
-    auto *triggers = reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_SPELL_TRIGGER);
-    auto *charges = reinterpret_cast<const int32_t *>(
-        record + Offsets::OFF_ITEMSTATS_SPELL_CHARGES);
-    auto *cooldowns = reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_SPELL_COOLDOWN);
-    auto *categories = reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_SPELL_CATEGORY);
-    auto *catCooldowns = reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_SPELL_CATEGORY_CD);
+    auto *ids = Game::Ptr<const uint32_t>(
+        record, Offsets::OFF_ITEMSTATS_SPELL_ID);
+    auto *triggers = Game::Ptr<const uint32_t>(
+        record, Offsets::OFF_ITEMSTATS_SPELL_TRIGGER);
+    auto *charges = Game::Ptr<const int32_t>(
+        record, Offsets::OFF_ITEMSTATS_SPELL_CHARGES);
+    auto *cooldowns = Game::Ptr<const uint32_t>(
+        record, Offsets::OFF_ITEMSTATS_SPELL_COOLDOWN);
+    auto *categories = Game::Ptr<const uint32_t>(
+        record, Offsets::OFF_ITEMSTATS_SPELL_CATEGORY);
+    auto *catCooldowns = Game::Ptr<const uint32_t>(
+        record, Offsets::OFF_ITEMSTATS_SPELL_CATEGORY_CD);
    int written = 0;
    for (int i = 0; i < Offsets::ITEMSTATS_SPELL_SLOT_COUNT; ++i) {
        if (ids[i] == 0)
@@ -244,38 +234,38 @@ void PushItemDataTable(void *L, uint32_t itemID, const uint8_t *record) {
    Game::Lua::SetFieldNumber(L, "itemID", static_cast<double>(itemID));

    // Identity strings
-    const char *name = *reinterpret_cast<const char *const *>(
-        record + Offsets::OFF_ITEMSTATS_NAME);
+    const char *name = Game::Read<const char *>(
+        record, Offsets::OFF_ITEMSTATS_NAME);
    Game::Lua::SetFieldString(L, "name", name);
-    const char *description = *reinterpret_cast<const char *const *>(
-        record + Offsets::OFF_ITEMSTATS_DESCRIPTION);
+    const char *description = Game::Read<const char *>(
+        record, Offsets::OFF_ITEMSTATS_DESCRIPTION);
    if (description != nullptr && description[0] != '\0')
        Game::Lua::SetFieldString(L, "description", description);

    // Display
-    const uint32_t displayInfoID = *reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_DISPLAY_INFO_ID);
+    const uint32_t displayInfoID = Game::Read<uint32_t>(
+        record, Offsets::OFF_ITEMSTATS_DISPLAY_INFO_ID);
    Game::Lua::SetFieldNumber(L, "displayInfoID", static_cast<double>(displayInfoID));
    char iconPath[260];
    if (BuildIconPath(displayInfoID, iconPath, sizeof(iconPath)))
        Game::Lua::SetFieldString(L, "icon", iconPath);

    // Quality / classification
-    const uint32_t quality = *reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_QUALITY);
+    const uint32_t quality = Game::Read<uint32_t>(
+        record, Offsets::OFF_ITEMSTATS_QUALITY);
    Game::Lua::SetFieldNumber(L, "quality", static_cast<double>(quality));

-    const uint32_t classID = *reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_CLASS);
-    const uint32_t subClassID = *reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_SUBCLASS);
+    const uint32_t classID = Game::Read<uint32_t>(
+        record, Offsets::OFF_ITEMSTATS_CLASS);
+    const uint32_t subClassID = Game::Read<uint32_t>(
+        record, Offsets::OFF_ITEMSTATS_SUBCLASS);
    Game::Lua::SetFieldNumber(L, "classID", static_cast<double>(classID));
    Game::Lua::SetFieldNumber(L, "subclassID", static_cast<double>(subClassID));
    Game::Lua::SetFieldString(L, "className", LookupClassName(classID));
    Game::Lua::SetFieldString(L, "subclassName", LookupSubClassName(classID, subClassID));

-    const uint32_t invType = *reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_INVENTORY_TYPE);
+    const uint32_t invType = Game::Read<uint32_t>(
+        record, Offsets::OFF_ITEMSTATS_INVENTORY_TYPE);
    Game::Lua::SetFieldNumber(L, "inventoryType", static_cast<double>(invType));
    Game::Lua::SetFieldString(L, "equipLoc", LookupInvType(invType));

@@ -283,8 +273,8 @@ void PushItemDataTable(void *L, uint32_t itemID, const uint8_t *record) {
    SetU32(L, record, "bindType", Offsets::OFF_ITEMSTATS_BONDING);

    // Flags: raw + decoded bits.
-    const uint32_t flags = *reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_FLAGS);
+    const uint32_t flags = Game::Read<uint32_t>(
+        record, Offsets::OFF_ITEMSTATS_FLAGS);
    Game::Lua::SetFieldNumber(L, "flags", static_cast<double>(flags));
    Game::Lua::SetFieldBool(L, "isConjured",
                            (flags & Offsets::ITEM_FLAG_CONJURED) != 0);
@@ -299,8 +289,8 @@ void PushItemDataTable(void *L, uint32_t itemID, const uint8_t *record) {
    SetI32(L, record, "maxStackSize", Offsets::OFF_ITEMSTATS_STACKABLE);
    SetI32(L, record, "maxCount", Offsets::OFF_ITEMSTATS_MAX_COUNT);
    SetU32(L, record, "containerSlots", Offsets::OFF_ITEMSTATS_CONTAINER_SLOTS);
-    const uint32_t rawBagFamily = *reinterpret_cast<const uint32_t *>(
-        record + Offsets::OFF_ITEMSTATS_BAG_FAMILY);
+    const uint32_t rawBagFamily = Game::Read<uint32_t>(
+        record, Offsets::OFF_ITEMSTATS_BAG_FAMILY);
    Game::Lua::SetFieldNumber(L, "bagFamily",
                              static_cast<double>(BagFamilyIdToBitmask(rawBagFamily)));

@@ -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;
@@ -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 *>(
--- a/Show More
+++ b/Show More