fix(object): gate ByGuid on the registry root to survive out-of-world calls

The engine resolver FUN_OBJECT_RESOLVE_BY_GUID funnels unconditionally
into FUN_00464890, whose first action loads the registry root from
[VAR_LOCAL_PLAYER_PTR] and derefs its +0x24 hash mask with no null
check. That root is NULL out of world (login, loading screens, logout
teardown), so any resolve reaching it mid-transition dies with ERROR
#132 (MOV EAX,[EDX+0x24], EDX=0) - hit in the wild by Aura::Source's
SMSG_SPELL_GO path, whose Store/Claim eviction consults
DescriptorListsAura while packets still dispatch during transitions.

Promote the readiness predicate from Unit::TokenObserver's private
RegistryReady into Object::RegistryReady (object/Resolve.h) and gate
ByGuid on it, returning nullptr out of world. That is both the
contract ByGuid's comment already promised ("pre-world ... safe from
any context") and provably behavior-preserving: a zero result is the
engine's own handled "not found" case (verified in Ghidra - 0x468460
null-checks the node; 0x464870 itself returns 0 for guid==0), and out
of world the call had no non-crashing outcome. Every ByGuid call site
already null-checks. TokenObserver now delegates to the shared helper.

Fixes #34

.github/workflows/build.yml

@@ -4,48 +4,130 @@ 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
 
+      # Bundle both debug artifacts into one zip so a crash from a shipped DLL
+      # can be triaged exactly. The PDB gives WinDbg/x64dbg/VS a line-level
+      # symbolicated call stack from a crash dump; the map resolves the
+      # `0001:offset` addresses in WoW's ERROR #132 crash log by hand when no
+      # dump is available. Both match THIS exact DLL build.
+      # The filename is deliberately off-putting: it is NOT the addon and has no
+      # value to a normal player. The loud all-caps name keeps them from
+      # grabbing it by mistake; the tag suffix lets a dev match symbols to the
+      # exact build. (pdb/map keep their real names inside so the pdb signature
+      # still lines up with the DLL.)
+      - name: Package debug symbols for release
+        if: steps.ver.outputs.is_release == 'true'
+        run: >
+          Compress-Archive
+          -Path build/Release/ClassicAPI.pdb, build/Release/ClassicAPI.map
+          -DestinationPath build/Release/Crash-Symbols-Use-For-Debugging-${{ steps.ver.outputs.tag }}.zip
+          -Force
+
       - 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/Crash-Symbols-Use-For-Debugging-${{ steps.ver.outputs.tag }}.zip
           generate_release_notes: true

.gitignore

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

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

@@ -7,6 +7,7 @@
 
 locales\locales.xml
 
+SecureTemplates.xml
 Compat.lua
 Util\Print.lua
 Util\Mixin.lua
@@ -38,3 +39,14 @@ Util\LinkUtil.lua
 Util\TradeSkillLink.lua
 Util\IconDataProvider.lua
 Util\GameTooltip.lua
+Util\Rectangle.lua
+Util\Vector2D.lua
+Util\Vector3D.lua
+Util\Vector4D.lua
+Util\UIParent.lua
+Util\AuraDurationModifiers.lua
+Util\AuraUtil.lua
+Util\SecureUnitMenu.lua
+Util\TextureUtil.lua
+Util\MacroOptions.lua
+Util\SecureStateDriver.lua

AddOns/!!!ClassicAPI/SecureTemplates.lua

@@ -0,0 +1,125 @@
+-- SecureTemplates.lua — Lua-side helpers for SecureActionButtonTemplate et al.
+--
+-- Backport of the modifier/button attribute-resolution functions from
+-- Blizzard's 2.0 SecureTemplates.lua that addons call directly
+-- (SecureButton_GetModifiedAttribute, SecureButton_GetModifierPrefix,
+-- SecureButton_GetUnit, …), plus the SecureUnitButton_OnLoad convenience.
+--
+-- Click dispatch is NOT here: the C++ Frame::Attributes module is the single
+-- dispatcher. Setting a "type*" attribute on a frame installs a native OnClick
+-- that resolves the verb (target/spell/item/macro/focus/assist/stop/menu/
+-- action/pet/click/custom), so the templates carry no <OnClick> and there is no
+-- parallel Lua dispatcher to drift out of sync.
+
+-- The "modified attribute" takes the form of: modifier-name-button
+-- The modifier is one of "shift-", "ctrl-", "alt-", and the button is a
+-- number from 1 through 5.
+--
+-- Setting the attribute by itself is equivalent to *attribute*
+
+ATTRIBUTE_NOOP = "";
+
+function SecureButton_GetModifierPrefix()
+    local prefix = "";
+    if IsShiftKeyDown() then
+        prefix = "shift-" .. prefix;
+    end
+    if IsControlKeyDown() then
+        prefix = "ctrl-" .. prefix;
+    end
+    if IsAltKeyDown() then
+        prefix = "alt-" .. prefix;
+    end
+    return prefix;
+end
+
+function SecureButton_GetButtonSuffix(button)
+    if button == "LeftButton" then
+        return "1";
+    elseif button == "RightButton" then
+        return "2";
+    elseif button == "MiddleButton" then
+        return "3";
+    elseif button == "Button4" then
+        return "4";
+    elseif button == "Button5" then
+        return "5";
+    elseif button and button ~= "" then
+        return "-" .. tostring(button);
+    end
+    return "";
+end
+
+function SecureButton_GetModifiedAttribute(frame, name, button, prefix, suffix)
+    if not prefix then
+        prefix = SecureButton_GetModifierPrefix();
+    end
+    if not suffix then
+        suffix = SecureButton_GetButtonSuffix(button);
+    end
+    local value = frame:GetAttribute(prefix .. name .. suffix) or
+                  frame:GetAttribute("*" .. name .. suffix) or
+                  frame:GetAttribute(prefix .. name .. "*") or
+                  frame:GetAttribute("*" .. name .. "*") or
+                  frame:GetAttribute(name);
+    if not value and (frame:GetAttribute("useparent-" .. name) or
+                      frame:GetAttribute("useparent*")) then
+        local parent = frame:GetParent();
+        if parent then
+            value = SecureButton_GetModifiedAttribute(parent, name, button, prefix, suffix);
+        end
+    end
+    if value == ATTRIBUTE_NOOP then
+        value = nil;
+    end
+    return value;
+end
+
+-- Unmodified attribute lookup (no modifier prefix, no button suffix).
+-- Overrides the simpler version in SecureStateDriver.lua with the full
+-- parent-walk + ATTRIBUTE_NOOP semantics.
+function SecureButton_GetAttribute(frame, name)
+    return SecureButton_GetModifiedAttribute(frame, name, nil, "", "");
+end
+
+function SecureButton_GetModifiedUnit(self, button)
+    local unit = SecureButton_GetModifiedAttribute(self, "unit", button);
+    if unit then
+        local unitsuffix = SecureButton_GetModifiedAttribute(self, "unitsuffix", button);
+        if unitsuffix then
+            unit = unit .. unitsuffix;
+            unit = string.gsub(unit, "^([^%d]+)([%d]+)[pP][eE][tT]", "%1pet%2");
+        end
+        return unit;
+    end
+    if SecureButton_GetModifiedAttribute(self, "checkselfcast", button) then
+        if IsAltKeyDown() then
+            return "player";
+        end
+    end
+end
+
+function SecureButton_GetUnit(self)
+    local unit = SecureButton_GetAttribute(self, "unit");
+    if unit then
+        local unitsuffix = SecureButton_GetAttribute(self, "unitsuffix");
+        if unitsuffix then
+            unit = unit .. unitsuffix;
+            unit = string.gsub(unit, "^([^%d]+)([%d]+)[pP][eE][tT]", "%1pet%2");
+        end
+        return unit;
+    end
+end
+
+-- ---------------------------------------------------------------------------
+-- SecureUnitButton_OnLoad — convenience for the common unit-button setup:
+-- left-click targets, any other button opens the right-click unit menu. The
+-- click behavior itself is native: setting these "type*"/"unit" attributes is
+-- what makes the C++ Frame::Attributes dispatcher act on the clicks.
+-- ---------------------------------------------------------------------------
+
+function SecureUnitButton_OnLoad(self, unit)
+    self:SetAttribute("type1", "target");
+    self:SetAttribute("type*", "menu");
+    self:SetAttribute("unit", unit);
+end

AddOns/!!!ClassicAPI/SecureTemplates.xml

@@ -0,0 +1,21 @@
+<Ui xmlns="http://www.blizzard.com/wow/ui/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.blizzard.com/wow/ui/
+..\FrameXML\UI.xsd">
+	<Script file="SecureTemplates.lua"/>
+
+	<!-- A base template for secure frames (no-op in 1.12, no taint system) -->
+	<Frame name="SecureFrameTemplate" virtual="true"/>
+
+	<!-- Secure action button. Click behavior is driven natively by the C++
+	     Frame::Attributes module: setting a "type*" attribute installs the
+	     OnClick dispatcher, so the template itself needs no <OnClick>. -->
+	<Button name="SecureActionButtonTemplate" inherits="SecureFrameTemplate" virtual="true"/>
+
+	<!-- Unit-button variant (identical to the action button on 1.12; its
+	     "type"/"unit" attributes drive it). SecureUnitButton_OnLoad is a Lua
+	     convenience for the common target + right-click-menu setup. -->
+	<Button name="SecureUnitButtonTemplate" inherits="SecureFrameTemplate" virtual="true"/>
+
+	<!-- Insecure variant: identical behavior in 1.12 (no combat lockdown), so
+	     just inherit the secure template rather than duplicate its OnClick. -->
+	<Button name="InsecureActionButtonTemplate" inherits="SecureActionButtonTemplate" virtual="true"/>
+</Ui>

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

@@ -15,12 +15,15 @@ if C_AddOns.DoesAddOnExist('pfUI') then
         -- written for on their pfActionBar buttons, which breaks them. While
         -- the actionbar module builds those buttons, temporarily wrap
         -- CreateFrame to shadow HookScript with a falsy field so those forks
-        -- fall back to their vanilla SetScript path. The maintained "brues"
-        -- fork handles HookScript itself, so it's detected via the TOC
-        -- X-Website tag and left alone. The wrapper is removed as soon as the
-        -- actionbar module finishes loading so it affects nothing else.
+        -- fall back to their vanilla SetScript path. The wrapper is removed as
+        -- soon as the actionbar module finishes loading so it affects nothing
+        -- else. A pfUI is trusted to handle HookScript itself if EITHER signal
+        -- is present: the maintained "brues" X-Website tag OR the
+        -- `pfUI.handlesHookScript` capability flag. Without the website the
+        -- flag is required; if neither is present we apply the shim.
         local website = GetAddOnMetadata("pfUI", "X-Website")
-        if not website or not strfind(website, 'brues') then
+        local hasBruesWebsite = website and strfind(website, 'brues')
+        if not hasBruesWebsite and not pfUI.handlesHookScript then
             local _createFrame = CreateFrame
             local HookedCreateFrame = function(frameType, name, parent, template)
                 local frame = _createFrame(frameType, name, parent, template)
@@ -38,4 +41,59 @@ if C_AddOns.DoesAddOnExist('pfUI') then
             end)
         end
     end)
-end
+end
+
+if C_AddOns.DoesAddOnExist("SpecialTalentUI") then
+    EventUtil.ContinueOnAddOnLoaded("SpecialTalentUI", CAPI_ApplyStandardColorGlobals)
+end
+
+-- ShaguTweaks libpredict register's TBC events that ClassicAPI backports.
+if C_AddOns.DoesAddOnExist("ShaguTweaks") then
+    EventUtil.ContinueOnAddOnLoaded("ShaguTweaks", function()
+        local libp = ShaguTweaks.libpredict
+        if libp then
+            libp.sender:UnregisterEvent("COMBAT_LOG_EVENT_UNFILTERED")
+            libp.sender:UnregisterEvent("UNIT_SPELLCAST_START")
+            libp.sender:UnregisterEvent("UNIT_SPELLCAST_STOP")
+            libp.sender:UnregisterEvent("UNIT_SPELLCAST_FAILED")
+            libp.sender:UnregisterEvent("UNIT_SPELLCAST_INTERRUPTED")
+            libp.sender:UnregisterEvent("UNIT_SPELLCAST_SENT")
+        end
+    end)
+end
+
+-- Guard UPDATE_MOUSEOVER_UNIT handlers (issue #12).
+function CAPI_MouseoverClearedCompat(frame)
+    if not frame then return end
+    local originalOnEvent = frame:GetScript("OnEvent")
+    frame:SetScript("OnEvent", function()
+        if event == "UPDATE_MOUSEOVER_UNIT" and not UnitExists("mouseover") then
+            return
+        end
+
+        if originalOnEvent then
+            originalOnEvent()
+        end
+    end)
+end
+
+CAPI_MouseoverClearedCompat(GameTooltip)
+
+if C_AddOns.DoesAddOnExist("Puppeteer") then
+    EventUtil.ContinueOnAddOnLoaded("Puppeteer", function()
+        CAPI_MouseoverClearedCompat(PTEnemyUpdater)
+    end)
+end
+
+-- Cartographer_Notes gates a WorldMap release-spirit hook behind an
+-- `if lua51` probe, treating a 5.1-capable Lua as a modern client that has
+-- the WorldMapDeathRelease frame. Our 5.1 syntax backport makes the probe
+-- pass, so Cartographer takes the modern branch and hooks a frame 1.12's
+-- WorldMap never had (WorldMapDeathRelease:SetScript in OnEnable) -> nil
+-- index. Provide an inert, hidden stub so the hook succeeds and does nothing
+-- -- the same outcome vanilla had, where the branch never ran. The embedded
+-- !!!ClassicAPI addon loads first, so the frame exists before Cartographer's
+-- OnEnable.
+if C_AddOns.DoesAddOnExist("Cartographer") and not WorldMapDeathRelease then
+    CreateFrame("Button", "WorldMapDeathRelease", WorldMapButton or UIParent):Hide()
+end

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

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

AddOns/!!!ClassicAPI/Util/AuraUtil.lua

@@ -0,0 +1,128 @@
+-- AuraUtil: iterate / find auras without allocating a table per aura.
+--
+-- Backport of FrameXML's AuraUtil, the helper library that sits on top of
+-- C_UnitAuras. Its whole value on 1.12 is the zero-allocation path: modern
+-- addons that scan many units' auras every frame call AuraUtil.ForEachAura (with
+-- usePackedAura false) instead of C_UnitAuras.GetAuraDataByIndex, so no AuraData
+-- table is built per aura -- which matters far more under Lua 5.0's mark-sweep
+-- GC than it does on retail's generational GC. See ClassicAPI issue #30.
+--
+-- Ported from the anniversary source (Blizzard_FrameXMLUtil/AuraUtil.lua),
+-- keeping the exact public shapes:
+--   * ForEachAura(unit, filter, batchSize, func, usePackedAura)
+--   * FindAura(predicate, unit, filter, arg1, arg2, arg3)
+--   * FindAuraByName(auraName, unit, filter)
+--   * UnpackAuraData(auraData)
+--
+-- Two deliberate differences from that source:
+--   1. Retail's ForEachAura/FindAura batch through GetAuraSlots / GetAuraDataBySlot
+--      (continuation tokens) -- 1.12 has no slot-batching API, so the bodies here
+--      iterate by index (1, 2, ...) until the accessor returns no aura. Same public
+--      contract, different internals.
+--   2. The non-packed ForEachAura and FindAura source each aura from the positional
+--      C_UnitAuras.UnitAura (no table), so both are zero-allocation here -- FindAura
+--      in particular, where the retail version allocates a table per aura scanned.
+--
+-- The comparator / dispel-priority / border helpers (DefaultAuraCompare,
+-- UnitFrameDebuffComparator, ShouldDisplayDebuff, SetAuraBorder*, IsPriorityDebuff)
+-- are NOT ported: they depend on isPriorityAura / auraInstanceID / the aura
+-- visualization pipeline / secure-call machinery, none of which exist on 1.12.
+
+local UnitAura = C_UnitAuras.UnitAura
+
+AuraUtil = AuraUtil or {};
+
+-- Returns the AuraData table's fields in the classic `UnitAura` positional order,
+-- for code written against that shape. Retail appends `unpack(auraData.points)`;
+-- vanilla auras carry no points, so the tuple ends at timeMod (15 values). Field
+-- #13 is `isFromPlayerOrPlayerPet` (the table's field) -- note the positional
+-- C_UnitAuras.UnitAura reports the higher-fidelity `castByPlayer` at #13 instead.
+function AuraUtil.UnpackAuraData(auraData)
+    if not auraData then
+        return nil;
+    end
+    return auraData.name,
+        auraData.icon,
+        auraData.applications,
+        auraData.dispelName,
+        auraData.duration,
+        auraData.expirationTime,
+        auraData.sourceUnit,
+        auraData.isStealable,
+        auraData.nameplateShowPersonal,
+        auraData.spellId,
+        auraData.canApplyAura,
+        auraData.isBossAura,
+        auraData.isFromPlayerOrPlayerPet,
+        auraData.nameplateShowAll,
+        auraData.timeMod;
+end
+
+-- Calls `func` for each aura on `unit` matching `filter`, in index order, until
+-- `func` returns a truthy value or the auras run out. Non-packed (default) passes
+-- the 15 positional `UnitAura` values (no table); `usePackedAura` passes the
+-- AuraData table from GetAuraDataByIndex. `batchSize <= 0` does nothing; any other
+-- value (or nil) visits every matching aura -- `batchSize` is retail's slot-batch
+-- hint, not a cap on how many auras are visited.
+function AuraUtil.ForEachAura(unit, filter, batchSize, func, usePackedAura)
+    if batchSize and batchSize <= 0 then
+        return;
+    end
+    local index = 1;
+    while true do
+        local done;
+        if usePackedAura then
+            local auraData = C_UnitAuras.GetAuraDataByIndex(unit, index, filter);
+            if auraData == nil then
+                return;
+            end
+            done = func(auraData);
+        else
+            local name, icon, count, dispelType, duration, expirationTime, source,
+                isStealable, nameplateShowPersonal, spellId, canApplyAura,
+                isBossDebuff, castByPlayer, nameplateShowAll, timeMod =
+                UnitAura(unit, index, filter);
+            if name == nil then
+                return;
+            end
+            done = func(name, icon, count, dispelType, duration, expirationTime,
+                source, isStealable, nameplateShowPersonal, spellId, canApplyAura,
+                isBossDebuff, castByPlayer, nameplateShowAll, timeMod);
+        end
+        if done then
+            return;
+        end
+        index = index + 1;
+    end
+end
+
+-- Recursive worker: `...` is the current aura's positional values (nil when the
+-- index is past the last aura). Tail-recurses to the next index. Lua 5.0 has
+-- proper tail calls, so depth is constant regardless of aura count.
+local function FindAuraRecurse(predicate, unit, filter, index, arg1, arg2, arg3, ...)
+    if ... == nil then
+        return nil; -- past the last aura -> not found
+    end
+    if predicate(arg1, arg2, arg3, ...) then
+        return ...;
+    end
+    index = index + 1;
+    return FindAuraRecurse(predicate, unit, filter, index, arg1, arg2, arg3,
+        UnitAura(unit, index, filter));
+end
+
+-- Returns the positional values of the first aura for which `predicate` returns
+-- truthy, or nil. `predicate` receives up to three caller args followed by the
+-- aura's positional values: predicate(arg1, arg2, arg3, name, icon, ...). Sources
+-- auras from the positional accessor, so no table is allocated while scanning.
+function AuraUtil.FindAura(predicate, unit, filter, arg1, arg2, arg3)
+    return FindAuraRecurse(predicate, unit, filter, 1, arg1, arg2, arg3,
+        UnitAura(unit, 1, filter));
+end
+
+-- Returns the positional values of the first aura whose name matches `auraName`,
+-- or nil. Names are localized and not unique -- this finds the first match.
+function AuraUtil.FindAuraByName(auraName, unit, filter)
+    return AuraUtil.UnpackAuraData(
+        C_UnitAuras.GetAuraDataBySpellName(unit, auraName, filter));
+end

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

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

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

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

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

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

AddOns/!!!ClassicAPI/Util/Constants.lua

@@ -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;

AddOns/!!!ClassicAPI/Util/FormattingUtil.lua

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

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

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

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

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

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

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

AddOns/!!!ClassicAPI/Util/MacroOptions.lua

@@ -0,0 +1,488 @@
+-- SecureCmdOptionParse(options) -> value[, target]
+--
+-- Backports the macro-conditional parser (added in 2.0) so a modern option
+-- string like "[combat,@focus] Foo; [nostealth] Bar; Baz" resolves to the
+-- value of the first matching clause. Used by Util/SecureStateDriver.lua and
+-- callable by any macro / click-verb system that wants Blizzard's grammar.
+--
+-- Grammar reverse-engineered from the 3.3.5 Wow.exe (functions 0x005f0df0
+-- clause splitter, 0x005f0bb0 group parser, 0x005f0040 condition parser,
+-- 0x005ef5c0 evaluator), so it matches Blizzard's own precedence exactly:
+--   * clauses are split on ';' at bracket depth 0;
+--   * a clause is zero or more [group] blocks followed by a value (the text
+--     after the last ']', edge-trimmed -- may be empty);
+--   * a clause with NO groups always matches; groups are OR'd (first pass
+--     wins); conditions inside a group are comma-split and AND'd;
+--   * an '@unit' or 'target=unit' piece (case-insensitive) sets the group's
+--     target; every other piece is a condition, optionally negated by a 'no'
+--     prefix (stripped only when the piece is >= 3 chars) and optionally
+--     carrying ':a/b/c' args (each trimmed, multiple args OR'd);
+--   * the match returns the clause value plus the passing group's target
+--     token (nil when the passing group set none).
+--
+-- The 33 condition keywords are the 3.3.5 set, matched case-sensitively, plus
+-- one ClassicAPI extension: [known:spellID] / [known:name].
+-- Where a keyword's underlying state does not exist on 1.12 (flying, flyable,
+-- vehicleui, unithasvehicleui) the condition is a constant false; where 1.12
+-- only has a partial answer (spec is always primary, button/actionbar default
+-- to the resting state) the closest honest mapping is used. An UNKNOWN keyword
+-- is a hard false with a one-time warning -- never a silent pass -- so a typo
+-- can't wrongly show a frame. See docs/API.md for the full contract.
+--
+-- Each unique options string is parsed ONCE into a clause structure and cached
+-- (a plain table, matching the 3.3.5 C hash -- entries are never evicted, and
+-- the set is bounded by the strings addons actually register). Evaluation then
+-- just walks the structure calling predicate functions, so the 0.2s driver
+-- poll re-parses nothing.
+
+local type = type;
+local tonumber = tonumber;
+local strlen = string.len;
+local strsub = string.sub;
+local strlower = string.lower;
+local strmatch = string.match;
+local gmatch = string.gmatch;
+
+local function Trim(s)
+    return strmatch(s, "^%s*(.-)%s*$") or "";
+end
+
+local function AlwaysTrue()
+    return true;
+end
+
+local function AlwaysFalse()
+    return false;
+end
+
+-- ---------------------------------------------------------------------------
+-- Query helpers used by more than one predicate
+-- ---------------------------------------------------------------------------
+
+-- The shapeshift-BAR index of the active form (1-based), or 0 when formless.
+-- [stance:N] / [form:N] number by this bar order (druid 1 = Bear, 3 = Cat),
+-- which is NOT the DBC form id GetShapeshiftFormID() returns -- so the ':N'
+-- form deliberately does not use that faster reader.
+local function GetCurrentFormIndex()
+    for i = 1, GetNumShapeshiftForms() do
+        local _, _, active = GetShapeshiftFormInfo(i);
+        if active then
+            return i;
+        end
+    end
+    return 0;
+end
+
+-- True when any equipped item (slots 1..19) matches `want` by localized item
+-- type, subtype, or equip-location slot name. C_Item.GetItemInfoInstant is
+-- synchronous and link-accepting; worn gear is always cached, and a nil field
+-- simply fails the match (fail-safe).
+local function IsEquippedTypeMatch(want)
+    want = strlower(want);
+    for slot = 1, 19 do
+        local link = GetInventoryItemLink("player", slot);
+        if link then
+            local _, itemType, itemSubType, equipLoc = C_Item.GetItemInfoInstant(link);
+            if (itemType and strlower(itemType) == want)
+                or (itemSubType and strlower(itemSubType) == want) then
+                return true;
+            end
+            if equipLoc and equipLoc ~= "" then
+                local slotName = _G[equipLoc];
+                if slotName and strlower(slotName) == want then
+                    return true;
+                end
+            end
+        end
+    end
+    return false;
+end
+
+-- True when a spell named `want` (case-insensitive) is in the player's
+-- spellbook. This is the name form of [known:...]. There is no name -> id
+-- resolver, so a name can only resolve against castable spellbook entries;
+-- talents / passives / profession recipes that IsPlayerSpell reports for a
+-- spell id are not found by name.
+local function IsSpellNameKnown(want)
+    want = strlower(want);
+    local i = 1;
+    while true do
+        local name = GetSpellName(i, "spell");
+        if not name then
+            return false;
+        end
+        if strlower(name) == want then
+            return true;
+        end
+        i = i + 1;
+    end
+end
+
+-- ---------------------------------------------------------------------------
+-- Condition predicates -- signature f(target, args) -> truthy.
+-- `args` is nil for a bare condition, else { n = <count>, [i] = <trimmed> };
+-- multiple args are OR'd.
+-- ---------------------------------------------------------------------------
+
+local CONDITIONS = {};
+
+CONDITIONS[""] = AlwaysTrue;                      -- empty keyword ([] / [ ]) always matches
+
+CONDITIONS.combat = function()
+    return UnitAffectingCombat("player");
+end
+
+CONDITIONS.exists = function(target)
+    return UnitExists(target);
+end
+
+CONDITIONS.dead = function(target)
+    return UnitIsDeadOrGhost(target);
+end
+
+CONDITIONS.help = function(target)
+    return UnitCanAssist("player", target);
+end
+
+CONDITIONS.harm = function(target)
+    return UnitCanAttack("player", target);
+end
+
+CONDITIONS.party = function(target)
+    return UnitPlayerOrPetInParty(target);
+end
+
+CONDITIONS.raid = function(target)
+    return UnitInRaid(target);
+end
+
+-- [group] = in any group; [group:party] true in a party OR raid (raid members
+-- occupy party subgroups, matching retail); [group:raid] true only in a raid.
+CONDITIONS.group = function(target, args)
+    local inParty = GetNumPartyMembers() > 0;
+    local inRaid = GetNumRaidMembers() > 0;
+    if args then
+        for i = 1, args.n do
+            local a = strlower(args[i]);
+            if a == "raid" then
+                if inRaid then return true; end
+            elseif a == "party" then
+                if inParty or inRaid then return true; end
+            end
+        end
+        return false;
+    end
+    return inParty or inRaid;
+end
+
+CONDITIONS.stance = function(target, args)
+    if args then
+        local cur = GetCurrentFormIndex();
+        for i = 1, args.n do
+            if tonumber(args[i]) == cur then return true; end
+        end
+        return false;
+    end
+    return GetShapeshiftFormID() ~= 0;
+end
+
+CONDITIONS.stealth = function()
+    return IsStealthed();
+end
+
+CONDITIONS.mounted = function()
+    return IsMounted();
+end
+
+CONDITIONS.swimming = function()
+    return IsSwimming();
+end
+
+CONDITIONS.indoors = function()
+    return IsIndoors();
+end
+
+CONDITIONS.outdoors = function()
+    return IsOutdoors();
+end
+
+-- Vanilla has one permanent spec: [spec] and [spec:1] pass, higher indices fail.
+CONDITIONS.spec = function(target, args)
+    if args then
+        for i = 1, args.n do
+            if args[i] == "1" then return true; end
+        end
+        return false;
+    end
+    return true;
+end
+
+CONDITIONS.modifier = function(target, args)
+    if args then
+        for i = 1, args.n do
+            local a = strlower(args[i]);
+            if a == "shift" then
+                if IsShiftKeyDown() then return true; end
+            elseif a == "ctrl" then
+                if IsControlKeyDown() then return true; end
+            elseif a == "alt" then
+                if IsAltKeyDown() then return true; end
+            end
+        end
+        return false;
+    end
+    return IsShiftKeyDown() or IsControlKeyDown() or IsAltKeyDown();
+end
+
+-- Outside a click context the "current" button is the left button.
+CONDITIONS.button = function(target, args)
+    if args then
+        for i = 1, args.n do
+            local a = args[i];
+            if a == "1" or strlower(a) == "leftbutton" then return true; end
+        end
+        return false;
+    end
+    return true;
+end
+
+CONDITIONS.actionbar = function(target, args)
+    if args then
+        local page = CURRENT_ACTIONBAR_PAGE or 1;
+        for i = 1, args.n do
+            if tonumber(args[i]) == page then return true; end
+        end
+        return false;
+    end
+    return true;
+end
+
+CONDITIONS.bonusbar = function(target, args)
+    local offset = GetBonusBarOffset();
+    if args then
+        for i = 1, args.n do
+            if tonumber(args[i]) == offset then return true; end
+        end
+        return false;
+    end
+    return offset > 0;
+end
+
+CONDITIONS.pet = function(target, args)
+    if args then
+        local petName = UnitName("pet");
+        local petFamily = UnitCreatureFamily("pet");
+        petName = petName and strlower(petName);
+        petFamily = petFamily and strlower(petFamily);
+        for i = 1, args.n do
+            local a = strlower(args[i]);
+            if a == petName or a == petFamily then return true; end
+        end
+        return false;
+    end
+    return UnitExists("pet");
+end
+
+-- ClassicAPI cedes the global name UnitChannelInfo/ChannelInfo to addons, so the
+-- player's channel state is read through the namespaced C_Spell.ChannelInfo().
+CONDITIONS.channeling = function(target, args)
+    local name = C_Spell.ChannelInfo();
+    if args then
+        if not name then return false; end
+        name = strlower(name);
+        for i = 1, args.n do
+            if strlower(args[i]) == name then return true; end
+        end
+        return false;
+    end
+    return name ~= nil;
+end
+
+CONDITIONS.equipped = function(target, args)
+    if not args then return false; end          -- [equipped] with no type never matches
+    for i = 1, args.n do
+        if IsEquippedTypeMatch(args[i]) then return true; end
+    end
+    return false;
+end
+
+CONDITIONS.cursor = function()
+    return GetCursorInfo() ~= nil;
+end
+
+-- ClassicAPI extension (not a 3.3.5 conditional). [known:spellID] uses
+-- IsPlayerSpell (broad knowledge -- spellbook, talents, recipes, racials);
+-- [known:name] falls back to a spellbook name scan (see IsSpellNameKnown).
+CONDITIONS.known = function(target, args)
+    if not args then return false; end
+    for i = 1, args.n do
+        local a = args[i];
+        local id = tonumber(a);
+        if id then
+            if IsPlayerSpell(id) then return true; end
+        elseif IsSpellNameKnown(a) then
+            return true;
+        end
+    end
+    return false;
+end
+
+-- No such state on 1.12.
+CONDITIONS.flying = AlwaysFalse;
+CONDITIONS.flyable = AlwaysFalse;
+CONDITIONS.vehicleui = AlwaysFalse;
+CONDITIONS.unithasvehicleui = AlwaysFalse;
+
+-- Aliases (share the function reference).
+CONDITIONS.form = CONDITIONS.stance;
+CONDITIONS.mod = CONDITIONS.modifier;
+CONDITIONS.btn = CONDITIONS.button;
+CONDITIONS.bar = CONDITIONS.actionbar;
+CONDITIONS.worn = CONDITIONS.equipped;
+
+-- ---------------------------------------------------------------------------
+-- Parser
+-- ---------------------------------------------------------------------------
+
+local warned = {};
+
+-- piece -> { pred = fn, neg = bool, args = { n, [i] } or nil }
+local function ParseCondition(piece)
+    local neg = false;
+    if strlen(piece) >= 3 and strsub(piece, 1, 2) == "no" then
+        neg = true;
+        piece = strsub(piece, 3);
+    end
+
+    local keyword, argstr = strmatch(piece, "^([^:]*):?(.*)$");
+    keyword = Trim(keyword);
+
+    local args;
+    if argstr ~= "" then
+        args = { n = 0 };
+        for a in gmatch(argstr .. "/", "([^/]*)/") do
+            args.n = args.n + 1;
+            args[args.n] = Trim(a);
+        end
+    end
+
+    local pred = CONDITIONS[keyword];
+    if not pred then
+        if not warned[keyword] then
+            warned[keyword] = true;
+            print("SecureCmdOptionParse: unknown condition '" .. keyword .. "'");
+        end
+        pred = AlwaysFalse;
+        neg = false;                            -- an unknown keyword is a hard false
+    end
+
+    return { pred = pred, neg = neg, args = args };
+end
+
+-- group body -> { target = str or nil, n, [i] = cond }
+local function ParseGroup(body)
+    local group = { n = 0 };
+    -- Sentinel comma so a run ending at end-of-body (and an empty body) yields
+    -- a piece; each piece is (non-comma)* up to a comma.
+    for piece in gmatch(body .. ",", "([^,]*),") do
+        piece = Trim(piece);
+        if strsub(piece, 1, 1) == "@" then
+            group.target = Trim(strsub(piece, 2));
+        elseif strlower(strsub(piece, 1, 7)) == "target=" then
+            group.target = Trim(strsub(piece, 8));
+        else
+            group.n = group.n + 1;
+            group[group.n] = ParseCondition(piece);
+        end
+    end
+    return group;
+end
+
+-- clause text -> { value = str, groups = { n, [i] = group } }
+local function ParseClause(text)
+    local groups = { n = 0 };
+    -- Greedy up to the LAST ']' splits the [group] blocks from the value.
+    local body, value = strmatch(text, "^%s*(.*%])(.*)$");
+    if not body then
+        return { value = Trim(text), groups = groups };
+    end
+    for groupBody in gmatch(body, "%[([^%]]*)%]") do
+        groups.n = groups.n + 1;
+        groups[groups.n] = ParseGroup(groupBody);
+    end
+    return { value = Trim(value), groups = groups };
+end
+
+-- options -> { n, [i] = clause }.  Splits on ';' at bracket depth 0.
+local function ParseOptions(options)
+    local clauses = { n = 0 };
+    local len = strlen(options);
+    local pos = 1;
+    while pos <= len + 1 do
+        local i = pos;
+        local depth = 0;
+        while i <= len do
+            local c = strsub(options, i, i);
+            if c == "[" then
+                depth = 1;
+            elseif c == "]" then
+                depth = 0;
+            elseif c == ";" and depth == 0 then
+                break;
+            end
+            i = i + 1;
+        end
+        clauses.n = clauses.n + 1;
+        clauses[clauses.n] = ParseClause(strsub(options, pos, i - 1));
+        pos = i + 1;
+    end
+    return clauses;
+end
+
+-- ---------------------------------------------------------------------------
+-- Evaluation
+-- ---------------------------------------------------------------------------
+
+local cache = {};
+
+local function GroupPasses(group)
+    local target = group.target or "target";
+    for i = 1, group.n do
+        local cond = group[i];
+        local ok = cond.pred(target, cond.args);
+        if cond.neg then
+            ok = not ok;
+        end
+        if not ok then
+            return false;
+        end
+    end
+    return true;
+end
+
+function SecureCmdOptionParse(options)
+    if type(options) ~= "string" then
+        error("Usage: SecureCmdOptionParse(\"options\")");
+        return nil;                             -- WoW's error() may not unwind
+    end
+
+    local clauses = cache[options];
+    if not clauses then
+        clauses = ParseOptions(options);
+        cache[options] = clauses;
+    end
+
+    for i = 1, clauses.n do
+        local clause = clauses[i];
+        local groups = clause.groups;
+        if groups.n == 0 then
+            return clause.value;
+        end
+        for j = 1, groups.n do
+            if GroupPasses(groups[j]) then
+                return clause.value, groups[j].target;
+            end
+        end
+    end
+    return nil;
+end

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

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

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

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

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

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

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

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

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

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

AddOns/!!!ClassicAPI/Util/SecureStateDriver.lua

@@ -0,0 +1,222 @@
+-- SecureStateDriver: automatic frame state / visibility from macro conditionals.
+--
+-- Backports FrameXML's SecureStateDriverManager. A registered driver re-runs
+-- SecureCmdOptionParse (Util/MacroOptions.lua) on a 0.2s poll (plus an instant
+-- rescan on the events below) and applies the result:
+--   * RegisterStateDriver(frame, "visibility", "[combat] hide; show") -> the
+--     value "show"/"hide" drives frame:Show()/Hide();
+--   * RegisterStateDriver / RegisterAttributeDriver for any other state ->
+--     frame:SetAttribute("state-"..state, value), so an OnAttributeChanged
+--     handler reacts to it;
+--   * RegisterUnitWatch(frame [, asState]) -> shows/hides (or sets
+--     "state-unitexists") as the frame's `unit` attribute comes and goes.
+--
+-- Base: 3.3.5 FrameXML/SecureStateDriver.lua, with the anniversary refinements
+-- grafted in (the resolveDriver() consolidation, tonumber() coercion of driver
+-- values, the literal string 'nil' -> nil, and the "statehidden" attribute).
+--
+-- Three deliberate deviations from upstream, all because 1.12 has no taint and
+-- our attribute system fires OnAttributeChanged SYNCHRONOUSLY:
+--   1. No attribute-bootstrap manager. Upstream drives itself through
+--      SecureStateDriverManager:SetAttribute("setframe"/"setstate"/...) -- a
+--      taint-boundary trick. Our SetAttribute has a recursion guard (a nested
+--      SetAttribute stores the value but does NOT fire the handler, see
+--      src/frame/Attributes.cpp), so doing the registration-time resolve from
+--      inside that handler would silently swallow the target frame's own
+--      OnAttributeChanged. Instead the public Register* functions write plain
+--      local tables and resolve immediately at top level. Public signatures are
+--      unchanged from retail.
+--   2. GetTime()-deadline throttle instead of the OnUpdate `elapsed` arg (1.12
+--      handlers take no parameters).
+--   3. UpdateUnitWatch guards its "statehidden"/"state-unitexists" writes on a
+--      real change, so a watched frame's handler is not fired at 5 Hz.
+
+-- ---------------------------------------------------------------------------
+-- SecureButton_* (minimal -- no taint, no modifier/button suffix machinery)
+-- ---------------------------------------------------------------------------
+
+-- SecureButton_GetAttribute and SecureButton_GetUnit are defined in
+-- SecureTemplates.lua (loaded earlier via SecureTemplates.xml).
+
+-- ---------------------------------------------------------------------------
+-- Private state
+-- ---------------------------------------------------------------------------
+
+local secureAttributeDrivers = {};              -- [frame][attribute] = optionsString
+local unitExistsWatchers = {};                  -- [frame] = doState (boolean)
+local unitExistsCache = setmetatable({}, {
+    __index = function(t, k)
+        local v = (UnitExists(k) and true) or false;
+        t[k] = v;
+        return v;
+    end,
+});
+
+local STATE_DRIVER_UPDATE_THROTTLE = 0.2;
+local nextUpdate = 0;
+
+local pairs = pairs;
+
+function UnitWatchRegistered(frame)
+    return unitExistsWatchers[frame] ~= nil;
+end
+
+-- ---------------------------------------------------------------------------
+-- Resolvers
+-- ---------------------------------------------------------------------------
+
+local function UpdateUnitWatch(frame, doState)
+    local unit = SecureButton_GetUnit(frame);
+    local exists = (unit and unitExistsCache[unit]) or false;
+    if doState then
+        if frame:GetAttribute("state-unitexists") ~= exists then
+            frame:SetAttribute("state-unitexists", exists);
+        end
+    else
+        if exists then
+            frame:Show();
+        else
+            frame:Hide();
+        end
+        local hidden = (not exists) or nil;
+        if frame:GetAttribute("statehidden") ~= hidden then
+            frame:SetAttribute("statehidden", hidden);
+        end
+    end
+end
+
+local function resolveDriver(frame, attribute, values)
+    local newValue = SecureCmdOptionParse(values);
+
+    if attribute == "state-visibility" then
+        if newValue == "show" then
+            frame:Show();
+            if frame:GetAttribute("statehidden") ~= nil then
+                frame:SetAttribute("statehidden", nil);
+            end
+        elseif newValue == "hide" then
+            frame:Hide();
+            if frame:GetAttribute("statehidden") ~= true then
+                frame:SetAttribute("statehidden", true);
+            end
+        end
+    elseif newValue then
+        if newValue == "nil" then
+            newValue = nil;
+        else
+            newValue = tonumber(newValue) or newValue;
+        end
+        if frame:GetAttribute(attribute) ~= newValue then
+            frame:SetAttribute(attribute, newValue);
+        end
+    end
+end
+
+-- ---------------------------------------------------------------------------
+-- Manager frame
+-- ---------------------------------------------------------------------------
+
+SecureStateDriverManager = CreateFrame("Frame", "SecureStateDriverManager");
+SecureStateDriverManager:Hide();                -- hidden -> no OnUpdate until a driver exists
+
+SecureStateDriverManager:SetScript("OnUpdate", function()
+    local now = GetTime();
+    if now < nextUpdate then
+        return;
+    end
+    nextUpdate = now + STATE_DRIVER_UPDATE_THROTTLE;
+
+    for frame, drivers in pairs(secureAttributeDrivers) do
+        for attribute, values in pairs(drivers) do
+            resolveDriver(frame, attribute, values);
+        end
+    end
+
+    for k in pairs(unitExistsCache) do
+        unitExistsCache[k] = nil;
+    end
+    for frame, doState in pairs(unitExistsWatchers) do
+        UpdateUnitWatch(frame, doState);
+    end
+end);
+
+SecureStateDriverManager:SetScript("OnEvent", function()
+    nextUpdate = 0;                             -- force a rescan on the next frame
+end);
+
+SecureStateDriverManager:SetScript("OnAttributeChanged", function()
+    if arg1 == "updatetime" and tonumber(arg2) then
+        STATE_DRIVER_UPDATE_THROTTLE = tonumber(arg2);
+    end
+end);
+
+-- Events that warrant an early rescan. Each is guarded so a name this client
+-- doesn't define (e.g. UPDATE_STEALTH) is simply skipped.
+local rescanEvents = {
+    "MODIFIER_STATE_CHANGED",                   -- ClassicAPI-fired
+    "PLAYER_FOCUS_CHANGED",                      -- ClassicAPI-fired
+    "UPDATE_SHAPESHIFT_FORM",                    -- ClassicAPI-fired (singular)
+    "UPDATE_SHAPESHIFT_FORMS",                   -- native 1.12 (plural)
+    "ACTIONBAR_PAGE_CHANGED",
+    "UPDATE_BONUS_ACTIONBAR",
+    "PLAYER_ENTERING_WORLD",
+    "UPDATE_STEALTH",
+    "PLAYER_TARGET_CHANGED",
+    "PLAYER_REGEN_DISABLED",
+    "PLAYER_REGEN_ENABLED",
+    "UNIT_PET",
+    "RAID_ROSTER_UPDATE",
+    "PARTY_MEMBERS_CHANGED",
+};
+for _, event in ipairs(rescanEvents) do
+    if C_EventUtils.IsEventValid(event) then
+        SecureStateDriverManager:RegisterEvent(event);
+    end
+end
+
+-- ---------------------------------------------------------------------------
+-- Public API
+-- ---------------------------------------------------------------------------
+
+function RegisterAttributeDriver(frame, attribute, values)
+    if attribute and values and string.sub(attribute, 1, 1) ~= "_" then
+        local drivers = secureAttributeDrivers[frame];
+        if not drivers then
+            drivers = {};
+            secureAttributeDrivers[frame] = drivers;
+        end
+        drivers[attribute] = values;
+        SecureStateDriverManager:Show();
+        resolveDriver(frame, attribute, values);
+    end
+end
+
+function UnregisterAttributeDriver(frame, attribute)
+    if attribute then
+        local drivers = secureAttributeDrivers[frame];
+        if drivers then
+            drivers[attribute] = nil;
+        end
+    else
+        secureAttributeDrivers[frame] = nil;
+    end
+end
+
+function RegisterStateDriver(frame, state, values)
+    RegisterAttributeDriver(frame, "state-" .. state, values);
+end
+
+function UnregisterStateDriver(frame, state)
+    UnregisterAttributeDriver(frame, state and ("state-" .. state));
+end
+
+function RegisterUnitWatch(frame, asState)
+    local doState = (asState and true) or false;
+    unitExistsWatchers[frame] = doState;
+    SecureStateDriverManager:Show();
+    UpdateUnitWatch(frame, doState);
+end
+
+function UnregisterUnitWatch(frame)
+    unitExistsWatchers[frame] = nil;
+end

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

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

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

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

AddOns/!!!ClassicAPI/Util/TextureUtil.lua

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,11 +1,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";

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

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

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

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

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

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

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

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

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

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

AddOns/DebugTools/DebugTools.lua

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

AddOns/DebugTools/DebugTools.xml

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

AddOns/DebugTools/TableInspector.lua

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

CMakeLists.txt

@@ -25,6 +25,39 @@ set(TINYCBOR_SOURCES
     external/tinycbor/src/cborparser_float.c
     external/tinycbor/src/cborerrorstrings.c)
 
+# Version derivation. Dev builds use a sentinel "newer than every
+# plausible release" so addon-side `CLASSIC_API_VERSION >= X` gates
+# always pass locally. CI release builds pass `-DCLASSICAPI_TAG=vX.Y.Z`,
+# which drives BOTH the compiled `CLASSIC_API_VERSION` int AND the
+# embedded addon's `## Version:` toc line (substituted in
+# embed_addon.cmake). The on-disk source toc stays `## Version: DEV`;
+# only the embedded copy is stamped, so a release build needs nothing
+# but the flag — no source edit.
+set(CLASSICAPI_VERSION_VALUE 99999999)
+set(CLASSICAPI_VER_MAJOR 9999)
+set(CLASSICAPI_VER_MINOR 99)
+set(CLASSICAPI_VER_PATCH 99)
+set(CLASSICAPI_TOC_VERSION "DEV")
+
+set(CLASSICAPI_TAG
+    ""
+    CACHE STRING "Release tag like v1.2.3")
+
+if(CLASSICAPI_TAG MATCHES "^v([0-9]+)\\.([0-9]+)\\.([0-9]+)$")
+  set(CLASSICAPI_VER_MAJOR "${CMAKE_MATCH_1}")
+  set(CLASSICAPI_VER_MINOR "${CMAKE_MATCH_2}")
+  set(CLASSICAPI_VER_PATCH "${CMAKE_MATCH_3}")
+  math(EXPR CLASSICAPI_VERSION_VALUE
+       "${CLASSICAPI_VER_MAJOR} * 10000 + ${CLASSICAPI_VER_MINOR} * 100 + ${CLASSICAPI_VER_PATCH}")
+  set(CLASSICAPI_TOC_VERSION
+      "${CLASSICAPI_VER_MAJOR}.${CLASSICAPI_VER_MINOR}.${CLASSICAPI_VER_PATCH}")
+elseif(CLASSICAPI_TAG)
+  message(
+    FATAL_ERROR
+      "Invalid CLASSICAPI_TAG: ${CLASSICAPI_TAG} (expected vMAJOR.MINOR.PATCH)"
+  )
+endif()
+
 # Bundle `AddOns/!!!ClassicAPI/` into a generated header so the DLL can
 # surface the addon to the engine even when the user doesn't have it
 # installed on disk. The file-read hook in `src/addons/Embedded.cpp`
@@ -34,12 +67,16 @@ set(EMBEDDED_CLASSICAPI_SRC "${CMAKE_CURRENT_SOURCE_DIR}/AddOns/!!!ClassicAPI")
 set(EMBEDDED_CLASSICAPI_HEADER "${CMAKE_BINARY_DIR}/generated/embedded_classicapi.h")
 file(GLOB_RECURSE EMBEDDED_CLASSICAPI_FILES CONFIGURE_DEPENDS
      "${EMBEDDED_CLASSICAPI_SRC}/*")
+# The `.classicapi-dev` marker is a disk-only developer signal — keep it
+# out of the embed inputs (embed_addon.cmake filters it too).
+list(FILTER EMBEDDED_CLASSICAPI_FILES EXCLUDE REGEX "/\\.classicapi-dev$")
 add_custom_command(
     OUTPUT "${EMBEDDED_CLASSICAPI_HEADER}"
     COMMAND ${CMAKE_COMMAND}
         -DSRC_DIR=${EMBEDDED_CLASSICAPI_SRC}
         -DOUT_HEADER=${EMBEDDED_CLASSICAPI_HEADER}
         -DADDON_NAME=ClassicAPI
+        -DADDON_VERSION=${CLASSICAPI_TOC_VERSION}
         -P "${CMAKE_CURRENT_SOURCE_DIR}/cmake/embed_addon.cmake"
     DEPENDS
         ${EMBEDDED_CLASSICAPI_FILES}
@@ -71,33 +108,6 @@ add_library(${PROJECT_NAME} SHARED
     ${EMBEDDED_CLASSICAPI_HEADER}
     ${EMBEDDED_BINDINGS_HEADER})
 
-# Dev-build sentinel — represents "newer than every plausible
-# release". Encoded as v9999.99.99 = 9999 * 10000 + 99 * 100 + 99 =
-# 99,999,999. Picked so addon-side feature gates of the form
-# `CLASSIC_API_VERSION >= X` always pass during local development;
-# CI release builds overwrite it via `-DCLASSICAPI_TAG=vX.Y.Z`.
-set(CLASSICAPI_VERSION_VALUE 99999999)
-set(CLASSICAPI_VER_MAJOR 9999)
-set(CLASSICAPI_VER_MINOR 99)
-set(CLASSICAPI_VER_PATCH 99)
-
-set(CLASSICAPI_TAG
-    ""
-    CACHE STRING "Release tag like v1.2.3")
-
-if(CLASSICAPI_TAG MATCHES "^v([0-9]+)\\.([0-9]+)\\.([0-9]+)$")
-  set(CLASSICAPI_VER_MAJOR "${CMAKE_MATCH_1}")
-  set(CLASSICAPI_VER_MINOR "${CMAKE_MATCH_2}")
-  set(CLASSICAPI_VER_PATCH "${CMAKE_MATCH_3}")
-  math(EXPR CLASSICAPI_VERSION_VALUE
-       "${CLASSICAPI_VER_MAJOR} * 10000 + ${CLASSICAPI_VER_MINOR} * 100 + ${CLASSICAPI_VER_PATCH}")
-elseif(CLASSICAPI_TAG)
-  message(
-    FATAL_ERROR
-      "Invalid CLASSICAPI_TAG: ${CLASSICAPI_TAG} (expected vMAJOR.MINOR.PATCH)"
-  )
-endif()
-
 target_compile_definitions(
   ${PROJECT_NAME}
   PRIVATE CLASSICAPI_VERSION_VALUE=${CLASSICAPI_VERSION_VALUE})
@@ -118,7 +128,9 @@ target_sources(${PROJECT_NAME} PRIVATE "${CLASSICAPI_VERSION_RC}")
 # ole32: COM (CoInitializeEx / CoCreateInstance / CoTaskMemFree) for the
 # SAPI text-to-speech backend in src/voicechat/Tts.cpp. The SAPI GUIDs are
 # instantiated in that TU via <initguid.h>, so no sapi.lib is needed.
-target_link_libraries(${PROJECT_NAME} PRIVATE minhook advapi32 ole32)
+# user32: Win32 clipboard API (OpenClipboard / SetClipboardData) for
+# CopyToClipboard in src/clipboard/Copy.cpp.
+target_link_libraries(${PROJECT_NAME} PRIVATE minhook advapi32 ole32 user32)
 
 target_include_directories(
   ${PROJECT_NAME} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src
@@ -130,7 +142,29 @@ target_include_directories(
 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")
+# /Zi retains full debug info (source file + line numbers, locals, types) in a
+# separate PDB WITHOUT disabling optimization — the DLL stays a fully optimized
+# /O2 release build; the symbols just live in ClassicAPI.pdb on the side. Feeds
+# the linker's /DEBUG below.
+set(CMAKE_CXX_FLAGS_RELEASE "/MT /O2 /Ob2 /DNDEBUG /Zi")
 set(CMAKE_SHARED_LINKER_FLAGS
-    "/OPT:REF /OPT:ICF /MERGE:.rdata=.text /MERGE:.pdata=.text /SECTION:.text,EWR /NODEFAULTLIB:MSVCRT"
+    # Two debug artifacts for triaging crashes from a SHIPPED DLL. Both are
+    # published as release artifacts, match this exact build, and have no effect
+    # on code layout:
+    #   /MAP   -> build/Release/ClassicAPI.map: a text symbol->address table
+    #             that resolves the `0001:offset` addresses in WoW's ERROR #132
+    #             crash log back to functions by hand (no debugger/dump needed).
+    #   /DEBUG -> build/Release/ClassicAPI.pdb: full symbols (paired with the
+    #             compiler's /Zi) so WinDbg/x64dbg/VS produce a line-level
+    #             symbolicated call stack from a crash dump. A SEPARATE file —
+    #             it is NOT embedded in the DLL, only a small signature record
+    #             linking the two is.
+    # /DEBUG implicitly disables /OPT:REF and /OPT:ICF (dead-code strip +
+    # identical-COMDAT fold); they are listed explicitly below so they stay ON
+    # and the shipped DLL does not grow. (/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 /DEBUG /DEF:${CMAKE_CURRENT_SOURCE_DIR}/src/ClassicAPI.def"
 )

README.md

@@ -1,52 +1,87 @@
 # ClassicAPI
 
-A small DLL for World of Warcraft 1.12.1 (Vanilla / Turtle WoW) that adds a
-collection of Lua API calls Blizzard never exposed in 1.12 but which make
-addon authoring noticeably less painful — primarily for backporting addons
-written against later API versions (3.3.5+) where these calls do exist.
+ClassicAPI is a DLL for World of Warcraft 1.12.1 (Vanilla / Turtle WoW). It
+backports a large part of the modern WoW API — 550+ functions and 50+ events,
+plus much of Lua 5.1 — into the 1.12 client, so addons written for later
+versions (3.3.5+ or Classic Era) run with little or no change.
 
-The DLL hooks the FrameScript engine after WoW boots and registers its
-extensions through the same in-engine mechanisms WoW uses for its own Lua
-functions. No companion addon is required.
+It hooks the engine after WoW boots and registers everything the same way WoW
+registers its own Lua functions. Nothing else to install — the DLL is
+self-contained.
 
-## What's added
+## Highlights
 
-Full per-function reference: **[docs/API.md](docs/API.md)**.
+The headline features. Each one takes effect as soon as the DLL loads, so your
+existing addons benefit without any code changes. The complete per-function
+reference is in **[docs/API.md](docs/API.md)**.
 
-### Calls
+### Lua 5.1 compatibility
+
+The flagship feature: run modern Lua 5.1 addon code on 1.12's Lua 5.0 VM.
+
+| Feature | Effect |
+|---------|--------|
+| Syntax | Compiles the Lua 5.1 length (`#`), modulo (`%`), `...`-expression, `0x` hex-literal, and leveled long bracket (`[=[ ]=]`) syntax that vanilla's Lua 5.0 rejects, by rewriting addon source before it compiles. Each addon file also receives its `(name, table)` through `...` (`local name, tbl = ...`). See [Lua 5.1 syntax](docs/API.md#lua-51-syntax). |
+| String methods | Every string value accepts method calls — `("asd"):upper()`, `("%d gold"):format(n)`, `msg:match("^!(%w+)")` — resolving through the `string` table, the way Lua 5.1 works. Vanilla's Lua 5.0 errors with `attempt to index a string value`. Works on literals and variables, in-world and on the login screen, and inside coroutines. See [String methods](docs/API.md#string-methods-supper-sformat). |
+| Script-handler arguments | Frame-script handlers receive their values as positional arguments — `OnMouseWheel(self, delta)`, `OnClick(self, button)`, `OnEvent(self, event, ...)`, etc. — the way 5.1+ clients do, so modern addon ports work unmodified. The `this` / `arg1` globals stay set. A handler that declares no parameters is unaffected. A handler that declared a parameter and expected nil now receives its real value. On by default. `SetModernScriptArgs(false)` restores exact vanilla dispatch. See [SetModernScriptArgs](docs/API.md#setmodernscriptargsenable--getmodernscriptargs). |
+
+### Modern client behaviors
+
+| Feature | Effect |
+|---------|--------|
+| 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. |
+| 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. |
+| Event-driven nameplates | The modern `C_NamePlate` API, driven by real events instead of vanilla frame-scraping. `NAME_PLATE_UNIT_ADDED` / `NAME_PLATE_UNIT_REMOVED` fire as plates appear and vanish, `nameplate1`..`nameplateN` tokens resolve with every `UnitX` function (and fire `UNIT_HEALTH`, `UNIT_AURA`, … as `arg1 == "nameplateN"`), and `C_NamePlate.GetNamePlateForUnit` / `GetNamePlates` hand back the live frames. See [NamePlate](docs/API.md#nameplate). |
+| Focus target | A sticky focus unit, like later clients. `FocusUnit("target")` pins it and `ClearFocus()` drops it, with `PLAYER_FOCUS_CHANGED` on every change. The `focus` / `focustarget` tokens resolve with every `UnitX` function and fire unit events (`UNIT_HEALTH`, `UNIT_AURA`, … as `arg1 == "focus"`), and the predefined `FOCUSTARGET` / `TARGETFOCUS` keybinds are ready to set. See [Focus](docs/API.md#focus). |
+| Multi-flavor & conditional TOC | Loads modern multi-flavor addons that ship one folder. Selects a version-specific TOC (`<Name>_ClassicAPI.toc` or `<Name>_Turtle.toc`) and the matching keybinding file (`Bindings_ClassicAPI.xml` / `Bindings_Turtle.xml`), accepts a comma-separated `## Interface:` version list (compatible when it includes the client version `11200`), and honors per-line `[AllowLoadGameType]` / `[AllowLoadTextLocale]` conditions and `[Family]` / `[Game]` / `[TextLocale]` path variables inside a TOC. See [Conditional and multi-flavor TOC loading](docs/API.md#conditional-and-multi-flavor-toc-loading). |
+
+## Full API reference
+
+Everything ClassicAPI adds, in full. Each section is collapsed — click a
+heading to expand it. For signatures and return values, see the per-function
+reference in **[docs/API.md](docs/API.md)**.
+
+<details>
+<summary><b>In-game Lua calls</b> — 550+ functions across ~60 namespaces</summary>
 
 | Namespace | Calls |
 |-----------|-------|
 | [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` |
+| [AddOns](docs/API.md#addons) | `C_AddOns.DoesAddOnExist`, `C_AddOns.GetAddOnLocalTable`, `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` |
+| [AuraUtil](docs/API.md#aurautil) | `AuraUtil.FindAura`, `AuraUtil.FindAuraByName`, `AuraUtil.ForEachAura`, `AuraUtil.UnpackAuraData` |
+| [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` |
+| [ColorUtil](docs/API.md#colorutil) | `C_ColorUtil.ConvertRGBToHSV`, `C_ColorUtil.ConvertHSVToRGB`, `C_ColorUtil.ConvertHSVToHSL`, `C_ColorUtil.ConvertHSLToHSV`, `C_ColorUtil.ConvertHSLToRGB`, `C_ColorUtil.GenerateTextColorCode`, `C_ColorUtil.WrapTextInColor`, `C_ColorUtil.WrapTextInColorCode` |
 | [Combat](docs/API.md#combat) | `InCombatLockdown` |
 | [CVar](docs/API.md#cvar) | `C_CVar.GetCVarBool` |
 | [Cursor](docs/API.md#cursor) | `GetCursorInfo` |
 | [Container](docs/API.md#container) | `C_Container.CalculateTotalNumberOfFreeBagSlots`, `C_Container.GetContainerItemCharges`, `C_Container.GetContainerItemDurability`, `C_Container.GetContainerItemID`, `C_Container.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` |
+| [Events](docs/API.md#events) | `C_EventUtils.IsEventValid`, `GetFramesRegisteredForEvent` |
 | [Expansion](docs/API.md#expansion) | `ClassicExpansionAtLeast`, `ClassicExpansionAtMost`, `GetClassicExpansionLevel` |
 | [Faction](docs/API.md#faction) | `C_Reputation.GetFactionDataByIndex`, `C_Reputation.GetFactionStandings`, `C_Reputation.GetLastStandingChange`, `C_Reputation.GetWatchedFactionData`, `C_Reputation.SetWatchedFactionByID`, `GetFactionIDByIndex`, `GetFactionInfoByID`, `GetFactionParentID` |
 | [Focus](docs/API.md#focus) | `ClearFocus`, `FocusUnit` |
-| [Frame](docs/API.md#frame) | `region:SetPoint("point")` (one-arg form), `region:SetSize`, `region:GetSize`, `frame:SetShown`, `frame:SetResizeBounds`, `frame:HookScript`, `frame:IsEventRegistered` |
-| [FriendList](docs/API.md#friendlist) | `C_FriendList.IsWhoQueryPending`, `C_FriendList.SendWhoQueryByName` |
-| [GameObject](docs/API.md#gameobject) | `C_GameObjectInfo.GetGameObjectInfoByID`, `C_GameObjectInfo.RequestLoadGameObjectByID` |
+| [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`, `fontstring:GetUnboundedStringWidth`, `fontstring:GetWrappedWidth`, `fontstring:GetNumLines`, `fontstring:GetLineHeight`, `fontstring:IsTruncated`, `fontstring:SetMaxLines`, `fontstring:GetMaxLines`, `fontstring:SetFormattedText`, `texture:SetRotation`, `texture:GetRotation`, `texture:SetVertexOffset`, `texture:GetVertexOffset`, `texture:SetColorTexture`, `texture:SetMask`, `frame:CreateMaskTexture`, `texture:AddMaskTexture`, `texture:RemoveMaskTexture`, `texture:GetNumMaskTextures`, `texture:GetMaskTexture`, `fontstring:SetRotation`, `fontstring:GetRotation`, `frame:SetResizeBounds`, `frame:HookScript`, `frame:IsEventRegistered`, `frame:GetEffectiveAlpha`, `frame:SetAttribute`, `frame:SetAttributeNoHandler`, `frame:ClearAttribute`, `frame:GetAttribute`, `OnAttributeChanged` (script), `SetModernScriptArgs`, `GetModernScriptArgs`, `SecureCmdOptionParse`, `RegisterStateDriver`, `UnregisterStateDriver`, `RegisterAttributeDriver`, `UnregisterAttributeDriver`, `RegisterUnitWatch`, `UnregisterUnitWatch`, `UnitWatchRegistered`, `SecureButton_GetAttribute`, `SecureButton_GetUnit` |
+| [FriendList](docs/API.md#friendlist) | `C_FriendList.GetFriendInfo`, `C_FriendList.GetFriendInfoByIndex`, `C_FriendList.GetNumFriends`, `C_FriendList.GetNumOnlineFriends`, `C_FriendList.GetNumWhoResults`, `C_FriendList.GetWhoInfo`, `C_FriendList.IsFriend`, `C_FriendList.IsIgnored`, `C_FriendList.IsIgnoredByGuid`, `C_FriendList.IsWhoQueryPending`, `C_FriendList.SendWhoQueryByName`, `C_FriendList.SetFriendNotes`, `C_FriendList.SetFriendNotesByIndex` |
+| [GameObject](docs/API.md#gameobject) | `C_GameObjectInfo.GetGameObjectInfoByID`, `C_GameObjectInfo.RequestLoadGameObjectByID`, `ClosestGameObjectPosition` |
+| [Glue](docs/API.md#glue) | `C_Glue.IsOnGlueScreen` |
 | [Gossip](docs/API.md#gossip) | `C_GossipInfo.CloseGossip`, `C_GossipInfo.GetActiveQuests`, `C_GossipInfo.GetAvailableQuests`, `C_GossipInfo.GetNumActiveQuests`, `C_GossipInfo.GetNumAvailableQuests`, `C_GossipInfo.GetNumOptions`, `C_GossipInfo.GetOptions`, `C_GossipInfo.GetText`, `C_GossipInfo.SelectActiveQuest`, `C_GossipInfo.SelectAvailableQuest`, `C_GossipInfo.SelectOption`, `C_GossipInfo.SelectOptionByIndex` |
-| [GameTooltip](docs/API.md#gametooltip) | `GameTooltip:GetGameObject`, `GameTooltip:GetItem`, `GameTooltip:GetOwner`, `GameTooltip:GetSpell`, `GameTooltip:GetUnitGUID`, `GameTooltip:HasGameObject`, `GameTooltip:HasItem`, `GameTooltip:HasSpell`, `GameTooltip:HasUnit`, `GameTooltip:IsEquippedItem`, `GameTooltip:SetEquipmentSet`, `GameTooltip:SetHyperlinkCompareItem`, `GameTooltip:SetInventoryItemByID`, `GameTooltip:SetItemByGUID`, `GameTooltip:SetItemByID`, `GameTooltip:SetSpellByID`, `GameTooltip:SetTalentByID`, `GameTooltip:SetUnitAura`, `OnTooltipSetItem` (script) |
+| [GameTooltip](docs/API.md#gametooltip) | `GameTooltip:AddSpellByID`, `GameTooltip:GetGameObject`, `GameTooltip:GetItem`, `GameTooltip:GetOwner`, `GameTooltip:GetSpell`, `GameTooltip:GetUnitGUID`, `GameTooltip:HasGameObject`, `GameTooltip:HasItem`, `GameTooltip:HasSpell`, `GameTooltip:HasUnit`, `GameTooltip:IsEquippedItem`, `GameTooltip:SetEquipmentSet`, `GameTooltip:SetHyperlinkCompareItem`, `GameTooltip:SetInventoryItemByID`, `GameTooltip:SetItemByGUID`, `GameTooltip:SetItemByID`, `GameTooltip:SetSpellByID`, `GameTooltip:SetTalentByID`, `GameTooltip:SetTotem`, `GameTooltip:SetUnitAura`, `OnTooltipSetItem`, `OnTooltipSetSpell`, `OnTooltipSetUnit`, `OnTooltipSetGameObject` (scripts) |
 | [Hooks](docs/API.md#hooks) | `hooksecurefunc` |
 | [Input](docs/API.md#input) | `GetMouseButtonClicked`, `IsLeftAltKeyDown`, `IsLeftControlKeyDown`, `IsLeftShiftKeyDown`, `IsModifierKeyDown`, `IsMouseButtonDown`, `IsRightAltKeyDown`, `IsRightControlKeyDown`, `IsRightShiftKeyDown` |
 | [Instance](docs/API.md#instance) | `GetInstanceInfo` |
-| [Item](docs/API.md#item) | `C_Item.DoesItemExist`, `C_Item.DoesItemExistByID`, `C_Item.EquipItemByName`, `C_Item.GetCurrentItemLevel`, `C_Item.GetDetailedItemLevelInfo`, `C_Item.GetEnchantInfo`, `C_Item.GetItemCount`, `C_Item.GetItemFamily`, `C_Item.GetItemGUID`, `C_Item.GetItemIcon`, `C_Item.GetItemIconByID`, `C_Item.GetItemID`, `C_Item.GetItemInfo`, `C_Item.GetItemInfoInstant`, `C_Item.GetItemInventorySlotInfo`, `C_Item.GetItemInventorySlotKey`, `C_Item.GetItemInventoryType`, `C_Item.GetItemInventoryTypeByID`, `C_Item.GetItemLink`, `C_Item.GetItemLocation`, `C_Item.GetItemMaxStackSize`, `C_Item.GetItemMaxStackSizeByID`, `C_Item.GetItemName`, `C_Item.GetItemNameByID`, `C_Item.GetItemQuality`, `C_Item.GetItemQualityByID`, `C_Item.GetItemSellPrice`, `C_Item.GetItemSellPriceByID`, `C_Item.GetItemSetID`, `C_Item.GetItemSetIDByID`, `C_Item.GetItemSetInfo`, `C_Item.GetItemSpell`, `C_Item.GetItemStatDelta`, `C_Item.GetItemStats`, `C_Item.GetItemSubClassInfo`, `C_Item.GetItemUniqueness`, `C_Item.GetItemUniquenessByID`, `C_Item.GetStackCount`, `C_Item.GetWeaponEnchantInfo`, `C_Item.IsBound`, `C_Item.IsConsumableItem`, `C_Item.IsEquippableItem`, `C_Item.IsEquippedItem`, `C_Item.IsItemDataCached`, `C_Item.IsItemDataCachedByID`, `C_Item.IsItemGUIDInInventory`, `C_Item.IsItemInRange`, `C_Item.IsItemOpenable`, `C_Item.IsLocked`, `C_Item.LockItem`, `C_Item.LockItemByGUID`, `C_Item.PickupItem`, `C_Item.UnlockAllItems`, `C_Item.UnlockItem`, `C_Item.RequestLoadItemData`, `C_Item.RequestLoadItemDataByID`, `C_Item.UseAtCursor`, `C_Item.UseAtUnit`, `C_Item.UseItemByName`, `GetAuctionItemID`, `GetAuctionSellItemID`, `GetAverageItemLevel`, `GetCraftReagentItemID`, `GetInboxItemID`, `GetInventoryItemDurability`, `GetInventoryItemID`, `GetInventoryItemsForSlot`, `GetInventoryItemRepairCost`, `GetItemIcon`, `GetLootRollItemID`, `GetLootSlotItemID`, `GetMerchantItemID`, `GetQuestItemID`, `GetQuestLogItemID`, `GetTradePlayerItemID`, `GetTradeSkillItemID`, `GetTradeSkillReagentItemID`, `GetTradeTargetItemID`, `OffhandHasWeapon` |
-| [Loot](docs/API.md#loot) | `C_Loot.GetNearbyLootableUnits`, `C_Loot.GetLastScanResults`, `C_Loot.IsScanInProgress`, `C_Loot.LootUnit`, `C_Loot.LootUnitItem`, `C_Loot.ScanNearbyLoot` |
+| [Item](docs/API.md#item) | `C_Item.DoesItemExist`, `C_Item.DoesItemExistByID`, `C_Item.EquipItemByName`, `C_Item.GetCurrentItemLevel`, `C_Item.GetDetailedItemLevelInfo`, `C_Item.GetEnchantInfo`, `C_Item.GetItemCount`, `C_Item.GetItemFamily`, `C_Item.GetItemGUID`, `C_Item.GetItemIcon`, `C_Item.GetItemIconByID`, `C_Item.GetItemID`, `C_Item.GetItemInfo`, `C_Item.GetItemInfoInstant`, `C_Item.GetItemInventorySlotInfo`, `C_Item.GetItemInventorySlotKey`, `C_Item.GetItemInventoryType`, `C_Item.GetItemInventoryTypeByID`, `C_Item.GetItemLink`, `C_Item.GetItemLocation`, `C_Item.GetItemMaxStackSize`, `C_Item.GetItemMaxStackSizeByID`, `C_Item.GetItemName`, `C_Item.GetItemNameByID`, `C_Item.GetItemQuality`, `C_Item.GetItemQualityByID`, `C_Item.GetItemSellPrice`, `C_Item.GetItemSellPriceByID`, `C_Item.GetItemSetID`, `C_Item.GetItemSetIDByID`, `C_Item.GetItemSetInfo`, `C_Item.GetItemSpell`, `C_Item.GetItemStatDelta`, `C_Item.GetItemStats`, `C_Item.GetItemClassInfo`, `C_Item.GetItemSubClassInfo`, `C_Item.GetItemUniqueness`, `C_Item.GetItemUniquenessByID`, `C_Item.GetStackCount`, `C_Item.GetWeaponEnchantInfo`, `C_Item.IsBound`, `C_Item.IsConsumableItem`, `C_Item.IsEquippableItem`, `C_Item.IsEquippedItem`, `C_Item.IsItemDataCached`, `C_Item.IsItemDataCachedByID`, `C_Item.IsItemGUIDInInventory`, `C_Item.IsItemInRange`, `C_Item.IsItemOpenable`, `C_Item.IsLocked`, `C_Item.LockItem`, `C_Item.LockItemByGUID`, `C_Item.PickupItem`, `C_Item.UnlockAllItems`, `C_Item.UnlockItem`, `C_Item.RequestLoadItemData`, `C_Item.RequestLoadItemDataByID`, `C_Item.UseAtCursor`, `C_Item.UseAtUnit`, `C_Item.UseItemByName`, `GetAuctionItemID`, `GetAuctionSellItemID`, `GetAverageItemLevel`, `GetCraftReagentItemID`, `GetInboxItemID`, `GetInventoryItemDurability`, `GetInventoryItemID`, `GetInventoryItemsForSlot`, `GetInventoryItemRepairCost`, `GetItemClassInfo`, `GetItemIcon`, `GetItemSubClassInfo`, `GetLootRollItemID`, `GetLootSlotItemID`, `GetMerchantItemID`, `GetQuestItemID`, `GetQuestLogItemID`, `GetTradePlayerItemID`, `GetTradeSkillItemID`, `GetTradeSkillReagentItemID`, `GetTradeTargetItemID`, `OffhandHasWeapon` |
+| [Loot](docs/API.md#loot) | `C_Loot.GetNearbyLootableUnits`, `C_Loot.GetLastScanResults`, `C_Loot.IsScanInProgress`, `C_Loot.LootAllCorpses`, `C_Loot.LootUnit`, `C_Loot.LootUnitItem`, `C_Loot.ScanNearbyLoot` |
 | [LootHistory](docs/API.md#loothistory) | `C_LootHistory.GetNumItems`, `C_LootHistory.GetItem`, `C_LootHistory.GetPlayerInfo`, `C_LootHistory.Clear` |
 | [LossOfControl](docs/API.md#lossofcontrol) | `C_LossOfControl.GetActiveLossOfControlData`, `C_LossOfControl.GetActiveLossOfControlDataCount` |
-| [Lua](docs/API.md#lua) | `coroutine.create`, `coroutine.resume`, `coroutine.status`, `coroutine.wrap`, `coroutine.yield`, `math.fmod`, `math.huge`, `math.modf`, `select`, `string.gmatch`, `string.match`, `string.reverse`, `strjoin`, `strreplace`, `strrev`, `strsplit`, `strtrim`, `table.wipe` |
-| [Macros](docs/API.md#macros) | `GetLooseMacroIcons`, `GetLooseMacroItemIcons`, `GetMacroIcons`, `GetMacroItemIcons`, `GetMacroSpell` |
+| [Lua](docs/API.md#lua) | `collectgarbage` (5.1 options), `coroutine.create`, `coroutine.resume`, `coroutine.running`, `coroutine.status`, `coroutine.wrap`, `coroutine.yield`, `CreateFromMixins`, `math.fmod`, `math.huge`, `math.modf`, `Mixin`, `select`, `string.gmatch`, `string.gsub` (table replacement), `string.match`, `string.reverse`, `strjoin`, `strreplace`, `strrev`, `strsplit`, `strtrim`, `table.count`, `table.maxn`, `table.wipe`, `unpack` (range args) |
+| [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` |
@@ -56,21 +91,26 @@ 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` |
-| [Screen](docs/API.md#screen) | `GetPhysicalScreenSize` |
-| [Spell](docs/API.md#spell) | `C_Spell.CancelSpellByID`, `C_Spell.CastAtCursor`, `C_Spell.CastAtUnit`, `C_Spell.CastingInfo`, `C_Spell.ChannelInfo`, `C_Spell.DoesSpellExist`, `C_Spell.GetSchoolString`, `C_Spell.GetSpellCooldown`, `C_Spell.GetSpellDescription`, `C_Spell.GetSpellInfo`, `C_Spell.GetSpellLevelInfo`, `C_Spell.GetSpellLink`, `C_Spell.GetSpellMechanicByID`, `C_Spell.GetSpellName`, `C_Spell.GetSpellPowerCost`, `C_Spell.GetSpellRadius`, `C_Spell.GetSpellReagents`, `C_Spell.GetSpellRequiredTargetLevel`, `C_Spell.GetSpellSubtext`, `C_Spell.GetSpellTexture`, `C_Spell.IsAutoAttackSpell`, `C_Spell.IsCurrentSpell`, `C_Spell.IsRangedAutoAttackSpell`, `C_Spell.IsSelfBuff`, `C_Spell.IsSpellHarmful`, `C_Spell.IsSpellHelpful`, `C_Spell.IsSpellInRange`, `C_Spell.IsSpellPassive`, `C_Spell.IsSpellUsable`, `C_Spell.SpellHasRange`, `C_Spell.UnitCastingInfo`, `C_Spell.UnitChannelInfo`, `CancelSpellByName`, `CastSpellNoToggle`, `GetCraftSpellID`, `GetSpellBonusDamage`, `GetSpellBonusHealing`, `GetSpellInfo`, `GetSpellLink`, `GetSpellRadius`, `GetSpellRequiredTargetLevel`, `GetSpellSchool`, `IsHarmfulSpell`, `IsHelpfulSpell`, `IsPassiveSpell`, `IsPlayerSpell`, `IsSpellKnown`, `IsUsableSpell`, `SpellHasRange` |
-| [SpellBook](docs/API.md#spellbook) | `C_SpellBook.GetCurrentLevelSpells`, `C_SpellBook.GetSkillLineName`, `C_SpellBook.GetSkillLineRank`, `C_SpellBook.GetSpellLevelLearned`, `C_SpellBook.GetSpellSkillLine`, `C_SpellBook.IsAutoAttackSpellBookItem`, `C_SpellBook.IsRangedAutoAttackSpellBookItem`, `FindSpellBookSlotByID` |
-| [State](docs/API.md#state) | `CancelShapeshiftForm`, `Dismount`, `GetMirrorTimerInfo`, `GetMirrorTimerProgress`, `GetShapeshiftFormID`, `IsAssistingRitual`, `IsFalling`, `IsInGroup`, `IsInRaid`, `IsLoggedIn`, `IsMounted`, `IsStealthed`, `IsSwimming` |
+| [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` |
-| [TaxiMap](docs/API.md#taximap) | `C_TaxiMap.GetTaxiNodesForMap`, `C_TaxiMap.GetAllTaxiNodes` |
-| [Time](docs/API.md#time) | `C_DateAndTime.AdjustTimeByDays`, `C_DateAndTime.AdjustTimeByMinutes`, `C_DateAndTime.CompareCalendarTime`, `C_DateAndTime.GetCalendarTimeFromEpoch`, `C_DateAndTime.GetCurrentCalendarTime`, `C_DateAndTime.GetSecondsUntilDailyReset`, `C_DateAndTime.GetServerTimeLocal`, `C_Timer.After`, `C_Timer.NewTicker`, `C_Timer.NewTimer`, `GetServerTime` |
+| [Targeting](docs/API.md#targeting) | `GetPlayerFacing`, `TargetDirectionEnemy`, `TargetDirectionFriend`, `TargetNearest`, `TargetNearestEnemyPlayer`, `TargetNearestFriendPlayer` |
+| [TaxiMap](docs/API.md#taximap) | `C_TaxiMap.GetTaxiNodesForMap`, `C_TaxiMap.GetAllTaxiNodes`, `C_TaxiMap.GetTaxiPaths`, `C_TaxiMap.GetTaxiPathWaypoints`, `C_TaxiMap.GetTaxiRoute` |
+| [Time](docs/API.md#time) | `C_DateAndTime.AdjustTimeByDays`, `C_DateAndTime.AdjustTimeByMinutes`, `C_DateAndTime.CompareCalendarTime`, `C_DateAndTime.GetCalendarTimeFromEpoch`, `C_DateAndTime.GetCurrentCalendarTime`, `C_DateAndTime.GetSecondsUntilDailyReset`, `C_DateAndTime.GetServerTimeLocal`, `C_Timer.After`, `C_Timer.NewTicker`, `C_Timer.NewTimer`, `GetServerTime`, `GetTimeCached` |
+| [Totem](docs/API.md#totem) | `GetTotemInfo`, `GetTotemTimeLeft`, `GetTotemDuration`, `TargetTotem` |
 | [TradeSkillUI](docs/API.md#tradeskillui) | `C_TradeSkillUI.GetTradeSkillListLink`, `C_TradeSkillUI.GetCraftListLink`, `C_TradeSkillUI.GetTradeSkillListRecipes` |
 | [UIColor](docs/API.md#uicolor) | `C_UIColor.GetColors` |
-| [Unit](docs/API.md#unit) | `GetUnitSpeed`, `UnitClassBase`, `UnitCreatureFamilyID`, `UnitCreatureTypeID`, `UnitDistanceSquared`, `UnitGUID`, `UnitInLineOfSight`, `UnitInRange`, `UnitIsAFK`, `UnitIsDND`, `UnitIsFeignDeath`, `UnitIsInMyGuild`, `UnitIsMinion`, `UnitIsOtherPlayersPet`, `UnitIsPet`, `UnitIsPossessed`, `UnitPower`, `UnitPowerMax`, `UnitPowerType`, `UnitRaceBase`, `UnitStandState`, `UnitSubName`, `UnitTokenFromGUID` |
-| [UnitAuras](docs/API.md#unitauras) | `C_UnitAuras.GetAuraDataByIndex`, `C_UnitAuras.GetAuraDataBySpellName`, `C_UnitAuras.GetAuraDispelTypeColor`, `C_UnitAuras.GetBuffDataByIndex`, `C_UnitAuras.GetDebuffDataByIndex`, `C_UnitAuras.GetPlayerAuraBySpellID`, `C_UnitAuras.GetUnitAuraBySpellID`, `C_UnitAuras.GetUnitAuras`, `C_UnitAuras.RegisterComboDuration` |
+| [Unit](docs/API.md#unit) | `ClosestUnitPosition`, `GetUnitSpeed`, `UnitClassBase`, `UnitCreatureFamilyID`, `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`, `C_UnitAuras.UnitAura`, `C_UnitAuras.UnitBuff`, `C_UnitAuras.UnitDebuff` |
 | [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` |
 
-### GlueXML calls
+</details>
+
+<details>
+<summary><b>GlueXML calls</b> — login / realm-select / character-select screens</summary>
 
 Registered on the **glue** Lua state (the engine that runs the login,
 realm-select, and character-select screens). The persistence entries
@@ -86,10 +126,14 @@ the glue state because GlueXML had no way to reach them otherwise.
 | [Account](docs/API.md#account) | `SaveAccount`, `DeleteAccount`, `GetSavedAccounts`, `LoginWithSavedAccount` (passwords encrypted in Windows Credential Manager, scoped per realmlist; plaintext never returned to Lua) |
 | [CharacterList](docs/API.md#characterlist) | `GetSavedCharacterOrder`, `SetSavedCharacterOrder` (persist to `WTF\Account\...\ClassicAPI.txt`) |
 | CVar | `GetCVar`, `SetCVar`, `RegisterCVar`, `GetCVarDefault`, `C_CVar.GetCVarBool` (storage is process-global — writes from glue are visible in-world and vice versa) |
+| [Glue](docs/API.md#glue) | `C_Glue.IsFirstLoadThisSession`, `C_Glue.IsOnGlueScreen` |
 | Script | `RunScript` (compile and run a Lua chunk in the glue state's globals — useful for slash-command-style helpers in GlueXML) |
 | State | `IsLoggedIn` |
 
-### Macros
+</details>
+
+<details>
+<summary><b>Macros</b> — engine-level parsing extensions</summary>
 
 Engine-level extensions to macro parsing and dispatch — no new Lua
 functions, just behavior the stock 1.12 engine didn't have. See the
@@ -101,7 +145,10 @@ functions, just behavior the stock 1.12 engine didn't have. See the
 | `CastSpellByName("<spellID>")` | Same — numeric strings resolve through the engine's name resolver |
 | `CastSpellNoToggle("<name>")` in a macro | Engine's macro parser now recognizes it as a primary-spell line, so the macro slot in an addon like pfUI highlights when its spell is auto-repeating or its self-aura is active |
 
-### Console commands
+</details>
+
+<details>
+<summary><b>Console commands</b> — developer console (<code>-console</code>)</summary>
 
 Registered on the engine's developer console (the `~` console available
 when launching with `-console`), not as Lua functions. See the
@@ -113,7 +160,10 @@ when launching with `-console`), not as Lua functions. See the
 | `ExportInterfaceFiles art` | Extracts Blizzard's UI art (`.blp`/`.tga`) from the MPQs to `BlizzardInterfaceArt\` |
 | `ExportDBCFiles` | Extracts the client's `.dbc` tables from the MPQs to `DBFilesClient\` |
 
-### Events
+</details>
+
+<details>
+<summary><b>Events</b> — new events fired to addons</summary>
 
 | Event | Payload |
 |-------|---------|
@@ -144,10 +194,24 @@ when launching with `-console`), not as Lua functions. See the
 | `PLAYER_STOPPED_MOVING` | *(none)* |
 | `PLAYER_STARTED_TURNING` | *(none)* |
 | `PLAYER_STOPPED_TURNING` | *(none)* |
+| `PLAYER_TOTEM_UPDATE` | `totemSlot` |
 | `QUEST_ACCEPTED` | `questLogIndex, questID` |
 | `QUEST_DATA_LOAD_RESULT` | `questID, success` |
 | `QUEST_REMOVED` | `questID` |
 | `QUEST_TURNED_IN` | `questID, xpReward, moneyReward` |
+| `UNIT_SPELLCAST_SENT` | `"player", target, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_START` | `unit, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_STOP` | `unit, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_DELAYED` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_SUCCEEDED` | `unit, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_INTERRUPTED` | `unit, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_FAILED` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_FAILED_QUIET` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_CHANNEL_START` | `unit, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_CHANNEL_UPDATE` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_CHANNEL_STOP` | `unit, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_RETICLE_TARGET` | `"player", "", spellID, spellName, rank` |
+| `UNIT_SPELLCAST_RETICLE_CLEAR` | `"player", "", spellID, spellName, rank` |
 | `UPDATE_INVENTORY_DURABILITY` | *(none)* |
 | `UPDATE_SHAPESHIFT_FORM` | *(none)* |
 | `VOICE_CHAT_TTS_PLAYBACK_STARTED` | `numConsumers, utteranceID, durationMS, destination` |
@@ -155,7 +219,10 @@ when launching with `-console`), not as Lua functions. See the
 | `VOICE_CHAT_TTS_PLAYBACK_FAILED` | `status, utteranceID, destination` |
 | `VOICE_CHAT_TTS_VOICES_UPDATE` | *(none)* |
 
-### Globals
+</details>
+
+<details>
+<summary><b>Globals & enums</b></summary>
 
 | Group | Constants |
 |-------|-----------|
@@ -166,34 +233,50 @@ when launching with `-console`), not as Lua functions. See the
 | Addon security | `Enum.AddOnSecurityStatus.{Secure,Insecure,Banned,NotAvailable}` |
 | Power type | `Enum.PowerType.{HealthCost,None,Mana,Rage,Focus,Energy,Happiness}` |
 | Inventory type | `Enum.InventoryType.Index*Type` (0–34, e.g. `IndexHeadType`=1 … `IndexRelicType`=28) |
+| Item class | `Enum.ItemClass.{Consumable,Container,Weapon,Gem,Armor,Reagent,Projectile,Tradegoods,ItemEnhancement,Recipe,Quiver,Questitem,Key,Miscellaneous,…}` (0–19) |
+| Item quality | `Enum.ItemQuality.{Poor,Common,Uncommon,Rare,Epic,Legendary,Artifact}` (0–6) |
+| 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
+</details>
+
+<details>
+<summary><b>Unit tokens</b> — <code>nameplateN</code>, <code>focus</code>, <code>markN</code></summary>
 
 | Token | Resolves to |
 |-------|-------------|
 | `nameplate1`..`nameplateN` | Unit behind the Nth visible nameplate, in creation-order. Works with every `UnitX` function — `UnitName`, `UnitGUID`, `UnitClass`, `UnitHealth`, etc. Suffix chains (`nameplate1target`, `nameplate1targettarget`) compose. See [NamePlate / Unit tokens](docs/API.md#unit-tokens-nameplaten). |
 | `focus` / `focustarget` | Sticky target set via [`FocusUnit`](docs/API.md#focusunitunit), cleared via [`ClearFocus`](docs/API.md#clearfocus). Same `UnitX` coverage as `nameplateN`. Fires [`PLAYER_FOCUS_CHANGED`](docs/API.md#player_focus_changed-event) on transition. See [Focus](docs/API.md#focus). |
+| `mark1`..`mark8` | Unit currently wearing the Nth raid-target marker (`mark1` = star … `mark8` = skull). Same `UnitX` coverage as `nameplateN`, and fires unit events (`UNIT_HEALTH`, `UNIT_AURA`, …) with `arg1 == "markN"`. `UnitExists("markN")` is `false` when the marker is unset, out of range, or on a non-unit. Suffix chains (`mark1target`) compose. See [Unit tokens (`markN`)](docs/API.md#unit-tokens-markn). |
 
-### Bindings
+</details>
 
-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.
+<details>
+<summary><b>Bindings</b> — direct-action and override binding families</summary>
+
+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.
 
 | Binding | Action |
 |---------|--------|
 | `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
-
-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. |
+</details>
 
 ## Installation
 
@@ -216,36 +299,38 @@ The Lua-side companion library lives in
 [`AddOns/!!!ClassicAPI/`](AddOns/!!!ClassicAPI/). It's a 1.12.1 /
 Lua 5.0 backport of the modern Blizzard helpers that aren't engine
 functions but that consumer code still expects to find as globals —
-`Mixin` / `CreateFromMixins`, `CallbackRegistryMixin`, `EventRegistry`,
-`ColorMixin` + `CreateColor`, `Item` / `ItemLocation`, `MathUtil`
-(`Lerp` / `Clamp` / `CreateCounter`), `TableUtil` (`tCompare`,
-`MergeTable`, `SafePack`, etc.), and `EventUtil`
+`CallbackRegistryMixin`, `EventRegistry`, `ColorMixin` + `CreateColor`,
+`Item` / `ItemLocation`, `MathUtil`(`Lerp` / `Clamp` / `CreateCounter`),
+`TableUtil` (`tCompare`, `MergeTable`, `SafePack`, etc.), and `EventUtil`
 (`ContinueOnAddOnLoaded` etc.).
 
-Some of the addon's surface depends on engine functions ClassicAPI
-provides (`C_UIColor.GetColors` populates the modern color globals,
-`C_Item.GetItemInfoInstant` powers `ItemMixin`, the
-`ITEM_DATA_LOAD_RESULT` event drives `ContinueOnItemLoad`); the rest
-is pure Lua and would work standalone. Without the DLL the addon
-still loads, but those features no-op.
-
-The triple-`!` prefix is **load-order-significant** — WoW loads
-addons alphabetically, so `!!!ClassicAPI` is guaranteed to run before
-any consumer that depends on its globals. Don't rename the folder.
-
 **You don't have to install the addon manually** — the DLL embeds
 the contents of [`AddOns/!!!ClassicAPI/`](AddOns/!!!ClassicAPI/) and
 registers them with the engine as a synthetic addon on startup, so
-the library is always available when the DLL is loaded. The engine
-sees it as a normal addon: it appears in `GetAddOnInfo`, fires
-`ADDON_LOADED`, supports `SavedVariables`, the works.
+the library is always available when the DLL is loaded. It fires
+`ADDON_LOADED`, supports `SavedVariables`, and is resolvable by name —
+`IsAddOnLoaded("!!!ClassicAPI")`, `GetAddOnInfo("!!!ClassicAPI")`, and
+`## Dependencies: !!!ClassicAPI` all work as usual.
 
-If you do drop the folder into your `Interface/AddOns/` directory,
-**that copy wins** — the DLL's embedded version is only registered
-when the engine's normal scan doesn't already have an entry under
-that name. Useful for editing the Lua locally without rebuilding the
-DLL. The dispatch is transparent: addons consuming `Mixin`,
-`ColorMixin`, `TableUtil`, etc. behave identically in both cases.
+**It is intentionally always-on and cannot be disabled.** The library
+provides FrameXML-compat fixes that other addons and the DLL's own
+features rely on, so leaving it toggleable would let a user (or a
+one-off character-select uncheck) silently break them. The DLL
+therefore hides it from the character-select AddOns list and
+force-enables it every login — so it never appears as a checkbox and
+can't be switched off. Being hidden means it's omitted from the
+index-based `GetNumAddOns()` / `GetAddOnInfo(i)` enumeration, but every
+by-name lookup and dependency reference still resolves normally.
+
+If you drop the folder into your `Interface/AddOns/` directory, **that
+copy's files win** — the DLL's embedded version only serves files when
+the engine's normal scan doesn't already have a newer entry under that
+name. Useful for editing the Lua locally without rebuilding the DLL.
+The hidden + force-enabled treatment applies either way (it's keyed to
+the addon name, not to which copy serves the files), so the local copy
+is also absent from the AddOns list. The dispatch is transparent:
+addons consuming `Mixin`, `ColorMixin`, `TableUtil`, etc. behave
+identically in both cases.
 
 ## Bundled addon: DebugTools
 

TODO.md

@@ -3815,3 +3815,42 @@ estimate. Anyone who wants vanilla threat should run an existing threat
 addon. ClassicAPI's only worthwhile contribution in this space is an
 unrelated precise-combat-log event feed — filed as its own thing, not as
 "threat".
+
+## 99. `C_AddOns.GetAddOnLocalTable(name)` — gate on loaded + opt-in TOC flag — DONE
+
+Shipped gated (branch `feat/lua-syntax-transpile`,
+[src/addons/LocalTable.cpp](src/addons/LocalTable.cpp)). Returns the addon's
+private namespace table **only** when BOTH hold, else `nil`:
+1. the addon `name` is **loaded** (`FUN_ADDON_IS_LOADED`, by-name), and
+2. its `.toc` declares `## AllowAddOnTableAccess: <nonzero>` (scanned via
+   `FUN_FILE_READ` on `Interface\AddOns\<name>\<name>.toc`, read as a TOC
+   boolean flag; approach (a) from the notes below — no parser hook).
+
+The two paths stay separate, as required:
+- **Internal** `__addonns` (the `local name, ns = ...` preamble) stays
+  **ungated** — an addon always gets its own namespace. Still in
+  `luasyntax/Transpile.cpp`.
+- **Public** `C_AddOns.GetAddOnLocalTable` carries the gate, in
+  `addons/LocalTable.cpp`.
+
+Both resolve to the SAME table per addon via `LuaSyntax::PushAddonNamespace`
+(the one owner of the registry-backed name→table map, exposed by
+[src/luasyntax/AddonNamespace.h](src/luasyntax/AddonNamespace.h)) — so an addon
+reads back exactly what it (or its files' `...`) stored.
+
+Directive spelling + function name verified present in the 1.15.8 Classic Era
+binary (`AllowAddOnTableAccess:` TOC key, `GetAddOnLocalTable`).
+
+Deliberate scope choices (revisit only if an addon needs otherwise):
+- **Name (string) input only.** A numeric index returns `nil` — cross-addon
+  table access is by name, and the map is name-keyed. Every other `C_AddOns.*`
+  wrapper accepts name-or-index; this one does not.
+- **`nil` on denial, not a Lua error.** Matches the project's modern-API
+  convention (nil over `lua_error`). Retail may raise instead; switch the
+  denial branches to `Game::Lua::Error` if strict parity is wanted.
+- **No per-name cache** on the TOC scan — GetAddOnLocalTable is not a hot path.
+
+Not shipped by default: no addon opts in yet. The embedded `!!!ClassicAPI`
+addon could add `## AllowAddOnTableAccess: 1` to its `.toc` to expose its own
+namespace as a worked example, but that's a product/security decision left to
+the maintainer.

cmake/embed_addon.cmake

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

docs/Events.md

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

docs/InlineTextureEscapes.md

@@ -0,0 +1,778 @@
+# 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).
+- **Chat has no one-frame lag** — a ScrollingMessageFrame re-`SetText`s every
+  visible line on each new message, and the engine builds each line lazily at
+  paint, so a line's icons would land one frame after its glyphs (glyphs draw
+  synchronously; the icon regions are separate objects whose placement is only
+  known once the line builds mid-paint, after the frame's texture pass already
+  drew). A co-hook on the SMF display refresh (`FUN_00788750`, which runs
+  pre-render from the frame's own methods) forces each icon-bearing line to
+  resolve+build and applies its icon placement synchronously — before the frame
+  draws — so icons move in lockstep with their text. It reuses the engine's own
+  `Realize(0)` → `RebuildString` → ensure-built path and the same placement math
+  the paint flush uses (`ComputePlacementsForNode`), so the later flush dedups to
+  a no-op. Additive and best-effort: any line whose rect isn't resolvable in time
+  falls back to the paint + tick pipeline (correct, one-frame lagged). A pure
+  scroll or drag never lagged — the icons are anchored to the line and the engine
+  moves them for free; only content changes on a reused line needed this.
+- **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
+two toggles: `_classicapi_InlineTexEnable` (the whole-feature kill switch; the
+SEH latch trips it on a flush fault) and `_classicapi_InlineTexEarly` (the
+SMF-refresh early apply above — on by default, toggle off to A/B the chat lag
+against the baseline paint+tick pipeline, which keeps running either way). 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.

docs/InlineTextureResidency.md

@@ -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.

src/ClassicAPI.def

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

src/Common.h

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

src/DllMain.cpp

@@ -16,8 +16,15 @@
 #include "MinHook.h"
 #include "Offsets.h"
 #include "event/Custom.h"
+#include "luasyntax/StringMethods.h"
+#include "model/DisplayInfo.h"
 #include "nameplate/Walk.h"
 #include "player/NameCache.h"
+#include "text/InlineTexture.h"
+#include "text/InlineTexturePool.h"
+#include "texture/Mask.h"
+#include "texture/Transform.h"
+#include "tooltip/SetEvents.h"
 
 static Game::FrameScript_Initialize_t FrameScript_Initialize_o = nullptr;
 static Game::LoadScriptFunctions_t LoadScriptFunctions_o = nullptr;
@@ -47,6 +54,35 @@ 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 per-region texture masks for the same reason (SetMask).
+    Texture::Mask::PrepareForReload();
+
+    // Drop pending character-dress jobs and their engine compositors — the
+    // reload destroys every Model frame the jobs point at.
+    Model::DisplayInfo::PrepareForReload();
+
+    // Drop the per-tooltip OnTooltipSet* handler cells — the reload destroys
+    // and recreates every tooltip object, and the handler refs die with the
+    // Lua reset (issue #33: the cell table filled after ~18 reloads, then
+    // recycled tooltip addresses fired dead refs).
+    Tooltip::SetEvents::PrepareForReload();
+
+    // Forget the captured `string` table before the world Lua state resets
+    // (this hook also fires on /logout, where the state's tables die) —
+    // string-method resolution fails closed (stock index error) until
+    // LoadScriptFunctions re-captures.
+    LuaSyntax::StringMethods::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 +107,14 @@ 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();
+    Texture::Mask::PrepareForReload();
 }
 
 // Every Lua-side `frame:RegisterEvent(...)` is a chance to claim a slot
@@ -86,47 +130,153 @@ 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, ONLY when VanillaFixes
+//     is not the loader (no VfPatcher.dll in the process), for injectors that
+//     never call `Load`.
+//
+// The worker MUST stand down under VanillaFixes. VF creates the process
+// suspended and injects every dlls.txt DLL sequentially via remote threads;
+// a worker spawned from our DllMain starts the moment our own LoadLibrary
+// releases the loader lock — i.e. while VF is still injecting the NEXT
+// dlls.txt DLL. Its ~90-prologue install (plus the MH_ApplyQueued
+// thread-freeze) then races that DLL's DllMain patching the same engine
+// functions, which made SuperWoWhook.dll fail to load whenever ClassicAPI
+// preceded it in dlls.txt. `Load` has no such race: VfPatcher calls it on the
+// game's main thread after the process resumes, when every DllMain in the
+// injection chain has already completed, serialized in dlls.txt order.
+// ---------------------------------------------------------------------------
+
+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).
+        //
+        // Under VanillaFixes, `Load` is the ONLY install trigger. VfPatcher.dll
+        // is injected before any dlls.txt DLL, so its presence identifies VF as
+        // the loader; and the `Load` mechanism shipped in the same VF release
+        // (v1.4) as dlls.txt support itself, so any VF that loaded us will call
+        // it. Spawning the worker here would race the DllMains of the dlls.txt
+        // DLLs VF injects after us (see the block comment above).
+        if (GetModuleHandleW(L"VfPatcher.dll") == nullptr) {
+            // Any other injector: no `Load` caller exists, so install from a
+            // worker off the lock. The new thread cannot run its body until
+            // DllMain returns and the loader lock releases, and we never wait
+            // on it. 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;
 }

src/Game.cpp

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

src/Game.h

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

src/addons/Embedded.cpp

@@ -47,6 +47,11 @@
 
 #include "Game.h"
 #include "Offsets.h"
+#include "addons/EngineIO.h"
+#include "addons/FlavorBindings.h"
+#include "addons/FlavorToc.h"
+#include "addons/Toc.h"
+#include "addons/TocRewrite.h"
 #include "bindings/Inject.h"
 
 #include <cstdint>
@@ -60,6 +65,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\…`
@@ -104,30 +116,15 @@ const ClassicAPIFiles::File *LookupEmbedded(const char *suffix) {
     return nullptr;
 }
 
-// Storm allocator — same one `FUN_FILE_READ` uses internally. Buffer
-// allocated here is freed cleanly by the caller's standard `SMemFree`
-// (`FUN_STORM_SMEM_FREE`). `__stdcall` per the function's `RET 0x10`
-// (4 args × 4 bytes = 16) epilogue.
-//   __stdcall void *SMemAlloc(size_t size, const char *file, int line, int flags)
-using SMemAlloc_t = void *(__stdcall *)(size_t size, const char *file, int line, int flags);
+// Engine file I/O + Storm allocator — see addons/EngineIO.h for the shapes and
+// the __stdcall / ESP-drift hazard. A buffer we SMemAlloc here is freed cleanly
+// by the caller's standard SMemFree in turn.
+using AddOns::EngineIO::FileReadFn;
+using AddOns::EngineIO::SMemAllocFn;
+using AddOns::EngineIO::SMemFreeFn;
 
-// `FUN_FILE_READ` — same shape derived from the Octo decompile.
-// Calling convention is `__stdcall` (callee cleans 28 bytes via
-// `RET 0x1C`), not `__cdecl` — confirmed via the function epilogue.
-// Getting this wrong silently corrupts the caller's stack frame.
-//   __stdcall int FileRead(int unused, const char *path, void **outBuf,
-//                          size_t *outSize, size_t extraBytes,
-//                          int flag1, int flag2)
-using FileRead_t = int(__stdcall *)(int unused, const char *path, void **outBuf,
-                                    size_t *outSize, size_t extraBytes,
-                                    int flag1, int flag2);
-FileRead_t FileRead_o = nullptr;
-
-// Storm-allocator free. Used to release the disk-TOC buffer after we
-// scrape its version line — same path the engine itself uses when
-// `FileRead_o` succeeded and the caller's done with the result.
-//   __stdcall void SMemFree(void *buf, const char *file, int line, int flags)
-using SMemFree_t = void(__stdcall *)(void *buf, const char *file, int line, int flags);
+// The trampoline to the original FUN_FILE_READ (installed by the co-hook below).
+FileReadFn FileRead_o = nullptr;
 
 // Extracts the value of the `## Version: X` line from a TOC byte
 // buffer. Writes into `out` (size `outSize`) and returns true on
@@ -135,38 +132,35 @@ using SMemFree_t = void(__stdcall *)(void *buf, const char *file, int line, int
 // sensitive on the key. Returns false if no Version line is found.
 bool ExtractTocVersion(const char *content, size_t size,
                        char *out, size_t outSize) {
-    static const char kKey[] = "## Version:";
-    constexpr size_t kKeyLen = sizeof(kKey) - 1;
-    for (size_t i = 0; i + kKeyLen <= size; ++i) {
-        const bool atLineStart = (i == 0) || content[i - 1] == '\n';
-        if (!atLineStart) continue;
-        if (std::memcmp(content + i, kKey, kKeyLen) != 0) continue;
-        const char *p = content + i + kKeyLen;
-        const char *end = content + size;
-        while (p < end && (*p == ' ' || *p == '\t')) ++p;
-        size_t j = 0;
-        while (p < end && *p != '\r' && *p != '\n' && j + 1 < outSize) {
-            out[j++] = *p++;
-        }
-        while (j > 0 && (out[j - 1] == ' ' || out[j - 1] == '\t')) --j;
-        out[j] = '\0';
-        return j > 0;
+    const char *v = nullptr;
+    size_t n = 0;
+    if (outSize == 0)
+        return false;
+    if (!AddOns::Toc::FindValue(content, size, "## Version:", &v, &n) || n == 0) {
+        out[0] = '\0';
+        return false;
     }
-    if (outSize > 0) out[0] = '\0';
-    return false;
+    if (n >= outSize)
+        n = outSize - 1;
+    std::memcpy(out, v, n);
+    out[n] = '\0';
+    return true;
 }
 
-// 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 +197,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<SMemFreeFn>(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);
@@ -232,7 +258,7 @@ void DecideSource() {
     // Free the disk buffer we just borrowed — we only needed it for
     // the version-line scrape. The actual content for the engine's
     // TOC read comes through the regular hook path below.
-    auto SMemFree = reinterpret_cast<SMemFree_t>(Offsets::FUN_STORM_SMEM_FREE);
+    auto SMemFree = reinterpret_cast<SMemFreeFn>(Offsets::FUN_STORM_SMEM_FREE);
     SMemFree(diskBuf, __FILE__, __LINE__, 0);
 
     // Missing or unparseable disk version → assume it's older than
@@ -259,10 +285,33 @@ int __stdcall FileRead_h(int unused, const char *path, void **outBuf,
 
     const char *suffix = StripAddonPrefix(path);
     if (suffix == nullptr) {
-        // Path isn't under `Interface\AddOns\!!!ClassicAPI\` — straight
-        // pass-through, we don't care.
-        return FileRead_o(unused, path, outBuf, outSize, extraBytes,
-                          flag1, flag2);
+        // Not our embedded addon. If this is a base-TOC read for a multi-flavor
+        // addon that ships only `<Name>_Turtle.toc` / `_ClassicAPI.toc`, serve
+        // that in place of the missing `<Name>.toc` so it registers and loads
+        // (see addons/FlavorToc.h).
+        int result;
+        if (AddOns::FlavorToc::TryHandle(unused, path, outBuf, outSize,
+                                         extraBytes, flag1, flag2, FileRead_o)) {
+            result = 1;
+        } else if (AddOns::FlavorBindings::TryHandle(unused, path, outBuf, outSize,
+                                                     extraBytes, flag1, flag2,
+                                                     FileRead_o)) {
+            // Flavor-specific addon keybindings: serve `Bindings_Turtle.xml` /
+            // `Bindings_ClassicAPI.xml` for a `…\AddOns\<Name>\Bindings.xml`
+            // read (see addons/FlavorBindings.h). The paired exists-check
+            // co-hook lives in that module.
+            result = 1;
+        } else {
+            result = FileRead_o(unused, path, outBuf, outSize, extraBytes,
+                                flag1, flag2);
+        }
+        // Per-line TOC directives: evaluate `[Condition]` and expand
+        // `[Variable]` tokens on this addon TOC's file lines so the load
+        // pass sees clean paths (see addons/TocRewrite.h). No-op unless
+        // `path` is an addon `.toc` that actually contains directives.
+        if (result != 0)
+            AddOns::TocRewrite::Transform(path, outBuf, outSize);
+        return result;
     }
 
     DecideSource();
@@ -289,7 +338,7 @@ int __stdcall FileRead_h(int unused, const char *path, void **outBuf,
                           flag1, flag2);
     }
 
-    auto SMemAlloc = reinterpret_cast<SMemAlloc_t>(
+    auto SMemAlloc = reinterpret_cast<SMemAllocFn>(
         Offsets::FUN_STORM_SMEM_ALLOC);
     const size_t totalSize = entry->size + extraBytes;
     void *buf = SMemAlloc(totalSize, __FILE__, __LINE__, 0);
@@ -336,7 +385,32 @@ using ListInsert_t = void(__thiscall *)(void *listCtrl, void *entry,
 constexpr uintptr_t VAR_ADDON_LIST_HEAD = 0x00BE1B6C;
 constexpr int OFF_ADDON_ENTRY_NAME_PTR = 0x14;
 
-void MoveEmbeddedToListHead() {
+// `entry+0x29` — the "filter-out" byte. The flat display-array builder
+// `FUN_0051da70` walks the linked list and copies an entry into
+// `GetNumAddOns`/`GetAddOnInfo`'s array ONLY when this byte is 0, so
+// setting it hides `!!!ClassicAPI` from the character-select AddOns
+// list — there's no checkbox, so it can't be toggled off. The builder
+// only ever *writes* this byte on the secure/SMSG path (`entry+0x28 !=
+// 0`); our entry is non-secure, so a manual `1` here is stable across
+// rebuilds. Hiding does NOT stop loading (the load pass `FUN_0051f600`
+// never reads `+0x29`) and does NOT break dependency resolution or
+// by-name queries (those use the addon hash table, which keeps the
+// entry regardless).
+constexpr int OFF_ADDON_ENTRY_FILTER_OUT = 0x29;
+
+// `entry+0x2b` — DefaultState (`## DefaultState: enabled/disabled`).
+// The enable resolver `FUN_ADDON_ENABLE_RESOLVE` falls back to this
+// when the player has no per-character override. Belt-and-suspenders
+// alongside the resolver co-hook below (which forces enabled anyway).
+constexpr int OFF_ADDON_ENTRY_DEFAULT_STATE = 0x2b;
+
+// Post-registration finalize for the embedded entry: move it to the
+// head of the load-order list (so consumers that read our globals from
+// their main chunk see them — see the block comment above the offsets),
+// hide it from the addon list, and mark it default-enabled. Combined
+// with the `FUN_ADDON_ENABLE_RESOLVE` co-hook, `!!!ClassicAPI` always
+// loads and never appears as a toggleable entry.
+void FinalizeEmbeddedEntry() {
     uintptr_t entry = *reinterpret_cast<uintptr_t *>(VAR_ADDON_LIST_HEAD);
     const int linkOffset = *reinterpret_cast<const int *>(
         static_cast<uintptr_t>(Offsets::VAR_ADDON_LIST_CTRL));
@@ -344,6 +418,11 @@ void MoveEmbeddedToListHead() {
         const char *name = *reinterpret_cast<const char *const *>(
             entry + OFF_ADDON_ENTRY_NAME_PTR);
         if (name != nullptr && std::strcmp(name, kAddonName) == 0) {
+            // Hide from the character-select AddOns list and default it
+            // to enabled.
+            *reinterpret_cast<uint8_t *>(entry + OFF_ADDON_ENTRY_FILTER_OUT) = 1;
+            *reinterpret_cast<uint8_t *>(entry + OFF_ADDON_ENTRY_DEFAULT_STATE) = 1;
+
             auto fn = reinterpret_cast<ListInsert_t>(
                 Offsets::FUN_INTRUSIVE_LIST_INSERT);
             fn(reinterpret_cast<void *>(
@@ -361,7 +440,24 @@ void __fastcall AddonInit_h(const char *accountName) {
     AddonInit_o(accountName);
     auto TocParser = reinterpret_cast<TocParser_t>(Offsets::FUN_TOC_PARSER);
     TocParser(kAddonName);
-    MoveEmbeddedToListHead();
+    FinalizeEmbeddedEntry();
+}
+
+// `FUN_ADDON_ENABLE_RESOLVE` — per-character enable resolver. We
+// co-hook it to force-enable `!!!ClassicAPI` regardless of DefaultState
+// or any stale WTF disable-override, so hiding it from the addon list
+// can never leave it stuck off. Returns 2 ("enabled for all"); the
+// load-pass gate only tests `!= 0`. Every other addon falls through to
+// the original untouched. See the Offsets.h note for the ABI.
+using AddonEnableResolve_t =
+    uint32_t(__fastcall *)(const char *name, const char *account, char resolveAll);
+AddonEnableResolve_t AddonEnableResolve_o = nullptr;
+
+uint32_t __fastcall AddonEnableResolve_h(const char *name, const char *account,
+                                         char resolveAll) {
+    if (name != nullptr && PathEqualsCI(name, kAddonName))
+        return 2;
+    return AddonEnableResolve_o(name, account, resolveAll);
 }
 
 const Game::HookAutoRegister _hookFileRead{
@@ -374,6 +470,11 @@ const Game::HookAutoRegister _hookAddonInit{
     reinterpret_cast<void *>(&AddonInit_h),
     reinterpret_cast<void **>(&AddonInit_o)};
 
+const Game::HookAutoRegister _hookEnableResolve{
+    Offsets::FUN_ADDON_ENABLE_RESOLVE,
+    reinterpret_cast<void *>(&AddonEnableResolve_h),
+    reinterpret_cast<void **>(&AddonEnableResolve_o)};
+
 } // namespace
 
 } // namespace Addons::Embedded

src/addons/EngineIO.h

@@ -0,0 +1,41 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <cstddef>
+
+// One home for the engine file-I/O and Storm-allocator function-pointer types
+// the addon modules call. These are ABI-critical: FUN_FILE_READ /
+// FUN_FILE_EXISTS / the Storm allocator are all `__stdcall` (callee cleans the
+// stack), and declaring one `__cdecl` by mistake drifts ESP a few bytes per
+// call and kills the process with no crash log. The shape lived in ~6 copies
+// across the addon files; centralize it so the convention cannot drift.
+namespace AddOns::EngineIO {
+
+// FUN_FILE_READ (0x00648620) — __stdcall, callee cleans 28 bytes (RET 0x1C).
+// arg0 is an optional archive handle (0 = merged VFS); outSize may be null.
+using FileReadFn = int(__stdcall *)(int unused, const char *path, void **outBuf,
+                                    size_t *outSize, size_t extraBytes,
+                                    int flag1, int flag2);
+
+// FUN_FILE_EXISTS (0x00648A30) — __stdcall, RET 8.
+using FileExistsFn = int(__stdcall *)(const char *path, int mode);
+
+// FUN_STORM_SMEM_ALLOC / FUN_STORM_SMEM_FREE — __stdcall, RET 0x10. Buffers
+// FUN_FILE_READ hands out are freed with SMemFreeFn; a buffer we allocate with
+// SMemAllocFn is freed cleanly by the engine's own SMemFree in turn.
+using SMemAllocFn = void *(__stdcall *)(size_t size, const char *file, int line, int flags);
+using SMemFreeFn = void(__stdcall *)(void *buf, const char *file, int line, int flags);
+
+} // namespace AddOns::EngineIO

src/addons/FlavorBindings.cpp

@@ -0,0 +1,130 @@
+// 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 "addons/EngineIO.h"
+#include "addons/FlavorBindings.h"
+#include "addons/Toc.h"
+
+#include "Game.h"
+#include "Offsets.h"
+#include "turtle/Detect.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+
+namespace AddOns::FlavorBindings {
+
+namespace {
+
+using AddOns::Toc::EqCI;
+using AddOns::Toc::Lower;
+
+constexpr size_t NPOS = static_cast<size_t>(-1);
+
+// If `path` is an addon Bindings read (`…\AddOns\<Name>\Bindings.xml`, CI),
+// return the length of the prefix up to the `Bindings.xml` filename (so a
+// flavor filename can be appended in its place); else NPOS.
+size_t AddonBindingsPrefix(const char *path) {
+    if (path == nullptr) return NPOS;
+    const size_t len = std::strlen(path);
+    const char *kFile = "bindings.xml"; // 12 chars, compared case-insensitively
+    const size_t flen = 12;
+    if (len < flen + 1) return NPOS;
+    for (size_t i = 0; i < flen; ++i)
+        if (Lower(path[len - flen + i]) != kFile[i]) return NPOS;
+    const size_t prefixLen = len - flen;
+    if (path[prefixLen - 1] != '\\' && path[prefixLen - 1] != '/')
+        return NPOS; // "Bindings.xml" must be a whole path segment
+    for (size_t i = 0; i + 8 <= len; ++i)
+        if (EqCI(path + i, 8, "\\AddOns\\")) return prefixLen;
+    return NPOS;
+}
+
+// Write `<prefix><flavorFile>` (e.g. `…\AddOns\Foo\Bindings_Turtle.xml`) into
+// `out`. Returns false if it would not fit.
+bool BuildFlavorPath(const char *path, size_t prefixLen, const char *flavorFile,
+                     char *out, size_t outSize) {
+    const size_t flen = std::strlen(flavorFile);
+    if (prefixLen + flen + 1 > outSize) return false;
+    std::memcpy(out, path, prefixLen);
+    std::memcpy(out + prefixLen, flavorFile, flen + 1); // incl. NUL
+    return true;
+}
+
+// Fills `order` with the flavor filenames to probe, most specific first, and
+// returns the count. `Bindings_Turtle.xml` only on a Turtle client.
+int FlavorOrder(const char *(&order)[2]) {
+    int count = 0;
+    if (Turtle::Detected())
+        order[count++] = "Bindings_Turtle.xml";
+    order[count++] = "Bindings_ClassicAPI.xml";
+    return count;
+}
+
+// Engine file-exists probe FUN_00648a30 — __stdcall(path, mode) (RET 8).
+using EngineIO::FileExistsFn;
+FileExistsFn g_origExists = nullptr;
+
+// Co-hook the exists-check so `Interface\AddOns\<Name>\Bindings.xml` reports as
+// existing when the base file is absent but a flavor variant is present — so
+// the loader (`FUN_004b6f70`, then our TryHandle redirect) runs for a
+// flavor-only addon. Every non-Bindings path passes straight through.
+int __stdcall FileExists_h(const char *path, int mode) {
+    const size_t prefixLen = AddonBindingsPrefix(path);
+    if (prefixLen == NPOS)
+        return g_origExists(path, mode);
+
+    if (g_origExists(path, mode) != 0)
+        return 1; // the plain Bindings.xml exists
+
+    const char *order[2];
+    const int count = FlavorOrder(order);
+    char cand[512];
+    for (int i = 0; i < count; ++i) {
+        if (BuildFlavorPath(path, prefixLen, order[i], cand, sizeof cand) &&
+            g_origExists(cand, mode) != 0)
+            return 1;
+    }
+    return 0;
+}
+
+const Game::HookAutoRegister _hookExists{
+    Offsets::FUN_FILE_EXISTS,
+    reinterpret_cast<void *>(&FileExists_h),
+    reinterpret_cast<void **>(&g_origExists)};
+
+} // namespace
+
+bool TryHandle(int unused, const char *path, void **outBuf, size_t *outSize,
+               size_t extraBytes, int flag1, int flag2, FileReadFn orig) {
+    const size_t prefixLen = AddonBindingsPrefix(path);
+    if (prefixLen == NPOS)
+        return false;
+
+    const char *order[2];
+    const int count = FlavorOrder(order);
+    char cand[512];
+    for (int i = 0; i < count; ++i) {
+        if (!BuildFlavorPath(path, prefixLen, order[i], cand, sizeof cand))
+            continue;
+        // Serve the flavor file in place of Bindings.xml (a selected flavor
+        // wins over a plain Bindings.xml). No recursion: `orig` is the original
+        // reader passed by the FUN_FILE_READ hook.
+        if (orig(unused, cand, outBuf, outSize, extraBytes, flag1, flag2) != 0)
+            return true;
+    }
+    return false; // no flavor variant — caller reads the base Bindings.xml
+}
+
+} // namespace AddOns::FlavorBindings

src/addons/FlavorBindings.h

@@ -0,0 +1,55 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <cstddef>
+
+#include "addons/EngineIO.h"
+
+namespace AddOns::FlavorBindings {
+
+using EngineIO::FileReadFn;
+
+// Flavor-specific addon Bindings selection — the Bindings.xml analog of
+// AddOns::FlavorToc.
+//
+// A modern addon can ship a flavor-specific keybinding file
+// (`Bindings_Turtle.xml` / `Bindings_ClassicAPI.xml`) instead of / alongside a
+// plain `Bindings.xml`. The per-addon loader `FUN_0051f240` only ever builds
+// `Interface\AddOns\<Name>\Bindings.xml`, gates it on an exists-check
+// (`FUN_00648a30`), and — when that passes — loads it via `FUN_004b6f70`, which
+// reads the file through `FUN_FILE_READ`. Two pieces make flavor files work:
+//
+//   1. This TryHandle, called from the FUN_FILE_READ hook: when `path` is an
+//      addon `…\AddOns\<Name>\Bindings.xml` read, serve a flavor variant in its
+//      place if one exists (a selected flavor wins over a plain `Bindings.xml`,
+//      matching FlavorToc). Probe order `Bindings_Turtle.xml` (only when
+//      Turtle::Detected) then `Bindings_ClassicAPI.xml`.
+//   2. A co-hook on the exists-check `FUN_00648a30` (inside FlavorBindings.cpp):
+//      report `Bindings.xml` as existing when the base is absent but a flavor
+//      variant is present — otherwise the loader is never called for a
+//      flavor-only addon.
+//
+// Only `_Turtle` / `_ClassicAPI` are selected — never `_Vanilla` / `_Classic`
+// (which target the 1.15 Classic Era build; its bindings reference handlers
+// that build defines and this client does not load, so they would bind to
+// missing functions). Both suffixes are ClassicAPI conventions, opt-in by the
+// addon author, and mirror FlavorToc.
+//
+// Returns false when `path` is not an addon Bindings.xml read or no flavor
+// variant exists — the caller then performs the normal base read.
+bool TryHandle(int unused, const char *path, void **outBuf, size_t *outSize,
+               size_t extraBytes, int flag1, int flag2, FileReadFn orig);
+
+} // namespace AddOns::FlavorBindings

src/addons/FlavorToc.cpp

@@ -0,0 +1,108 @@
+// 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 "addons/FlavorToc.h"
+
+#include "turtle/Detect.h"
+
+#include <cstring>
+
+namespace AddOns::FlavorToc {
+
+namespace {
+
+// If `path` is `…\AddOns\<Name>\<Name>.toc` (case-insensitive), set `*prefixLen`
+// to the byte length of the path up to and including the base `<Name>` filename
+// (so a `_Vanilla.toc` suffix can be appended in place) and return true.
+bool ParseBaseToc(const char *path, size_t *prefixLen) {
+    const size_t len = std::strlen(path);
+    if (len < 5 || _strnicmp(path + len - 4, ".toc", 4) != 0)
+        return false;
+
+    // Last separator -> "<Name>.toc" file part.
+    size_t lastSep = static_cast<size_t>(-1);
+    for (size_t i = len; i-- > 0;)
+        if (path[i] == '\\' || path[i] == '/') { lastSep = i; break; }
+    if (lastSep == static_cast<size_t>(-1))
+        return false;
+    const char *file = path + lastSep + 1;              // "<Name>.toc"
+    const size_t nameLen = (len - (lastSep + 1)) - 4;   // strip ".toc"
+    if (nameLen == 0)
+        return false;
+
+    // Previous separator -> "<Name>" folder segment; it must equal the base name.
+    size_t prevSep = static_cast<size_t>(-1);
+    for (size_t i = lastSep; i-- > 0;)
+        if (path[i] == '\\' || path[i] == '/') { prevSep = i; break; }
+    if (prevSep == static_cast<size_t>(-1))
+        return false;
+    const char *folder = path + prevSep + 1;
+    const size_t folderLen = lastSep - (prevSep + 1);
+    if (folderLen != nameLen || _strnicmp(folder, file, nameLen) != 0)
+        return false;
+
+    // Grandparent segment must be "AddOns" (so FrameXML/other .toc reads pass through).
+    size_t prev2Sep = static_cast<size_t>(-1);
+    for (size_t i = prevSep; i-- > 0;)
+        if (path[i] == '\\' || path[i] == '/') { prev2Sep = i; break; }
+    if (prev2Sep == static_cast<size_t>(-1))
+        return false;
+    const char *gp = path + prev2Sep + 1;
+    const size_t gpLen = prevSep - (prev2Sep + 1);
+    if (gpLen != 6 || _strnicmp(gp, "AddOns", 6) != 0)
+        return false;
+
+    *prefixLen = lastSep + 1 + nameLen; // "…\AddOns\<Name>\<Name>"
+    return true;
+}
+
+} // namespace
+
+bool TryHandle(int unused, const char *path, void **outBuf, size_t *outSize,
+               size_t extraBytes, int flag1, int flag2, FileReadFn orig) {
+    if (path == nullptr)
+        return false;
+
+    size_t prefixLen = 0;
+    if (!ParseBaseToc(path, &prefixLen))
+        return false;
+
+    char cand[512];
+    if (prefixLen + 16 >= sizeof cand) // "_ClassicAPI.toc" + NUL is 16 (longest)
+        return false;                  // pathological path length — let base read run
+    std::memcpy(cand, path, prefixLen);
+
+    // Only flavors that describe THIS environment, most specific first:
+    //   `_Turtle`     — Turtle client/content, only when Turtle is detected;
+    //   `_ClassicAPI` — 1.12 + ClassicAPI, ALWAYS (ClassicAPI is present by
+    //                   definition — it is the code doing this redirect).
+    // Deliberately NOT `_Vanilla`/`_Classic` (those target the 1.15 Classic Era
+    // client — a modern engine + full modern API — which this 1.12 +
+    // partial-backport client is not), nor `_Mainline`/`_Cata`/etc.
+    const char *order[2];
+    int count = 0;
+    if (Turtle::Detected())
+        order[count++] = "_Turtle.toc";
+    order[count++] = "_ClassicAPI.toc";
+
+    for (int i = 0; i < count; ++i) {
+        std::memcpy(cand + prefixLen, order[i], std::strlen(order[i]) + 1); // incl. NUL
+        if (orig(unused, cand, outBuf, outSize, extraBytes, flag1, flag2) != 0)
+            return true; // served the flavor TOC in place of the base
+    }
+    // No matching flavor TOC — fall through: the caller reads the base path,
+    // which chains through any other FUN_FILE_READ hooker before the engine.
+    return false;
+}
+
+} // namespace AddOns::FlavorToc

src/addons/FlavorToc.h

@@ -0,0 +1,60 @@
+// 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>
+
+#include "addons/EngineIO.h"
+
+namespace AddOns::FlavorToc {
+
+using EngineIO::FileReadFn;
+
+// Modern-client multi-flavor TOC selection, backported.
+//
+// A modern addon that targets several game flavors from one folder ships
+// `<Name>_Vanilla.toc` / `_Mainline.toc` / `_Cata.toc` / … and often NO plain
+// `<Name>.toc`. Vanilla 1.12 only ever opens `<Name>\<Name>.toc`, so such an
+// addon never registers — it is invisible, not merely mis-loaded.
+//
+// Called from the FUN_FILE_READ hook. If `path` is an addon base-TOC read
+// (`…\AddOns\<Name>\<Name>.toc`), probe the flavor TOCs that describe THIS
+// environment and, if one exists, serve it via `orig` (as if it were the base
+// TOC) and return true. Order, most specific first:
+//   `<Name>_Turtle.toc`     — Turtle client/content, ONLY when Turtle is
+//                             detected (Turtle::Detected); a ClassicAPI extension;
+//   `<Name>_ClassicAPI.toc` — 1.12 + ClassicAPI, ALWAYS (ClassicAPI is present
+//                             by definition — it is the code doing this redirect).
+// Both are ClassicAPI conventions, not retail flavors. We deliberately do NOT
+// map to `_Vanilla`/`_Classic` (those target the 1.15 Classic Era client — a
+// modern engine + full modern API — which a 1.12 + partial-backport client is
+// not), nor `_Mainline`/`_Cata`/etc. A selected flavor wins over an existing
+// base `<Name>.toc`. If neither flavor exists, TryHandle returns false and the
+// caller does the normal base read — which chains through any other DLL that
+// hooked FUN_FILE_READ before reaching the engine.
+//
+// The redirect fires at BOTH the registration scan (glue/char-select) and the
+// in-world load pass, which must agree on the flavor. `Turtle::Detected()` is
+// therefore consistent across both: it reads the in-world `TURTLE_WOW_VERSION`
+// global AND Turtle's glue-time `TURTLE_*` GlueXML globals, so it returns true
+// at the glue scan too (see turtle/Detect.h).
+//
+// Returns false when `path` is not a base-TOC read, or no vanilla flavor TOC
+// exists — the caller then performs the normal base read. Because the redirect
+// is at the read layer, the addon scan (FUN_0051C9B0), the load pass
+// (FUN_006edb90) and GetAddOnMetadata all see the same selected TOC.
+bool TryHandle(int unused, const char *path, void **outBuf, size_t *outSize,
+               size_t extraBytes, int flag1, int flag2, FileReadFn orig);
+
+} // namespace AddOns::FlavorToc

src/addons/LocalTable.cpp

@@ -0,0 +1,132 @@
+// 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_AddOns.GetAddOnLocalTable(name)` — the public, gated view of an addon's
+// private namespace table (the `local _, addonTable = ...` second vararg the
+// transpiler injects; see luasyntax/AddonNamespace.h).
+//
+// Retail added this in 11.0 alongside the `## AllowAddOnTableAccess` TOC
+// directive: one addon can read another's local table ONLY when the target
+// opts in. We mirror that gate:
+//   1. the named addon is currently LOADED, and
+//   2. its `.toc` declares `## AllowAddOnTableAccess: 1`.
+// Either check failing returns nil. The internal preamble path (an addon
+// receiving its OWN table) is a different, ungated function (`__addonns`) —
+// an addon never needs permission for its own namespace.
+//
+// Directive spelling verified against the 1.15.8 Classic Era binary (both the
+// `AllowAddOnTableAccess:` TOC key and the `GetAddOnLocalTable` name are
+// present there). The vanilla 1.12 TOC parser drops unknown `##` directives,
+// so we scan the `.toc` ourselves via `FUN_FILE_READ`.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "addons/EngineIO.h"
+#include "addons/Toc.h"
+#include "luasyntax/AddonNamespace.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <cstdio>
+
+namespace AddOns::LocalTable {
+
+namespace {
+
+// IS_LOADED is a by-name hash lookup returning the loaded byte (`entry+0x18`);
+// passing the name string works because the lookup hashes it. See Offsets.h.
+using IsLoadedFn_t = uint8_t(__fastcall *)(const char *name);
+
+// FUN_FILE_READ / the Storm free (see addons/EngineIO.h). Calling the raw
+// FUN_FILE_READ address routes through Embedded's file-read hook, which forwards
+// every non-`!!!ClassicAPI` path to the original untouched — what we want here.
+using AddOns::EngineIO::FileReadFn;
+using AddOns::EngineIO::SMemFreeFn;
+
+// True iff the addon's `.toc` has a line `## AllowAddOnTableAccess: <nonzero>`.
+// The value is read as a TOC boolean flag: parse the leading integer, true iff
+// non-zero (so `1` opts in, `0`/absent do not) — matching WoW's numeric TOC
+// flag semantics. Not cached: GetAddOnLocalTable is not a hot path.
+bool TocAllowsTableAccess(const char *name) {
+    // A registered, loaded addon name never carries a path separator; reject
+    // any that does so the read stays bounded to the addon's own folder.
+    for (const char *p = name; *p; ++p)
+        if (*p == '\\' || *p == '/')
+            return false;
+
+    char path[300];
+    std::snprintf(path, sizeof path, "Interface\\AddOns\\%s\\%s.toc", name, name);
+
+    void *buf = nullptr;
+    size_t size = 0;
+    auto fileRead = reinterpret_cast<FileReadFn>(Offsets::FUN_FILE_READ);
+    if (fileRead(0, path, &buf, &size, 1, 1, 0) == 0 || buf == nullptr)
+        return false;
+
+    const char *v = nullptr;
+    size_t n = 0;
+    bool allowed = false;
+    if (AddOns::Toc::FindValue(static_cast<const char *>(buf), size,
+                               "## AllowAddOnTableAccess:", &v, &n)) {
+        int value = 0;
+        bool anyDigit = false;
+        for (size_t k = 0; k < n && v[k] >= '0' && v[k] <= '9'; ++k) {
+            value = value * 10 + (v[k] - '0');
+            anyDigit = true;
+        }
+        allowed = anyDigit && value != 0;
+    }
+
+    auto smemFree = reinterpret_cast<SMemFreeFn>(Offsets::FUN_STORM_SMEM_FREE);
+    smemFree(buf, __FILE__, __LINE__, 0);
+    return allowed;
+}
+
+// `C_AddOns.GetAddOnLocalTable(name)` -> table, or nil.
+//
+// Name (string) input only — the local table is a by-name concept (one addon
+// asking for another by name), and the namespace map is name-keyed. Numeric
+// index is not accepted (returns nil); no addon references another's table by
+// load order.
+int __fastcall Script_GetAddOnLocalTable(void *L) {
+    const char *name = Game::Lua::ToString(L, 1);
+    if (name == nullptr || *name == '\0') {
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+
+    auto isLoaded = reinterpret_cast<IsLoadedFn_t>(Offsets::FUN_ADDON_IS_LOADED);
+    if (isLoaded(name) == 0) { // not loaded (covers "does not exist")
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+
+    if (!TocAllowsTableAccess(name)) { // opted out / no directive
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+
+    LuaSyntax::PushAddonNamespace(L, name);
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_AddOns", "GetAddOnLocalTable",
+                                     &Script_GetAddOnLocalTable);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace AddOns::LocalTable

src/addons/SavedVarsFirst.cpp

@@ -0,0 +1,270 @@
+// 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/>.
+
+// `## LoadSavedVariablesFirst: 1` — modern TOC directive, backported.
+//
+// Retail loads a flagged addon's SavedVariables BEFORE its Lua runs, so
+// file-scope code (`local db = MyAddonDB`) sees restored config immediately.
+// Vanilla 1.12 always does the opposite: the per-addon loader `FUN_0051f240`
+// runs the addon's files (`FUN_ADDON_LOAD_FILES`), THEN loads SavedVariables,
+// THEN fires `ADDON_LOADED`. So file-scope SV is always nil, and vanilla never
+// parses the directive at all.
+//
+// We co-hook `FUN_ADDON_LOAD_FILES` (the per-addon file load, once per addon,
+// in-world). For an addon whose TOC declares `## LoadSavedVariablesFirst`
+// (nonzero), load its SavedVariables first — mirroring the engine's OWN path
+// construction two steps later in `FUN_0051f240` (verified by disassembly):
+//   account : WTF\Account\<account>\SavedVariables\<Name>.lua
+//   per-char: WTF\Account\<account>\<realm>\<character>\SavedVariables\<Name>.lua,
+//             falling back to WTF\Account\<account>\<character>\SavedVariables\<Name>.lua
+// (account = *VAR_ACCOUNT_NAME_PTR, realm = FUN_GET_REALM_NAME,
+// character = FUN_GET_LOGIN_ACCOUNT_NAME) — then call the original so the
+// files run with SV present. `FUN_LUA_LOAD_FILE` no-ops on a missing file, and
+// `FUN_FILE_EXISTS` picks the same per-char variant the engine would.
+//
+// The engine STILL runs its own SavedVariables load at the normal step, right
+// after the files. Left alone, that re-load would overwrite any value the
+// addon wrote to its SavedVariable at file scope before ADDON_LOADED. So we
+// also co-hook FUN_LUA_LOAD_FILE and suppress that one redundant re-load: each
+// path we pre-load is remembered, and the engine's imminent load of that exact
+// path is skipped once. This makes the behavior match true
+// LoadSavedVariablesFirst — file-scope reads AND writes both survive. Our own
+// early load calls the trampoline directly, so it is never self-suppressed.
+// FUN_LUA_LOAD_FILE loads FILES only (not RunScript string execution), so the
+// extra hook is a cold, addon-load-time path.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "addons/EngineIO.h"
+#include "addons/Toc.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <cstdio>
+#include <cstring>
+#include <string>
+#include <vector>
+
+namespace AddOns::SavedVarsFirst {
+
+namespace {
+
+constexpr size_t NPOS = static_cast<size_t>(-1);
+
+// Engine file I/O via the hooked FUN_FILE_READ (so a flavor TOC's flag is read —
+// FlavorToc applies), the exists-check, and the Storm free. See addons/EngineIO.h.
+using AddOns::EngineIO::FileExistsFn;
+using AddOns::EngineIO::FileReadFn;
+using AddOns::EngineIO::SMemFreeFn;
+using LoadTocFilesFn = uint32_t(__fastcall *)(char *tocPath, int *a2, int *a3);
+using LuaLoadFileFn = uint32_t(__fastcall *)(const char *path, void *a2, void *a3);
+using NameFn = const char *(*)(); // no-arg readers (return in EAX)
+
+LoadTocFilesFn g_orig = nullptr;
+LuaLoadFileFn g_origLuaLoad = nullptr;
+
+// Full SV paths we pre-loaded whose imminent engine re-load must be skipped
+// once. Populated in LoadSavedVarsEarly, drained by LuaLoad_h. Only ever holds
+// a handful of entries (one addon's SV files, briefly). Main-thread only.
+std::vector<std::string> g_pendingSuppress;
+
+using AddOns::Toc::EqCI;
+using AddOns::Toc::Lower;
+
+bool SamePathCI(const char *a, const char *b) {
+    for (; *a != '\0' && *b != '\0'; ++a, ++b)
+        if (Lower(*a) != Lower(*b)) return false;
+    return *a == *b;
+}
+
+// Extract "<Name>" from an addon base-TOC path `…\AddOns\<Name>\<Name>.toc`.
+// Returns false for anything else (FrameXML.toc, nested paths, …) so the
+// SavedVariables reorder only touches real addon loads.
+bool AddonNameFromToc(const char *path, char *out, size_t outSize) {
+    const size_t len = std::strlen(path);
+    if (len < 4 || !(path[len - 4] == '.' && Lower(path[len - 3]) == 't' &&
+                     Lower(path[len - 2]) == 'o' && Lower(path[len - 1]) == 'c'))
+        return false;
+    size_t lastSep = NPOS;
+    for (size_t i = len; i-- > 0;)
+        if (path[i] == '\\' || path[i] == '/') { lastSep = i; break; }
+    if (lastSep == NPOS) return false;
+    size_t prevSep = NPOS;
+    for (size_t i = lastSep; i-- > 0;)
+        if (path[i] == '\\' || path[i] == '/') { prevSep = i; break; }
+    if (prevSep == NPOS) return false;
+    size_t gpSep = NPOS;
+    for (size_t i = prevSep; i-- > 0;)
+        if (path[i] == '\\' || path[i] == '/') { gpSep = i; break; }
+    if (gpSep == NPOS) return false;
+    if (prevSep - (gpSep + 1) != 6 || !EqCI(path + gpSep + 1, 6, "AddOns"))
+        return false;
+    const size_t nameLen = lastSep - (prevSep + 1);
+    if (nameLen == 0 || nameLen + 1 > outSize) return false;
+    std::memcpy(out, path + prevSep + 1, nameLen);
+    out[nameLen] = '\0';
+    return true;
+}
+
+// True iff the leading integer of a TOC value is nonzero (WoW numeric flag).
+bool NonzeroFlag(const char *v, size_t n) {
+    long val = 0;
+    bool digit = false;
+    for (size_t i = 0; i < n && v[i] >= '0' && v[i] <= '9'; ++i) {
+        val = val * 10 + (v[i] - '0');
+        digit = true;
+    }
+    return digit && val != 0;
+}
+
+// The SavedVariables directives that decide what LoadSavedVarsEarly does.
+struct SvFlags {
+    bool first = false;   // `## LoadSavedVariablesFirst:` is nonzero
+    bool account = false; // `## SavedVariables:` declares at least one variable
+    bool perChar = false; // `## SavedVariablesPerCharacter:` declares at least one
+};
+
+// Read the addon's TOC once (through the hooked FUN_FILE_READ, so a flavor
+// TOC's directives are honored) and extract the three flags above.
+SvFlags ReadSvFlags(const char *tocPath) {
+    SvFlags f;
+    auto FileRead =
+        reinterpret_cast<FileReadFn>(static_cast<uintptr_t>(Offsets::FUN_FILE_READ));
+    void *buf = nullptr;
+    size_t size = 0;
+    if (FileRead(0, tocPath, &buf, &size, 1, 1, 0) == 0 || buf == nullptr)
+        return f;
+    const char *b = static_cast<const char *>(buf);
+
+    const char *v = nullptr;
+    size_t n = 0;
+    if (AddOns::Toc::FindValue(b, size, "## LoadSavedVariablesFirst:", &v, &n))
+        f.first = NonzeroFlag(v, n);
+    // Gate each SV file on the DECLARATION, not mere file existence — mirroring
+    // the engine, which loads the account file iff `## SavedVariables` is
+    // declared and the per-char file iff `## SavedVariablesPerCharacter` is.
+    // (The trailing `:` keeps "## SavedVariables:" from matching the
+    // "## SavedVariablesPerCharacter:" line.) Otherwise a stale SV file from a
+    // scope the addon no longer declares would be executed early — Lua the
+    // engine never runs — and queued for a suppression the engine never drains.
+    f.account = AddOns::Toc::FindValue(b, size, "## SavedVariables:", &v, &n) && n > 0;
+    f.perChar =
+        AddOns::Toc::FindValue(b, size, "## SavedVariablesPerCharacter:", &v, &n) && n > 0;
+
+    reinterpret_cast<SMemFreeFn>(static_cast<uintptr_t>(Offsets::FUN_STORM_SMEM_FREE))(
+        buf, __FILE__, __LINE__, 0);
+    return f;
+}
+
+bool FileExists(const char *path) {
+    return reinterpret_cast<FileExistsFn>(
+               static_cast<uintptr_t>(Offsets::FUN_FILE_EXISTS))(path, 1) != 0;
+}
+
+// Load a SavedVariables file we found, then mark its path so the engine's own
+// re-load of it (right after the addon's files) is suppressed — preserving any
+// file-scope write. Calls the trampoline directly so this load is never itself
+// suppressed by our LuaLoad_h hook.
+void RunLuaFile(const char *path) {
+    if (g_origLuaLoad == nullptr)
+        return;
+    g_origLuaLoad(path, nullptr, nullptr);
+    g_pendingSuppress.emplace_back(path);
+}
+
+// Load the addon's SavedVariables early, mirroring FUN_0051f240's own paths.
+// Each scope loads only when its directive is declared (`hasAccount` /
+// `hasPerChar`) AND the file exists — exactly what the engine's own SV step
+// would re-load, so every suppress entry we queue is later drained.
+void LoadSavedVarsEarly(const char *addonName, bool hasAccount, bool hasPerChar) {
+    const char *account = *reinterpret_cast<const char *const *>(
+        static_cast<uintptr_t>(Offsets::VAR_ACCOUNT_NAME_PTR));
+    if (account == nullptr || *account == '\0')
+        return;
+
+    char path[260];
+
+    // Account-wide (`## SavedVariables`).
+    if (hasAccount) {
+        std::snprintf(path, sizeof path, "WTF\\Account\\%s\\SavedVariables\\%s.lua",
+                      account, addonName);
+        if (FileExists(path))
+            RunLuaFile(path);
+    }
+
+    // Per-character (`## SavedVariablesPerCharacter`): prefer the realm-scoped
+    // file, else the realm-less one — the engine's own fallback order.
+    if (!hasPerChar)
+        return;
+    const char *character = reinterpret_cast<NameFn>(
+        static_cast<uintptr_t>(Offsets::FUN_GET_LOGIN_ACCOUNT_NAME))();
+    if (character == nullptr || *character == '\0')
+        return;
+    const char *realm = reinterpret_cast<NameFn>(
+        static_cast<uintptr_t>(Offsets::FUN_GET_REALM_NAME))();
+
+    if (realm != nullptr && *realm != '\0') {
+        std::snprintf(path, sizeof path,
+                      "WTF\\Account\\%s\\%s\\%s\\SavedVariables\\%s.lua", account,
+                      realm, character, addonName);
+        if (FileExists(path)) {
+            RunLuaFile(path);
+            return;
+        }
+    }
+    std::snprintf(path, sizeof path, "WTF\\Account\\%s\\%s\\SavedVariables\\%s.lua",
+                  account, character, addonName);
+    if (FileExists(path))
+        RunLuaFile(path);
+}
+
+uint32_t __fastcall LoadTocFiles_h(char *tocPath, int *a2, int *a3) {
+    char name[128];
+    if (tocPath != nullptr && AddonNameFromToc(tocPath, name, sizeof name)) {
+        const SvFlags f = ReadSvFlags(tocPath);
+        if (f.first)
+            LoadSavedVarsEarly(name, f.account, f.perChar);
+    }
+    return g_orig(tocPath, a2, a3);
+}
+
+// Skip the engine's one redundant SavedVariables re-load per pre-loaded path.
+// Every other file load passes straight through. Match is by full path
+// (case-insensitive); a path is suppressed exactly once, so nothing else is
+// affected. Our own early load bypasses this via the trampoline.
+uint32_t __fastcall LuaLoad_h(const char *path, void *a2, void *a3) {
+    if (path != nullptr) {
+        for (size_t i = 0; i < g_pendingSuppress.size(); ++i) {
+            if (SamePathCI(g_pendingSuppress[i].c_str(), path)) {
+                g_pendingSuppress.erase(g_pendingSuppress.begin() +
+                                        static_cast<std::ptrdiff_t>(i));
+                return 0; // suppress — the addon's file-scope SV writes survive
+            }
+        }
+    }
+    return g_origLuaLoad(path, a2, a3);
+}
+
+const Game::HookAutoRegister _hook{
+    Offsets::FUN_ADDON_LOAD_FILES,
+    reinterpret_cast<void *>(&LoadTocFiles_h),
+    reinterpret_cast<void **>(&g_orig)};
+
+const Game::HookAutoRegister _hookLua{
+    Offsets::FUN_LUA_LOAD_FILE,
+    reinterpret_cast<void *>(&LuaLoad_h),
+    reinterpret_cast<void **>(&g_origLuaLoad)};
+
+} // namespace
+
+} // namespace AddOns::SavedVarsFirst

src/addons/Toc.h

@@ -0,0 +1,69 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <cstddef>
+#include <cstring>
+
+namespace AddOns::Toc {
+
+// Fold an ASCII letter to lower case (leaves every other byte unchanged).
+inline char Lower(char c) {
+    return (c >= 'A' && c <= 'Z') ? static_cast<char>(c + 32) : c;
+}
+
+// Case-insensitive equality of the `n` bytes at `s` against the NUL-terminated
+// `lit` (ASCII). True only when the lengths match too. Shared by the addon
+// modules that scan `…\AddOns\<Name>\…` paths and TOC directive lines.
+inline bool EqCI(const char *s, size_t n, const char *lit) {
+    for (size_t i = 0; i < n; ++i)
+        if (lit[i] == '\0' || Lower(s[i]) != Lower(lit[i]))
+            return false;
+    return lit[n] == '\0';
+}
+
+// Scans an in-memory TOC buffer for `directive` (the full line prefix, e.g.
+// "## Version:") at a line start, case-insensitively, and returns the value
+// that follows via out-params: [*valStart, *valStart + *valLen), trimmed of
+// leading and trailing spaces/tabs and excluding the CR/LF/EOF terminator.
+// Returns false (out-params untouched) when the directive is absent. Pure —
+// reads no files; the caller owns the buffer (via FUN_FILE_READ, or an embedded
+// copy). Shared by addons/LocalTable.cpp (AllowAddOnTableAccess) and
+// addons/Embedded.cpp (Version) so the line-scan lives in one place.
+inline bool FindValue(const char *buf, size_t size, const char *directive,
+                      const char **valStart, size_t *valLen) {
+    const size_t dlen = std::strlen(directive);
+    if (dlen == 0)
+        return false;
+    for (size_t i = 0; i + dlen <= size; ++i) {
+        const bool atLineStart = (i == 0) || buf[i - 1] == '\n';
+        if (!atLineStart || _strnicmp(buf + i, directive, dlen) != 0)
+            continue;
+        const char *p = buf + i + dlen;
+        const char *end = buf + size;
+        while (p < end && (*p == ' ' || *p == '\t'))
+            ++p;
+        const char *v = p;
+        while (p < end && *p != '\r' && *p != '\n')
+            ++p;
+        while (p > v && (p[-1] == ' ' || p[-1] == '\t'))
+            --p;
+        *valStart = v;
+        *valLen = static_cast<size_t>(p - v);
+        return true;
+    }
+    return false;
+}
+
+} // namespace AddOns::Toc

src/addons/TocRewrite.cpp

@@ -0,0 +1,297 @@
+// 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 "addons/EngineIO.h"
+#include "addons/TocRewrite.h"
+#include "addons/Toc.h"
+
+#include "Offsets.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <string>
+
+namespace AddOns::TocRewrite {
+
+namespace {
+
+using AddOns::EngineIO::SMemAllocFn;
+using AddOns::EngineIO::SMemFreeFn;
+using AddOns::Toc::EqCI;
+using AddOns::Toc::Lower;
+
+bool IsSpace(char c) { return c == ' ' || c == '\t'; }
+
+// The client locale code ("enUS", "frFR", …) — the exact string
+// GetLocale() returns (Offsets.h VAR_LOCALE_NAME_TABLE derivation).
+const char *ClientLocale() {
+    uint32_t idx = *reinterpret_cast<const uint32_t *>(
+        static_cast<uintptr_t>(Offsets::VAR_LOCALE_INDEX));
+    if (idx > 7) idx = 0; // slot 8 overreads the string pool — clamp
+    const char *const *table = reinterpret_cast<const char *const *>(
+        static_cast<uintptr_t>(Offsets::VAR_LOCALE_NAME_TABLE));
+    const char *s = table[idx];
+    return (s != nullptr) ? s : "enUS";
+}
+
+// True iff the comma-separated `list` (spaces allowed) contains `token` (CI).
+bool ListContains(const char *list, size_t listLen, const char *token) {
+    size_t i = 0;
+    while (i < listLen) {
+        while (i < listLen && (IsSpace(list[i]) || list[i] == ',')) ++i;
+        const size_t start = i;
+        while (i < listLen && list[i] != ',') ++i;
+        size_t end = i; // [start, end) is one item, maybe with trailing space
+        while (end > start && IsSpace(list[end - 1])) --end;
+        if (end > start && EqCI(list + start, end - start, token)) return true;
+    }
+    return false;
+}
+
+// A single-word `[Token]` variable expansion, or nullptr if `head` is not
+// a known variable. This 1.12 + ClassicAPI client is the Classic family,
+// the Vanilla game type, and whatever the client text locale is.
+const char *VariableValue(const char *head, size_t headLen) {
+    if (EqCI(head, headLen, "Family")) return "Classic";
+    if (EqCI(head, headLen, "Game")) return "Vanilla";
+    if (EqCI(head, headLen, "TextLocale")) return ClientLocale();
+    return nullptr;
+}
+
+// The client interface version the loadability check compares against
+// (FUN_0051d7d0 -> 0x2BC0 = 11200). Read live so we mirror the engine's own
+// value rather than hardcoding it.
+using ClientIfaceVer_t = uint32_t(__cdecl *)();
+uint32_t ClientInterfaceVersion() {
+    return reinterpret_cast<ClientIfaceVer_t>(
+        static_cast<uintptr_t>(Offsets::FUN_ADDON_CLIENT_INTERFACE_VERSION))();
+}
+
+// If `line` is a `## Interface:` directive whose value is a comma-list that
+// contains the client version but does NOT lead with it, append a normalized
+// `<prefix>: <clientVersion>` line to `out` and return true. Vanilla's parser
+// reads only the first number, so without this a later 11200 is never seen and
+// the addon is marked out of date. Returns false for any other line, and for
+// an interface line that needs no change (single value, no client version, or
+// client version already first) — the caller then copies the line verbatim.
+bool TryRewriteInterfaceLine(const char *line, size_t len, std::string &out) {
+    size_t s = 0;
+    while (s < len && IsSpace(line[s])) ++s;
+    if (s + 1 >= len || line[s] != '#' || line[s + 1] != '#') return false;
+    size_t p = s + 2;
+    while (p < len && IsSpace(line[p])) ++p;
+    static const char kKey[] = "interface"; // matched case-insensitively
+    const size_t klen = 9;
+    if (p + klen > len) return false;
+    for (size_t i = 0; i < klen; ++i)
+        if (Lower(line[p + i]) != kKey[i]) return false;
+    p += klen;
+    while (p < len && IsSpace(line[p])) ++p;
+    if (p >= len || line[p] != ':') return false;
+    ++p;                       // past ':'
+    const size_t prefixEnd = p; // "## Interface:" (author spacing preserved)
+
+    const uint32_t client = ClientInterfaceVersion();
+    long first = -1;
+    bool hasComma = false, hasClient = false;
+    size_t q = p;
+    while (q < len) {
+        while (q < len && (IsSpace(line[q]) || line[q] == ',')) {
+            if (line[q] == ',') hasComma = true;
+            ++q;
+        }
+        long v = 0;
+        bool digit = false;
+        while (q < len && line[q] >= '0' && line[q] <= '9') {
+            v = v * 10 + (line[q] - '0');
+            ++q;
+            digit = true;
+        }
+        if (digit) {
+            if (first < 0) first = v;
+            if (static_cast<uint32_t>(v) == client) hasClient = true;
+        } else if (q < len) {
+            ++q; // skip a stray non-digit so the scan always advances
+        }
+    }
+    if (!hasComma || !hasClient || first == static_cast<long>(client))
+        return false; // single value / no client version / already first
+
+    out.append(line, prefixEnd);
+    out.push_back(' ');
+    out += std::to_string(client);
+    return true;
+}
+
+// Evaluate a `[keyword args]` condition — the return is whether the line should
+// load. An unrecognized keyword returns false so the caller drops the line (a
+// condition we cannot confirm must not load — fail safe).
+bool EvalCondition(const char *head, size_t headLen, const char *args,
+                   size_t argsLen) {
+    if (EqCI(head, headLen, "AllowLoadGameType"))
+        return ListContains(args, argsLen, "vanilla");
+    if (EqCI(head, headLen, "AllowLoadTextLocale"))
+        return ListContains(args, argsLen, ClientLocale());
+    if (EqCI(head, headLen, "AllowLoad"))
+        return ListContains(args, argsLen, "game"); // addon files: in-game only
+    return false;
+}
+
+// Rewrite one file-reference line into `out`: expand `[Variable]` tokens,
+// evaluate and strip `[Condition]` directives. Returns true to KEEP the
+// line (all conditions passed); on true `out` holds the cleaned,
+// right-trimmed path.
+bool ProcessFileLine(const char *line, size_t len, std::string &out) {
+    out.clear();
+    bool keep = true;
+    size_t i = 0;
+    while (i < len) {
+        const char c = line[i];
+        if (c != '[') {
+            out.push_back(c);
+            ++i;
+            continue;
+        }
+        size_t close = i + 1;
+        while (close < len && line[close] != ']') ++close;
+        if (close >= len) { // unterminated '[' — copy the rest verbatim
+            out.append(line + i, len - i);
+            break;
+        }
+        const char *inner = line + i + 1;
+        const size_t innerLen = close - (i + 1);
+        size_t h = 0;
+        while (h < innerLen && !IsSpace(inner[h])) ++h; // [0,h) = head word
+        size_t a = h;
+        while (a < innerLen && IsSpace(inner[a])) ++a;  // skip separating ws
+        const char *head = inner;
+        const size_t headLen = h;
+        const char *args = inner + a;
+        const size_t argsLen = innerLen - a;
+
+        if (argsLen == 0) {
+            // Single word: a variable to expand, else leave verbatim (an
+            // unknown token becomes a path the engine cannot open — the
+            // file just does not load).
+            const char *val = VariableValue(head, headLen);
+            if (val != nullptr) out.append(val);
+            else out.append(line + i, (close + 1) - i);
+        } else {
+            // Keyword + args: a condition. Strip it from the path (drop a
+            // space we already emitted before it so nothing dangles).
+            keep = keep && EvalCondition(head, headLen, args, argsLen);
+            if (!out.empty() && out.back() == ' ') out.pop_back();
+        }
+        i = close + 1;
+    }
+    while (!out.empty() && IsSpace(out.back())) out.pop_back();
+    return keep;
+}
+
+// Walk the whole TOC, preserving line terminators and any UTF-8 BOM.
+// `#` comment and `##` metadata lines pass through verbatim; only file
+// reference lines are rewritten. A gated-out line becomes a `#` comment
+// so the load loop skips it (and a dumped TOC shows why it was dropped).
+void RebuildToc(const char *src, size_t srcLen, std::string &out) {
+    out.clear();
+    out.reserve(srcLen + 32);
+    size_t i = 0;
+    if (srcLen >= 3 && static_cast<uint8_t>(src[0]) == 0xEF &&
+        static_cast<uint8_t>(src[1]) == 0xBB &&
+        static_cast<uint8_t>(src[2]) == 0xBF) {
+        out.append(src, 3);
+        i = 3;
+    }
+    std::string lineOut;
+    while (i < srcLen) {
+        const size_t lineStart = i;
+        while (i < srcLen && src[i] != '\r' && src[i] != '\n') ++i;
+        const char *line = src + lineStart;
+        const size_t len = i - lineStart;
+
+        const size_t termStart = i;
+        if (i < srcLen && src[i] == '\r') ++i;
+        if (i < srcLen && src[i] == '\n') ++i;
+
+        size_t s = 0;
+        while (s < len && IsSpace(line[s])) ++s;
+        if (s >= len) {
+            out.append(line, len); // blank
+        } else if (line[s] == '#') {
+            // Comment / `##` metadata — verbatim, except a multi-flavor
+            // `## Interface:` list that hides the client version.
+            if (!TryRewriteInterfaceLine(line, len, out))
+                out.append(line, len);
+        } else if (ProcessFileLine(line, len, lineOut)) {
+            out.append(lineOut);
+        } else {
+            out.push_back('#'); // gated out — comment it so the loader skips it
+            out.append(line, len);
+        }
+        out.append(src + termStart, i - termStart);
+    }
+}
+
+// True iff `path` is an addon `.toc` read (…\AddOns\…\*.toc). Gates the
+// rewrite off every non-TOC read (a `.lua` with a `t[1]` subscript would
+// otherwise be mangled) and off non-addon TOCs (FrameXML.toc, etc.).
+bool IsAddonToc(const char *path) {
+    const size_t len = std::strlen(path);
+    if (len < 4) return false;
+    if (!(path[len - 4] == '.' && Lower(path[len - 3]) == 't' &&
+          Lower(path[len - 2]) == 'o' && Lower(path[len - 1]) == 'c'))
+        return false;
+    for (size_t i = 0; i + 8 <= len; ++i)
+        if (EqCI(path + i, 8, "\\addons\\")) return true;
+    return false;
+}
+
+} // namespace
+
+void Transform(const char *path, void **outBuf, size_t *outSize) {
+    if (path == nullptr || outBuf == nullptr || *outBuf == nullptr) return;
+    if (!IsAddonToc(path)) return;
+
+    const char *content = static_cast<const char *>(*outBuf);
+    const size_t size = (outSize != nullptr && *outSize != 0)
+                            ? *outSize
+                            : std::strlen(content);
+    if (size == 0) return;
+
+    // Fast path: no '[' (directives) and no ',' (a possible `## Interface:`
+    // list) means nothing to do — leave the engine buffer alone.
+    if (std::memchr(content, '[', size) == nullptr &&
+        std::memchr(content, ',', size) == nullptr)
+        return;
+
+    std::string rebuilt;
+    RebuildToc(content, size, rebuilt);
+    if (rebuilt.size() == size &&
+        std::memcmp(rebuilt.data(), content, size) == 0)
+        return; // brackets/commas were only in unaffected lines — nothing changed
+
+    auto SMemAlloc = reinterpret_cast<SMemAllocFn>(Offsets::FUN_STORM_SMEM_ALLOC);
+    auto SMemFree = reinterpret_cast<SMemFreeFn>(Offsets::FUN_STORM_SMEM_FREE);
+    const size_t newLen = rebuilt.size();
+    void *buf = SMemAlloc(newLen + 1, __FILE__, __LINE__, 0); // +1 NUL (extraBytes=1)
+    if (buf == nullptr) return;                               // OOM — keep the original
+    std::memcpy(buf, rebuilt.data(), newLen);
+    static_cast<char *>(buf)[newLen] = '\0';
+
+    SMemFree(*outBuf, __FILE__, __LINE__, 0);
+    *outBuf = buf;
+    if (outSize != nullptr) *outSize = newLen;
+}
+
+} // namespace AddOns::TocRewrite

src/addons/TocRewrite.h

@@ -0,0 +1,79 @@
+// 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 AddOns::TocRewrite {
+
+// Modern-client per-line TOC directives, backported.
+//
+// A single-TOC multi-flavor addon gates individual file lines with
+// conditions and expands path variables:
+//
+//   [Family]\Init.lua                         # -> Classic\Init.lua
+//   Vanilla.lua      [AllowLoadGameType vanilla]
+//   Mainline.lua     [AllowLoadGameType mainline]   # dropped on this client
+//   Localization\[TextLocale].lua             # -> Localization\enUS.lua
+//   deDE.lua         [AllowLoadTextLocale deDE]
+//
+// Vanilla 1.12's TOC parsers never understood any of this. The scan
+// parser (FUN_0051C9B0) reads only `##` metadata; the load pass
+// (FUN_006edb90) hands each non-`#` line to the per-file loader verbatim,
+// where the trailing ` [...]` breaks the extension check and the file
+// silently never loads. `[Variable]` tokens likewise become part of a
+// path that does not exist.
+//
+// This closes the gap at the FUN_FILE_READ layer (alongside FlavorToc /
+// Embedded): after an addon TOC is read, rewrite its file-reference lines
+// so the engine's own load loop sees clean paths. `##` metadata and `#`
+// comment lines are copied verbatim, with ONE exception (`## Interface:`,
+// below); metadata-line conditions, added in retail 12.0.7, are out of
+// scope. What the tokens resolve to on this 1.12 client:
+//
+//   [AllowLoadGameType ...]   keep the line iff the list contains `vanilla`
+//   [AllowLoadTextLocale ...] keep the line iff the list contains the
+//                             client locale (GetLocale() code, e.g. enUS)
+//   [AllowLoad ...]           addon files only load in-game, so `game`
+//                             keeps and `glue` drops
+//   [Family]                  -> Classic
+//   [Game]                    -> Vanilla
+//   [TextLocale]              -> the client locale code
+//
+// All conditions on a line must pass for it to load (AND). An unknown
+// `[keyword args]` condition fails safe (drops the line); an unknown
+// single-word `[Token]` is left verbatim (the engine then fails to find
+// that path, so the file does not load).
+//
+// Multi-flavor `## Interface:` list. Retail lets a TOC list several
+// interface versions (`## Interface: 120100, 50504, 11200`). Vanilla's
+// parser is a plain atoi that reads only the FIRST number, so it never
+// sees a later 11200 and marks the addon out of date. When the client
+// version (FUN_ADDON_CLIENT_INTERFACE_VERSION, 11200) appears anywhere in
+// the list but is not first, the `## Interface:` line is rewritten to that
+// single value so the engine marks the addon compatible. A list WITHOUT
+// the client version is left unchanged — it still parses to its first
+// value and stays out of date, exactly as before.
+//
+// Called from the FUN_FILE_READ hook after the read succeeds. Does
+// nothing unless `path` is an addon `.toc` read AND its content contains a
+// `[` (directives) or a `,` (a possible `## Interface:` list) — the
+// fast-path bail keeps every unaffected TOC zero-copy, and a rebuild that
+// changes nothing is discarded by a content compare. When it does rewrite,
+// it allocates a fresh Storm buffer, frees the original, and updates
+// `*outBuf` / `*outSize` — the caller frees the replacement exactly as it
+// would the engine's own read buffer.
+void Transform(const char *path, void **outBuf, size_t *outSize);
+
+} // namespace AddOns::TocRewrite

src/auctionhouse/PostItem.cpp

@@ -55,8 +55,10 @@
 #include "Game.h"
 #include "Offsets.h"
 #include "event/Custom.h"
+#include "item/CGItem.h"
 #include "item/ID.h"
 #include "item/Location.h"
+#include "item/Record.h"
 #include "item/Swap.h"
 #include "tick/WorldTick.h"
 
@@ -97,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) {

src/aura/Api.cpp

@@ -17,18 +17,27 @@
 // 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"
 
 #include "Game.h"
 #include "Offsets.h"
 #include "ui/ColorData.h"
+#include "unit/Identity.h"
 
 #include <cstdint>
 #include <cstring>
@@ -47,24 +56,84 @@ const uint8_t *ResolveUnit(const char *token) {
     return static_cast<const uint8_t *>(fn(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;
+// Resolves a token to its GUID for the out-of-range (no live CGUnit) path.
+// Only valid to call AFTER `ResolveUnit(token)` returned null *without raising*:
+// `ResolveUnit` runs the engine's token→GUID resolver first, so reaching a null
+// return means the token was well-formed (the resolver never raised). This runs
+// the same non-raising resolver and returns 0 for a token that maps to no
+// rostered member — which the group-array push paths treat as "no auras".
+uint64_t GuidForOutOfRange(const char *token) {
+    if (token == nullptr)
+        return 0;
+    return Unit::Identity::GuidForToken(token);
 }
 
-// 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;
+// 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;
+}
+
+// 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) {
@@ -89,18 +158,52 @@ 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);
-    const int slot = Data::FindNthSlot(unit, index, filter, playerOnly);
-    if (slot >= 0) {
-        Data::Push(L, unit, slot);
-        return 1;
+    if (unit != nullptr) {
+        const int slot = Data::FindNthSlot(unit, index, filter, match);
+        if (slot >= 0) {
+            Data::Push(L, unit, slot);
+            return 1;
+        }
+        // Descriptor exhausted — an aura the engine dropped from the slot array
+        // (rogue stealth, nearby party range fluctuation) may still be live in
+        // the Aura::Source cache. Surface it after the descriptor entries.
+        if (Data::PushNthCacheFallback(L, unit, index, filter, 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, match))
+            return 1;
+    }
+    Game::Lua::PushNil(L);
+    return 1;
+}
+
+// Positional (multi-return) sibling of `PushAuraByIndex` for the
+// `C_UnitAuras.UnitAura` family: pushes the Classic-Era `UnitAura` 15-tuple with
+// NO table allocation (the zero-GC path). Returns 15 on a hit, or 1 (a single
+// nil) on a miss. The bool-returning push helpers leave exactly the 15-tuple on a
+// hit and nothing on a miss, so the miss `PushNil` + `return 1` needs no cleanup.
+int PushUnitAuraPositional(void *L, const char *unitToken, int index,
+                           Data::Filter filter, Data::Match match = {}) {
+    const uint8_t *unit = ResolveUnit(unitToken);
+    if (unit != nullptr) {
+        const int slot = Data::FindNthSlot(unit, index, filter, match);
+        if (slot >= 0) {
+            Data::Push(L, unit, slot, Data::Emit::Positional);
+            return 15;
+        }
+        if (Data::PushNthCacheFallback(L, unit, index, filter, match,
+                                       Data::Emit::Positional))
+            return 15;
+    } else if (Data::PushNthGroupAura(L, GuidForOutOfRange(unitToken), index,
+                                      filter, match, Data::Emit::Positional)) {
+        return 15;
     }
-    // Descriptor exhausted — an aura the engine dropped from the slot array
-    // (rogue stealth, party range fluctuation) may still be live in the
-    // Aura::Source cache. Surface it after the descriptor entries.
-    if (Data::PushNthCacheFallback(L, unit, index, filter, playerOnly))
-        return 1;
     Game::Lua::PushNil(L);
     return 1;
 }
@@ -113,8 +216,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) {
@@ -137,6 +240,50 @@ int __fastcall Script_GetDebuffDataByIndex(void *L) {
     return PushAuraByIndex(L, unit, index, Data::Filter::Harmful);
 }
 
+// Zero-allocation positional accessors — Classic-Era `UnitAura`/`UnitBuff`/
+// `UnitDebuff` shape, namespaced under `C_UnitAuras` to avoid clashing with the
+// native `UnitBuff`/`UnitDebuff` globals (which keep their vanilla short return).
+// `UnitAura` reads the range from the filter (helpful by default); `UnitBuff` /
+// `UnitDebuff` lock the range and still honor the filter's PLAYER/DISPELLABLE/
+// CROWD_CONTROL predicates.
+int __fastcall Script_UnitAura(void *L) {
+    const char *unit = ArgUnit(L, 1);
+    const int index = ArgInt(L, 2);
+    const char *filterStr = ArgOptString(L, 3);
+    if (unit == nullptr || index < 1) {
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+    const ParsedFilter pf = ParseFilters(filterStr);
+    return PushUnitAuraPositional(L, unit, index, RangeFilter(pf), pf.ToMatch());
+}
+
+int __fastcall Script_UnitBuff(void *L) {
+    const char *unit = ArgUnit(L, 1);
+    const int index = ArgInt(L, 2);
+    const char *filterStr = ArgOptString(L, 3);
+    if (unit == nullptr || index < 1) {
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+    const ParsedFilter pf = ParseFilters(filterStr);
+    return PushUnitAuraPositional(L, unit, index, Data::Filter::Helpful,
+                                  pf.ToMatch());
+}
+
+int __fastcall Script_UnitDebuff(void *L) {
+    const char *unit = ArgUnit(L, 1);
+    const int index = ArgInt(L, 2);
+    const char *filterStr = ArgOptString(L, 3);
+    if (unit == nullptr || index < 1) {
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+    const ParsedFilter pf = ParseFilters(filterStr);
+    return PushUnitAuraPositional(L, unit, index, Data::Filter::Harmful,
+                                  pf.ToMatch());
+}
+
 int __fastcall Script_GetUnitAuraBySpellID(void *L) {
     const char *unitToken = ArgUnit(L, 1);
     const int spellID = ArgInt(L, 2);
@@ -146,19 +293,23 @@ 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 int slot = Data::FindSlotBySpellID(unit, static_cast<uint32_t>(spellID),
-                                             fp, HasPlayerFilter(filterStr));
-    if (slot < 0) {
-        Game::Lua::PushNil(L);
+    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, 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,
+                                            pf.ToMatch())) {
+        // Out-of-range groupmate — read from the group-member aura array.
         return 1;
     }
-    Data::Push(L, unit, slot);
+    Game::Lua::PushNil(L);
     return 1;
 }
 
@@ -171,19 +322,21 @@ 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 int slot = Data::FindSlotBySpellName(unit, spellName, fp,
-                                               HasPlayerFilter(filterStr));
-    if (slot < 0) {
-        Game::Lua::PushNil(L);
+    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, pf.ToMatch());
+        if (slot >= 0) {
+            Data::Push(L, unit, slot);
+            return 1;
+        }
+    } else if (Data::PushGroupAuraBySpellName(L, GuidForOutOfRange(unitToken),
+                                              spellName, fp, pf.ToMatch())) {
+        // Out-of-range groupmate — read from the group-member aura array.
         return 1;
     }
-    Data::Push(L, unit, slot);
+    Game::Lua::PushNil(L);
     return 1;
 }
 
@@ -207,7 +360,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;
@@ -217,14 +370,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) {
@@ -234,22 +388,29 @@ int __fastcall Script_GetUnitAuras(void *L) {
 
     Game::Lua::SetTop(L, 0);
     Game::Lua::NewTable(L);
-    if (unit == nullptr)
-        return 1;
 
     // Range tokens are independent of PLAYER: an explicit HELPFUL/HARMFUL
     // selects that range, neither selects both. So `"PLAYER"` alone returns
     // 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 (hasHelpful || both)
-        AppendRangeToArray(L, unit, 1, Data::Filter::Helpful, nextKey, playerOnly);
-    if (hasHarmful || both)
-        AppendRangeToArray(L, unit, 1, Data::Filter::Harmful, nextKey, playerOnly);
+    if (unit != nullptr) {
+        if (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 (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;
 }
 
@@ -334,6 +495,12 @@ static void RegisterLuaFunctions() {
                                      &Script_GetBuffDataByIndex);
     Game::Lua::RegisterTableFunction("C_UnitAuras", "GetDebuffDataByIndex",
                                      &Script_GetDebuffDataByIndex);
+    Game::Lua::RegisterTableFunction("C_UnitAuras", "UnitAura",
+                                     &Script_UnitAura);
+    Game::Lua::RegisterTableFunction("C_UnitAuras", "UnitBuff",
+                                     &Script_UnitBuff);
+    Game::Lua::RegisterTableFunction("C_UnitAuras", "UnitDebuff",
+                                     &Script_UnitDebuff);
     Game::Lua::RegisterTableFunction("C_UnitAuras", "GetUnitAuraBySpellID",
                                      &Script_GetUnitAuraBySpellID);
     Game::Lua::RegisterTableFunction("C_UnitAuras", "GetPlayerAuraBySpellID",

src/aura/ComboDuration.cpp

@@ -21,7 +21,9 @@
 #include "Offsets.h"
 #include "dbc/Lookup.h"
 #include "net/PacketReader.h"
+#include "net/SendObserver.h"
 #include "spell/Mod.h"
+#include "time/Clock.h"
 #include "unit/Identity.h"
 
 #include <cstdint>
@@ -31,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) ------------------------
 
@@ -56,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
@@ -86,28 +107,17 @@ int ConsumeCapturedCP(uint32_t spellId) {
 // re-entry, but still build and send CMSG_CAST_SPELL through the engine).
 // Snapshot the combo points at the moment the cast request leaves: the
 // server consumes them before SMSG_SPELL_GO arrives, so reading at
-// SpellGo time is too late.
-using NetSend_t = void(__fastcall *)(void *conn, void *edx,
-                                     CDataStore *packet);
-NetSend_t g_origNetSend = nullptr;
-
-void __fastcall NetSend_h(void *conn, void *edx, CDataStore *packet) {
-    if (packet != nullptr) {
-        const uint32_t saved = packet->m_read;
-        const uint32_t opcode = Net::Read<uint32_t>(packet);
-        if (opcode == Offsets::OP_CMSG_CAST_SPELL) {
-            const uint32_t spellId = Net::Read<uint32_t>(packet);
-            if (spellId != 0)
-                g_capture = {spellId, CurrentComboPoints(), NowMs()};
-        }
-        packet->m_read = saved;
-    }
-    g_origNetSend(conn, edx, packet);
+// SpellGo time is too late. We watch sends through the shared
+// `Net::SendObserver` rather than owning the funnel hook ourselves.
+void OnSend(uint32_t opcode, Net::CDataStore *packet) {
+    if (opcode != Offsets::OP_CMSG_CAST_SPELL)
+        return;
+    const uint32_t spellId = Net::Read<uint32_t>(packet);
+    if (spellId != 0)
+        RememberCapture(spellId, CurrentComboPoints(), NowMs());
 }
 
-const Game::HookAutoRegister _sendHook{
-    Offsets::FUN_NET_SEND, reinterpret_cast<void *>(&NetSend_h),
-    reinterpret_cast<void **>(&g_origNetSend)};
+const Net::SendObserver::AutoSubscribe _sendSub{&OnSend};
 
 // ---- Duration data (SpellDuration.dbc + Lua overrides) --------------------
 
@@ -132,30 +142,19 @@ const Override *FindOverride(uint32_t spellId) {
     return nullptr;
 }
 
-// Known values for spells whose duration row DANGLES — a non-zero
-// DurationIndex pointing at a SpellDuration row the client doesn't have.
-// Consulted ONLY when that exact condition holds, so the gate is the bug
-// itself, not a server fingerprint: on a stock client every one of these
-// resolves to a valid row and this table is never reached, and if the
-// broken client data is ever fixed the DBC row takes over automatically.
-//
-// Turtle's reworked Rip is the known case: all six ranks point at
-// SpellDuration row 87, which Turtle added on the SERVER only
-// ({8000, 0, 18000} — live server data shows 10/12/14/16/18s at 1..5 CP,
-// i.e. 8s + 2s per combo point); their client patch never shipped the
-// row (the client table jumps 86 -> 105). Verified the only dangling
-// duration index in the entire client Spell.dbc.
-constexpr Override kDanglingRowKnown[] = {
-    {1079, 8000, 18000}, {9492, 8000, 18000}, {9493, 8000, 18000},
-    {9752, 8000, 18000}, {9894, 8000, 18000}, {9896, 8000, 18000},
-};
+// Resolver chain for dangling-duration-row spells (client DBC missing the
+// row). The KNOWN VALUES themselves are server-custom data and live in
+// their own module (e.g. `src/turtle/ComboDuration.cpp` for Turtle's
+// reworked Rip); this stock module only owns the mechanism and the
+// dangling-condition gate. Chained at static-init by `AutoDanglingResolver`.
+AutoDanglingResolver *g_danglingResolvers = nullptr;
 
-const Override *FindDanglingRowKnown(uint32_t spellId) {
-    for (const auto &k : kDanglingRowKnown) {
-        if (k.spellId == spellId)
-            return &k;
-    }
-    return nullptr;
+bool ResolveDangling(uint32_t spellId, int32_t *baseMs, int32_t *maxMs) {
+    for (AutoDanglingResolver *r = g_danglingResolvers; r != nullptr;
+         r = r->next)
+        if (r->fn(spellId, baseMs, maxMs))
+            return true;
+    return false;
 }
 
 // `C_UnitAuras.RegisterComboDuration(spellID, baseSeconds, maxSeconds)`
@@ -203,6 +202,11 @@ const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
 
 } // namespace
 
+AutoDanglingResolver::AutoDanglingResolver(DanglingResolver f)
+    : fn(f), next(g_danglingResolvers) {
+    g_danglingResolvers = this;
+}
+
 uint32_t TryComboScaledMs(const uint8_t *spellRecord, uint32_t spellId) {
     if (spellRecord == nullptr || spellId == 0)
         return 0;
@@ -227,12 +231,11 @@ uint32_t TryComboScaledMs(const uint8_t *spellRecord, uint32_t spellId) {
             maxMs = *reinterpret_cast<const int32_t *>(row + 0xC);
         } else if (idx != 0) {
             // Dangling duration index — the client data is broken for this
-            // spell. Fall back to the built-in known values (Turtle Rip).
-            const Override *k = FindDanglingRowKnown(spellId);
-            if (k == nullptr)
+            // spell. Defer to a registered resolver (the known values are
+            // server-custom data owned by a platform module, e.g.
+            // src/turtle for Turtle's reworked Rip).
+            if (!ResolveDangling(spellId, &baseMs, &maxMs))
                 return 0;
-            baseMs = k->baseMs;
-            maxMs = k->maxMs;
         } else {
             return 0; // no duration row at all
         }

src/aura/ComboDuration.h

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

src/aura/Data.cpp

@@ -17,7 +17,11 @@
 #include "Offsets.h"
 #include "aura/Source.h"
 #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>
@@ -27,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;
@@ -71,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 *);
@@ -139,6 +136,20 @@ double PlayerBuffExpirationSeconds(const uint8_t *entry) {
     const uint32_t expirationMs = expirationTable[slotCode];
     if (expirationMs == 0)
         return 0.0;
+    // Report "no timer" once the stored expiration has elapsed — this is not a
+    // heuristic, it's exactly what the engine's own GetPlayerBuffTimeLeft does.
+    // Script_GetPlayerBuffTimeLeft (0x004e4930) → FUN_004e4450 reads this same
+    // expiration table and returns:
+    //     if ((int)(now - expiration[slot]) >= 0) return 0;  // elapsed -> 0
+    //     return expiration[slot] - now;                      // else remaining
+    // Permanent auras (paladin auras, passives, racials) carry an infinite
+    // Spell.dbc duration (SpellDuration base -1); the server stores the fixed
+    // cast-time in this slot for them, so it's always "already elapsed" and the
+    // engine shows no countdown. `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;
 }
 
@@ -192,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)
@@ -200,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) {
@@ -233,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)
@@ -255,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;
@@ -264,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)
@@ -278,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;
     }
@@ -286,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)
@@ -301,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;
     }
@@ -350,23 +449,44 @@ const char *DispelName(uint32_t dispelTypeID) {
     return (name == nullptr || *name == '\0') ? nullptr : name;
 }
 
+// The display fields resolved from a spell record + caster, shared by the table
+// emitter (`BuildTable`) and the positional emitter (`PushPositional`) so the
+// name / icon / dispel-name lookups live in exactly one place. `castByPlayer` is
+// the positional tuple's field #13; the table uses `isFromPlayerOrPlayerPet`
+// instead, mirroring retail's own divergence between the two aura shapes.
+struct Display {
+    const char *name;
+    const char *icon;
+    const char *dispelName;
+    bool castByPlayer;
+};
+
+static Display ResolveDisplay(uint32_t spellID, uint64_t casterGuid) {
+    const uint8_t *spellRecord = SpellRecord(spellID);
+    uint32_t dispelTypeID = 0;
+    if (spellRecord != nullptr) {
+        dispelTypeID = *reinterpret_cast<const uint32_t *>(
+            spellRecord + Offsets::OFF_SPELL_DISPEL_TYPE);
+    }
+    Display d;
+    d.name = LocalizedSpellName(spellRecord);
+    d.icon = SpellIconPath(spellRecord);
+    d.dispelName = DispelName(dispelTypeID);
+    d.castByPlayer =
+        casterGuid != 0 && casterGuid == Unit::Identity::PlayerGuid();
+    return d;
+}
+
 // Writes the full modern AuraData table on top of the Lua stack from
 // already-resolved values. Shared by the descriptor path (`Push`) and the
 // cache-fallback path (`PushFromCache`). Net stack effect: +1 (the table).
 static void BuildTable(void *L, uint32_t spellID, int applications,
                        bool isHelpful, double duration, double expirationTime,
                        uint64_t casterGuid) {
-    const uint8_t *spellRecord = SpellRecord(spellID);
-
-    uint32_t dispelTypeID = 0;
-    if (spellRecord != nullptr) {
-        dispelTypeID = *reinterpret_cast<const uint32_t *>(
-            spellRecord + Offsets::OFF_SPELL_DISPEL_TYPE);
-    }
-
-    const char *name = LocalizedSpellName(spellRecord);
-    const char *icon = SpellIconPath(spellRecord);
-    const char *dispel = DispelName(dispelTypeID);
+    const Display disp = ResolveDisplay(spellID, casterGuid);
+    const char *name = disp.name;
+    const char *icon = disp.icon;
+    const char *dispel = disp.dispelName;
 
     Game::Lua::NewTable(L);
 
@@ -419,56 +539,127 @@ static void BuildTable(void *L, uint32_t spellID, int applications,
     // yields nil, so the table doesn't need an explicit entry.
 }
 
-void Push(void *L, const uint8_t *unit, int slot) {
-    const uint32_t spellID = ReadSpellID(unit, slot);
-    const bool isHelpful = slot < Offsets::UNIT_AURA_BUFF_COUNT;
+// Emits the Classic-Era `UnitAura` 15-value tuple onto the Lua stack from the
+// same already-resolved values `BuildTable` takes. Net stack effect: +15 — NO
+// table allocation, the zero-GC path behind `C_UnitAuras.UnitAura`. Field order
+// matches Classic-Era `UnitAura`: name, icon, count, dispelType(string),
+// duration, expirationTime, source, isStealable, nameplateShowPersonal, spellId,
+// canApplyAura, isBossDebuff, castByPlayer, nameplateShowAll, timeMod. Values
+// mirror the AuraData table exactly so packed / non-packed callers agree: name /
+// icon / dispelType push `""` when absent (as `SetFieldString` does), while
+// `source` pushes nil when there's no caster (as the table omits `sourceUnit`).
+// `isHelpful` is unused (the tuple has no isHelpful/isHarmful) — kept so the leaf
+// dispatch calls either emitter with a uniform arg list.
+static void PushPositional(void *L, uint32_t spellID, int applications,
+                           bool /*isHelpful*/, double duration,
+                           double expirationTime, uint64_t casterGuid) {
+    const Display disp = ResolveDisplay(spellID, casterGuid);
 
-    // Timing fields. Vanilla doesn't broadcast cast time / duration for ANY
-    // unit's auras except the local player's — for everyone else (target,
-    // party, raid, mouseover) `expirationTime` stays 0 unless the
-    // `Aura::Source` cache observed the cast. For the player we read the
-    // engine's `VAR_PLAYER_BUFF_TABLE` (same data `GetPlayerBuffTimeLeft`
-    // returns), which gives a real expiration timestamp.
-    //
-    // `duration` comes from Spell.dbc → SpellDuration.dbc with level scaling
-    // (the *base* value); talent / glyph duration-extension modifiers are
-    // already baked into the expiration timestamp on the caster's side, so
-    // `expirationTime - GetTime()` reflects true remaining time even when the
-    // base `duration` doesn't include the talent boost.
+    const char *source = nullptr;
+    char tokenBuf[32];
+    if (casterGuid != 0)
+        source = Unit::Identity::TokenFromGUID(casterGuid, tokenBuf,
+                                               sizeof tokenBuf);
+
+    Game::Lua::PushString(L, disp.name ? disp.name : "");            // 1  name
+    Game::Lua::PushString(L, disp.icon ? disp.icon : "");            // 2  icon
+    Game::Lua::PushNumber(L, static_cast<double>(applications));     // 3  count
+    Game::Lua::PushString(L, disp.dispelName ? disp.dispelName : ""); // 4  dispelType
+    Game::Lua::PushNumber(L, duration);                              // 5  duration
+    Game::Lua::PushNumber(L, expirationTime);                        // 6  expirationTime
+    Game::Lua::PushString(L, source);                                // 7  source (nil if none)
+    Game::Lua::PushBool(L, false);                                   // 8  isStealable
+    Game::Lua::PushBool(L, false);                                   // 9  nameplateShowPersonal
+    Game::Lua::PushNumber(L, static_cast<double>(spellID));          // 10 spellId
+    Game::Lua::PushBool(L, false);                                   // 11 canApplyAura
+    Game::Lua::PushBool(L, false);                                   // 12 isBossDebuff
+    Game::Lua::PushBool(L, disp.castByPlayer);                       // 13 castByPlayer
+    Game::Lua::PushBool(L, false);                                   // 14 nameplateShowAll
+    Game::Lua::PushNumber(L, 1);                                     // 15 timeMod
+}
+
+// Enriches a bare `(guid, spellID)` into a full AuraData table — the shared
+// core behind every push path (descriptor, cache fallback, group-array). No
+// dependence on a live descriptor: the descriptor path passes what it read
+// (stacks, level, is-this-the-player), the others pass their known-or-default
+// values.
+//
+// Timing rules (identical across paths): `duration` is the Spell.dbc →
+// SpellDuration.dbc base scaled by `unitLevel` (0 skips scaling); talent/glyph
+// duration modifiers are baked into the caster-side expiration, so
+// `expirationTime - GetTime()` is the true remaining time even when `duration`
+// omits the boost. `expirationTime` for the local player comes from the engine
+// buff table (gated on `isPlayer`); for everyone else it, the caster, and the
+// applied (caster-modified) duration come from the `Aura::Source` SMSG_SPELL_GO
+// cache when it observed the cast — a miss leaves the modern-truthful defaults
+// (expiration 0, no sourceUnit/GUID). `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, int slot,
+                         const Attribution *known = nullptr,
+                         Emit emit = Emit::Table) {
     double duration = 0.0;
     double expirationTime = 0.0;
     uint64_t casterGuid = 0;
-    const uint8_t *player = LocalPlayer();
-    if (spellID != 0) {
-        const int unitLevel = (unit != nullptr) ? PlayerLevel(unit) : 0;
+    if (spellID != 0)
         duration = SpellBaseDurationSeconds(spellID, unitLevel);
-    }
-    if (unit != nullptr && unit == player) {
+    if (isPlayer && spellID != 0) {
         const uint8_t *entry = FindPlayerBuffEntry(spellID);
         if (entry != nullptr)
             expirationTime = PlayerBuffExpirationSeconds(entry);
     }
-    // Caster + non-player expiration from the SMSG_SPELL_GO cache, captured at
-    // cast time (the descriptor has neither). The player-buff table above is
-    // authoritative for the player's own expiration; the cache fills it for
-    // everyone else. Prefer the applied (caster-modified) duration so it stays
-    // consistent with `expirationTime` — otherwise a talented DoT (Improved
-    // Shadow Word: Pain) would show remaining time exceeding the base.
-    if (spellID != 0) {
-        uint64_t c = 0;
-        uint32_t expMs = 0;
-        uint32_t durMs = 0;
-        if (Aura::Source::Get(UnitGuid(unit), 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;
-        }
+    if (spellID != 0 && guid != 0) {
+        // 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;
     }
+    if (emit == Emit::Positional)
+        PushPositional(L, spellID, applications, isHelpful, duration,
+                       expirationTime, casterGuid);
+    else
+        BuildTable(L, spellID, applications, isHelpful, duration, expirationTime,
+                   casterGuid);
+}
 
-    BuildTable(L, spellID, ReadStacks(unit, slot), 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, Emit emit) {
+    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(), slot,
+                 /*known*/ nullptr, emit);
 }
 
 namespace {
@@ -478,18 +669,17 @@ namespace {
 // in SMSG_SPELL_GO, so `applications` defaults to 1. `duration` uses the
 // applied (caster-modified) ms when known, else the Spell.dbc base.
 void PushFromCache(void *L, const uint8_t *unit,
-                   const Aura::Source::CachedAura &c, bool isHelpful) {
-    double duration = 0.0;
-    if (c.durationMs != 0) {
-        duration = static_cast<double>(c.durationMs) * 0.001;
-    } else {
-        const int unitLevel = (unit != nullptr) ? PlayerLevel(unit) : 0;
-        duration = SpellBaseDurationSeconds(c.spellId, unitLevel);
-    }
-    const double expirationTime =
-        (c.expirationMs != 0) ? static_cast<double>(c.expirationMs) * 0.001 : 0.0;
-    BuildTable(L, c.spellId, 1, isHelpful, duration, expirationTime,
-               c.casterGuid);
+                   const Aura::Source::CachedAura &c, bool isHelpful,
+                   Emit emit = Emit::Table) {
+    // `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;
+    const Attribution a = CachedAttribution(c);
+    PushEnriched(L, UnitGuid(unit), c.spellId, isHelpful, 1, unitLevel, false,
+                 c.slot, &a, emit);
 }
 
 // Reconciles the `Aura::Source` cache against `unit`'s descriptor: when the
@@ -506,15 +696,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
@@ -536,8 +720,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)
@@ -549,7 +733,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;
     }
@@ -559,21 +743,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;
 }
@@ -581,7 +765,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, Emit emit) {
     if (unit == nullptr)
         return false;
     ReconcileCache(unit); // drop entries the (synced) descriptor contradicts
@@ -590,7 +774,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);
@@ -601,10 +785,10 @@ 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);
+            PushFromCache(L, unit, buf[i], filter == Filter::Helpful, emit);
             return true;
         }
     }
@@ -612,7 +796,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
@@ -625,7 +809,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);
@@ -633,4 +817,280 @@ void AppendCacheFallbacks(void *L, const uint8_t *unit, Filter filter,
     }
 }
 
+// ── Out-of-range groupmate path ────────────────────────────────────────────
+
+namespace {
+
+// Absolute slot range [start, end) for a filter, matching the descriptor
+// convention (helpful 0..31, harmful 32..47).
+void GroupRange(Filter filter, int &start, int &end) {
+    start = (filter == Filter::Harmful) ? Offsets::UNIT_AURA_BUFF_COUNT : 0;
+    end = (filter == Filter::Harmful) ? Offsets::UNIT_AURA_TOTAL
+                                      : Offsets::UNIT_AURA_BUFF_COUNT;
+}
+
+// Spell ID at group-array slot (0..47), 0 if `arr` null / OOB / empty.
+uint32_t GroupSpellID(const uint16_t *arr, int slot) {
+    if (arr == nullptr || slot < 0 || slot >= Offsets::UNIT_AURA_TOTAL)
+        return 0;
+    return arr[slot];
+}
+
+// Whether the group-array slot holds a surfacable aura for this query. Mirrors
+// the engine's per-slot test in Script_UnitBuff/UnitDebuff — a non-zero spell
+// ID with a real Spell.dbc record that passes the visibility predicate (the
+// server only transmits *applied* auras, so there is no flag nibble to check).
+// `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,
+                       Match match) {
+    const uint32_t id = GroupSpellID(arr, slot);
+    if (id == 0 || !IsVisible(SpellRecord(id)))
+        return false;
+    if (!MatchesAura(match, GroupIsPlayerCast(guid, id), id))
+        return false;
+    return true;
+}
+
+// The groupmate's level, for Spell.dbc duration scaling (0 = skip). Cheap
+// roster lookup; only hit on the out-of-range path.
+int GroupMemberLevel(uint64_t guid) {
+    return Group::MemberStats::Lookup(guid).level;
+}
+
+// True if the group array exposes ANY visible aura (either kind). When it
+// does, the server's out-of-range aura data is present and authoritative, so
+// we do NOT supplement from the Aura::Source cache — mirroring how the
+// descriptor path treats a populated descriptor (DescriptorHasVisibleAura).
+// Only when the array is entirely empty do we fall back to the cache: the
+// server resends out-of-range stats as deltas only, so a member seen in range
+// and then moved away again leaves an empty party-stats aura array (the array
+// is cleared when they become visible and never re-sent), yet their auras
+// still sit in the cache from when we observed them in range.
+bool GroupArrayHasVisibleAura(const uint16_t *arr) {
+    for (int slot = 0; slot < Offsets::UNIT_AURA_TOTAL; ++slot) {
+        const uint32_t id = GroupSpellID(arr, slot);
+        if (id != 0 && IsVisible(SpellRecord(id)))
+            return true;
+    }
+    return false;
+}
+
+// Whether cache entry `c` may supplement the (empty) group array: a visible
+// aura, not already present in the array, and — when player-filtered — cast by
+// us. See GroupArrayHasVisibleAura for when this path runs.
+bool GroupFallbackEligible(const uint16_t *arr, const Aura::Source::CachedAura &c,
+                           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 (!MatchesAura(match, c.casterGuid == Unit::Identity::PlayerGuid(), c.spellId))
+        return false;
+    return true;
+}
+
+// Nth (1-based) cache-fallback aura of `filter`'s kind for an out-of-range
+// member whose group array is empty. Pushes the AuraData table on a hit.
+bool PushNthGroupCacheFallback(void *L, uint64_t guid, const uint16_t *arr,
+                               int oneBasedIndex, Filter filter, Match match,
+                               Emit emit = Emit::Table) {
+    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], match))
+            continue;
+        if (++seen == oneBasedIndex) {
+            const Attribution a = CachedAttribution(buf[i]);
+            PushEnriched(L, guid, buf[i].spellId, filter == Filter::Helpful, 1,
+                         GroupMemberLevel(guid), false, buf[i].slot, &a, emit);
+            return true;
+        }
+    }
+    return false;
+}
+
+// Append every cache-fallback aura of `filter`'s kind into the array table.
+void AppendGroupCacheFallbacks(void *L, uint64_t guid, const uint16_t *arr,
+                               Filter filter, 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], 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, buf[i].slot, &a);
+        Game::Lua::SetTable(L, outerIdx);
+    }
+}
+
+// Single cache-fallback aura matching `spellID` (when nonzero) or `spellName`
+// (when non-null), of the given kind. Backs the by-ID / by-name group queries.
+bool PushGroupCacheFallbackMatch(void *L, uint64_t guid, const uint16_t *arr,
+                                 bool harmful, uint32_t spellID,
+                                 const char *spellName, Match match) {
+    Aura::Source::CachedAura buf[kFallbackMax];
+    const int n = Aura::Source::Enumerate(guid, harmful, buf, kFallbackMax);
+    for (int i = 0; i < n; ++i) {
+        if (spellID != 0 && buf[i].spellId != spellID)
+            continue;
+        if (spellName != nullptr) {
+            const char *nm = LocalizedSpellName(SpellRecord(buf[i].spellId));
+            if (nm == nullptr || std::strcmp(nm, spellName) != 0)
+                continue;
+        }
+        if (!GroupFallbackEligible(arr, buf[i], match))
+            continue;
+        const Attribution a = CachedAttribution(buf[i]);
+        PushEnriched(L, guid, buf[i].spellId, !harmful, 1, GroupMemberLevel(guid),
+                     false, buf[i].slot, &a);
+        return true;
+    }
+    return false;
+}
+
+} // namespace
+
+bool PushNthGroupAura(void *L, uint64_t guid, int oneBasedIndex, Filter filter,
+                      Match match, Emit emit) {
+    if (guid == 0 || oneBasedIndex < 1)
+        return false;
+    const uint16_t *arr = Group::MemberStats::AuraArray(guid);
+    if (arr == nullptr)
+        return false;
+    Aura::Source::ObserveGroupAuras(guid, arr);
+    int start, end;
+    GroupRange(filter, start, end);
+    int matches = 0;
+    for (int slot = start; slot < end; ++slot) {
+        if (!GroupSlotEligible(guid, arr, slot, match))
+            continue;
+        if (++matches == oneBasedIndex) {
+            PushEnriched(L, guid, GroupSpellID(arr, slot),
+                         filter == Filter::Helpful, 1, GroupMemberLevel(guid),
+                         false, Aura::Source::SLOT_UNBOUND, /*known*/ nullptr,
+                         emit);
+            return true;
+        }
+    }
+    // Empty array (server delta-resend gap): supplement from the cache.
+    if (!GroupArrayHasVisibleAura(arr))
+        return PushNthGroupCacheFallback(L, guid, arr, oneBasedIndex, filter,
+                                         match, emit);
+    return false;
+}
+
+bool PushGroupAuraBySpellID(void *L, uint64_t guid, uint32_t spellID,
+                            const Filter *filter, Match match) {
+    if (guid == 0 || spellID == 0)
+        return false;
+    const uint16_t *arr = Group::MemberStats::AuraArray(guid);
+    if (arr == nullptr)
+        return false;
+    Aura::Source::ObserveGroupAuras(guid, arr);
+    const int start = (filter != nullptr && *filter == Filter::Harmful)
+                          ? Offsets::UNIT_AURA_BUFF_COUNT
+                          : 0;
+    const int end = (filter != nullptr && *filter == Filter::Helpful)
+                        ? Offsets::UNIT_AURA_BUFF_COUNT
+                        : Offsets::UNIT_AURA_TOTAL;
+    for (int slot = start; slot < end; ++slot) {
+        if (GroupSpellID(arr, slot) != spellID)
+            continue;
+        if (!GroupSlotEligible(guid, arr, slot, match))
+            continue;
+        PushEnriched(L, guid, spellID, slot < Offsets::UNIT_AURA_BUFF_COUNT, 1,
+                     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,
+                                        match))
+            return true;
+        if ((both || *filter == Filter::Harmful) &&
+            PushGroupCacheFallbackMatch(L, guid, arr, true, spellID, nullptr,
+                                        match))
+            return true;
+    }
+    return false;
+}
+
+bool PushGroupAuraBySpellName(void *L, uint64_t guid, const char *spellName,
+                              const Filter *filter, Match match) {
+    if (guid == 0 || spellName == nullptr || *spellName == '\0')
+        return false;
+    const uint16_t *arr = Group::MemberStats::AuraArray(guid);
+    if (arr == nullptr)
+        return false;
+    Aura::Source::ObserveGroupAuras(guid, arr);
+    const int start = (filter != nullptr && *filter == Filter::Harmful)
+                          ? Offsets::UNIT_AURA_BUFF_COUNT
+                          : 0;
+    const int end = (filter != nullptr && *filter == Filter::Helpful)
+                        ? Offsets::UNIT_AURA_BUFF_COUNT
+                        : Offsets::UNIT_AURA_TOTAL;
+    for (int slot = start; slot < end; ++slot) {
+        const uint32_t id = GroupSpellID(arr, slot);
+        if (id == 0)
+            continue;
+        const char *name = LocalizedSpellName(SpellRecord(id));
+        if (name == nullptr || std::strcmp(name, spellName) != 0)
+            continue;
+        if (!GroupSlotEligible(guid, arr, slot, match))
+            continue;
+        PushEnriched(L, guid, id, slot < Offsets::UNIT_AURA_BUFF_COUNT, 1,
+                     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,
+                                        match))
+            return true;
+        if ((both || *filter == Filter::Harmful) &&
+            PushGroupCacheFallbackMatch(L, guid, arr, true, 0, spellName,
+                                        match))
+            return true;
+    }
+    return false;
+}
+
+void AppendGroupAuras(void *L, uint64_t guid, Filter filter, Match match,
+                      int outerIdx, int &nextKey) {
+    if (guid == 0)
+        return;
+    const uint16_t *arr = Group::MemberStats::AuraArray(guid);
+    if (arr == nullptr)
+        return;
+    Aura::Source::ObserveGroupAuras(guid, arr);
+    int start, end;
+    GroupRange(filter, start, end);
+    const int level = GroupMemberLevel(guid);
+    for (int slot = start; slot < end; ++slot) {
+        if (!GroupSlotEligible(guid, arr, slot, match))
+            continue;
+        Game::Lua::PushNumber(L, static_cast<double>(nextKey++));
+        PushEnriched(L, guid, GroupSpellID(arr, slot),
+                     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, match, outerIdx,
+                                  nextKey);
+}
+
 } // namespace Aura::Data

src/aura/Data.h

@@ -33,6 +33,45 @@ namespace Aura::Data {
 // to helpful when no filter is specified.
 enum class Filter { Helpful, Harmful };
 
+// How a resolved aura is emitted onto the Lua stack by the single-aura push
+// paths. `Table` builds the modern `AuraData` table (net stack +1); `Positional`
+// pushes the Classic-Era `UnitAura` 15-value tuple (net stack +15) with NO table
+// allocation, for the `C_UnitAuras.UnitAura/UnitBuff/UnitDebuff` accessors that
+// avoid the per-call GC churn. Selection + timing resolution are identical for
+// both — only the terminal leaf differs.
+enum class Emit { Table, Positional };
+
+// 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 +89,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);
@@ -109,8 +162,9 @@ const char *DispelName(uint32_t dispelTypeID);
 //   nameplateShowPersonal=false, canApplyAura=false,
 //   shouldConsolidate=false, isRaid=false
 //
-// Net stack effect: +1 (the table).
-void Push(void *L, const uint8_t *unit, int slot);
+// Net stack effect: +1 for `Emit::Table` (the table), +15 for `Emit::Positional`
+// (the Classic-Era `UnitAura` tuple — see `Emit`).
+void Push(void *L, const uint8_t *unit, int slot, Emit emit = Emit::Table);
 
 // Fallback for the index path when the descriptor has dropped an aura's slot
 // (rogue stealth, party range fluctuation) but it's still active server-side.
@@ -120,9 +174,11 @@ void Push(void *L, const uint8_t *unit, int slot);
 // order). On a hit it pushes the AuraData table and returns true; on a miss it
 // pushes nothing and returns false (caller pushes nil). Only entries whose
 // helpful/harmful classification matches `filter` and that aren't already in a
-// populated descriptor slot are considered.
+// populated descriptor slot are considered. `emit` selects the table vs the
+// positional tuple leaf (see `Emit`); the pushed count follows `Push`.
 bool PushNthCacheFallback(void *L, const uint8_t *unit, int oneBasedIndex,
-                          Filter filter, bool playerOnly = false);
+                          Filter filter, Match match = {},
+                          Emit emit = Emit::Table);
 
 // Appends every eligible `Aura::Source` cache fallback for `unit` matching
 // `filter` into the array table at `outerIdx`, continuing from `nextKey`
@@ -130,6 +186,48 @@ 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 ────────────────────────────────────────────
+//
+// When a party/raid member has no live CGUnit at all (different map, far out
+// of range) the token resolves to a GUID but no object, so there is no
+// descriptor to read. The server still transmits that member's current aura
+// spell IDs via SMSG_PARTY_MEMBER_STATS, which the client keeps in the
+// group-member stats structs (`Group::MemberStats::AuraArray`). These functions
+// enumerate that array — exactly what the built-in `UnitBuff`/`UnitDebuff` do
+// out of range — and build the same AuraData table.
+//
+// Spell IDs only come off the wire: `applications` is 1 (stacks aren't sent)
+// and IDs are u16-truncated (custom IDs > 65535 are wrong). Any caster / real
+// expirationTime we observed for the member via SMSG_SPELL_GO is still merged
+// in from the `Aura::Source` cache. `guid` of 0 (not a rostered member) yields
+// no results. These are only meaningful when the unit has NO descriptor —
+// callers use them in the `unit == nullptr` branch, so there is no descriptor
+// to dedup against.
+
+// Pushes AuraData for the `oneBasedIndex`-th group-array aura on `guid`
+// matching `filter`. On a hit pushes the aura and returns true; otherwise
+// pushes nothing and returns false (caller pushes nil). `emit` selects the
+// table vs the positional tuple leaf (see `Emit`).
+bool PushNthGroupAura(void *L, uint64_t guid, int oneBasedIndex, Filter filter,
+                      Match match = {}, Emit emit = Emit::Table);
+
+// 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, 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, 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, Match match,
+                      int outerIdx, int &nextKey);
 
 } // namespace Aura::Data

src/aura/Source.h

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

src/bag/UpdateDelayed.cpp

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

src/baselib/Ascii.h

@@ -0,0 +1,38 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+// Tiny ASCII string helpers. Header-only — no locale, no allocation, safe from
+// any context (hook callbacks, DBC walks). Use these instead of hand-rolling
+// yet another case-insensitive compare.
+
+namespace Ascii {
+
+// Fold a single ASCII char to lower case (non-letters unchanged).
+inline char ToLower(char c) {
+    return (c >= 'A' && c <= 'Z') ? static_cast<char>(c - 'A' + 'a') : c;
+}
+
+// Case-insensitive full-string equality over ASCII. Two null pointers compare
+// equal; a null vs non-null does not.
+inline bool EqualCI(const char *a, const char *b) {
+    if (a == nullptr || b == nullptr)
+        return a == b;
+    for (; *a && *b; ++a, ++b)
+        if (ToLower(*a) != ToLower(*b))
+            return false;
+    return *a == *b;
+}
+
+} // namespace Ascii

src/baselib/CollectGarbage.cpp

@@ -0,0 +1,145 @@
+// 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/>.
+
+// `collectgarbage(opt [, arg])` — accept Lua 5.1's string options on the
+// 5.0 collector. 5.0's collectgarbage takes only an optional NUMBER (a KB
+// threshold for the next cycle) and errors on every 5.1 option (verified
+// in-game: `collectgarbage("count")` → "bad argument #1 (number expected,
+// got string)"). Shim dispatch:
+//
+//   "count"    → KB of Lua memory in use — the engine's own gcinfo()
+//                value, the same number 5.1's "count" reports.
+//   "collect"  → original collectgarbage(0): threshold 0 forces a full
+//                cycle, the canonical 5.0 "collect now". Returns 0.
+//   "step"     → no-op returning true ("cycle finished"): the 5.0 GC
+//                cannot step incrementally, and true is the loop-safe
+//                sentinel (`repeat until collectgarbage("step")` exits
+//                immediately instead of spinning forever).
+//   "stop" / "restart" / "setpause" / "setstepmul"
+//              → accepted no-ops returning 0 — the 5.0 GC has no toggle
+//                or tuning; callers just lose the optimization.
+//   number / no argument
+//              → forwarded to the original untouched (5.0 threshold
+//                semantics preserved for vanilla-era callers).
+//
+// The originals (`collectgarbage`, `gcinfo`) are function objects stashed
+// in the state's registry at registration, BEFORE the global is
+// overwritten — no raw engine address needed, and each /reload re-stashes
+// the freshly re-registered engine original (module callbacks run after
+// the engine's own registration pass). Registered on BOTH states.
+
+#include "Game.h"
+
+#include <cstring>
+
+namespace BaseLib::CollectGarbage {
+
+namespace {
+
+constexpr const char *kOrigCollect = "__classicapi_orig_collectgarbage";
+constexpr const char *kOrigGcInfo = "__classicapi_orig_gcinfo";
+
+// Pushes registry[key]; true when it holds a function (left on the
+// stack), false otherwise (stack unchanged).
+bool PushStashed(void *L, const char *key) {
+    Game::Lua::PushString(L, key);
+    Game::Lua::RawGet(L, Game::Lua::REGISTRY_INDEX);
+    if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_FUNCTION)
+        return true;
+    Game::Lua::SetTop(L, -2);
+    return false;
+}
+
+int __fastcall Script_collectgarbage(void *L) {
+    if (Game::Lua::Type(L, 1) == Game::Lua::TYPE_STRING) {
+        const char *opt = Game::Lua::ToString(L, 1);
+        if (std::strcmp(opt, "count") == 0) {
+            if (PushStashed(L, kOrigGcInfo)) {
+                Game::Lua::Call(L, 0, 1); // gcinfo's first return = KB in use
+                return 1;
+            }
+            Game::Lua::PushNumber(L, 0.0); // no gcinfo on this state
+            return 1;
+        }
+        if (std::strcmp(opt, "collect") == 0) {
+            if (PushStashed(L, kOrigCollect)) {
+                Game::Lua::PushNumber(L, 0.0); // threshold 0 = collect now
+                Game::Lua::Call(L, 1, 0);
+            }
+            Game::Lua::PushNumber(L, 0.0); // 5.1 returns 0 for "collect"
+            return 1;
+        }
+        if (std::strcmp(opt, "step") == 0) {
+            Game::Lua::PushBool(L, true); // "cycle finished" — see header
+            return 1;
+        }
+        if (std::strcmp(opt, "stop") == 0 || std::strcmp(opt, "restart") == 0 ||
+            std::strcmp(opt, "setpause") == 0 ||
+            std::strcmp(opt, "setstepmul") == 0) {
+            Game::Lua::PushNumber(L, 0.0);
+            return 1;
+        }
+        Game::Lua::Error(L, "bad argument #1 to 'collectgarbage' (invalid option '%s')",
+                         opt);
+        return 0; // unreachable
+    }
+
+    // Number or no argument: original 5.0 threshold behavior, forwarded.
+    const int n = Game::Lua::GetTop(L);
+    if (!PushStashed(L, kOrigCollect))
+        return 0; // no original captured — inert
+    for (int idx = 1; idx <= n; ++idx)
+        Game::Lua::PushValue(L, idx);
+    Game::Lua::Call(L, n, Game::Lua::MULTRET);
+    return Game::Lua::GetTop(L) - n;
+}
+
+// Stashes the function at `_G[name]` under registry[key]; true when a
+// function was actually stashed.
+bool Stash(void *L, const char *name, const char *key) {
+    Game::Lua::PushString(L, name);
+    Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX); // [fn?]
+    if (Game::Lua::Type(L, -1) != Game::Lua::TYPE_FUNCTION) {
+        Game::Lua::SetTop(L, -2);
+        return false;
+    }
+    Game::Lua::PushString(L, key); // [fn, key]
+    Game::Lua::Insert(L, -2);      // [key, fn]
+    Game::Lua::RawSet(L, Game::Lua::REGISTRY_INDEX);
+    return true;
+}
+
+void DoRegister(bool glue) {
+    void *L = Game::Lua::State();
+    if (L == nullptr)
+        return;
+    // Stash BEFORE overwriting; if the engine original is somehow absent,
+    // leave the global untouched rather than installing a dead shim.
+    if (!Stash(L, "collectgarbage", kOrigCollect))
+        return;
+    Stash(L, "gcinfo", kOrigGcInfo); // optional; "count" degrades to 0
+    if (glue)
+        Game::Lua::RegisterGlueFunction("collectgarbage", &Script_collectgarbage);
+    else
+        Game::Lua::RegisterGlobalFunction("collectgarbage", &Script_collectgarbage);
+}
+
+void RegisterInGame() { DoRegister(false); }
+void RegisterGlue() { DoRegister(true); }
+
+const Game::ModuleAutoRegister _autoreg{&RegisterInGame};
+const Game::GlueModuleAutoRegister _autoregGlue{&RegisterGlue};
+
+} // namespace
+
+} // namespace BaseLib::CollectGarbage

src/baselib/Mixin.cpp

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

src/baselib/StringLib.cpp

@@ -15,6 +15,7 @@
 //
 //   - `string.match(s, pattern [, init])` — first-match extraction (5.1).
 //   - `string.gmatch(s, pattern)`         — match iterator (5.1).
+//   - `string.gsub` TABLE replacement     — 5.1 form (see the shim below).
 //   - `strsplit(sep, str [, pieces])`     — WoW global; split on any char.
 //   - `strjoin(delimiter, ...)`           — WoW global; join varargs.
 //   - `strtrim(str [, chars])`            — WoW global; trim a char set.
@@ -28,12 +29,11 @@
 //     it as a direct alias of the engine's `gfind` C function.
 // `strsplit` is a hand-rolled port of 3.3.5's `strsplit` (see below).
 //
-// NOTE: only the `string.foo(s, ...)` call form works — NOT the
-// `("x"):foo(...)` method sugar. WoW's Lua VM strips type-metatables for
-// every value except tables/userdata (both `lua_setmetatable` and the VM's
-// `luaT_gettmbyobj` hard-return "no metamethod" for strings), so strings have
-// no `__index`, and there's no client-side way to add one short of hooking a
-// hot VM-core function. This is the long-standing vanilla constraint.
+// NOTE: both call forms work — `string.foo(s, ...)` AND the `("x"):foo(...)`
+// method sugar. Method calls resolve through this same `string` table via
+// LuaSyntax::StringMethods (the Lua 5.1 string-metatable backport), so
+// everything registered here is automatically reachable as a method, on
+// both states.
 
 #include "Game.h"
 #include "Offsets.h"
@@ -261,10 +261,138 @@ int __fastcall Script_string_reverse(void *L) {
     return 1;
 }
 
+// --- string.gsub table-replacement upgrade (Lua 5.1) ------------------------
+//
+// 5.1 allows a TABLE as gsub's replacement: each match looks up the first
+// capture (the whole match when the pattern declares no captures) in the
+// table; a nil/false value keeps the original match; string/number values
+// substitute. This engine's gsub (FUN_LUA_STR_GSUB) is stock 5.0 —
+// string/function only ("string or function expected" otherwise), and its
+// add_value appends NOTHING when a replacement function returns a
+// non-string (match → empty; verified by decode, see Offsets.h). So a
+// plain table→closure adapter would EAT unmatched tokens where 5.1 keeps
+// them, and the closure can't reconstruct the whole match from capture
+// args alone.
+//
+// The shim therefore rewrites the pattern with one OUTER capture —
+// `pat` → `(pat)`, keeping a leading `^` and an unescaped trailing `$`
+// outside (both are anchors only at their positional ends; inside the
+// parens they'd turn literal) — so the adapter closure always receives
+// the whole match as arg 1, the pattern's own first capture as arg 2, and
+// can hand arg 1 back to reproduce 5.1's keep-match for missing keys.
+// Patterns containing a `%1`..`%9` back-reference can't be wrapped (the
+// outer capture would renumber what `%N` refers to); those fall back to
+// an unwrapped adapter whose missing-key behavior is the engine's own
+// (match → empty) — the one documented divergence, and the combination
+// (table replacement + pattern back-references) is essentially absent
+// from real code. String/function replacements tail-call the engine gsub
+// untouched.
+
+// True when the pattern contains a `%1`..`%9` back-reference. Escape-aware:
+// the char after any `%` is consumed, so `%%1` (literal percent, then '1')
+// doesn't count.
+bool PatternHasBackref(const char *p, unsigned len) {
+    for (unsigned i = 0; i + 1 < len; ++i) {
+        if (p[i] != '%')
+            continue;
+        const char c = p[i + 1];
+        if (c >= '1' && c <= '9')
+            return true;
+        ++i; // skip the escaped char
+    }
+    return false;
+}
+
+// Adapter for the wrapped-pattern path: arg 1 = whole match, arg 2 = the
+// pattern's own first capture (when it declared any). Upvalue 1 = the
+// replacement table. Missing/false value → return the whole match (5.1's
+// keep-match).
+int __fastcall GsubTableLookupWrapped(void *L) {
+    const int nargs = Game::Lua::GetTop(L);
+    Game::Lua::PushValue(L, nargs >= 2 ? 2 : 1);        // the 5.1 lookup key
+    Game::Lua::GetTable(L, Game::Lua::UpvalueIndex(1)); // tbl[key]
+    const int t = Game::Lua::Type(L, -1);
+    if (t == Game::Lua::TYPE_NIL ||
+        (t == Game::Lua::TYPE_BOOLEAN && Game::Lua::ToBoolean(L, -1) == 0))
+        Game::Lua::PushValue(L, 1); // keep the original match
+    return 1;                       // top value is the result
+}
+
+// Adapter for back-reference patterns (unwrapped): arg 1 is already the
+// 5.1 key. A missing key returns nil → the engine appends nothing.
+int __fastcall GsubTableLookupPlain(void *L) {
+    Game::Lua::PushValue(L, 1);
+    Game::Lua::GetTable(L, Game::Lua::UpvalueIndex(1));
+    return 1;
+}
+
+int __fastcall Script_string_gsub(void *L) {
+    const auto engineGsub =
+        reinterpret_cast<Game::Lua::CFunction>(Offsets::FUN_LUA_STR_GSUB);
+    if (Game::Lua::Type(L, 3) != Game::Lua::TYPE_TABLE)
+        return engineGsub(L); // string/function/error paths untouched
+
+    const char *pat = Game::Lua::ToString(L, 2);
+    if (pat == nullptr)
+        return engineGsub(L); // let the engine raise its own arg error
+    const unsigned patLen = Game::Lua::StrLen(L, 2);
+
+    Game::Lua::SetTop(L, 4); // normalize to (s, pat, tbl, n) — gsub reads ≤4
+
+    if (!PatternHasBackref(pat, patLen)) {
+        // Build `(body)` with the anchors outside the capture.
+        unsigned b = 0, e = patLen;
+        std::string wrapped;
+        wrapped.reserve(patLen + 3);
+        if (e > b && pat[0] == '^') {
+            wrapped += '^';
+            b = 1;
+        }
+        bool anchoredBack = false;
+        if (e > b && pat[e - 1] == '$') {
+            // `$` is an anchor only when not %-escaped: an even number of
+            // `%` immediately before it means the `$` itself is unescaped.
+            unsigned pc = 0;
+            for (int idx = static_cast<int>(e) - 2;
+                 idx >= static_cast<int>(b) && pat[idx] == '%'; --idx)
+                ++pc;
+            anchoredBack = (pc % 2) == 0;
+            if (anchoredBack)
+                --e;
+        }
+        wrapped += '(';
+        wrapped.append(pat + b, e - b);
+        wrapped += ')';
+        if (anchoredBack)
+            wrapped += '$';
+
+        Game::Lua::PushLString(L, wrapped.data(),
+                               static_cast<unsigned int>(wrapped.size())); // 5
+        Game::Lua::PushValue(L, 3);                                        // 6: tbl
+        Game::Lua::PushCClosure(L, &GsubTableLookupWrapped, 1);            // 6: closure
+        Game::Lua::Insert(L, 2); // closure→2: s, closure, pat, tbl, n, wrapped
+        Game::Lua::Insert(L, 2); // wrapped→2: s, wrapped, closure, pat, tbl, n
+        Game::Lua::Remove(L, 4); // drop the original pattern
+        Game::Lua::Remove(L, 4); // drop the table → (s, wrapped, closure, n)
+    } else {
+        Game::Lua::PushValue(L, 3);                           // 5: tbl
+        Game::Lua::PushCClosure(L, &GsubTableLookupPlain, 1); // 5: closure
+        Game::Lua::Insert(L, 3); // → s, pat, closure, tbl, n
+        Game::Lua::Remove(L, 4); // → s, pat, closure, n
+    }
+    return engineGsub(L);
+}
+
 void RegisterFns() {
     Game::Lua::RegisterTableFunction("string", "match", &Script_string_match);
     Game::Lua::RegisterTableFunction("string", "gmatch", Script_string_gmatch);
+    Game::Lua::RegisterTableFunction("string", "gsub", &Script_string_gsub);
     Game::Lua::RegisterTableFunction("string", "reverse", &Script_string_reverse);
+    Game::Lua::RegisterTableFunction("string", "split", &Script_strsplit);
+    // The bare `gsub` global (1.12 exposes the string functions as globals
+    // too) must match `string.gsub`, so addons calling either form get the
+    // table-replacement upgrade.
+    Game::Lua::RegisterGlobalFunction("gsub", &Script_string_gsub);
     Game::Lua::RegisterGlobalFunction("strsplit", &Script_strsplit);
     Game::Lua::RegisterGlobalFunction("strjoin", &Script_strjoin);
     Game::Lua::RegisterGlobalFunction("strtrim", &Script_strtrim);

src/baselib/Unpack.cpp

@@ -0,0 +1,86 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `unpack(list [, i [, j]])` — upgrade 1.12's Lua 5.0 `unpack` to the 5.1
+// signature. 5.0's unpack takes NO range arguments and silently ignores
+// extras, so 5.1 code calling `unpack(t, 2)` got the WHOLE table back —
+// wrong values with no error, the worst failure mode (verified in-game:
+// `unpack({10,20,30}, 2)` returned 10, 20, 30). This replacement is a
+// port of 5.1's `luaB_unpack` (lbaselib.c): `i` defaults to 1 and `j` to
+// the table length via luaL_getn — which reads a `t.n` field first, so
+// the transpiler's `unpack(arg)` vararg expansion keeps its
+// embedded-nil-aware count exactly as before.
+//
+// Registered on BOTH states (language-level helper, both are 5.0).
+
+#include "Game.h"
+#include "Offsets.h"
+
+namespace BaseLib::Unpack {
+
+namespace {
+
+// Engine auxlib/API entries (see Offsets.h for derivations).
+using LuaLGetN_t = int(__fastcall *)(void *L, int idx);
+using RawGetI_t = void(__fastcall *)(void *L, int idx, int n);
+
+// Range argument at `idx`: absent/nil → `fallback`; a number (or numeric
+// string, matching luaL_optint's coercion) → its value; anything else
+// errors like 5.1's luaL_optint.
+int OptRange(void *L, int idx, int fallback) {
+    if (Game::Lua::Type(L, idx) <= Game::Lua::TYPE_NIL) // none or nil
+        return fallback;
+    if (!Game::Lua::IsNumber(L, idx)) {
+        Game::Lua::Error(L, "bad argument #%d to 'unpack' (number expected)", idx);
+        return 0; // unreachable
+    }
+    return static_cast<int>(Game::Lua::ToNumber(L, idx));
+}
+
+int __fastcall Script_unpack(void *L) {
+    if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) {
+        Game::Lua::Error(L, "bad argument #1 to 'unpack' (table expected)");
+        return 0; // unreachable
+    }
+    const int i = OptRange(L, 2, 1);
+    const int e = OptRange(
+        L, 3, reinterpret_cast<LuaLGetN_t>(Offsets::LUAL_GETN)(L, 1));
+    if (i > e)
+        return 0;
+    // `n <= 0` guards the int overflow of `e - i + 1` (i <= e holds here),
+    // mirroring 5.1's luaB_unpack.
+    const int n = e - i + 1;
+    if (n <= 0 || Game::Lua::CheckStack(L, n) == 0) {
+        Game::Lua::Error(L, "too many results to unpack");
+        return 0; // unreachable
+    }
+    const auto rawGetI = reinterpret_cast<RawGetI_t>(Offsets::LUA_RAWGETI);
+    for (int k = i; k <= e; ++k)
+        rawGetI(L, 1, k);
+    return n;
+}
+
+void RegisterInGame() {
+    Game::Lua::RegisterGlobalFunction("unpack", &Script_unpack);
+}
+
+void RegisterGlue() {
+    Game::Lua::RegisterGlueFunction("unpack", &Script_unpack);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterInGame};
+const Game::GlueModuleAutoRegister _autoregGlue{&RegisterGlue};
+
+} // namespace
+
+} // namespace BaseLib::Unpack

src/bindings/Api.cpp

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

src/bindings/Bindings.xml

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

src/chat/CurrentGUID.cpp

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

src/chat/CurrentGUID.h

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

src/chat/Dispatch.cpp

@@ -0,0 +1,105 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// 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

src/chat/IconFilter.cpp

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

src/chat/IconFilter.h

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

src/chat/RaidMarkers.cpp

@@ -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 {
+
+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];
+                    // `:0:0` = auto-size. The inline emitter resolves height/width
+                    // to the target line's font pixel height at draw time, so a
+                    // marker tracks the chat font size (and grows in speech bubbles)
+                    // exactly like retail's ICON_LIST `…Icon_%d:0`. The rest of the
+                    // payload crops the 256x256 sheet to the cell (l,r,t,b).
+                    const int m = std::snprintf(
+                        markup, sizeof markup,
+                        "||TInterface\\TargetingFrame\\UI-RaidTargetingIcons:0:0:0:0:256:256:"
+                        "%d:%d:%d:%d||t",
+                        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

src/chat/RaidMarkers.h

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

src/chatbubble/Info.cpp

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

src/classes/Info.cpp

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

src/clipboard/Copy.cpp

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

src/color/Util.cpp

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

src/container/FreeSlots.cpp

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

src/container/ItemInfo.cpp

@@ -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;
     }

src/coroutine/Library.cpp

@@ -211,12 +211,42 @@ static int __fastcall Script_Coroutine_Wrap(void *L) {
     return 1;
 }
 
+// `coroutine.running()` — Lua 5.1 addition: the running coroutine, or
+// nil when called from the main thread. The 5.0 C API has no
+// `lua_pushthread` (also a 5.1 addition), so the thread TValue is
+// written to the stack raw: this build's TValue is 16 bytes with
+// {tt @ +0, value @ +8} (see LuaSyntax::StringMethods for the layout
+// derivation), tag 8 = thread, and the value is the running `lua_State`
+// itself — exactly what `lua_newthread` stores and what LUA_TO_POINTER
+// reads back at tvalue[2]. No stack-overflow check needed: every C
+// function is guaranteed LUA_MINSTACK free slots and this pushes one.
+// The running thread is trivially GC-alive, so no anchoring either.
+// Main-thread detection: module callbacks run on the state's main
+// thread, so the L captured at registration IS the main thread;
+// coroutine bodies run on their own lua_State.
+static void *g_mainL = nullptr;
+static constexpr uintptr_t OFF_L_TOP = 0x8; // L->top (push helpers' [ecx+8])
+
+static int __fastcall Script_Coroutine_Running(void *L) {
+    if (L == g_mainL) {
+        Game::Lua::PushNil(L);
+        return 1;
+    }
+    uint8_t *top = Game::Read<uint8_t *>(L, OFF_L_TOP);
+    *reinterpret_cast<int *>(top) = Game::Lua::TYPE_THREAD;
+    *reinterpret_cast<void **>(top + 8) = L;
+    Game::Ref<uint8_t *>(L, OFF_L_TOP) = top + 16;
+    return 1;
+}
+
 static void RegisterLuaFunctions() {
+    g_mainL = Game::Lua::State(); // the state's main thread (see Running)
     Game::Lua::RegisterTableFunction("coroutine", "create", &Script_Coroutine_Create);
     Game::Lua::RegisterTableFunction("coroutine", "resume", &Script_Coroutine_Resume);
     Game::Lua::RegisterTableFunction("coroutine", "yield", &Script_Coroutine_Yield);
     Game::Lua::RegisterTableFunction("coroutine", "status", &Script_Coroutine_Status);
     Game::Lua::RegisterTableFunction("coroutine", "wrap", &Script_Coroutine_Wrap);
+    Game::Lua::RegisterTableFunction("coroutine", "running", &Script_Coroutine_Running);
 }
 
 static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};

src/creature/Info.cpp

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

src/creature/Info.h

@@ -13,18 +13,15 @@
 
 #pragma once
 
-namespace Tooltip::SetItemEvent {
+#include <cstdint>
 
-// RAII guard that suppresses OnTooltipSetItem firing for the duration of an
-// engine item-build we invoke *internally* (Tooltip::Compare building the
-// equipped item into a shopping tooltip). Without it, a handler would run in
-// the middle of our line-shift / delta rendering and see a half-built tooltip.
-// Nestable (ref-counted).
-struct Suppressor {
-    Suppressor();
-    ~Suppressor();
-    Suppressor(const Suppressor &) = delete;
-    Suppressor &operator=(const Suppressor &) = delete;
-};
+namespace Creature::Info {
 
-} // namespace Tooltip::SetItemEvent
+// 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

src/currency/CoinText.cpp

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

src/cursor/Info.cpp

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