================================================================
  KnowledgeDemon v2.4.0 — User Guide & Developer Reference
  Updated: 2026-03-18 for WoW Midnight 12.0.1 (TOC 120001)
================================================================

OVERVIEW
--------
KnowledgeDemon analyzes your active Destruction Warlock talents and
displays spell modifier breakdowns. It tracks crit chance, crit damage,
and flat damage bonuses from talents, spec passives, racials, hero
talents, apex talents, and tier set bonuses.

CHANGELOG v1.6.0
-----------------
  1. CLAUSE-LEVEL AUTO-DETECTION (TalentScanner.lua)
     - Multi-conditional talents like Scald now parse correctly.
     - Previously: entire description scanned as one blob, summing ALL
       percentages and applying them to ALL mentioned spells.
       Scald showed +275% damage to both Fireball and Scorch.
     - Now: description split into sentences, then sub-clauses on " and "
       boundaries. Each clause's percentage is mapped only to the spell(s)
       mentioned in that clause.
       Scald now correctly shows: +25% dmg to Fireball, +250% dmg to Scorch,
       +100% crit to Fireball (always crits below 30% health).

  2. SCROLLBAR REMOVED (UI.lua)
     - Broken manual scrollbar + thumb replaced with mousewheel-only scroll.
     - Subtle bottom fade gradient indicates more content below.
     - No more visual artifacts from scrollbar track/thumb.

  3. SPELL CARD EXPAND PERSISTENCE (UI.lua)
     - Expanded/collapsed state persists across UI rebuilds (talent changes,
       /kd refresh, combat events). Previously, any background refresh
       collapsed all open cards instantly.
     - Uses a persistent _expandedState table keyed by spell name.
     - Cards restore their expanded state when rebuilt.

v1.5.0 CHANGELOG
-----------------
  1. CLAUSE-LEVEL AUTO-DETECTION (TalentScanner.lua)
     Multi-conditional talents like Scald are now parsed at the
     sentence/clause level. Each percentage is associated only with the
     spells mentioned in that specific clause. Example: Scald now
     correctly assigns +25% damage to Fireball and +250% damage to
     Scorch (and +100% crit to Fireball only), instead of lumping
     +275% onto both spells.

  2. SCROLLBAR REMOVED (UI.lua)
     The broken custom scrollbar has been replaced with mousewheel-only
     scrolling plus a subtle bottom fade indicator that shows when more
     content exists below the viewport.

  3. SPELL CARD DROPDOWN PERSISTENCE (UI.lua)
     Expanded spell cards now stay expanded across UI rebuilds triggered
     by talent changes, /kd refresh, or other events. Cards only
     collapse when explicitly clicked closed by the user.

SLASH COMMANDS
--------------
  /kd              Toggle main analysis window
  /kd refresh      Force re-scan talents and spell data
  /kd settings     Open settings panel (toggle features)
  /kd debug        Toggle debug mode + full state dump
  /kd tt           Tooltip system diagnostic
  /kd help         Show command list

FEATURES
--------
  Spell Cards      Expandable cards per tracked spell with modifier sources
  Stat Panel       Live stats: Int, SP, Crit%, Mastery%, Haste%, Vers%
  Damage Estimates Estimated ranges vs Lvl 90 PvP Training Dummy (60%)
  Tooltip Inject   KD data shown on spell tooltips (action bar, spellbook)
  Talent Overlay   Spell impact panel when hovering talent tree nodes
  Settings Panel   Toggle each feature independently

DEBUG MODE (/kd debug)
-----------------------
Prints comprehensive diagnostics including:
  - API availability (all relevant WoW APIs)
  - Spec detection chain and config ID
  - Live player stats with values
  - All active modifiers with source/type/value
  - Computed spell stats for each tracked spell
  - Full tracked spell list with IDs
  - Untracked talents (IDs not in ModifierDB — use to add new entries)

TOOLTIP DIAGNOSTIC (/kd tt)
----------------------------
Quick health check: shows whether TooltipDataProcessor is available,
spell data is loaded, and tooltips are enabled.

MIDNIGHT 12.0.1 COMPATIBILITY NOTES
-------------------------------------
  - Tooltip API: Uses TooltipDataProcessor.AddTooltipPostCall with
    Enum.TooltipDataType.Spell. data.id works for spellIDs.
    Note: Enum.TooltipDataType.Talent and .Trait are nil in 12.0.1.
  - Scroll System: Bare ScrollFrame + SetScrollChild (no UIPanelScrollFrameTemplate)
  - Stat APIs: Multiple fallback paths per stat for removed/changed APIs
  - Talent Config: Delayed retry system for C_ClassTalents.GetActiveConfigID
  - Spell Data: C_Spell.RequestLoadSpellData + retry for damage descriptions
  - Key lesson: securecallfunction in tooltip callbacks silently swallows all
    Lua errors. Code in these callbacks must be error-free with zero pcall.

DAMAGE CALCULATION MODEL
--------------------------
For regular spells:
  Talent mult = (1 + dmgBonus/100) * (1 + critDmgBonus/100 * critFreq)
  
For Chaos Bolt (always crits, crit% → 1:1 bonus damage):
  Talent mult = (1 + (dmgBonus + talentCrit)/100) * (1 + critDmgBonus/100)
  Where talentCrit = total crit from talents minus the 100% baseline

Damage estimates vs PvP dummy apply 60% dampening factor.
Mastery: Chaotic Energies adds a random 0–mastery% bonus (shown as range).

ADDING NEW TALENTS
-------------------
1. Run /kd debug — note "Untracked" talent IDs
2. Add to ModifierDB.lua:
    [SPELLID] = {
        name   = "Talent Name",
        spec   = "DESTRUCTION",
        type   = "damage",        -- "crit" | "critDamage" | "damage"
        value  = 10,
        spells = { "Chaos Bolt" }, -- or "*" for all tracked spells
        source = "talent",
    },

FILE STRUCTURE
--------------
  Core.lua           Events, utilities, stat collection, slash commands
  ModifierDB.lua     Talent/racial/tier modifier database + tracked spells
  TalentScanner.lua  C_Traits walker, hero tree detection, clause-level auto-parser
  Calculator.lua     Modifier aggregation, damage model, estimates
  UI.lua             Main window, clip-scroll, spell cards, stat panel
  Tooltip.lua        Spell/talent tooltip injection via TooltipDataProcessor
  Overlay.lua        Floating talent impact panel
  Settings.lua       Feature toggle checkboxes
  Debug.lua          Diagnostic logging, full state dump, API checker

  CHANGELOG v2.3.0:
  - Calculator: 95 SP/AP coefficients across all 13 classes from SimC DBC
  - Calculator: Mastery formulas for all 39 specs (6 formula types)
  - Calculator: Armor penetration for ~35 physical spells (SimC formula)
  - Calculator: Haste DoT tick count wired to Tooltip + UI spell cards
  - Calculator: Multiplicative damage stacking per SimC model
  - Calculator: SimC crit formula: (2*critDmgMult-1) not (2+critDmgPct)
  - Calculator: Versatility applied to damage estimates
  - Tooltip: Macro tooltip support (resolves macro → spellID)
  - Tooltip: issecretvalue guard prevents crashes on sentinel data
  - Tooltip: Replaced spell resolution (Drain Soul→Shadow Bolt, etc.)
  - Tooltip: DoT haste line, physical armor indicator
  - TalentScanner: Blacklisted talent-spell combos (Harrek pattern)
  - TalentScanner: O(1) matchedSpellIDs set replaces O(n*m) check
  - Core: CRITICAL FIX - attackPower now collected in PlayerStats
  - UI: Spell Info row shows SP/AP coeff, mastery type, physical flag
  - UI: DoT haste row in spell cards
  - ModifierDB: Complete racial DB (26 races, all DBC-verified)
  - SpellEffectDB: 1913 talent entries from SimC SpellDataDump
  - Cleanup: removed dead code, fixed stale version comments
