feat(editor): add WSPV (Spell Variant) — 113th open format

Novel replacement for the implicit context-conditional
spell substitution rules vanilla WoW encoded across
SpellSpecificType, SpellEffect.EffectMechanic override
fields, and the proc-modified spell tables in
SpellProcEvent. Each entry binds one base spell to a
variant spell that activates when a runtime condition
is met (player in a specific stance, talent talented,
racial buff active, weapon equipped, aura present).

Six conditionKind values cover the full substitution
surface: Stance / Form / Talent / Race / EquippedWeapon
/ AuraActive. The conditionValue field is polymorphic —
its semantics depend on conditionKind (a stance spellId,
a talentId, a race bit, etc.). The spell-cast pipeline
iterates findByBaseSpell at cast time and picks the
highest-priority variant whose condition is satisfied,
falling through to the base spell if none matches.

Three preset emitters demonstrating the pattern:
makeWarriorStance (4 stance-conditional Warrior
variants — Heroic Strike Berserker damage bonus,
Battle baseline, Mocking Blow Defensive AoE taunt,
Pummel Berserker-only gate), makeTalentMod (4 talent-
modified variants — Frostbolt + Brain Freeze instant,
Lava Burst + Flame Shock auto-crit, Earth Shield +
Improved bonus heal, Ferocious Bite + Berserk),
makeRacial (4 race-gated racials — Stoneform Dwarf,
War Stomp Tauren, Berserking Troll, Will of the
Forsaken).

Validator's most novel check is the (baseSpell,
conditionKind, conditionValue, priority) 4-tuple
uniqueness — two variants with all four matching
would tie at runtime and resolve non-deterministically
(the spell-cast pipeline's std::sort by priority is
stable but the underlying iteration order is undefined
when priorities tie). Packs the tuple into 64 bits
(base 32 | value 16 | kind 8 | prio 8) for set lookup.

Format count 112 -> 113. CLI flag count 1213 -> 1218.

src/pipeline/wowee_spell_variants.cpp

@@ -0,0 +1,277 @@
+#include "pipeline/wowee_spell_variants.hpp"
+
+#include <algorithm>
+#include <cstdio>
+#include <cstring>
+#include <fstream>
+
+namespace wowee {
+namespace pipeline {
+
+namespace {
+
+constexpr char kMagic[4] = {'W', 'S', 'P', 'V'};
+constexpr uint32_t kVersion = 1;
+
+template <typename T>
+void writePOD(std::ofstream& os, const T& v) {
+    os.write(reinterpret_cast<const char*>(&v), sizeof(T));
+}
+
+template <typename T>
+bool readPOD(std::ifstream& is, T& v) {
+    is.read(reinterpret_cast<char*>(&v), sizeof(T));
+    return is.gcount() == static_cast<std::streamsize>(sizeof(T));
+}
+
+void writeStr(std::ofstream& os, const std::string& s) {
+    uint32_t n = static_cast<uint32_t>(s.size());
+    writePOD(os, n);
+    if (n > 0) os.write(s.data(), n);
+}
+
+bool readStr(std::ifstream& is, std::string& s) {
+    uint32_t n = 0;
+    if (!readPOD(is, n)) return false;
+    if (n > (1u << 20)) return false;
+    s.resize(n);
+    if (n > 0) {
+        is.read(s.data(), n);
+        if (is.gcount() != static_cast<std::streamsize>(n)) {
+            s.clear();
+            return false;
+        }
+    }
+    return true;
+}
+
+std::string normalizePath(std::string base) {
+    if (base.size() < 5 || base.substr(base.size() - 5) != ".wspv") {
+        base += ".wspv";
+    }
+    return base;
+}
+
+uint32_t packRgba(uint8_t r, uint8_t g, uint8_t b, uint8_t a = 0xFF) {
+    return (static_cast<uint32_t>(a) << 24) |
+           (static_cast<uint32_t>(b) << 16) |
+           (static_cast<uint32_t>(g) << 8)  |
+            static_cast<uint32_t>(r);
+}
+
+} // namespace
+
+const WoweeSpellVariants::Entry*
+WoweeSpellVariants::findById(uint32_t variantId) const {
+    for (const auto& e : entries)
+        if (e.variantId == variantId) return &e;
+    return nullptr;
+}
+
+std::vector<const WoweeSpellVariants::Entry*>
+WoweeSpellVariants::findByBaseSpell(uint32_t baseSpellId) const {
+    std::vector<const Entry*> out;
+    for (const auto& e : entries)
+        if (e.baseSpellId == baseSpellId) out.push_back(&e);
+    std::sort(out.begin(), out.end(),
+              [](const Entry* a, const Entry* b) {
+                  return a->priority > b->priority;
+              });
+    return out;
+}
+
+bool WoweeSpellVariantsLoader::save(const WoweeSpellVariants& cat,
+                                      const std::string& basePath) {
+    std::ofstream os(normalizePath(basePath), std::ios::binary);
+    if (!os) return false;
+    os.write(kMagic, 4);
+    writePOD(os, kVersion);
+    writeStr(os, cat.name);
+    uint32_t entryCount = static_cast<uint32_t>(cat.entries.size());
+    writePOD(os, entryCount);
+    for (const auto& e : cat.entries) {
+        writePOD(os, e.variantId);
+        writeStr(os, e.name);
+        writeStr(os, e.description);
+        writePOD(os, e.baseSpellId);
+        writePOD(os, e.variantSpellId);
+        writePOD(os, e.conditionKind);
+        writePOD(os, e.priority);
+        writePOD(os, e.pad0);
+        writePOD(os, e.pad1);
+        writePOD(os, e.conditionValue);
+        writePOD(os, e.iconColorRGBA);
+    }
+    return os.good();
+}
+
+WoweeSpellVariants WoweeSpellVariantsLoader::load(
+    const std::string& basePath) {
+    WoweeSpellVariants out;
+    std::ifstream is(normalizePath(basePath), std::ios::binary);
+    if (!is) return out;
+    char magic[4];
+    is.read(magic, 4);
+    if (std::memcmp(magic, kMagic, 4) != 0) return out;
+    uint32_t version = 0;
+    if (!readPOD(is, version) || version != kVersion) return out;
+    if (!readStr(is, out.name)) return out;
+    uint32_t entryCount = 0;
+    if (!readPOD(is, entryCount)) return out;
+    if (entryCount > (1u << 20)) return out;
+    out.entries.resize(entryCount);
+    for (auto& e : out.entries) {
+        if (!readPOD(is, e.variantId)) {
+            out.entries.clear(); return out;
+        }
+        if (!readStr(is, e.name) || !readStr(is, e.description)) {
+            out.entries.clear(); return out;
+        }
+        if (!readPOD(is, e.baseSpellId) ||
+            !readPOD(is, e.variantSpellId) ||
+            !readPOD(is, e.conditionKind) ||
+            !readPOD(is, e.priority) ||
+            !readPOD(is, e.pad0) ||
+            !readPOD(is, e.pad1) ||
+            !readPOD(is, e.conditionValue) ||
+            !readPOD(is, e.iconColorRGBA)) {
+            out.entries.clear(); return out;
+        }
+    }
+    return out;
+}
+
+bool WoweeSpellVariantsLoader::exists(const std::string& basePath) {
+    std::ifstream is(normalizePath(basePath), std::ios::binary);
+    return is.good();
+}
+
+WoweeSpellVariants WoweeSpellVariantsLoader::makeWarriorStance(
+    const std::string& catalogName) {
+    using V = WoweeSpellVariants;
+    WoweeSpellVariants c;
+    c.name = catalogName;
+    auto add = [&](uint32_t id, const char* name,
+                    uint32_t baseId, uint32_t variantSpell,
+                    uint32_t stanceId, uint8_t prio,
+                    const char* desc) {
+        V::Entry e;
+        e.variantId = id; e.name = name; e.description = desc;
+        e.baseSpellId = baseId;
+        e.variantSpellId = variantSpell;
+        e.conditionKind = V::Stance;
+        e.priority = prio;
+        e.conditionValue = stanceId;
+        e.iconColorRGBA = packRgba(220, 60, 60);   // warrior red
+        c.entries.push_back(e);
+    };
+    // Stance spell IDs (3.3.5a):
+    // Battle Stance = 2457, Defensive = 71,
+    // Berserker = 2458.
+    add(1, "HeroicStrikeBerserker", 78, 25286, 2458, 2,
+        "Heroic Strike — Berserker Stance variant. "
+        "Replaces base ID 78 with variant ID 25286 "
+        "(higher rage cost, higher damage). Priority 2 "
+        "overrides Battle Stance variant.");
+    add(2, "HeroicStrikeBattle", 78, 78, 2457, 1,
+        "Heroic Strike — Battle Stance baseline (no "
+        "modification). Priority 1 — falls through to "
+        "base when in Battle Stance.");
+    add(3, "MockingBlowDefensive", 694, 25266, 71, 3,
+        "Mocking Blow — Defensive Stance variant adds "
+        "AoE taunt component (3-target splash). "
+        "Priority 3 (active only when in Defensive).");
+    add(4, "PummelBerserker", 6552, 6552, 2458, 1,
+        "Pummel — Berserker Stance only (cannot be cast "
+        "in other stances). Variant equals base ID "
+        "because the spell IS gated to Berserker — "
+        "the stance check provides the gate.");
+    return c;
+}
+
+WoweeSpellVariants WoweeSpellVariantsLoader::makeTalentMod(
+    const std::string& catalogName) {
+    using V = WoweeSpellVariants;
+    WoweeSpellVariants c;
+    c.name = catalogName;
+    auto add = [&](uint32_t id, const char* name,
+                    uint32_t baseId, uint32_t variantSpell,
+                    uint32_t talentId, uint8_t prio,
+                    const char* desc) {
+        V::Entry e;
+        e.variantId = id; e.name = name; e.description = desc;
+        e.baseSpellId = baseId;
+        e.variantSpellId = variantSpell;
+        e.conditionKind = V::Talent;
+        e.priority = prio;
+        e.conditionValue = talentId;
+        e.iconColorRGBA = packRgba(180, 100, 240);   // talent purple
+        c.entries.push_back(e);
+    };
+    add(100, "FrostboltBrainFreeze",   116, 44614, 11160, 5,
+        "Frostbolt becomes instant-cast when Brain "
+        "Freeze proc is active. Talent 11160 = Brain "
+        "Freeze passive. Priority 5 — high priority so "
+        "the proc takes effect immediately.");
+    add(101, "LavaBurstFlameShock", 51505, 51505, 60043, 3,
+        "Lava Burst — auto-crit when Flame Shock DoT is "
+        "active on target. Talent 60043 = Lava Flows "
+        "passive. Same spell ID; the proc replaces the "
+        "rolled outcome with guaranteed crit.");
+    add(102, "EarthShieldImproved", 974, 974, 16544, 2,
+        "Earth Shield — Improved variant adds bonus heal "
+        "per charge consumed. Talent 16544 = Improved "
+        "Earth Shield. Same spell ID; passive talent "
+        "modifies effect magnitude.");
+    add(103, "FerociousBiteBerserk", 22568, 22568, 50334, 4,
+        "Ferocious Bite — modified by Berserk passive "
+        "(50% energy reduction during Berserk). "
+        "Talent 50334 = Berserk. Same spell ID; "
+        "modifier overrides energy cost.");
+    return c;
+}
+
+WoweeSpellVariants WoweeSpellVariantsLoader::makeRacial(
+    const std::string& catalogName) {
+    using V = WoweeSpellVariants;
+    WoweeSpellVariants c;
+    c.name = catalogName;
+    auto add = [&](uint32_t id, const char* name,
+                    uint32_t baseId, uint32_t variantSpell,
+                    uint32_t raceBit, uint8_t prio,
+                    const char* desc) {
+        V::Entry e;
+        e.variantId = id; e.name = name; e.description = desc;
+        e.baseSpellId = baseId;
+        e.variantSpellId = variantSpell;
+        e.conditionKind = V::Race;
+        e.priority = prio;
+        e.conditionValue = raceBit;
+        e.iconColorRGBA = packRgba(220, 200, 80);   // racial gold
+        c.entries.push_back(e);
+    };
+    // Race bits (WCHC):
+    // Human=1, Orc=2, Dwarf=4, NightElf=8,
+    // Undead=16, Tauren=32, Gnome=64, Troll=128,
+    // BloodElf=512, Draenei=1024.
+    add(200, "Stoneform_Dwarf",     20594, 20594,    4, 5,
+        "Stoneform — Dwarf-only racial. Removes "
+        "bleed/poison/disease, +10%% armor for 8s. "
+        "Variant spell ID equals base; the race gate "
+        "does the activation.");
+    add(201, "WarStomp_Tauren",     20549, 20549,   32, 5,
+        "War Stomp — Tauren-only racial. 2-yard AoE "
+        "stun for 2s. Castable in any stance/form.");
+    add(202, "Berserking_Troll",    26297, 26297,  128, 5,
+        "Berserking — Troll-only racial. +10-30%% "
+        "haste for 10s, scaling with current health "
+        "%.");
+    add(203, "WilloftheForsaken",   7744,   7744,   16, 5,
+        "Will of the Forsaken — Undead-only racial. "
+        "Removes fear/sleep/charm effects, 2-min "
+        "cooldown.");
+    return c;
+}
+
+} // namespace pipeline
+} // namespace wowee