azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/character/spellbook.ts

@@ -0,0 +1,169 @@
+import type { SpellDef } from '../../data/schema.ts';
+
+export interface SpellBook {
+  known: number[];
+}
+
+/** Minimal lookup used when resolving LEARN_SPELL stubs → castable taught abilities. */
+export type SpellLookup = { spell(id: number): SpellDef | undefined };
+
+export function emptySpellBook(): SpellBook {
+  return { known: [] };
+}
+
+export function knows(sb: SpellBook, id: number): boolean {
+  return sb.known.includes(id);
+}
+
+// True when `teaches` points at a triggered payload rather than a LEARN_SPELL target. Following
+// one grants the orphan proc instead of the castable ability (KI-254 Charge Stun and friends).
+export function isTriggerPayloadTeaches(parent: SpellDef, taughtId: number, ds: SpellLookup): boolean {
+  if ((parent.effects ?? []).some((e) => e.kind === 'trigger_spell' && e.spellId === taughtId)) {
+    return true;
+  }
+  const taught = ds.spell(taughtId);
+  if (!taught) return false;
+  const taughtInert =
+    (taught.cost ?? 0) === 0
+    && (taught.gcdMs ?? 0) === 0
+    && (taught.cooldownMs ?? 0) === 0
+    && (taught.castTimeMs ?? 0) === 0
+    && !(taught.costPct && taught.costPct > 0)
+    && !(taught.rageGenerated && taught.rageGenerated > 0);
+  const parentHasEconomy =
+    (parent.cost ?? 0) > 0
+    || (parent.gcdMs ?? 0) > 0
+    || (parent.cooldownMs ?? 0) > 0
+    || (parent.castTimeMs ?? 0) > 0
+    || (parent.costPct != null && parent.costPct > 0)
+    || (parent.rageGenerated != null && parent.rageGenerated > 0);
+  return taughtInert && parentHasEconomy;
+}
+
+// True when `childId` is a trigger_spell or proc companion of `parent`. The bake sometimes stamps
+// `teaches` at those, and that is not a LEARN stub — it must not rewrite the castable parent away.
+function isTriggerCompanionOf(parent: SpellDef, childId: number): boolean {
+  return (parent.effects ?? []).some(
+    (e) =>
+      (e.kind === 'trigger_spell' && e.spellId === childId)
+      || (e.kind === 'proc_trigger_spell' && e.triggerSpellId === childId),
+  );
+}
+
+// Resolve a spell id for learning or casting: LEARN_SPELL (36) and LEARN_PET_SPELL (57) stubs keep
+// the castable on `teaches`. Multi-slot stubs need learnGrantIds; `teaches` is a single stamp.
+export function resolveSpellId(id: number, ds: SpellLookup): number {
+  let cur = id;
+  for (let n = 0; n < 4; n++) {
+    const sp = ds.spell(cur);
+    if (!sp) break;
+    const stamped = sp.teaches ?? 0;
+    const next = stamped > 0 ? stamped : learnTriggerFromRaw(sp);
+    if (next == null || next === cur) break;
+    if (isTriggerPayloadTeaches(sp, next, ds) || isTriggerCompanionOf(sp, next)) break;
+    cur = next;
+  }
+  return cur;
+}
+
+/** SPELL_EFFECT_LEARN_SPELL — SharedDefines / SpellEffectDefines.h. */
+export const SPELL_EFFECT_LEARN_SPELL = 36;
+// SPELL_EFFECT_LEARN_PET_SPELL. Same EffectTriggerSpell hop as LEARN_SPELL — the stub is not the
+// castable rank. Cite: SpellEffects.cpp:3386–3404 EffectLearnPetSpell; pin de8f729.
+export const SPELL_EFFECT_LEARN_PET_SPELL = 57;
+
+/** True when this raw slot is a learn stub (player 36 or pet 57). */
+function isLearnStubEffect(effect: number): boolean {
+  return effect === SPELL_EFFECT_LEARN_SPELL || effect === SPELL_EFFECT_LEARN_PET_SPELL;
+}
+
+// Last LEARN_SPELL / LEARN_PET_SPELL EffectTriggerSpell on the row. The bake stamps `teaches` for
+// effect 36 only, so pet rank stubs need this hop at runtime: Firebolt 7886 → 3110, no re-bake.
+export function learnTriggerFromRaw(sp: SpellDef): number | undefined {
+  let taught = 0;
+  for (const r of sp.rawEffects ?? []) {
+    if (!isLearnStubEffect(Number(r.effect) | 0)) continue;
+    const t = Number(r.triggerSpell) | 0;
+    if (t > 0) taught = t;
+  }
+  return taught > 0 ? taught : undefined;
+}
+
+// Stamp `teaches` from a LEARN_PET_SPELL (57) trigger when the bake left it empty. Effect 36
+// already has it from spell.chain. Cite: SpellEffects.cpp:3386–3404; spell-chain-port.mjs.
+export function withPetLearnTeachesIfEmpty(spell: SpellDef): SpellDef {
+  if ((spell.teaches ?? 0) > 0) return spell;
+  const taught = learnTriggerFromRaw(spell);
+  if (!taught) return spell;
+  return { ...spell, teaches: taught };
+}
+
+// Every castable spell id a LEARN_SPELL / LEARN_PET_SPELL row grants. Multi-slot stubs teach
+// several (Path of Defense 8121 → 71 + 7386 + 355), so read rawEffects 36/57, not `teaches`.
+export function learnGrantIds(id: number, ds: SpellLookup): number[] {
+  const sp = ds.spell(id);
+  if (!sp) return [id];
+  const triggers = (sp.rawEffects ?? [])
+    .filter((r) => isLearnStubEffect(Number(r.effect) | 0) && (Number(r.triggerSpell) | 0) > 0)
+    .map((r) => Number(r.triggerSpell) | 0);
+  if (triggers.length > 0) {
+    const out: number[] = [];
+    for (const t of triggers) {
+      // Nested LEARN stubs on a trigger are rare; one resolve hop. Does not follow
+      // trigger_spell companions (Charge Stun) — those are not effect-36 targets.
+      const g = resolveSpellId(t, ds);
+      if (!out.includes(g)) out.push(g);
+    }
+    return out;
+  }
+  // No raw LEARN slots: single `teaches` hop (fixtures / older rows without rawEffects).
+  return [resolveSpellId(id, ds)];
+}
+
+export function learn(sb: SpellBook, id: number): SpellBook {
+  if (sb.known.includes(id)) return sb;
+  return { known: [...sb.known, id] };
+}
+
+/** Drop a known spell id (profession specialization unlearn, rank migration, etc.). */
+export function forget(sb: SpellBook, id: number): SpellBook {
+  if (!sb.known.includes(id)) return sb;
+  return { known: sb.known.filter((x) => x !== id) };
+}
+
+// Learn `id`, resolving LEARN stubs to every castable taught ability (multi-slot aware). Cite:
+// SpellEffects.cpp:2445–2465; learnGrantIds.
+export function learnResolved(sb: SpellBook, id: number, ds: SpellLookup): SpellBook {
+  let next = sb;
+  for (const g of learnGrantIds(id, ds)) next = learn(next, g);
+  return next;
+}
+
+// Replace any LEARN stub ids in the spellbook with their taught castables, expanding multi-slot
+// stubs. Idempotent. Also returns the stub→taught pairs so callers rewrite bars and rotations.
+export function migrateLearnStubs(
+  sb: SpellBook,
+  ds: SpellLookup,
+): { spellbook: SpellBook; replacements: Array<{ from: number; to: number }> } {
+  const replacements: Array<{ from: number; to: number }> = [];
+  const next: number[] = [];
+  const seen = new Set<number>();
+  for (const id of sb.known) {
+    const grants = learnGrantIds(id, ds);
+    if (grants.length === 1 && grants[0] === id) {
+      if (!seen.has(id)) {
+        seen.add(id);
+        next.push(id);
+      }
+      continue;
+    }
+    for (const g of grants) {
+      if (g !== id) replacements.push({ from: id, to: g });
+      if (seen.has(g)) continue;
+      seen.add(g);
+      next.push(g);
+    }
+  }
+  if (!replacements.length) return { spellbook: sb, replacements };
+  return { spellbook: { known: next }, replacements };
+}

package/src/domain/character/stanceBar.ts

@@ -0,0 +1,354 @@
+// Stance bar and primary action-bar paging for Classic shapeshift and stance forms, off
+// SpellShapeshiftForm.dbc BonusActionBar. Pure serializable helpers — the UI casts the real path.
+
+import type { SpellDef } from '../../data/schema.ts';
+import { CLASS, SHAPESHIFT_FORM } from '../../data/schema.ts';
+import {
+  emptyItems,
+  emptyMacros,
+  emptyOutfits,
+  SLOTS_PER_BAR,
+  type ActionBar,
+} from './actionbar.ts';
+import { isMacroId } from '../macro/types.ts';
+import { formIdFromSpell, isFormSpell } from './forms.ts';
+import { SPELL_ATTR_EX2, hasAttrEx2 } from '../../engine/spells/spellAttributes.ts';
+
+/** Classic BonusActionBar index for the primary (main) action bar. 0 = no swap / default. */
+export type PrimaryBarPageId = 0 | 1 | 2 | 3;
+
+/** Content of one primary-bar page (keys stay on actionBars[0] across pages). */
+export interface PrimaryBarPageLayout {
+  slots: (number | null)[];
+  items: (number | null)[];
+  /** Macro ids per slot. Absent on pre-macro saves — normalizePrimaryPages backfills nulls. */
+  macros?: (string | null)[];
+  outfits?: (string | null)[];
+}
+
+/** Optional map of primary pages keyed by page id string ("0"…"3"). */
+export type PrimaryBarPages = Partial<Record<string, PrimaryBarPageLayout>>;
+
+/** One button on the stance / shapeshift bar. */
+export interface StanceBarSlot {
+  spellId: number;
+  formId: number;
+  name: string;
+  icon?: string;
+  /** Classic SetChecked — true while this form/stance is active. */
+  active: boolean;
+}
+
+// Canonical form-enter spell ids per class in stance-bar order; only KNOWN ids become slots.
+// Ghost Wolf 2645 is a normal action-bar spell (BonusActionBar 0), not a stance strip entry.
+export const CLASS_STANCE_SPELLS: Readonly<Record<number, readonly number[]>> = {
+  [CLASS.WARRIOR]: [2457, 71, 2458], // Battle, Defensive, Berserker
+  // Bear, Aquatic, Cat, Travel, Moonkin, Dire Bear — common Classic strip order
+  [CLASS.DRUID]: [5487, 1066, 768, 783, 24858, 9634],
+  [CLASS.ROGUE]: [1784], // Stealth
+  [CLASS.PRIEST]: [15473], // Shadowform
+  // Shaman: no stance bar. Ghost Wolf is cast from the main action bar like any other spell.
+};
+
+// Primary action-bar page for the active form, from SpellShapeshiftForm.BonusActionBar only.
+// Shadowform, Moonkin, Travel, Aquatic and Ghost Wolf stay on the default main bar.
+export function primaryBarPageForForm(form: number): PrimaryBarPageId {
+  const f = form | 0;
+  switch (f) {
+    case SHAPESHIFT_FORM.CAT:
+    case SHAPESHIFT_FORM.BATTLESTANCE:
+    case SHAPESHIFT_FORM.STEALTH:
+      return 1;
+    case SHAPESHIFT_FORM.DEFENSIVESTANCE:
+      return 2;
+    case SHAPESHIFT_FORM.BEAR:
+    case SHAPESHIFT_FORM.DIREBEAR:
+    case SHAPESHIFT_FORM.BERSERKERSTANCE:
+      return 3;
+    default:
+      // BonusActionBar=0: humanoid, Travel, Aquatic, Ghost Wolf, Shadowform, Moonkin, …
+      return 0;
+  }
+}
+
+/** True when this form replaces the main action bar page (BonusActionBar != 0). */
+export function formPagesPrimaryBar(form: number): boolean {
+  return primaryBarPageForForm(form) !== 0;
+}
+
+function emptyLayout(): PrimaryBarPageLayout {
+  return {
+    slots: Array(SLOTS_PER_BAR).fill(null),
+    items: emptyItems(),
+    macros: emptyMacros(),
+    outfits: emptyOutfits(),
+  };
+}
+
+/** Macro ids of a layout / bar, normalized to exactly SLOTS_PER_BAR entries. */
+function macroRow(src: { macros?: (string | null)[] } | undefined): (string | null)[] {
+  return Array.from({ length: SLOTS_PER_BAR }, (_, i) => (isMacroId(src?.macros?.[i]) ? src!.macros![i]! : null));
+}
+
+function outfitRow(src: { outfits?: (string | null)[] } | undefined): (string | null)[] {
+  return Array.from({ length: SLOTS_PER_BAR }, (_, i) => {
+    const v = src?.outfits?.[i];
+    return typeof v === 'string' && v.trim() ? v.trim() : null;
+  });
+}
+
+function cloneLayout(layout: PrimaryBarPageLayout): PrimaryBarPageLayout {
+  return {
+    slots: Array.from({ length: SLOTS_PER_BAR }, (_, i) =>
+      typeof layout.slots[i] === 'number' ? layout.slots[i]! : null),
+    items: Array.from({ length: SLOTS_PER_BAR }, (_, i) =>
+      typeof layout.items[i] === 'number' ? layout.items[i]! : null),
+    macros: macroRow(layout),
+    outfits: outfitRow(layout),
+  };
+}
+
+/** True when a page layout has no spells and no items. */
+export function primaryPageLayoutEmpty(layout: PrimaryBarPageLayout | undefined | null): boolean {
+  if (!layout) return true;
+  return layout.slots.every((s) => s == null)
+    && layout.items.every((e) => e == null)
+    && (layout.macros ?? []).every((m) => m == null)
+    && (layout.outfits ?? []).every((o) => o == null);
+}
+
+// When the form-selected primary page is empty but page "0" has content, copy page 0 onto it —
+// warriors start in Battle Stance while autofill filled bar 0. Never overwrites a customized page.
+export function seedFormPageFromDefaultIfEmpty(
+  pages: PrimaryBarPages,
+  form: number,
+): PrimaryBarPages {
+  const pageId = primaryBarPageForForm(form | 0);
+  if (pageId === 0) return pages;
+  const key = String(pageId);
+  const def = pages['0'];
+  if (!def || primaryPageLayoutEmpty(def)) return pages;
+  if (!primaryPageLayoutEmpty(pages[key])) return pages;
+  return { ...pages, [key]: cloneLayout(def) };
+}
+
+// Normalize primary page storage. Legacy saves have only actionBars[0] as the default page — seed page "0"
+// from bar 0 when pages are absent/partial. Extra multi-bars are never paged.
+export function normalizePrimaryPages(
+  pages: PrimaryBarPages | undefined | null,
+  bar0: ActionBar | undefined,
+): PrimaryBarPages {
+  const out: PrimaryBarPages = {};
+  if (pages && typeof pages === 'object') {
+    for (const [k, v] of Object.entries(pages)) {
+      if (!v || !Array.isArray(v.slots)) continue;
+      out[k] = {
+        slots: Array.from({ length: SLOTS_PER_BAR }, (_, i) =>
+          typeof v.slots[i] === 'number' ? v.slots[i]! : null),
+        items: Array.from({ length: SLOTS_PER_BAR }, (_, i) =>
+          typeof v.items?.[i] === 'number' ? v.items[i]! : null),
+        macros: macroRow(v),
+        outfits: outfitRow(v),
+      };
+    }
+  }
+  if (!out['0'] && bar0) {
+    out['0'] = {
+      slots: Array.from({ length: SLOTS_PER_BAR }, (_, i) =>
+        typeof bar0.slots[i] === 'number' ? bar0.slots[i]! : null),
+      items: Array.from({ length: SLOTS_PER_BAR }, (_, i) =>
+        typeof bar0.items?.[i] === 'number' ? bar0.items[i]! : null),
+      macros: macroRow(bar0),
+      outfits: outfitRow(bar0),
+    };
+  }
+  if (!out['0']) out['0'] = emptyLayout();
+  return out;
+}
+
+// Layout for a primary page id, defaulting to bar0 content. A form page never written yet
+// inherits the default rather than coming back empty, which dumped every known spell on one row.
+export function primaryPageLayout(
+  bar0: ActionBar,
+  pages: PrimaryBarPages | undefined,
+  pageId: PrimaryBarPageId,
+): PrimaryBarPageLayout {
+  const fromMap = pages?.[String(pageId)];
+  if (fromMap) return cloneLayout(fromMap);
+  const def = pageId !== 0 ? pages?.['0'] : undefined;
+  if (def) return cloneLayout(def);
+  return {
+    slots: Array.from({ length: SLOTS_PER_BAR }, (_, i) =>
+      typeof bar0.slots[i] === 'number' ? bar0.slots[i]! : null),
+    items: Array.from({ length: SLOTS_PER_BAR }, (_, i) =>
+      typeof bar0.items?.[i] === 'number' ? bar0.items[i]! : null),
+    macros: macroRow(bar0),
+    outfits: outfitRow(bar0),
+  };
+}
+
+// Action bars with primary (bar 0) content swapped to the page for `form`. Extra bars (1+) are unchanged.
+// Keys on bar 0 are stable across pages (Classic).
+export function actionBarsForForm(
+  bars: ActionBar[],
+  pages: PrimaryBarPages | undefined,
+  form: number,
+): ActionBar[] {
+  if (!bars.length) return bars;
+  const pageId = primaryBarPageForForm(form);
+  const layout = primaryPageLayout(bars[0]!, pages, pageId);
+  return bars.map((b, i) => {
+    if (i !== 0) return b;
+    return {
+      slots: [...layout.slots],
+      keys: [...b.keys],
+      items: [...layout.items],
+      macros: macroRow(layout),
+      outfits: outfitRow(layout),
+    };
+  });
+}
+
+// Apply a bars mutator against the form-visible layout, then persist primary page content. Bar 0
+// always mirrors page "0" for legacy readers; other pages live only in primaryBarPages.
+export function mutateActionBarsForForm(
+  bars: ActionBar[],
+  pages: PrimaryBarPages | undefined,
+  form: number,
+  mutator: (visible: ActionBar[]) => ActionBar[],
+): { bars: ActionBar[]; primaryBarPages: PrimaryBarPages } {
+  const pageMap = normalizePrimaryPages(pages, bars[0]);
+  const pageId = primaryBarPageForForm(form);
+  const visible = actionBarsForForm(bars, pageMap, form);
+  const next = mutator(visible);
+  if (!next.length) return { bars: next, primaryBarPages: pageMap };
+
+  // Capture current form's primary layout from the mutator result.
+  pageMap[String(pageId)] = {
+    slots: Array.from({ length: SLOTS_PER_BAR }, (_, i) =>
+      typeof next[0]!.slots[i] === 'number' ? next[0]!.slots[i]! : null),
+    items: Array.from({ length: SLOTS_PER_BAR }, (_, i) =>
+      typeof next[0]!.items?.[i] === 'number' ? next[0]!.items![i]! : null),
+    macros: macroRow(next[0]!),
+    outfits: outfitRow(next[0]!),
+  };
+
+  // Default page snapshot on bars[0]; keys from mutator (keybinds are shared).
+  const defaultLayout = pageMap['0'] ?? emptyLayout();
+  const stored: ActionBar[] = next.map((b, i) => {
+    if (i !== 0) return {
+      slots: [...b.slots],
+      keys: [...b.keys],
+      items: Array.from({ length: SLOTS_PER_BAR }, (_, j) =>
+        typeof b.items?.[j] === 'number' ? b.items[j]! : null),
+      macros: macroRow(b),
+      outfits: outfitRow(b),
+    };
+    return {
+      slots: [...defaultLayout.slots],
+      keys: [...b.keys],
+      items: [...defaultLayout.items],
+      macros: macroRow(defaultLayout),
+      outfits: outfitRow(defaultLayout),
+    };
+  });
+  return { bars: stored, primaryBarPages: pageMap };
+}
+
+/** Write a full primary-page layout for `form` (tests / bulk set). Does not touch multi-bars. */
+export function writePrimaryPageContent(
+  bars: ActionBar[],
+  pages: PrimaryBarPages | undefined,
+  form: number,
+  _barIndex: number,
+  _slot: number,
+  next: { slots: (number | null)[]; items: (number | null)[]; macros?: (string | null)[]; outfits?: (string | null)[] },
+): { bars: ActionBar[]; primaryBarPages: PrimaryBarPages } {
+  const pageMap = normalizePrimaryPages(pages, bars[0]);
+  const pageId = primaryBarPageForForm(form);
+  pageMap[String(pageId)] = {
+    slots: Array.from({ length: SLOTS_PER_BAR }, (_, i) =>
+      typeof next.slots[i] === 'number' ? next.slots[i]! : null),
+    items: Array.from({ length: SLOTS_PER_BAR }, (_, i) =>
+      typeof next.items[i] === 'number' ? next.items[i]! : null),
+    macros: macroRow(next),
+    outfits: outfitRow(next),
+  };
+  if (!bars[0]) return { bars, primaryBarPages: pageMap };
+  const defaultLayout = pageMap['0'] ?? emptyLayout();
+  const nextBars = bars.map((b, i) => {
+    if (i !== 0) return b;
+    return {
+      slots: [...defaultLayout.slots],
+      keys: [...b.keys],
+      items: [...defaultLayout.items],
+      macros: macroRow(defaultLayout),
+      outfits: outfitRow(defaultLayout),
+    };
+  });
+  return { bars: nextBars, primaryBarPages: pageMap };
+}
+
+// Dire Bear (9634) supersedes Bear (5487) on the stance strip — one bear slot, since both share
+// page 3. The spellbook still keeps Bear; the bar is the upgrade path.
+const BEAR_FORM_SPELL = 5487;
+const DIRE_BEAR_FORM_SPELL = 9634;
+
+// Stance-bar slots for a character: known form spells only, in class order. Active = form id matches
+// `activeForm` (or warrior default Battle when formless + known).
+export function listStanceSlots(
+  classId: number,
+  knownSpellIds: ReadonlyArray<number>,
+  spellOf: (id: number) => SpellDef | undefined,
+  activeForm: number,
+): StanceBarSlot[] {
+  const candidates = CLASS_STANCE_SPELLS[classId | 0];
+  if (!candidates?.length) return [];
+  const known = new Set(knownSpellIds);
+  const form = activeForm | 0;
+  const slots: StanceBarSlot[] = [];
+  for (const spellId of candidates) {
+    if (!known.has(spellId)) continue;
+    // One bear form at a time: hide Bear once Dire Bear is known.
+    if (spellId === BEAR_FORM_SPELL && known.has(DIRE_BEAR_FORM_SPELL)) continue;
+    const sp = spellOf(spellId);
+    if (!sp) continue;
+    if (hasAttrEx2(sp, SPELL_ATTR_EX2.NO_SHAPESHIFT_UI)) continue;
+    // Prefer real form spells; still accept known canonical ids if bake is thin.
+    if (!isFormSpell(sp) && sp.role !== 'stealth' && sp.role !== 'form' && !hasAttrEx2(sp, SPELL_ATTR_EX2.USE_SHAPESHIFT_BAR)) continue;
+    let formId = formIdFromSpell(sp);
+    if (!formId) {
+      // Canonical fallbacks when effects[] not yet resolved (rawEffects still present via isFormSpell).
+      formId = FORM_ID_BY_SPELL[spellId] ?? 0;
+    }
+    if (!formId) continue;
+    slots.push({
+      spellId,
+      formId,
+      name: sp.name,
+      icon: sp.icon,
+      active: form === formId,
+    });
+  }
+  return slots;
+}
+
+/** Form id for each canonical stance-bar spell (1.12). */
+const FORM_ID_BY_SPELL: Readonly<Record<number, number>> = {
+  2457: SHAPESHIFT_FORM.BATTLESTANCE,
+  71: SHAPESHIFT_FORM.DEFENSIVESTANCE,
+  2458: SHAPESHIFT_FORM.BERSERKERSTANCE,
+  5487: SHAPESHIFT_FORM.BEAR,
+  9634: SHAPESHIFT_FORM.DIREBEAR,
+  768: SHAPESHIFT_FORM.CAT,
+  783: SHAPESHIFT_FORM.TRAVEL,
+  1066: SHAPESHIFT_FORM.AQUA,
+  24858: SHAPESHIFT_FORM.MOONKIN,
+  15473: SHAPESHIFT_FORM.SHADOWFORM,
+  1784: SHAPESHIFT_FORM.STEALTH,
+};
+
+/** Classes that show a stance bar when they know at least one form spell. */
+export function classHasStanceBar(classId: number): boolean {
+  return !!CLASS_STANCE_SPELLS[classId | 0]?.length;
+}

package/src/domain/character/stancePrereq.ts

@@ -0,0 +1,70 @@
+// What a pressed ability wants from the stance bar: the form it must fire in, and the stance spell
+// that gets there. The macro `/cast [stance:3] Pummel ; Berserker Stance` is the same two steps
+// spelled by hand (domain/macro/templates.ts:125-128).
+
+import type { ShapeshiftFormId, SpellDef } from '../../data/schema.ts';
+import { formIdFromSpell, isFormSpell, isStealthShapeshift, shapeshiftCastError } from './forms.ts';
+import { listStanceSlots } from './stanceBar.ts';
+
+/** A press's claim on the stance bar. */
+export interface StanceIntent {
+  /** Form the press must fire in — nothing may shift out of it while the press waits. */
+  holdForm: ShapeshiftFormId;
+  /** Stance spell to cast before the press, or null when already in `holdForm`. */
+  castSpellId: number | null;
+}
+
+/**
+ * The stance a press needs, or null when a stance change cannot affect it. `holdForm` is the
+ * CURRENT form when that already casts and some other stance on the bar would refuse — that is
+ * what stops a rotation stance row popping the player back between the swap and the press.
+ */
+export function stanceIntentForPress(
+  spell: SpellDef,
+  form: ShapeshiftFormId,
+  classId: number,
+  known: ReadonlyArray<number>,
+  spellOf: (id: number) => SpellDef | undefined,
+): StanceIntent | null {
+  // A stance press is its own answer, and Stealth is an opener with a cooldown and a snare — the
+  // player enters it deliberately, never as a side effect of pressing Ambush.
+  if (isFormSpell(spell)) return null;
+  const slots = listStanceSlots(classId, known, spellOf, form)
+    .filter((s) => !isStealthShapeshift(s.formId));
+  if (!slots.length) return null;
+
+  if (shapeshiftCastError(spell, form) === 'ok') {
+    const fragile = slots.some((s) => s.formId !== form && shapeshiftCastError(spell, s.formId) !== 'ok');
+    return fragile ? { holdForm: form, castSpellId: null } : null;
+  }
+  // Class bar order (Battle, Defensive, Berserker): Execute is Battle|Berserker and comes back
+  // Battle, where the rest of an Arms rotation already lives.
+  const fix = slots.find((s) => shapeshiftCastError(spell, s.formId) === 'ok');
+  return fix ? { holdForm: fix.formId, castSpellId: fix.spellId } : null;
+}
+
+/** A live claim on the stance bar: what to hold, and when it lapses. */
+export interface StanceHold {
+  form: ShapeshiftFormId;
+  // Session clock the claim lapses at. Null while a press is still queued for it — that press is
+  // the deadline, and cancelling it is how the player hands the stance back.
+  until: number | null;
+}
+
+// A stance the player pressed by hand, with nothing queued behind it, holds this long. Five GCDs:
+// enough to reach the ability they swapped for, short enough that a stray press is not permanent.
+export const STANCE_HOLD_MS = 8000;
+
+/**
+ * True when a rotation pick shifts out of the stance a press claimed. Without it the warrior packs'
+ * own `Battle Stance when formId != 17` row re-casts on the tick after the swap, every time.
+ */
+export function rotationPickBlockedByHold(
+  spell: SpellDef,
+  hold: StanceHold | null,
+  now: number,
+): boolean {
+  if (!hold) return false;
+  if (hold.until != null && now >= hold.until) return false;
+  return isFormSpell(spell) && formIdFromSpell(spell) !== hold.form;
+}

package/src/domain/character/talentBuilds.ts

@@ -0,0 +1,63 @@
+// Named talent loadouts saved from the wiki calculator and assigned to a player or companion.
+// The stored value is the classic Wowhead talent string; apply re-spends it at the target's level.
+
+export interface TalentBuild {
+  id: string;
+  name: string;
+  cls: number;
+  /** Classic talent string, trees separated by '-'. */
+  link: string;
+}
+
+export const MAX_TALENT_BUILDS = 20;
+const DEFAULT_NAME = 'Build';
+
+/** Deterministic id from the existing set — no RNG, no Date. */
+export function nextTalentBuildId(existing: readonly TalentBuild[]): string {
+  let n = existing.length + 1;
+  const taken = new Set(existing.map((b) => b.id));
+  while (taken.has(`b${n}`)) n++;
+  return `b${n}`;
+}
+
+/** Trim, collapse whitespace, cap length. Never returns ''. */
+export function sanitizeTalentBuildName(raw: unknown, fallback = DEFAULT_NAME): string {
+  const s = typeof raw === 'string' ? raw.replace(/\s+/g, ' ').trim().slice(0, 32) : '';
+  return s || fallback;
+}
+
+/** A name not already taken in this list ("Arms", "Arms 2", …). */
+export function uniqueTalentBuildName(existing: readonly TalentBuild[], want: string): string {
+  const base = sanitizeTalentBuildName(want);
+  const taken = new Set(existing.map((b) => b.name.toLowerCase()));
+  if (!taken.has(base.toLowerCase())) return base;
+  for (let i = 2; i < 100; i++) {
+    const cand = `${base} ${i}`;
+    if (!taken.has(cand.toLowerCase())) return cand;
+  }
+  return base;
+}
+
+/** Drop malformed rows, dedupe ids, cap length. Empty / junk input → []. */
+export function normalizeTalentBuilds(raw: unknown): TalentBuild[] {
+  if (!Array.isArray(raw)) return [];
+  const out: TalentBuild[] = [];
+  const seen = new Set<string>();
+  for (const r of raw) {
+    if (!r || typeof r !== 'object') continue;
+    const row = r as { id?: unknown; name?: unknown; cls?: unknown; link?: unknown };
+    const id = typeof row.id === 'string' ? row.id.trim() : '';
+    const link = typeof row.link === 'string' ? row.link.trim() : '';
+    const cls = typeof row.cls === 'number' && Number.isInteger(row.cls) ? row.cls : 0;
+    if (!id || seen.has(id) || !link || cls < 1) continue;
+    seen.add(id);
+    out.push({
+      id,
+      name: sanitizeTalentBuildName(row.name),
+      cls,
+      link,
+    });
+    if (out.length >= MAX_TALENT_BUILDS) break;
+  }
+  return out;
+}