debugtools: use DEBUG_FRAMESTACK from locale if available

Modern WoW exposes GetMouseFoci() (the stack of frames under the
cursor) alongside GetMouseFocus(), with GetMouseFocus() ==
GetMouseFoci()[1]. Vanilla stores only the single topmost focus
(Script_GetMouseFocus reads *(ctx + 0x7C)); there is no stored stack.

Reimplement natively (no Lua polyfill, no hooks): walk the engine frame
list that Script_EnumerateFrames iterates (head *(ctx + 0xCC4), next
+0x308, low-bit/null sentinel), keep frames that are visible +
mouse-enabled and whose rect contains the cursor (Region getters +
cursor/effective-scale, mirroring Frame::Modern's IsMouseOver), order
top-first by strata rank then frame level (level read directly from
+0xC4), and force index 1 to the engine's stored focus so the invariant
holds by Lua table identity. Frames are pushed via the shared
UI::FrameObject::Push so == compares the same wrapper GetMouseFocus
returns.

Filters to the mouse-enabled (interactive) stack, matching 1.15.x
(verified: GetMouseFocus skips a higher non-mouse-enabled cooldown to
land on the button, and 1.15.x GetMouseFoci returns the same set).
/framestack lists more because it is a pure-geometry debug view, not the
mouse-focus set.

Docs: API.md entry (Simplified Technical English).

.github/workflows/build.yml

@@ -4,6 +4,18 @@ 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
@@ -16,36 +28,52 @@ jobs:
         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
+        shell: bash
         run: |
-          $version = '${{ github.ref_name }}' -replace '^v',''
-          $toc = 'AddOns/!!!ClassicAPI/!!!ClassicAPI.toc'
-          (Get-Content $toc) -replace '^## Version:.*', "## Version: $version" |
-            Set-Content $toc
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ -n "${{ inputs.tag }}" ]; then
+            tag="${{ inputs.tag }}"
+          elif [[ "${{ github.ref }}" == refs/tags/v* ]]; then
+            tag="${{ github.ref_name }}"
+          else
+            tag=""
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          if [ -n "$tag" ]; then
+            echo "is_release=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_release=false" >> "$GITHUB_OUTPUT"
+          fi
 
-      - name: Configure (tag)
-        if: startsWith(github.ref, 'refs/tags/v')
-        run: cmake -B build -A Win32 "-DCLASSICAPI_TAG=${{ github.ref_name }}"
+      - name: Configure (release)
+        if: steps.ver.outputs.is_release == 'true'
+        run: cmake -B build -A Win32 "-DCLASSICAPI_TAG=${{ steps.ver.outputs.tag }}"
 
-      - name: Configure (branch)
-        if: "!startsWith(github.ref, 'refs/tags/v')"
+      - name: Configure (dev)
+        if: steps.ver.outputs.is_release != 'true'
         run: cmake -B build -A Win32
 
       - name: Build
         run: cmake --build build --config Release
 
       - name: Upload artifact
-        if: "!startsWith(github.ref, 'refs/tags/v')"
+        if: steps.ver.outputs.is_release != 'true'
         uses: actions/upload-artifact@v4
         with:
           name: ClassicAPI-${{ github.sha }}
           path: build/Release/ClassicAPI.dll
 
       - name: Release
-        if: startsWith(github.ref, 'refs/tags/v')
+        if: steps.ver.outputs.is_release == 'true'
         uses: softprops/action-gh-release@v2
         with:
+          tag_name: ${{ steps.ver.outputs.tag }}
           files: build/Release/ClassicAPI.dll
           generate_release_notes: true

.gitignore

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

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

@@ -58,3 +58,26 @@ if C_AddOns.DoesAddOnExist("ShaguTweaks") then
         end
     end)
 end
+
+-- Guard UPDATE_MOUSEOVER_UNIT handlers (issue #12).
+function CAPI_MouseoverClearedCompat(frame)
+    if not frame then return end
+    local originalOnEvent = frame:GetScript("OnEvent")
+    frame:SetScript("OnEvent", function()
+        if event == "UPDATE_MOUSEOVER_UNIT" and not UnitExists("mouseover") then
+            return
+        end
+
+        if originalOnEvent then
+            originalOnEvent()
+        end
+    end)
+end
+
+CAPI_MouseoverClearedCompat(GameTooltip)
+
+if C_AddOns.DoesAddOnExist("Puppeteer") then
+    EventUtil.ContinueOnAddOnLoaded("Puppeteer", function()
+        CAPI_MouseoverClearedCompat(PTEnemyUpdater)
+    end)
+end

AddOns/!!!ClassicAPI/Util/GameTooltip.lua

@@ -90,31 +90,3 @@ function GameTooltip_ShowCompareItem(self, shift)
 		end
 	end
 end
-
--- Guard the stock GameTooltip UPDATE_MOUSEOVER_UNIT handler (issue #12).
---
--- ClassicAPI's DLL now fires UPDATE_MOUSEOVER_UNIT on mouseover LOSS too (retail
--- parity), not just on gain. The stock inline handler in FrameXML/GameTooltip.xml
--- recolors the name unconditionally:
---     _G[this:GetName().."TextLeft1"]:SetTextColor(GameTooltip_UnitColor("mouseover"))
--- and GameTooltip_UnitColor returns white (1,1,1) when "mouseover" doesn't exist.
--- So the loss fire (and the transient clear that happens when clicking a unit)
--- repaints the still-visible/fading name white before it disappears -- reported
--- as NPC and PvP-flagged-player names flashing white.
---
--- We wrap the stock handler instead of replacing its body: swallow the event
--- only when there is no mouseover unit to color, otherwise delegate to the
--- original untouched. During the loss window the name simply keeps its last
--- color instead of going white; when a mouseover resolves again it recolors
--- normally. (1.12 OnEvent handlers read the `event`/`this` globals the engine
--- sets before invoking us, so calling the original as a plain function works.)
-local originalOnEvent = GameTooltip:GetScript("OnEvent")
-GameTooltip:SetScript("OnEvent", function()
-	if ( event == "UPDATE_MOUSEOVER_UNIT" and not UnitExists("mouseover") ) then
-		return;
-	end
-
-	if ( originalOnEvent ) then
-		originalOnEvent();
-	end
-end)

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

@@ -4,6 +4,11 @@ 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.";

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

@@ -4,6 +4,11 @@ BINDING_NAME_TARGETFOCUS = "Target Focus";
 CONFIRM_DELETE_EQUIPMENT_SET = "Are you sure you want to delete the equipment set %s?";
 CONFIRM_SAVE_EQUIPMENT_SET = "Would you like to save the equipment set \"%s\"?";
 COPPER_AMOUNT_SYMBOL = "c";
+DEBUFF_SYMBOL_CURSE = "Cu";
+DEBUFF_SYMBOL_DISEASE = "Di";
+DEBUFF_SYMBOL_MAGIC = "Ma";
+DEBUFF_SYMBOL_POISON = "Po";
+DEBUG_FRAMESTACK = "Frame Stack";
 EQUIPMENT_MANAGER = "Equipment Manager";
 EQUIPMENT_MANAGER_IGNORE_SLOT = "Ignore This Slot";
 EQUIPMENT_MANAGER_IS_DISABLED = "The Equipment Manager is disabled.";

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

@@ -4,6 +4,11 @@ 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.";

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

@@ -4,6 +4,11 @@ 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é.";

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

@@ -4,6 +4,11 @@ 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 = "Управление экипировкой отключено.";

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

@@ -4,6 +4,11 @@ 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 = "装备管理已禁用。";

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

@@ -4,6 +4,11 @@ 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 = "裝備管理員已關閉。";

AddOns/DebugTools/DebugTools.lua

@@ -1018,7 +1018,7 @@ end
 
 local function _UpdateFrameStackTooltip(tooltip, showHidden)
     tooltip:ClearLines();
-    tooltip:AddLine("Frame Stack", 1, 1, 1);
+    tooltip:AddLine(DEBUG_FRAMESTACK or "Frame Stack", 1, 1, 1);
     local matches = _CollectFramesUnderMouse(showHidden);
     local count = table.getn(matches);
     if (count == 0) then

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})

README.md

@@ -35,7 +35,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | [Expansion](docs/API.md#expansion) | `ClassicExpansionAtLeast`, `ClassicExpansionAtMost`, `GetClassicExpansionLevel` |
 | [Faction](docs/API.md#faction) | `C_Reputation.GetFactionDataByIndex`, `C_Reputation.GetFactionStandings`, `C_Reputation.GetLastStandingChange`, `C_Reputation.GetWatchedFactionData`, `C_Reputation.SetWatchedFactionByID`, `GetFactionIDByIndex`, `GetFactionInfoByID`, `GetFactionParentID` |
 | [Focus](docs/API.md#focus) | `ClearFocus`, `FocusUnit` |
-| [Frame](docs/API.md#frame) | `region:SetPoint("point")` (one-arg form), `region:SetSize`, `region:GetSize`, `region:IsMouseOver`, `region:GetRect`, `region:IsDragging`, `frame:SetShown`, `frame:SetResizeBounds`, `frame:HookScript`, `frame:IsEventRegistered`, `frame:GetEffectiveAlpha`, `frame:SetAttribute`, `frame:SetAttributeNoHandler`, `frame:ClearAttribute`, `frame:GetAttribute`, `OnAttributeChanged` (script), `SetModernScriptArgs`, `GetModernScriptArgs` |
+| [Frame](docs/API.md#frame) | `region:SetPoint("point")` (one-arg form), `region:SetSize`, `region:GetSize`, `region:IsMouseOver`, `region:GetRect`, `region:IsDragging`, `GetMouseFoci`, `frame:SetShown`, `frame:SetResizeBounds`, `frame:HookScript`, `frame:IsEventRegistered`, `frame:GetEffectiveAlpha`, `frame:SetAttribute`, `frame:SetAttributeNoHandler`, `frame:ClearAttribute`, `frame:GetAttribute`, `OnAttributeChanged` (script), `SetModernScriptArgs`, `GetModernScriptArgs` |
 | [FriendList](docs/API.md#friendlist) | `C_FriendList.IsWhoQueryPending`, `C_FriendList.SendWhoQueryByName` |
 | [GameObject](docs/API.md#gameobject) | `C_GameObjectInfo.GetGameObjectInfoByID`, `C_GameObjectInfo.RequestLoadGameObjectByID`, `ClosestGameObjectPosition` |
 | [Glue](docs/API.md#glue) | `C_Glue.IsOnGlueScreen` |

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/API.md

@@ -159,6 +159,7 @@ build instructions.
   - [`region:IsMouseOver([topOffset, bottomOffset, leftOffset, rightOffset])`](#regionismouseovertopoffset-bottomoffset-leftoffset-rightoffset)
   - [`region:GetRect()`](#regiongetrect)
   - [`region:IsDragging()`](#regionisdragging)
+  - [`GetMouseFoci()`](#getmousefoci)
   - [`frame:SetShown(shown)`](#framesetshownshown)
   - [`frame:SetResizeBounds(minWidth, minHeight [, maxWidth, maxHeight])`](#framesetresizeboundsminwidth-minheight--maxwidth-maxheight)
   - [`frame:HookScript(scriptType, handler)`](#framehookscriptscripttype-handler)
@@ -3719,6 +3720,20 @@ fontstrings) always report `false`, since only frames can be dragged.
 if self:IsDragging() then ... end
 ```
 
+### `GetMouseFoci()`
+
+Returns a table of the mouse-enabled frames under the cursor, from top
+to bottom. Index 1 is the frame that `GetMouseFocus()` returns, so
+`GetMouseFocus() == GetMouseFoci()[1]` is always true.
+
+```lua
+local foci = GetMouseFoci()
+-- foci[1] == GetMouseFocus()
+for i = 1, table.getn(foci) do
+    print(foci[i]:GetName() or "<anonymous>")
+end
+```
+
 ### `frame:SetShown(shown)`
 
 `Show()` if `shown` is truthy, `Hide()` otherwise. Registered for

src/Offsets.h

@@ -1498,6 +1498,16 @@ enum Offsets {
     // cursor is over no mouse-enabled frame. `Frame::Attributes` polls this to
     // drive the `mouseover` override from the hovered frame's `unit` attribute.
     OFF_UI_CONTEXT_MOUSE_FOCUS = 0x7C,
+    // Head of the engine's frame list (`*(*VAR_UI_CONTEXT_PTR + 0xCC4)`),
+    // and each frame CObject's next-in-enumeration pointer at +0x308 — the
+    // list `Script_EnumerateFrames` (0x00705F60) walks. A node with its low
+    // bit set (or null) is the end sentinel. `Frame::MouseFoci` walks it to
+    // build the GetMouseFoci stack.
+    OFF_UI_CONTEXT_FRAME_LIST_HEAD = 0xCC4,
+    OFF_FRAME_ENUM_NEXT = 0x308,
+    // Frame level, a plain int at CObject +0xC4 (the value `Script_GetFrameLevel`
+    // at 0x007744A0 pushes as `frame[0x31]`). Read directly for stack ordering.
+    OFF_FRAME_LEVEL = 0xC4,
     FUN_SCRIPT_FRAME_SHOW = 0x00775750,
     FUN_SCRIPT_FRAME_HIDE = 0x00775810,
     FUN_SCRIPT_FRAME_SETMINRESIZE = 0x00776020,
@@ -1508,6 +1518,14 @@ enum Offsets {
     // it so a unit-attributed frame registers as the mouse-focus (bare frames
     // otherwise never hover). Standard `int __fastcall(void *L)` Script_* shape.
     FUN_SCRIPT_FRAME_ENABLEMOUSE = 0x00777070,
+    // Frame predicates used by `Frame::MouseFoci` to filter the enumeration to
+    // the interactive stack (visible + mouse-enabled). Standard Script_* shape
+    // `int __fastcall(void *L)`, self at Lua idx 1, result pushed at idx 2.
+    FUN_SCRIPT_FRAME_IS_VISIBLE = 0x007758D0,
+    FUN_SCRIPT_FRAME_IS_MOUSE_ENABLED = 0x00777130,
+    // `frame:GetFrameStrata()` — pushes the strata name string; ranked for
+    // stack ordering (`Frame::MouseFoci`).
+    FUN_SCRIPT_FRAME_GET_STRATA = 0x007742A0,
     // Button OnClick dispatcher — `__thiscall(button, buttonCode)` at
     // 0x00779540, invoking the button's OnClick slot `[button+0x4CC]`. NOTE: do
     // NOT MinHook it — SuperWoW's click-casting inline-hooks the same prologue

src/addons/Embedded.cpp

@@ -60,6 +60,13 @@ namespace {
 constexpr const char *kAddonName = "!!!ClassicAPI";
 constexpr const char *kAddonTocFile = "!!!ClassicAPI.toc";
 
+// Developer marker. When this file exists in the on-disk addon folder,
+// the disk copy wins unconditionally (see `DiskHasDevMarker` /
+// `DecideSource`). It is gitignored, excluded from the embed, and the
+// release ships only the DLL — so it can only exist where a developer
+// deliberately created it, never in a normal user's install.
+constexpr const char *kDevMarkerFile = ".classicapi-dev";
+
 // `Interface\AddOns\!!!ClassicAPI\` — the prefix the engine
 // constructs for any of our addon's files. Comparing case-
 // insensitively because the TOC parser uses `Interface\AddOns\%s\…`
@@ -156,17 +163,20 @@ bool ExtractTocVersion(const char *content, size_t size,
     return false;
 }
 
-// Returns -1/0/+1 for `a < b` / `a == b` / `a > b`. "DEV" is a
-// sentinel meaning "newer than any real release" — local dev builds
-// always win against installed-on-disk versions. Otherwise the two
-// strings are walked as dot-separated numeric semver components
+// Returns -1/0/+1 for `a < b` / `a == b` / `a > b`. "DEV" is the
+// local-build sentinel: two DEV builds are equal, but a DEV build sorts
+// BELOW any real release. Dev-over-release precedence is signalled
+// explicitly by the `.classicapi-dev` marker now — NOT by the toc
+// version — so a stray `## Version: DEV` disk copy (repo clone / old
+// bundle) never silently shadows a newer embedded release. Otherwise
+// the two strings are walked as dot-separated numeric semver components
 // (`1.2` < `1.10`).
 int CompareVersions(const char *a, const char *b) {
     const bool aDev = std::strcmp(a, "DEV") == 0;
     const bool bDev = std::strcmp(b, "DEV") == 0;
     if (aDev && bDev) return 0;
-    if (aDev) return 1;
-    if (bDev) return -1;
+    if (aDev) return -1;
+    if (bDev) return 1;
     while (*a || *b) {
         int va = 0, vb = 0;
         while (*a >= '0' && *a <= '9') { va = va * 10 + (*a - '0'); ++a; }
@@ -203,16 +213,48 @@ void EnsureEmbeddedVersionExtracted() {
     }
 }
 
+// True iff the on-disk addon folder contains the `.classicapi-dev`
+// marker. Read via the ORIGINAL `FUN_FILE_READ` (bypassing our embed
+// hook), so it reflects a real file on disk / in an MPQ — never an
+// embedded copy. That makes it a clean "is this a developer working
+// tree" signal: the marker is gitignored + excluded from the embed and
+// the release ships only the DLL, so a normal user's install can't
+// carry it.
+bool DiskHasDevMarker() {
+    char fullPath[256];
+    std::snprintf(fullPath, sizeof(fullPath), "%s%s",
+                  kAddonPathPrefix, kDevMarkerFile);
+    void *buf = nullptr;
+    size_t size = 0;
+    const int ok = FileRead_o(0, fullPath, &buf, &size, 1, 1, 0);
+    if (ok == 0 || buf == nullptr)
+        return false;
+    auto SMemFree = reinterpret_cast<SMemFree_t>(Offsets::FUN_STORM_SMEM_FREE);
+    SMemFree(buf, __FILE__, __LINE__, 0);
+    return true;
+}
+
 // Decide whether disk or embedded should serve all reads for this
 // addon. Called on the first FileRead_h call with a matching prefix.
-// Reads the on-disk TOC via the original `FUN_FILE_READ` (bypassing
-// our hook), parses its version, compares to the embedded version,
-// and caches the winner. If disk has no TOC at all, embedded wins by
-// default.
+// The `.classicapi-dev` marker forces disk unconditionally (explicit
+// developer override). Otherwise reads the on-disk TOC via the original
+// `FUN_FILE_READ` (bypassing our hook), parses its version, compares to
+// the embedded version, and caches the newer. If disk has no TOC at
+// all, embedded wins by default.
 void DecideSource() {
     if (g_source != Source::Undecided) return;
     EnsureEmbeddedVersionExtracted();
 
+    // Explicit developer override: disk wins regardless of version. This
+    // is how a dev keeps disk precedence when running local Lua against a
+    // *released* DLL (where the embedded version would otherwise be newer
+    // and win). Dev intent lives in this marker, decoupled from the toc
+    // version — so users never get silently shadowed by a stray copy.
+    if (DiskHasDevMarker()) {
+        g_source = Source::Disk;
+        return;
+    }
+
     char fullPath[256];
     std::snprintf(fullPath, sizeof(fullPath), "%s%s",
                   kAddonPathPrefix, kAddonTocFile);

src/aura/Source.cpp

@@ -130,6 +130,7 @@ struct Entry {
     uint32_t spellId;
     uint32_t expirationMs; // 0 = infinite / unknown duration
     uint32_t durationMs;   // applied duration (incl. caster mods); 0 = none
+    uint32_t stampMs;      // last write time; EvictAbsent grace (see below)
     int8_t kind;           // Kind; descriptor-slot-derived, KIND_UNKNOWN if only seen via SpellGo
     bool used;
 };
@@ -138,6 +139,16 @@ constexpr int kCacheSize = 256;
 Entry g_cache[kCacheSize];
 int g_writeCursor = 0;
 
+// SMSG_SPELL_GO arrives before the SMSG_UPDATE_OBJECT that adds the aura to
+// the target's descriptor, so for a brief window a just-captured entry names
+// an aura the descriptor doesn't list yet. `EvictAbsent` (run from a query's
+// ReconcileCache) must not drop such a fresh entry — doing so discards the
+// caster we just captured, which OnAuraAdded then recreates caster-less
+// (verified: druid buff → sourceGUID lost). Entries younger than this window
+// are exempt from EvictAbsent; a genuinely-removed aura is far older and still
+// gets dropped (and OnAuraRemoved evicts real removals directly regardless).
+constexpr uint32_t kEvictGraceMs = 2000;
+
 // `fromCast` true: the SpellGo hook — authoritative caster + caster-modified
 // (talented) timing. False: the OnAuraAdded application hook — timing only,
 // no caster, and it must not clobber an entry SpellGo already owns (that
@@ -149,9 +160,12 @@ void Store(uint64_t targetGuid, uint32_t spellId, uint64_t casterGuid,
     if (targetGuid == 0 || spellId == 0)
         return;
 
+    const uint32_t now = NowMs();
+
     // Update an existing entry for this exact aura instance.
     for (auto &e : g_cache) {
         if (e.used && e.targetGuid == targetGuid && e.spellId == spellId) {
+            e.stampMs = now; // refresh EvictAbsent grace on any touch
             // Learn the classification whenever a slot-derived kind arrives —
             // independent of caster/timing ownership, and never downgrade a
             // known kind back to unknown.
@@ -167,18 +181,17 @@ void Store(uint64_t targetGuid, uint32_t spellId, uint64_t casterGuid,
         }
     }
     // Take a free slot, else an expired one, else evict round-robin.
-    const uint32_t now = NowMs();
     for (auto &e : g_cache) {
         if (!e.used || (e.expirationMs != 0 && now >= e.expirationMs)) {
             e = {targetGuid, casterGuid, spellId, expirationMs, durationMs,
-                 kind, true};
+                 now, kind, true};
             return;
         }
     }
     Entry &slot = g_cache[g_writeCursor];
     g_writeCursor = (g_writeCursor + 1) % kCacheSize;
-    slot = {targetGuid, casterGuid, spellId, expirationMs, durationMs, kind,
-            true};
+    slot = {targetGuid, casterGuid, spellId, expirationMs, durationMs, now,
+            kind, true};
 }
 
 // ---- Out-of-range group-member aura snapshots ---------------------------
@@ -775,9 +788,14 @@ bool Get(uint64_t unitGuid, uint32_t spellId, uint64_t *outCaster,
 void EvictAbsent(uint64_t unitGuid, const uint32_t *presentSpellIds, int count) {
     if (unitGuid == 0 || presentSpellIds == nullptr || count <= 0)
         return;
+    const uint32_t now = NowMs();
     for (auto &e : g_cache) {
         if (!e.used || e.targetGuid != unitGuid)
             continue;
+        // Fresh SpellGo capture the descriptor hasn't synced yet — see
+        // kEvictGraceMs. Don't evict it; that's the sourceGUID-loss race.
+        if (now - e.stampMs < kEvictGraceMs)
+            continue;
         bool present = false;
         for (int i = 0; i < count; ++i)
             if (presentSpellIds[i] == e.spellId) {

src/encoding/CBOR.cpp

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

src/frame/MouseFoci.cpp

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

src/spell/Tooltip.cpp

@@ -28,7 +28,7 @@ static constexpr int OFF_SPELL_NAME = 0x1E0; // localized char *[9]
 static constexpr int OFF_SPELL_RANK = 0x204; // localized char *[9]
 
 using BuildSpellTooltip_t = void(__thiscall *)(void *thisObj, int spellID, int arg2, int arg3,
-                                               int isPet, int arg5, int arg6, int arg7);
+                                               int isPet, int showRank, int arg6, int arg7);
 
 void ShowByID(void *L, int spellID) {
     if (spellID <= 0)
@@ -38,7 +38,7 @@ void ShowByID(void *L, int spellID) {
         return;
     auto BuildSpellTooltip =
         reinterpret_cast<BuildSpellTooltip_t>(Offsets::FUN_GAMETOOLTIP_BUILD_SPELL_TOOLTIP);
-    BuildSpellTooltip(tooltipObj, spellID, 0, 0, 0, 0, 0, 0);
+    BuildSpellTooltip(tooltipObj, spellID, 0, 0, 0, /*showRank=*/1, 0, 0);
 }
 
 static int __fastcall Script_GameTooltipSetSpellByID(void *L) {

src/spell/Tooltip.h

@@ -17,7 +17,9 @@ namespace Spell::Tooltip {
 
 // Resolves the `GameTooltip` self at Lua stack[1] (via the
 // engine's `FrameScript_PushObject`/`FrameScript_GetObject` chain)
-// and dispatches the engine's spell-tooltip builder for `spellID`.
+// and dispatches the engine's spell-tooltip builder for `spellID`,
+// with the spell's rank shown in the top-right corner of the title
+// line (matching `SetAction`/`SetPetAction`; native `SetSpell` omits it).
 // Silent no-op if `spellID <= 0` or stack[1] isn't a frame object.
 //
 // Used by `GameTooltip:SetSpellByID` directly, and by