docs: client bug report — GameTooltipMods nil lineText (MultiCast totem tooltip crash)

CLIENT-BUG-GameTooltipMods.md

@@ -0,0 +1,63 @@
+# CoA client bug — GameTooltipMods.lua nil `lineText` in ModTooltipSetSpell
+
+**Component:** CoA/Ascension client FrameXML mod (shipped in `Data/patch-B.MPQ` →
+`Interface\FrameXML\GameTooltipMods.lua`). NOT an addon — this is the client.
+
+**Realm seen:** Vol'jin — CoA Beta. Reproduces on a custom-class character (e.g.
+Guardian) by **hovering a MultiCast totem / standard action button** with any
+tooltip-embedding addon active (TradeSkillMaster's LibExtraTip in our case, but
+any addon that re-fires the tooltip triggers it).
+
+## Error
+
+```
+Interface\FrameXML\GameTooltipMods.lua:109: attempt to index local 'lineText' (a nil value)
+  GameTooltipMods.lua:109: in function `func'
+  GameTooltip.lua:361 ... LibExtraTip ... SetAction
+  ActionButton.lua:514 ActionButton_SetTooltip
+  MultiCastActionBarFrame.lua:462 MultiCastActionButton_OnEnter
+spellName = "Standard of Recovery", spellID = 500260, line index i = 4
+```
+
+## Cause
+
+`ModTooltipSetSpell:EmbedSpell` (and the custom-class totem block lower in the
+file) call `left:GetText()` and immediately index the result with no nil guard:
+
+```lua
+function ModTooltipSetSpell:EmbedSpell(left, right, spellID)
+    local lineText = left:GetText()
+    if lineText:find("%b@@") then          -- line 109: lineText can be nil
+```
+
+`GameTooltipTextLeftN` regions exist but return `nil` from `GetText()` when the
+line is empty (common on multi-line spell tooltips like totem/standard buttons —
+here line 4 is blank). The sibling `ModTooltipSetItem:DoCustomFormatters` in the
+**same file** already guards correctly:
+
+```lua
+function ModTooltipSetItem:DoCustomFormatters(left)
+    if not left:GetFont() or not left:GetText() or not left:GetText():find("%b@@") then return end
+```
+
+`ModTooltipSetSpell:EmbedSpell` just needs the same guard.
+
+## Fix (one line each)
+
+`ModTooltipSetSpell:EmbedSpell` — add at the top of the function:
+
+```lua
+function ModTooltipSetSpell:EmbedSpell(left, right, spellID)
+    local lineText = left:GetText()
+    if not lineText then return end        -- <-- add
+    if lineText:find("%b@@") then
+        ...
+```
+
+And the custom-class totem block lower down (the second
+`local lineText = left:GetText()` followed by `lineText:startswith(SPELL_TOTEMS)`)
+needs the same `if not lineText then return end` / `if lineText and ...` guard —
+it has the identical latent nil-deref.
+
+No addon-side fix is possible; the crash is in client FrameXML. Reported by
+Sub-Net (Exiles guild) from the coa-* addon-porting work.