azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/bots/squadRun.ts

@@ -0,0 +1,81 @@
+// Track-A squad model — RETIRED from production runs. Kept as a pure formula module for tests and
+// reference; squad pulls are real withSquad sessions now. Pure: no DOM, DataStore or rng.
+
+import { armorMitigation } from '../../engine/combat/mitigation.ts';
+
+export interface SquadMemberContribution {
+  name: string;
+  role: 'tank' | 'healer' | 'dps';
+  /** Damage per second measured from the member's own mini-sim (dps role). */
+  dps?: number;
+}
+
+export interface SquadPullInputs {
+  enemyMaxHp: number;
+  /** Average unmitigated melee DPS of the enemy from its real creature def. */
+  enemyDps: number;
+  enemyLevel: number;
+  /** The player's real sim: duration and total damage they dealt. */
+  playerDurationMs: number;
+  playerDamageDealt: number;
+  tank?: { name: string; maxHealth: number; armor: number };
+  healer?: { name: string; hps: number; healingBudget: number };
+  dpsMembers: Array<{ name: string; dps: number }>;
+}
+
+export interface SquadPullModel {
+  /** Modeled kill time with the whole group's damage on the target. */
+  groupDurationMs: number;
+  /** Who soaked the enemy: the tank when present, else the player's own sim already did. */
+  tankIntake: number;
+  healingUsed: number;
+  healingBudget: number;
+  /** Group-layer wipe: the tank died with the healer dry. */
+  wiped: boolean;
+  wipeReason?: string;
+  /** Damage share per contributor (player + dps companions), summing to ~1. */
+  dpsShare: Array<{ name: string; pct: number }>;
+}
+
+// Model one pull: group kill time is enemy HP over the summed damage rates. With a tank the
+// enemy's DPS lands on them through the real armor curve, and intake past HP plus healing wipes.
+export function modelSquadPull(inp: SquadPullInputs): SquadPullModel {
+  const playerDps = inp.playerDurationMs > 0 ? inp.playerDamageDealt / (inp.playerDurationMs / 1000) : 0;
+  const groupDps = playerDps + inp.dpsMembers.reduce((n, m) => n + Math.max(0, m.dps), 0);
+  const groupDurationMs = groupDps > 0 ? Math.round((inp.enemyMaxHp / groupDps) * 1000) : inp.playerDurationMs;
+
+  const shares: Array<{ name: string; pct: number }> = [];
+  if (groupDps > 0) {
+    shares.push({ name: 'you', pct: playerDps / groupDps });
+    for (const m of inp.dpsMembers) shares.push({ name: m.name, pct: Math.max(0, m.dps) / groupDps });
+  }
+
+  let tankIntake = 0;
+  let healingUsed = 0;
+  let wiped = false;
+  let wipeReason: string | undefined;
+  const healingBudget = inp.healer?.healingBudget ?? 0;
+
+  if (inp.tank) {
+    // Real armor curve: Unit.cpp CalcArmorReducedDamage via engine/mitigation.
+    const mit = armorMitigation(inp.tank.armor, inp.enemyLevel);
+    tankIntake = Math.round(inp.enemyDps * (1 - mit) * (groupDurationMs / 1000));
+    const deficit = tankIntake - inp.tank.maxHealth;
+    if (deficit > 0) {
+      healingUsed = Math.min(deficit, healingBudget);
+      // The healer also has to land it in time: cap by hps × duration.
+      const hpsCap = (inp.healer?.hps ?? 0) * (groupDurationMs / 1000);
+      healingUsed = Math.min(healingUsed, hpsCap);
+      if (deficit > healingUsed) {
+        wiped = true;
+        wipeReason = inp.healer
+          ? healingBudget <= hpsCap
+            ? `${inp.tank.name} died - ${inp.healer.name} ran out of mana`
+            : `${inp.tank.name} died - the damage came in faster than ${inp.healer.name} could heal`
+          : `${inp.tank.name} died with no healer`;
+      }
+    }
+  }
+
+  return { groupDurationMs, tankIntake, healingUsed, healingBudget, wiped, wipeReason, dpsShare: shares };
+}

package/src/domain/character/actionbar.ts

@@ -0,0 +1,346 @@
+// Action bars: what sits in which numbered slot and the key that fires it. A slot holds EITHER a
+// spell or an item, never both. Pure serializable data; bar 0 is always present.
+
+import { isMacroId } from '../macro/types.ts';
+
+export const SLOTS_PER_BAR = 12;
+export const MAX_BARS = 5;
+
+// One action bar. A non-null `items[i]` makes slot i an item slot and outranks `slots[i]`, and
+// `macros[i]` outranks both. Older saves without those arrays load unchanged.
+export interface ActionBar {
+  slots: (number | null)[]; // length SLOTS_PER_BAR; spell id (null = empty / item slot)
+  keys: (string | null)[];  // length SLOTS_PER_BAR; a normalized key, e.g. '1', 'q', 'shift+2'
+  items?: (number | null)[]; // length SLOTS_PER_BAR; item entry (null = not an item slot)
+  macros?: (string | null)[]; // length SLOTS_PER_BAR; macro id (null = not a macro slot)
+  /** Outfit name (Outfitter). Outranks macro/item/spell. */
+  outfits?: (string | null)[];
+}
+
+/** Tagged content of a single slot — what the UI/combat should render and fire. */
+export type SlotContent =
+  | { kind: 'spell'; id: number }
+  | { kind: 'item'; entry: number }
+  | { kind: 'macro'; id: string }
+  | { kind: 'outfit'; name: string }
+  | null;
+
+// Bar 0 is the number row. Extra bars ship UNBOUND: Shift/Ctrl/Alt + digit are the browser's own
+// tab-switch keys, so claiming them by default takes them from a player who never asked.
+const NUMBER_ROW = ['1', '2', '3', '4', '5', '6', '7', '8', '9', '0', '-', '='];
+
+export function defaultKeys(barIndex: number): (string | null)[] {
+  return barIndex === 0 ? [...NUMBER_ROW] : Array(SLOTS_PER_BAR).fill(null);
+}
+
+/** Empty item row (all slots spell-capable). */
+export function emptyItems(): (number | null)[] {
+  return Array(SLOTS_PER_BAR).fill(null);
+}
+
+/** Empty macro row (no slot is a macro slot). */
+export function emptyMacros(): (string | null)[] {
+  return Array(SLOTS_PER_BAR).fill(null);
+}
+
+/** Empty outfit row. */
+export function emptyOutfits(): (string | null)[] {
+  return Array(SLOTS_PER_BAR).fill(null);
+}
+
+function outfitNameAt(v: unknown): string | null {
+  return typeof v === 'string' && v.trim() ? v.trim() : null;
+}
+
+export function emptyBar(barIndex = 0): ActionBar {
+  return {
+    slots: Array(SLOTS_PER_BAR).fill(null),
+    keys: defaultKeys(barIndex),
+    items: emptyItems(),
+    macros: emptyMacros(),
+    outfits: emptyOutfits(),
+  };
+}
+
+export function defaultActionBars(): ActionBar[] {
+  return [emptyBar(0)];
+}
+
+const cloneBars = (bars: ActionBar[]): ActionBar[] => bars.map((b) => ({
+  slots: [...b.slots],
+  keys: [...b.keys],
+  // Always materialize items/macros/outfits so mutators can write into them without a guard.
+  items: Array.from({ length: SLOTS_PER_BAR }, (_, i) => (typeof b.items?.[i] === 'number' ? b.items![i]! : null)),
+  macros: Array.from({ length: SLOTS_PER_BAR }, (_, i) => (isMacroId(b.macros?.[i]) ? b.macros![i]! : null)),
+  outfits: Array.from({ length: SLOTS_PER_BAR }, (_, i) => outfitNameAt(b.outfits?.[i])),
+}));
+
+/** Coerce a possibly-legacy/short/oversized bar list into exactly-shaped bars (for load/migrate). */
+export function normalizeBars(bars: ActionBar[] | undefined | null): ActionBar[] {
+  if (!Array.isArray(bars) || !bars.length) return defaultActionBars();
+  return bars.slice(0, MAX_BARS).map((b, idx) => {
+    // Only bar 0 backfills: a null key on an extra bar is a bind the player cleared, not a gap.
+    const dk = idx === 0 ? defaultKeys(0) : null;
+    return {
+      slots: Array.from({ length: SLOTS_PER_BAR }, (_, i) => (typeof b?.slots?.[i] === 'number' ? b.slots[i] : null)),
+      keys: Array.from({ length: SLOTS_PER_BAR }, (_, i) => (b?.keys?.[i] ?? dk?.[i] ?? null)),
+      items: Array.from({ length: SLOTS_PER_BAR }, (_, i) => (typeof b?.items?.[i] === 'number' ? b.items![i]! : null)),
+      // A malformed macro id never survives load: the slot reads empty instead of "?".
+      macros: Array.from({ length: SLOTS_PER_BAR }, (_, i) => (isMacroId(b?.macros?.[i]) ? b.macros![i]! : null)),
+      outfits: Array.from({ length: SLOTS_PER_BAR }, (_, i) => outfitNameAt(b?.outfits?.[i])),
+    };
+  });
+}
+
+/** What sits in bar/slot: outfit, macro, item, spell, or nothing (that precedence). */
+export function slotAt(bar: ActionBar, i: number): SlotContent {
+  if (i < 0 || i >= SLOTS_PER_BAR) return null;
+  const outfitName = outfitNameAt(bar.outfits?.[i]);
+  if (outfitName) return { kind: 'outfit', name: outfitName };
+  const macroId = bar.macros?.[i];
+  if (macroId != null && isMacroId(macroId)) return { kind: 'macro', id: macroId };
+  const entry = bar.items?.[i];
+  if (entry != null) return { kind: 'item', entry };
+  const id = bar.slots[i];
+  if (id != null) return { kind: 'spell', id };
+  return null;
+}
+
+/** Every spellId currently placed on any bar. */
+export function assignedSpellIds(bars: ActionBar[]): Set<number> {
+  const set = new Set<number>();
+  for (const b of bars) for (const s of b.slots) if (s != null) set.add(s);
+  return set;
+}
+
+/** Every item entry currently placed on any bar. */
+export function assignedItemEntries(bars: ActionBar[]): Set<number> {
+  const set = new Set<number>();
+  for (const b of bars) if (b.items) for (const e of b.items) if (e != null) set.add(e);
+  return set;
+}
+
+/** Every macro id currently placed on any bar. */
+export function assignedMacroIds(bars: ActionBar[]): Set<string> {
+  const set = new Set<string>();
+  for (const b of bars) if (b.macros) for (const m of b.macros) if (m != null) set.add(m);
+  return set;
+}
+
+/** Put `spellId` (or null to clear) in bar/slot. De-dupes: the spell is removed from any other
+ *  slot. Placing a spell clears any item that was in the same slot (a slot is spell OR item). */
+export function setSlot(bars: ActionBar[], bar: number, slot: number, spellId: number | null): ActionBar[] {
+  if (bar < 0 || bar >= bars.length || slot < 0 || slot >= SLOTS_PER_BAR) return bars;
+  const next = cloneBars(bars);
+  if (spellId != null) {
+    for (const b of next) for (let i = 0; i < b.slots.length; i++) if (b.slots[i] === spellId) b.slots[i] = null;
+    // A slot holds exactly one kind of content.
+    next[bar].items![slot] = null;
+    next[bar].macros![slot] = null;
+    next[bar].outfits![slot] = null;
+  }
+  next[bar].slots[slot] = spellId;
+  return next;
+}
+
+/** Put item `entry` (or null to clear) in bar/slot. De-dupes across bars. Placing an item clears
+ *  any spell in the same slot. */
+export function setItemSlot(bars: ActionBar[], bar: number, slot: number, entry: number | null): ActionBar[] {
+  if (bar < 0 || bar >= bars.length || slot < 0 || slot >= SLOTS_PER_BAR) return bars;
+  const next = cloneBars(bars);
+  if (entry != null) {
+    for (const b of next) for (let i = 0; i < b.items!.length; i++) if (b.items![i] === entry) b.items![i] = null;
+    next[bar].slots[slot] = null;
+    next[bar].macros![slot] = null;
+    next[bar].outfits![slot] = null;
+  }
+  next[bar].items![slot] = entry;
+  return next;
+}
+
+/** Put macro `id` (or null to clear) in bar/slot. De-dupes across bars, like a spell or an item. */
+export function setMacroSlot(bars: ActionBar[], bar: number, slot: number, id: string | null): ActionBar[] {
+  if (bar < 0 || bar >= bars.length || slot < 0 || slot >= SLOTS_PER_BAR) return bars;
+  if (id != null && !isMacroId(id)) return bars;
+  const next = cloneBars(bars);
+  if (id != null) {
+    for (const b of next) for (let i = 0; i < b.macros!.length; i++) if (b.macros![i] === id) b.macros![i] = null;
+    next[bar].slots[slot] = null;
+    next[bar].items![slot] = null;
+    next[bar].outfits![slot] = null;
+  }
+  next[bar].macros![slot] = id;
+  return next;
+}
+
+/** Drop every slot holding macro `id` (a deleted macro must not leave a live button). */
+export function clearMacroFromBars(bars: ActionBar[], id: string): ActionBar[] {
+  if (!assignedMacroIds(bars).has(id)) return bars;
+  const next = cloneBars(bars);
+  for (const b of next) for (let i = 0; i < b.macros!.length; i++) if (b.macros![i] === id) b.macros![i] = null;
+  return next;
+}
+
+/** Put outfit `name` (or null to clear) in bar/slot. De-dupes by case-insensitive name. */
+export function setOutfitSlot(bars: ActionBar[], bar: number, slot: number, name: string | null): ActionBar[] {
+  if (bar < 0 || bar >= bars.length || slot < 0 || slot >= SLOTS_PER_BAR) return bars;
+  const next = cloneBars(bars);
+  const trimmed = name && name.trim() ? name.trim() : null;
+  if (trimmed) {
+    const low = trimmed.toLowerCase();
+    for (const b of next) {
+      for (let i = 0; i < b.outfits!.length; i++) {
+        if (b.outfits![i]?.toLowerCase() === low) b.outfits![i] = null;
+      }
+    }
+    next[bar].slots[slot] = null;
+    next[bar].items![slot] = null;
+    next[bar].macros![slot] = null;
+  }
+  next[bar].outfits![slot] = trimmed;
+  return next;
+}
+
+/** Clear whatever (outfit, macro, item or spell) is in bar/slot. */
+export function clearSlot(bars: ActionBar[], bar: number, slot: number): ActionBar[] {
+  if (bar < 0 || bar >= bars.length || slot < 0 || slot >= SLOTS_PER_BAR) return bars;
+  const next = cloneBars(bars);
+  next[bar].slots[slot] = null;
+  next[bar].items![slot] = null;
+  next[bar].macros![slot] = null;
+  next[bar].outfits![slot] = null;
+  return next;
+}
+
+/** Bind `key` (null to clear) to bar/slot. Keys are unique across bars: binding here clears it elsewhere. */
+export function setKey(bars: ActionBar[], bar: number, slot: number, key: string | null): ActionBar[] {
+  if (bar < 0 || bar >= bars.length || slot < 0 || slot >= SLOTS_PER_BAR) return bars;
+  const norm = key ? key.trim().toLowerCase() : null;
+  const next = cloneBars(bars);
+  if (norm) for (const b of next) for (let i = 0; i < b.keys.length; i++) if (b.keys[i] === norm) b.keys[i] = null;
+  next[bar].keys[slot] = norm;
+  return next;
+}
+
+/** First empty bar/slot, or null when every slot is filled. */
+export function firstEmptySlot(bars: ActionBar[]): { bar: number; slot: number } | null {
+  for (let bi = 0; bi < bars.length; bi++) {
+    const b = bars[bi]!;
+    for (let i = 0; i < SLOTS_PER_BAR; i++) {
+      if (slotAt(b, i) == null) return { bar: bi, slot: i };
+    }
+  }
+  return null;
+}
+
+export function addBar(bars: ActionBar[]): ActionBar[] {
+  if (bars.length >= MAX_BARS) return bars;
+  return [...cloneBars(bars), emptyBar(bars.length)];
+}
+
+/** Remove the last bar (never the only one). */
+export function removeBar(bars: ActionBar[]): ActionBar[] {
+  if (bars.length <= 1) return bars;
+  return cloneBars(bars.slice(0, -1));
+}
+
+// Place every eligible spell not already on a bar into the first free slots of bars[0..lastBar], in
+// order. Idempotent, so it is safe on every learn or load, and it skips item slots.
+function fillFreeSlots(bars: ActionBar[], eligibleIds: number[], lastBar: number): ActionBar[] {
+  const have = assignedSpellIds(bars);
+  const missing = eligibleIds.filter((id) => !have.has(id));
+  if (!missing.length) return bars;
+  const next = cloneBars(bars);
+  let mi = 0;
+  for (const b of next.slice(0, lastBar + 1)) {
+    for (let i = 0; i < b.slots.length && mi < missing.length; i++) {
+      if (b.slots[i] == null && b.items![i] == null && b.macros![i] == null && b.outfits![i] == null) {
+        b.slots[i] = missing[mi++];
+      }
+    }
+    if (mi >= missing.length) break;
+  }
+  return next;
+}
+
+/** Autofill every bar — a fresh or legacy kit, and companion bars, which nobody hand-edits. */
+export function autofill(bars: ActionBar[], eligibleIds: number[]): ActionBar[] {
+  return fillFreeSlots(bars, eligibleIds, bars.length - 1);
+}
+
+// Autofill bar 0 only: a bar the player added is their own layout, and a learn used to stuff every
+// free slot on it with the rest of the spellbook.
+export function autofillPrimaryBar(bars: ActionBar[], eligibleIds: number[]): ActionBar[] {
+  return fillFreeSlots(bars, eligibleIds, 0);
+}
+
+/** The spellId bound to `key` across all bars (null if unbound, empty, or an item slot). */
+export function spellForKey(bars: ActionBar[], key: string): number | null {
+  const c = slotForKey(bars, key);
+  return c && c.kind === 'spell' ? c.id : null;
+}
+
+/** The slot content (spell OR item) bound to `key` across all bars (null if unbound/empty). */
+export function slotForKey(bars: ActionBar[], key: string): SlotContent {
+  const norm = key.toLowerCase();
+  for (const b of bars) {
+    for (let i = 0; i < b.keys.length; i++) if (b.keys[i] === norm) return slotAt(b, i);
+  }
+  return null;
+}
+
+// Copy keybinds from `keySource` onto `content` by bar and slot index — when driving a companion
+// their slot CONTENT stays theirs but the keys match the player's. Extra bars keep their own.
+export function overlayKeys(content: ActionBar[], keySource: ActionBar[]): ActionBar[] {
+  const macrosOf = (bar: ActionBar): (string | null)[] =>
+    Array.from({ length: SLOTS_PER_BAR }, (_, i) => (isMacroId(bar.macros?.[i]) ? bar.macros![i]! : null));
+  const outfitsOf = (bar: ActionBar): (string | null)[] =>
+    Array.from({ length: SLOTS_PER_BAR }, (_, i) => outfitNameAt(bar.outfits?.[i]));
+  return content.map((bar, bi) => {
+    const src = keySource[bi];
+    if (!src) {
+      return {
+        slots: [...bar.slots],
+        keys: [...bar.keys],
+        items: bar.items ? [...bar.items] : emptyItems(),
+        macros: macrosOf(bar),
+        outfits: outfitsOf(bar),
+      };
+    }
+    return {
+      slots: [...bar.slots],
+      keys: Array.from({ length: SLOTS_PER_BAR }, (_, i) => src.keys[i] ?? null),
+      items: Array.from({ length: SLOTS_PER_BAR }, (_, i) =>
+        typeof bar.items?.[i] === 'number' ? bar.items[i]! : null),
+      macros: macrosOf(bar),
+      outfits: outfitsOf(bar),
+    };
+  });
+}
+
+/** Bar/slot index of the first slot bound to `key` (for shared-keybind targeting). */
+export function barSlotForKey(bars: ActionBar[], key: string): { bar: number; slot: number } | null {
+  const norm = key.toLowerCase();
+  for (let bi = 0; bi < bars.length; bi++) {
+    const b = bars[bi]!;
+    for (let i = 0; i < b.keys.length; i++) if (b.keys[i] === norm) return { bar: bi, slot: i };
+  }
+  return null;
+}
+
+// Replace all occurrences of `oldId` with `newId` on the bars (e.g. rank 1 -> rank 2 of same spell). Keeps
+// the spell in the same slot(s). Does not de-dupe against other copies of newId (rare).
+export function replaceSpell(bars: ActionBar[], oldId: number, newId: number): ActionBar[] {
+  if (oldId === newId) return bars;
+  const next = cloneBars(bars);
+  let changed = false;
+  for (const b of next) {
+    for (let i = 0; i < b.slots.length; i++) {
+      if (b.slots[i] === oldId) {
+        b.slots[i] = newId;
+        changed = true;
+      }
+    }
+  }
+  return changed ? next : bars;
+}

package/src/domain/character/appearance.ts

@@ -0,0 +1,165 @@
+// Character appearance — the five customization slots stored as 0-based indices into each body's
+// legal Choices. Pure, and the deterministic picker is a name hash so a look is stable forever.
+
+import { APPEARANCE_OPTIONS, type BodyAppearance } from '../../data/appearanceOptions.ts';
+
+// The five appearance slots in canonical order, each a 0-based index into that slot's legal
+// Choices. A race may rename a slot, but the index meaning is fixed by position.
+export interface Appearance {
+  skin: number;
+  face: number;
+  hairStyle: number;
+  hairColor: number;
+  facialHair: number;
+}
+
+/** Appearance slots in canonical (option) order — index i maps to options[i]. */
+export const APPEARANCE_SLOTS = ['skin', 'face', 'hairStyle', 'hairColor', 'facialHair'] as const;
+export type AppearanceSlot = (typeof APPEARANCE_SLOTS)[number];
+
+/** All-zero appearance: Choices[0] of every slot (the viewer's own default customization). */
+export const DEFAULT_APPEARANCE: Appearance = { skin: 0, face: 0, hairStyle: 0, hairColor: 0, facialHair: 0 };
+
+// race id -> slug, matching ui/core/icons.ts RACE_SLUG and render-paperdoll.mjs (kept local so the
+// pure layer never imports the UI). Race 5 is 'undead' (not 'scourge').
+const RACE_SLUG: Record<number, string> = {
+  1: 'human', 2: 'orc', 3: 'dwarf', 4: 'nightelf', 5: 'undead', 6: 'tauren', 7: 'gnome', 8: 'troll',
+};
+
+/** Body slug ("human-male") for a race/gender, or null for an unknown race. */
+export function bodySlug(race: number, gender: 0 | 1 | undefined): string | null {
+  const r = RACE_SLUG[race];
+  return r ? `${r}-${gender === 1 ? 'female' : 'male'}` : null;
+}
+
+/** The BodyAppearance (five option metas) for a race/gender, or undefined if unmapped. */
+export function bodyOptions(race: number, gender: 0 | 1 | undefined): BodyAppearance | undefined {
+  const slug = bodySlug(race, gender);
+  return slug ? APPEARANCE_OPTIONS[slug] : undefined;
+}
+
+/** Legal Choice count for one slot of a body (0 when the body/slot is unknown). */
+export function slotCount(race: number, gender: 0 | 1 | undefined, slot: number): number {
+  return bodyOptions(race, gender)?.options[slot]?.count ?? 0;
+}
+
+// FNV-1a 32-bit — a tiny stable string hash (no crypto, deterministic across platforms).
+function hashString(s: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+// Deterministic-by-name appearance: hash(name|slug|slot) % count per slot, constrained to legal
+// Choices and stable forever. An unmapped race returns DEFAULT_APPEARANCE, never a bad index.
+export function deterministicAppearance(name: string, race: number, gender: 0 | 1 | undefined): Appearance {
+  const body = bodyOptions(race, gender);
+  if (!body) return { ...DEFAULT_APPEARANCE };
+  const slug = bodySlug(race, gender);
+  const pick = (slot: number): number => {
+    const count = body.options[slot]?.count ?? 0;
+    if (count <= 1) return 0;
+    const h = hashString(`${name}|${slug}|${slot}`);
+    // hairStyle index 0 is None (bald/hornless) — a deliberate PLAYER opt-in, never auto-derived,
+    // so bots and defaults get a real style. facialHair index 0 stays a normal derived outcome.
+    if (slot === 2 && body.options[2]?.none && count > 1) return 1 + (h % (count - 1));
+    return h % count;
+  };
+  return { skin: pick(0), face: pick(1), hairStyle: pick(2), hairColor: pick(3), facialHair: pick(4) };
+}
+
+const clampIndex = (v: unknown, count: number): number => {
+  if (typeof v !== 'number' || !Number.isFinite(v) || count <= 0) return 0;
+  const i = Math.floor(v);
+  if (i < 0) return 0;
+  return i >= count ? count - 1 : i;
+};
+
+// Clamp every slot into its body's legal range, and push a stored index off a None the client never
+// offered — an old save must not leave a tauren hornless.
+export function clampAppearance(a: Appearance, race: number, gender: 0 | 1 | undefined): Appearance {
+  const body = bodyOptions(race, gender);
+  if (!body) return { ...DEFAULT_APPEARANCE };
+  const at = (slot: number, v: unknown): number => {
+    const i = clampIndex(v, body.options[slot].count);
+    const floor = body.options[slot].noneSelectable === false ? 1 : 0;
+    return i < floor && body.options[slot].count > floor ? floor : i;
+  };
+  return {
+    skin: at(0, a.skin),
+    face: at(1, a.face),
+    hairStyle: at(2, a.hairStyle),
+    hairColor: at(3, a.hairColor),
+    facialHair: at(4, a.facialHair),
+  };
+}
+
+// Resolve a stored or absent appearance for load and migration: a valid object is clamped, and
+// anything missing falls back to the deterministic look so no character is a clone.
+export function normalizeAppearance(
+  raw: unknown,
+  name: string,
+  race: number,
+  gender: 0 | 1 | undefined,
+): Appearance {
+  if (raw && typeof raw === 'object') {
+    const r = raw as Partial<Record<AppearanceSlot, unknown>>;
+    const hasAny = APPEARANCE_SLOTS.some((k) => typeof r[k] === 'number');
+    if (hasAny) {
+      return clampAppearance(
+        {
+          skin: Number(r.skin) || 0,
+          face: Number(r.face) || 0,
+          hairStyle: Number(r.hairStyle) || 0,
+          hairColor: Number(r.hairColor) || 0,
+          facialHair: Number(r.facialHair) || 0,
+        },
+        race,
+        gender,
+      );
+    }
+  }
+  return deterministicAppearance(name, race, gender);
+}
+
+// Cycle one slot by `dir`, wrapping within the body's legal Choices — the creation screen's picker
+// arrows. Pure, and unchanged when the body is unmapped or the slot has fewer than two choices.
+export function cycleAppearance(
+  a: Appearance,
+  race: number,
+  gender: 0 | 1 | undefined,
+  slot: number,
+  dir: 1 | -1,
+): Appearance {
+  const count = slotCount(race, gender, slot);
+  if (count <= 1 || slot < 0 || slot >= APPEARANCE_SLOTS.length) return a;
+  const key = APPEARANCE_SLOTS[slot];
+  const floor = lowestSelectable(race, gender, slot);
+  if (count - floor <= 1) return a;
+  const cur = Math.max(clampIndex(a[key], count), floor);
+  const span = count - floor;
+  const next = floor + (((cur - floor + dir) % span) + span) % span;
+  return { ...a, [key]: next };
+}
+
+// First index a PLAYER may pick: 1 where index 0 is a None the client never offered, else 0. The
+// index space keeps the None either way, because the bake's base IS that None.
+export function lowestSelectable(race: number, gender: 0 | 1 | undefined, slot: number): number {
+  return bodyOptions(race, gender)?.options[slot]?.noneSelectable === false ? 1 : 0;
+}
+
+// True when the hairStyle slot is REAL hair a helm should hide — its option name mentions "Hair".
+// Tauren horns and any non-hair scalp return false, so a helm never removes them.
+export function hairStyleHiddenByHelm(race: number, gender: 0 | 1 | undefined): boolean {
+  const name = bodyOptions(race, gender)?.options[2]?.name ?? '';
+  return /hair/i.test(name);
+}
+
+// True when the hairStyle slot has a synthetic None at index 0, which every mapped body now does.
+// The picker labels it "None" and it pushes no overlay, so the bald base shows through.
+export function hairStyleHasNone(race: number, gender: 0 | 1 | undefined): boolean {
+  return bodyOptions(race, gender)?.options[2]?.none === true;
+}