azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/character/talentImport.ts

@@ -0,0 +1,130 @@
+// Talent strings from outside this game: a Wowhead classic talent-calc URL, a classicdb.ch hash, or
+// the bare digit string. A hash ends a tree by its talent count, so these take the DataStore.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import { CLASS } from '../../data/schema.ts';
+import { className } from '../core/ids.ts';
+
+/** Wowhead classic talent-calc path segment per 1.12 class. */
+export const CLASS_SLUG: Record<number, string> = {
+  [CLASS.WARRIOR]: 'warrior', [CLASS.PALADIN]: 'paladin', [CLASS.HUNTER]: 'hunter',
+  [CLASS.ROGUE]: 'rogue', [CLASS.PRIEST]: 'priest', [CLASS.SHAMAN]: 'shaman',
+  [CLASS.MAGE]: 'mage', [CLASS.WARLOCK]: 'warlock', [CLASS.DRUID]: 'druid',
+};
+
+// classicdb.ch runs the old Wowhead calculator; every constant below is read from
+// templates/wowhead/js/TalentCalc.js?16.7 (fetched 2026-09-04) at the line named.
+const AH = '0zMcmVokRsaqbdrfwihuGINALpTjnyxtgevElBCDFHJKOPQSUWXYZ123456789'; // TalentCalc.js:51
+const SEP = 'Z'; // TalentCalc.js:52 (`L`); index 52, clear of the pair range 0-35
+/** classId → calculator slot, `aw.L` at TalentCalc.js:1139-1149 (6→9 is the DK, not 1.12). */
+const CALC_SLOT: Record<number, number> = {
+  [CLASS.DRUID]: 0, [CLASS.HUNTER]: 1, [CLASS.MAGE]: 2, [CLASS.PALADIN]: 3, [CLASS.PRIEST]: 4,
+  [CLASS.ROGUE]: 5, [CLASS.SHAMAN]: 6, [CLASS.WARLOCK]: 7, [CLASS.WARRIOR]: 8,
+};
+const CLASS_BY_SLOT = new Map<number, number>(
+  Object.entries(CALC_SLOT).map(([cls, slot]) => [slot, Number(cls)]),
+);
+
+export type TalentImport = { link: string; cls?: number } | { error: string };
+
+/** The Wowhead classic calculator link for a build (checked 2026-09-04; classic.wowhead.com 301s here). */
+export function wowheadTalentUrl(cls: number, link: string): string {
+  return `https://www.wowhead.com/classic/talent-calc/${CLASS_SLUG[cls] ?? 'warrior'}/${link}`;
+}
+
+/** The classicdb.ch calculator link for a build. Page href is `?talent#<build>` (TalentCalc.js:1339). */
+export function classicdbTalentUrl(cls: number, link: string, ds: DataStore): string {
+  return `https://classicdb.ch/?talent#${classicdbHashFromLink(cls, link, ds)}`;
+}
+
+function treeSizes(cls: number, ds: DataStore): number[] {
+  return ds.talentTrees(cls).map((t) => t.talents.length);
+}
+
+/** Digit pairs → one char each, `x()` at TalentCalc.js:1076-1088. An odd tail pads with 0. */
+function encodePairs(digits: string): string {
+  let out = '';
+  for (let i = 0; i < digits.length; i += 2) {
+    // Pair index caps at 35 (5*6+5): 5 is the highest maxRank in 1.12, so it never leaves the alphabet.
+    const a = Math.min(5, Number(digits[i]) || 0);
+    const b = Math.min(5, Number(digits[i + 1]) || 0);
+    out += AH.charAt(a * 6 + b);
+  }
+  return out;
+}
+
+// A digit link → the classicdb hash. `getWhBuild` at TalentCalc.js:150-180: rtrim each tree's zeros,
+// pair-encode, separator only when the even-rounded length falls short, class char in front.
+export function classicdbHashFromLink(cls: number, link: string, ds: DataStore): string {
+  const sizes = treeSizes(cls, ds);
+  const parts = link.split('-');
+  let body = '';
+  for (let t = 0; t < sizes.length; t++) {
+    const digits = (parts[t] ?? '').slice(0, sizes[t]).replace(/0+$/, '');
+    body += encodePairs(digits);
+    const written = digits.length + (digits.length % 2);
+    if (written < sizes[t]!) body += SEP;
+  }
+  const slot = CALC_SLOT[cls];
+  const head = slot === undefined ? '' : AH.charAt(slot * 3); // TalentCalc.js:176
+  return head + body.replace(/Z+$/, '');
+}
+
+// The inverse: `aA` at TalentCalc.js:1440-1483 for the body, TalentCalc.js:1776-1785 for the class
+// char. Returns null when the head names no 1.12 class.
+export function linkFromClassicdbHash(hash: string, ds: DataStore): { cls: number; link: string } | null {
+  const raw = hash.trim().replace(/^#/, '').split(':')[0] ?? '';
+  const head = raw ? AH.indexOf(raw.charAt(0)) : -1;
+  if (head < 0 || head > 27) return null;
+  const cls = CLASS_BY_SLOT.get(Math.floor(head / 3));
+  if (cls === undefined) return null;
+  const sizes = treeSizes(cls, ds);
+  if (sizes.length === 0) return null;
+  const trees = sizes.map(() => '');
+  let tree = 0;
+  let at = 0;
+  for (let i = 1; i < raw.length && tree < sizes.length; i++) {
+    const ch = raw.charAt(i);
+    if (ch !== SEP) {
+      const idx = AH.indexOf(ch);
+      if (idx < 0) continue;
+      const second = idx % 6;
+      for (const rank of [(idx - second) / 6, second]) {
+        trees[tree] += String(rank);
+        if (++at >= sizes[tree]!) break;
+      }
+    }
+    if (at >= sizes[tree]! || ch === SEP) { at = 0; tree++; }
+  }
+  const link = trees.map((s) => s.replace(/0+$/, '')).join('-').replace(/-+$/, '');
+  return { cls, link };
+}
+
+const BARE_LINK = /^[0-9]+(?:-[0-9]*)*$/;
+const WOWHEAD_URL = /(?:^|\/\/)(?:www\.|classic\.)?wowhead\.com\/(?:classic\/)?talent-calc\/([a-z-]+)\/?([^/?#\s]*)/i;
+
+// A paste from either calculator, or our own string. A bare digit string carries no class and is
+// taken as-is; a URL or hash naming another class is refused by name, not left to fit nothing.
+export function parseTalentImport(text: string, cls: number, ds: DataStore): TalentImport {
+  const raw = text.trim();
+  if (!raw) return { error: 'Paste a talent string first.' };
+  const url = WOWHEAD_URL.exec(raw);
+  if (url) {
+    const slug = (url[1] ?? '').toLowerCase();
+    const owner = Number(Object.keys(CLASS_SLUG).find((k) => CLASS_SLUG[Number(k)] === slug) ?? 0);
+    if (!owner) return { error: `That Wowhead link is not a 1.12 class ("${slug}").` };
+    if (owner !== cls) return { error: `That is a ${className(owner)} build. You are a ${className(cls)}.` };
+    const link = url[2] ?? '';
+    if (!BARE_LINK.test(link)) return { error: 'That Wowhead link carries no talent string.' };
+    return { link, cls: owner };
+  }
+  const bare = raw.replace(/^#/, '');
+  if (BARE_LINK.test(bare)) return { link: bare.replace(/-+$/, '') };
+  const hashText = raw.includes('#') ? raw.slice(raw.indexOf('#') + 1) : raw;
+  const decoded = linkFromClassicdbHash(hashText, ds);
+  if (!decoded) return { error: 'That is not a talent string, a Wowhead link, or a classicdb hash.' };
+  if (decoded.cls !== cls) {
+    return { error: `That is a ${className(decoded.cls)} build. You are a ${className(cls)}.` };
+  }
+  return { link: decoded.link, cls: decoded.cls };
+}

package/src/domain/character/talentLink.ts

@@ -0,0 +1,123 @@
+// Premade playerbot spec links → real talent maps. Each spec is a classic Wowhead talent string in
+// the order seed-talents bakes; spending toward the stage build mirrors InitTalentsTree. Pure.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { BotSpecDef } from '../../data/schema.ts';
+import type { Character } from './character.ts';
+import { canSpend, pointsForLevel } from './talents.ts';
+
+/** The link stage a bot of `level` works toward: highest stage.level <= level, else the first. */
+export function stageFor(spec: BotSpecDef, level: number): { level: number; link: string } {
+  let best = spec.stages[0]!;
+  for (const st of spec.stages) {
+    if (st.level <= level) best = st;
+  }
+  return best;
+}
+
+// Deterministic prob-weighted spec pick (PremadeSpecProb, conf default 100). Returns the spec index into
+// ds.botSpecs(cls), or undefined when none baked.
+export function pickSpecIndex(specs: readonly BotSpecDef[], seed: number): number | undefined {
+  if (specs.length === 0) return undefined;
+  const total = specs.reduce((s, sp) => s + Math.max(1, sp.prob), 0);
+  let r = Math.abs(seed) % total;
+  for (let i = 0; i < specs.length; i++) {
+    r -= Math.max(1, specs[i]!.prob);
+    if (r < 0) return i;
+  }
+  return specs.length - 1;
+}
+
+/** One build per (ds, spec, cls, level). Nothing in the tree writes into a returned map. */
+const specTalents = new WeakMap<DataStore, WeakMap<BotSpecDef, Map<string, Record<number, number>>>>();
+
+// Materialize a spec link as spent talents for `cls` at `level`, multi-pass so prereqs later in
+// the string still fill. Cached: rebuilding per body was 114 ms of a Molten Core pack-clear.
+export function talentsForSpec(spec: BotSpecDef, cls: number, level: number, ds: DataStore): Record<number, number> {
+  let byDs = specTalents.get(ds);
+  if (!byDs) specTalents.set(ds, (byDs = new WeakMap()));
+  let bySpec = byDs.get(spec);
+  if (!bySpec) byDs.set(spec, (bySpec = new Map()));
+  const key = `${cls}|${level}`;
+  const hit = bySpec.get(key);
+  if (hit) return hit;
+  const built = buildTalentsForSpec(spec, cls, level, ds);
+  bySpec.set(key, built);
+  return built;
+}
+
+function buildTalentsForSpec(spec: BotSpecDef, cls: number, level: number, ds: DataStore): Record<number, number> {
+  return talentsFromLink(stageFor(spec, level).link, cls, level, ds);
+}
+
+/** A tree's talents in link-digit order: TalentTab OrderIndex outer, (tier, col) inner. */
+function talentsInLinkOrder(tree: { talents: readonly { id: number; tier: number; col: number; maxRank: number }[] }):
+  { id: number; maxRank: number }[] {
+  return [...tree.talents]
+    .sort((a, b) => (a.tier - b.tier) || (a.col - b.col))
+    .map((t) => ({ id: t.id, maxRank: t.maxRank }));
+}
+
+// Decode a classic Wowhead talent string into spent talents for `cls` at `level`, under the real
+// rules and multi-pass for late prereqs. Unknown or short trees no-op.
+export function talentsFromLink(link: string, cls: number, level: number, ds: DataStore): Record<number, number> {
+  const trees = ds.talentTrees(cls);
+  const linkTrees = link.split('-');
+  // Desired ranks in link order.
+  const desired: { id: number; rank: number }[] = [];
+  for (let t = 0; t < trees.length; t++) {
+    const digits = linkTrees[t] ?? '';
+    const tals = talentsInLinkOrder(trees[t]!);
+    for (let i = 0; i < tals.length && i < digits.length; i++) {
+      const rank = Number(digits[i]) || 0;
+      if (rank > 0) desired.push({ id: tals[i]!.id, rank: Math.min(rank, tals[i]!.maxRank) });
+    }
+  }
+  if (desired.length === 0) return {};
+  // Scratch character purely for the spend rules, spent in place: only `talents` escapes and every
+  // helper re-reads char. Cloning char and the talents map per POINT was 56 ms of a pack-clear.
+  const talents: Record<number, number> = {};
+  const char: Character = {
+    name: '', race: 0, cls, level: Math.max(1, level), xp: 0, gold: 0, zoneId: '',
+    health: 1, power: 0, equipped: {}, activeBuffs: [], activeAuras: [],
+    skills: {}, knownRecipes: [], talents,
+  };
+  let budget = pointsForLevel(level);
+  let progress = true;
+  while (budget > 0 && progress) {
+    progress = false;
+    for (const d of desired) {
+      while (budget > 0 && ((talents[d.id] ?? 0) < d.rank) && canSpend(char, d.id, ds).ok) {
+        talents[d.id] = (talents[d.id] ?? 0) + 1;
+        budget--;
+        progress = true;
+      }
+    }
+  }
+  return talents;
+}
+
+// The inverse of talentsFromLink: one digit per talent in (tier, col) order, trees joined by '-'.
+// Trailing zeros per tree and empty trailing trees are both trimmed, so the string is byte-equal to
+// the one Wowhead prints for the same build ("303050213520105001-0505300502", botSpecs.json).
+export function talentLinkFromTalents(
+  talents: Record<number, number>, cls: number, ds: DataStore,
+): string {
+  return ds.talentTrees(cls)
+    .map((tree) => talentsInLinkOrder(tree)
+      .map((t) => String(Math.min(9, talents[t.id] ?? 0)))
+      .join('')
+      .replace(/0+$/, ''))
+    .join('-')
+    .replace(/-+$/, '');
+}
+
+/** Per-tree point split of a talent map (candidate vetting UI: "Holy 31 / Ret 20"). */
+export function talentTreeSplit(
+  talents: Record<number, number>, cls: number, ds: DataStore,
+): { name: string; points: number }[] {
+  return ds.talentTrees(cls).map((tree) => ({
+    name: tree.name,
+    points: tree.talents.reduce((s, t) => s + (talents[t.id] ?? 0), 0),
+  }));
+}

package/src/domain/character/talents.ts

@@ -0,0 +1,201 @@
+// Pure talent point math, prerequisites, spend and respec, data-driven from ds.talent* and the
+// flat pointsForLevel formula. No DOM, no RNG. Immutable updates only.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { Character } from './character.ts';
+
+/** Talent.dbc MAX_TALENT_RANK. Cite: DBCStructure.h:946; Player.cpp:19661 Row * MAX_TALENT_RANK. */
+export const TALENT_TIER_POINTS = 5;
+
+/** Classic 1.12 talent points: 0 until level 10, then +1 per level. */
+export function pointsForLevel(level: number): number {
+  return Math.max(0, (level | 0) - 9);
+}
+
+/** Total points the character has spent across all trees. */
+export function spentPoints(char: Character): number {
+  const t = char.talents ?? {};
+  let sum = 0;
+  for (const v of Object.values(t)) sum += (v as number) || 0;
+  return sum;
+}
+
+/** Points spent inside one specific tree (used for tier gates: tier*5). */
+export function spentInTree(char: Character, tabId: number, ds: DataStore): number {
+  return sumTreePoints(char, tabId, ds, () => true);
+}
+
+/** Points in this tree in rows strictly below `tier`. Remaining-spec form of Player.cpp:19661. */
+export function spentBelowTier(char: Character, tabId: number, tier: number, ds: DataStore): number {
+  return sumTreePoints(char, tabId, ds, (t) => t < tier);
+}
+
+function sumTreePoints(
+  char: Character,
+  tabId: number,
+  ds: DataStore,
+  pred: (tier: number) => boolean,
+): number {
+  const trees = ds.talentTrees(char.cls);
+  const tree = trees.find((tr) => tr.tabId === tabId);
+  if (!tree) return 0;
+  const tals = char.talents ?? {};
+  let sum = 0;
+  for (const td of tree.talents) {
+    if (pred(td.tier)) sum += (tals[td.id] as number) || 0;
+  }
+  return sum;
+}
+
+/** How many points remain to spend (total pool minus spent). */
+export function availablePoints(char: Character): number {
+  return Math.max(0, pointsForLevel(char.level) - spentPoints(char));
+}
+
+export interface CanSpendResult {
+  ok: boolean;
+  reason?: string;
+}
+
+// Can this talent receive another point right now? Checks: known talent, room in maxRank, available points,
+// tier gate (points in tree >= tier*5), and prereq talent rank.
+export function canSpend(char: Character, talentId: number, ds: DataStore): CanSpendResult {
+  const tal = ds.talent(talentId);
+  if (!tal) return { ok: false, reason: 'Unknown talent' };
+  // prevent learn talent for different class (cheating). Cite: Player.cpp:19585-19587.
+  if (!ds.talentTrees(char.cls).some((tr) => tr.tabId === tal.tabId)) {
+    return { ok: false, reason: 'Unknown talent' };
+  }
+  const cur = ((char.talents ?? {})[talentId] as number) || 0;
+  if (cur >= tal.maxRank) return { ok: false, reason: 'Already at max rank' };
+  if (availablePoints(char) <= 0) return { ok: false, reason: 'No talent points available' };
+  const inTree = spentInTree(char, tal.tabId, ds);
+  if (inTree < tal.tier * TALENT_TIER_POINTS) {
+    return { ok: false, reason: `Requires ${tal.tier * TALENT_TIER_POINTS} points spent in this tree` };
+  }
+  if (tal.prereq) {
+    const pre = ((char.talents ?? {})[tal.prereq.talentId] as number) || 0;
+    if (pre < tal.prereq.rank) return { ok: false, reason: 'Prerequisite not met' };
+  }
+  return { ok: true };
+}
+
+// Simulate removing one rank; remaining talents must still pass LearnTalent's Row*5 gate against
+// points BELOW that row, plus prereqs. Whole-tree sum lets a hollow spec keep its deep ranks.
+export function canRefund(char: Character, talentId: number, ds: DataStore): CanSpendResult {
+  const cur = ((char.talents ?? {})[talentId] as number) || 0;
+  if (cur <= 0) return { ok: false, reason: 'Talent not spent' };
+
+  const talents: Record<number, number> = { ...(char.talents ?? {}) };
+  if (cur === 1) {
+    delete talents[talentId];
+  } else {
+    talents[talentId] = cur - 1;
+  }
+  const next: Character = { ...char, talents };
+
+  for (const [tidStr, rankRaw] of Object.entries(talents)) {
+    const tid = Number(tidStr) | 0;
+    const rank = (rankRaw as number) || 0;
+    if (rank <= 0) continue;
+    const tal = ds.talent(tid);
+    // Unknown / synthetic talent ids (tests) cannot be validated — skip.
+    if (!tal) continue;
+    if (spentBelowTier(next, tal.tabId, tal.tier, ds) < tal.tier * TALENT_TIER_POINTS) {
+      return { ok: false, reason: 'Would break tier requirements for another talent' };
+    }
+    if (tal.prereq) {
+      const pre = (talents[tal.prereq.talentId] as number) || 0;
+      if (pre < tal.prereq.rank) {
+        return { ok: false, reason: 'Required by another talent' };
+      }
+    }
+  }
+  return { ok: true };
+}
+
+/** Spend one rank in the talent if allowed. Returns a new Character (or the same if not allowed). */
+export function spendTalent(char: Character, talentId: number, ds: DataStore): Character {
+  const check = canSpend(char, talentId, ds);
+  if (!check.ok) return char;
+  const talents: Record<number, number> = { ...(char.talents ?? {}) };
+  talents[talentId] = ((talents[talentId] as number) || 0) + 1;
+  return { ...char, talents };
+}
+
+// Refund one rank from a spent talent if the remaining build stays legal (see canRefund). Returns a new
+// Character, or the same reference when refund is refused / not spent.
+export function refundTalent(char: Character, talentId: number, ds: DataStore): Character {
+  const check = canRefund(char, talentId, ds);
+  if (!check.ok) return char;
+  const tals = char.talents ?? {};
+  const cur = (tals[talentId] as number) || 0;
+  if (cur <= 0) return char;
+  const talents: Record<number, number> = { ...tals };
+  if (cur === 1) {
+    delete talents[talentId];
+  } else {
+    talents[talentId] = cur - 1;
+  }
+  return { ...char, talents };
+}
+
+/** Full respec: clear all spent talent points. Returns a new Character. Gold cost is handled by caller (Game). */
+export function respec(char: Character): Character {
+  const t = char.talents;
+  if (!t || Object.keys(t).length === 0) return char;
+  return { ...char, talents: {} };
+}
+
+// Spell ids currently granted by spent talent ranks via grant_spell / grant_passive, scanning
+// every rank 1..current so multi-rank grants stay tracked after a rank-up.
+export function talentGrantedSpellIds(char: Character, ds: DataStore): Set<number> {
+  const out = new Set<number>();
+  const spent = char.talents ?? {};
+  for (const [tidStr, rnkRaw] of Object.entries(spent)) {
+    const tid = Number(tidStr) | 0;
+    const rnk = (rnkRaw as number) || 0;
+    if (rnk < 1) continue;
+    const tal = ds.talent(tid);
+    if (!tal) continue;
+    const maxR = Math.min(rnk, tal.ranks.length);
+    for (let r = 1; r <= maxR; r++) {
+      const rank = tal.ranks[r - 1];
+      if (!rank) continue;
+      for (const eff of rank.effects ?? []) {
+        if (eff.kind === 'grant_spell' && typeof (eff as { spellId?: number }).spellId === 'number') {
+          out.add((eff as { spellId: number }).spellId);
+        }
+        if (eff.kind === 'grant_passive' && rank.spellId) {
+          out.add(rank.spellId);
+        }
+      }
+    }
+  }
+  return out;
+}
+
+// Every spell id ANY talent of `cls` can grant, so the spent set is always a subset and a
+// "known but not granted" diff cannot accuse a talent the character took. 73 ids in the bake.
+const allTalentGrantsByStore = new WeakMap<object, Map<number, Set<number>>>();
+export function allTalentGrantedSpellIds(cls: number, ds: DataStore): Set<number> {
+  let byCls = allTalentGrantsByStore.get(ds as object);
+  if (!byCls) { byCls = new Map(); allTalentGrantsByStore.set(ds as object, byCls); }
+  const hit = byCls.get(cls);
+  if (hit) return hit;
+  const out = new Set<number>();
+  for (const tree of ds.talentTrees(cls) ?? []) {
+    for (const tal of tree.talents ?? []) {
+      for (const rank of tal.ranks ?? []) {
+        for (const eff of rank.effects ?? []) {
+          if (eff.kind === 'grant_spell' && typeof (eff as { spellId?: number }).spellId === 'number') {
+            out.add((eff as { spellId: number }).spellId);
+          }
+          if (eff.kind === 'grant_passive' && rank.spellId) out.add(rank.spellId);
+        }
+      }
+    }
+  }
+  byCls.set(cls, out);
+  return out;
+}

package/src/domain/core/conditionSnapshot.ts

@@ -0,0 +1,92 @@
+// The PLAYER half of a ConditionSnapshot in ONE place. The evaluator reports `unsupported` when a
+// supplier is absent, so an omitted field silently turns content off. Cite: Conditions.cpp Meets.
+
+import type { Character } from '../character/character.ts';
+import type { DataStore } from '../../data/dataStore.ts';
+import type { SpellBook } from '../character/spellbook.ts';
+import { SKILL_LINE_BY_ID } from '../../data/schema/profession.ts';
+import { activeEventIds, activeHolidayIds } from '../world/gameEvents.ts';
+import { calculateHonorRank } from '../run/honor.ts';
+import { factionOf } from '../character/races.ts';
+import { getRank } from '../creature/reputation.ts';
+import { professionSkillValue } from '../professions/professions.ts';
+
+/** SharedDefines.h Team. Cite: Conditions.cpp:206-214 CONDITION_TEAM. */
+export const TEAM_ALLIANCE = 469;
+export const TEAM_HORDE = 67;
+
+/** Every skill id the trade-line store can answer for, so a caller can enumerate them. */
+export const TRADE_SKILL_IDS: readonly number[] = Object.freeze(
+  Object.keys(SKILL_LINE_BY_ID).map(Number),
+);
+
+// GetSkillValueBase over BOTH stores: combatSkills by id and the trade lines by name. Undefined
+// means !HasSkill, which must stay distinct from a trained 0. Cite: Conditions.cpp:377-385.
+export function playerSkillValue(
+  char: Character,
+  ds?: DataStore | null,
+  sb?: SpellBook | null,
+): (skillId: number) => number | undefined {
+  return (skillId: number): number | undefined => {
+    const combat = (char.combatSkills ?? {})[skillId];
+    if (combat) return combat.current;
+    const line = SKILL_LINE_BY_ID[skillId];
+    if (!line) return undefined;
+    return professionSkillValue(char, line, ds, sb);
+  };
+}
+
+// CONDITION_RACE_CLASS masks. The DB stores 1 << (race - 1), so race or class 0 has no bit and
+// must stay undefined — mask 1 would answer "yes, human" for every unset character.
+export function playerRaceClassMasks(
+  char: Pick<Character, 'race' | 'cls'>,
+): { raceMask?: number; classMask?: number } {
+  const out: { raceMask?: number; classMask?: number } = {};
+  if ((char.race | 0) > 0) out.raceMask = 1 << ((char.race | 0) - 1);
+  if ((char.cls | 0) > 0) out.classMask = 1 << ((char.cls | 0) - 1);
+  return out;
+}
+
+/** Player-derived suppliers. Context (floor bodies, waypoints, instance data) is the caller's. */
+export interface PlayerConditionFacts {
+  level: number;
+  team: number;
+  gender: number;
+  raceMask?: number;
+  classMask?: number;
+  knownSpells: number[];
+  reputationRank: (factionId: number) => number;
+  skillValue: (skillId: number) => number | undefined;
+  activeEvents: number[];
+  activeHolidays: number[];
+  pvpRank: number;
+}
+
+/** Everything the evaluator can learn from the character sheet alone; spread it into a snapshot.
+ *  @param nowMs game-event clock, passed by the caller so this stays pure. */
+export function playerConditionFacts(
+  ds: DataStore,
+  char: Character,
+  spellbook: SpellBook | null | undefined,
+  nowMs: number,
+): PlayerConditionFacts {
+  const events = ds.gameEvents();
+  return {
+    level: char.level,
+    team: factionOf(ds, char.race) === 'horde' ? TEAM_HORDE : TEAM_ALLIANCE,
+    // 0 male / 1 female, the convention Conditions.cpp:373-376 compares against.
+    gender: char.gender ?? 0,
+    ...playerRaceClassMasks(char),
+    knownSpells: [...(spellbook?.known ?? [])],
+    // Rank, not standing: CONDITION_REPUTATION_RANK_* compares ReputationMgr GetRank.
+    reputationRank: (factionId: number): number => {
+      const fac = ds.faction(factionId);
+      if (!fac) return 0;
+      return getRank(char.reputations, fac, char.race, char.cls);
+    },
+    skillValue: playerSkillValue(char, ds, spellbook),
+    activeEvents: [...activeEventIds(events, nowMs)],
+    activeHolidays: [...activeHolidayIds(events, nowMs)],
+    pvpRank: calculateHonorRank(char.honor?.rp ?? 0).rank,
+  };
+}

package/src/domain/core/hover.ts

@@ -0,0 +1,14 @@
+/** SPELL_AURA_HOVER SetHover. Cite: SpellAuras.cpp:1681–1688; Unit.cpp:12428–12438; Object.h:750. */
+
+/** Cite: Object.h:750 MOVEFLAG_HOVER. */
+export const MOVEFLAG_HOVER = 0x40000000;
+
+/** Cite: Unit.cpp:12428–12438 SetHover Add/RemoveMovementFlag. */
+export function setHover(moveFlags: number, enable: boolean): number {
+  return enable ? (moveFlags | MOVEFLAG_HOVER) : (moveFlags & ~MOVEFLAG_HOVER);
+}
+
+/** Cite: Unit.h:1788 IsHovering HasMovementFlag(MOVEFLAG_HOVER). */
+export function isHovering(moveFlags: number): boolean {
+  return (moveFlags & MOVEFLAG_HOVER) !== 0;
+}

package/src/domain/core/ids.ts

@@ -0,0 +1,58 @@
+// Gameplay id helpers and display names. (Numeric race/class ids live in
+// data/schema.ts as the RACE/CLASS constants; the ETL uses the same numbers.)
+
+import { CLASS, RACE } from '../../data/schema.ts';
+import type { PowerType } from '../../data/schema.ts';
+
+/** Rage is a fixed 0..100 pool; mana comes from the stat tables. */
+export const RAGE_MAX = 100;
+
+// Energy pool max (rogue / later feral cat). Sourced from CMaNGOS `Unit.h`
+// PowerDefaults::POWER_ENERGY_DEFAULT = 100 (UI units 1:1, not ×10 like rage).
+export const ENERGY_MAX = 100;
+
+/** Soul Shard item entry from the MaNGOS DB. Warlocks get these when a target dies under Drain
+ * Soul; we map the real DB item instead of synthesizing a counter. */
+export const SOUL_SHARD_ITEM = 6265;
+
+export function classPowerType(cls: number): PowerType {
+  if (cls === CLASS.WARRIOR) return 'rage';
+  if (cls === CLASS.ROGUE) return 'energy';
+  return 'mana';
+}
+
+// Whether a class auto-attacks at range with its equipped ranged weapon instead of the main hand.
+// Hunters are the ranged-primary class; everyone else melees and only fires ranged via Shoot.
+export function classUsesRangedAuto(cls: number): boolean {
+  return cls === CLASS.HUNTER;
+}
+
+export const CLASS_NAMES: Record<number, string> = {
+  [CLASS.WARRIOR]: 'Warrior',
+  [CLASS.PALADIN]: 'Paladin',
+  [CLASS.HUNTER]: 'Hunter',
+  [CLASS.ROGUE]: 'Rogue',
+  [CLASS.PRIEST]: 'Priest',
+  [CLASS.SHAMAN]: 'Shaman',
+  [CLASS.MAGE]: 'Mage',
+  [CLASS.WARLOCK]: 'Warlock',
+  [CLASS.DRUID]: 'Druid',
+};
+
+export const RACE_NAMES: Record<number, string> = {
+  [RACE.HUMAN]: 'Human',
+  [RACE.ORC]: 'Orc',
+  [RACE.DWARF]: 'Dwarf',
+  [RACE.NIGHTELF]: 'Night Elf',
+  [RACE.UNDEAD]: 'Undead',
+  [RACE.TAUREN]: 'Tauren',
+  [RACE.GNOME]: 'Gnome',
+  [RACE.TROLL]: 'Troll',
+};
+
+export function className(cls: number): string {
+  return CLASS_NAMES[cls] ?? `Class ${cls}`;
+}
+export function raceName(race: number): string {
+  return RACE_NAMES[race] ?? `Race ${race}`;
+}

package/src/domain/core/internalNameTags.ts

@@ -0,0 +1,5 @@
+/** `<TXT>` / trailing `<PH>` are locale leftovers on a handful of vanilla names. */
+export function stripInternalNameTags(name: string): string {
+  const cleaned = String(name ?? '').replace(/^<TXT>/, '').replace(/\s*<PH>\s*$/, '').trim();
+  return cleaned || name;
+}