azeroth-shell 0.0.0-stage → 0.1.1

package/src/cli/rotationText.mjs

@@ -0,0 +1,226 @@
+// Plain-English rendering of rotation rules and conditions for the terminal. Ported from phonecraft's
+// src/ui/rotation/rotationEditorSentence.ts so a rule reads the same sentence here as in the web editor.
+import { CREATURE_TYPE, SHAPESHIFT_FORM } from '../data/schema.ts';
+import { DISPEL_TYPE } from '../domain/spells/dispel.ts';
+import { raidJobFromCode } from '../domain/raid/raidPlan.ts';
+import { COND_METRIC_LABEL } from '../domain/rotation/condMetricPicker.ts';
+import { CLASS_NAMES } from '../domain/core/ids.ts';
+
+export const SUBJECT_LABEL = { self: 'you', target: 'the enemy', pet: 'your pet', ally: 'an ally' };
+const ALLY_ROLE_LABEL = { tank: 'tank', healer: 'healer', damage: 'DPS' };
+const COND_OP_LABEL = { '<': 'less than', '<=': 'at most', '>': 'more than', '>=': 'at least', '==': 'equal to', '!=': 'not equal to' };
+const RAID_JOB_LABEL = { 'main-tank': 'Main tank', 'off-tank': 'Off-tank', healer: 'Healer', dps: 'DPS' };
+const SCHOOL_NAMES = ['Physical', 'Holy', 'Fire', 'Nature', 'Frost', 'Shadow', 'Arcane'];
+const TOTEM_ELEMENTS = ['Fire', 'Earth', 'Water', 'Air'];
+const AOE_MODE_NAMES = { 0: 'auto', 1: 'AoE', 2: 'single-target' };
+
+const titleCase = (k) => k.charAt(0) + k.slice(1).toLowerCase().replace(/_/g, ' ');
+const CREATURE_TYPE_NAME = new Map(Object.entries(CREATURE_TYPE).map(([k, v]) => [v, titleCase(k)]));
+const DISPEL_TYPE_NAME = new Map(Object.entries(DISPEL_TYPE).map(([k, v]) => [v, titleCase(k)]));
+const creatureMaskName = (mask) => {
+  const hit = [...CREATURE_TYPE_NAME].filter(([t]) => (((1 << (t - 1)) & (mask ?? 0)) !== 0));
+  return hit.length ? hit.map(([, n]) => n).join(' or ') : 'that creature type';
+};
+export const FORM_NAMES = {
+  [SHAPESHIFT_FORM.NONE]: 'no form', [SHAPESHIFT_FORM.CAT]: 'Cat Form', [SHAPESHIFT_FORM.TREE]: 'Tree of Life',
+  [SHAPESHIFT_FORM.TRAVEL]: 'Travel Form', [SHAPESHIFT_FORM.AQUA]: 'Aquatic Form', [SHAPESHIFT_FORM.BEAR]: 'Bear Form',
+  [SHAPESHIFT_FORM.DIREBEAR]: 'Dire Bear Form', [SHAPESHIFT_FORM.BATTLESTANCE]: 'Battle Stance',
+  [SHAPESHIFT_FORM.DEFENSIVESTANCE]: 'Defensive Stance', [SHAPESHIFT_FORM.BERSERKERSTANCE]: 'Berserker Stance',
+  [SHAPESHIFT_FORM.SHADOWFORM]: 'Shadowform', [SHAPESHIFT_FORM.STEALTH]: 'Stealth', [SHAPESHIFT_FORM.MOONKIN]: 'Moonkin Form',
+};
+
+const allyFilterIsAny = (f) => !f || (f.classId == null && f.role == null && f.notRole == null && !f.unit);
+function allySubjectPhrase(f, seatName) {
+  if (allyFilterIsAny(f)) return 'the most-hurt ally';
+  if (f.unit) return seatName ? seatName(f.unit) : f.unit;
+  const bits = [];
+  if (f.classId != null) bits.push(CLASS_NAMES[f.classId] ?? `class ${f.classId}`);
+  if (f.role != null) bits.push(ALLY_ROLE_LABEL[f.role]);
+  if (f.notRole != null) bits.push(`non-${ALLY_ROLE_LABEL[f.notRole]}`);
+  return `the most-hurt ${bits.join(' ')} ally`;
+}
+const condHasCompare = (op, value, suffix = '') => `has ${COND_OP_LABEL[op]} ${value}${suffix}`;
+
+/** One condition as a sentence. `names.spell(id)` / `names.item(id)` resolve references. */
+export function condSentence(c, names) {
+  const subj = c.subject === 'ally' ? allySubjectPhrase(c.ally, names.seat) : SUBJECT_LABEL[c.subject];
+  const poss = c.subject === 'self' ? 'your' : c.subject === 'target' ? "the enemy's" : c.subject === 'ally' ? `${subj}'s` : "your pet's";
+  const yes = c.op === '!=' ? c.value === 0 : c.value !== 0;
+  const cmp = COND_OP_LABEL[c.op];
+  const isAre = c.subject === 'self' ? 'are' : 'is';
+  const have = c.subject === 'self' ? 'have' : 'has';
+  const haveNot = c.subject === 'self' ? "don't have" : "doesn't have";
+  const refOr = (fallback) => (c.ref != null && c.ref > 0 ? c.ref : fallback);
+  switch (c.metric) {
+    case 'healthPct': return `${poss} health ${condHasCompare(c.op, c.value, '%')}`;
+    case 'powerPct': return `${poss} mana/power ${condHasCompare(c.op, c.value, '%')}`;
+    case 'manaPct': return `${poss} mana ${condHasCompare(c.op, c.value, '%')}`;
+    case 'buffRemainingMs':
+    case 'debuffRemainingMs':
+      return `${names.spell(c.ref)} on ${subj} ${cmp} ${(c.value / 1000).toFixed(c.value % 1000 ? 1 : 0)}s left`;
+    case 'canAfford': return yes ? `you can pay for ${names.spell(c.ref)}` : `you can't pay for ${names.spell(c.ref)}`;
+    case 'level': return `${poss} level ${condHasCompare(c.op, c.value)}`;
+    case 'alive': return `${subj} ${isAre} ${yes ? 'alive' : 'dead'}`;
+    case 'buffPresent':
+    case 'debuffPresent': return yes ? `${subj} ${have} ${names.spell(c.ref)}` : `${subj} ${haveNot} ${names.spell(c.ref)}`;
+    case 'buffStacks':
+    case 'debuffStacks': return `${names.spell(c.ref)} stacks on ${subj} ${cmp} ${c.value}`;
+    case 'castingPresent': return `${subj} ${isAre} ${yes ? '' : 'not '}casting`;
+    case 'castingSchool': return `the cast is ${SCHOOL_NAMES[c.value] ?? '?'} school`;
+    case 'castingIsHeal': return yes ? 'the cast is a heal' : 'the cast is not a heal';
+    case 'castingSpellId': return yes ? 'casting that ability' : 'not casting that ability';
+    case 'dodgedRecently': return yes ? `${subj} dodged recently` : `${subj} ${c.subject === 'self' ? "haven't" : "hasn't"} dodged recently`;
+    case 'defenseReactRecently': return yes ? `${subj} had a defense react (dodge/parry/block)` : `${subj} ${have} no defense react`;
+    case 'hunterParryRecently': return yes ? `${subj} parried recently` : `${subj} ${c.subject === 'self' ? "haven't" : "hasn't"} parried recently`;
+    case 'inMelee': return `${subj} ${isAre} ${yes ? 'in melee' : 'at range'}`;
+    case 'charmed': return `${subj} ${isAre} ${yes ? 'charmed / possessed' : 'not charmed'}`;
+    case 'itemCount': return `${names.item(c.ref)} in bags ${cmp} ${c.value}`;
+    case 'itemEquipped': return `${names.item(c.ref)} ${yes ? '' : 'not '}equipped`;
+    case 'petHappiness': return `pet happiness ${condHasCompare(c.op, c.value, '%')}`;
+    case 'combatTimeMs': return `fight time ${cmp} ${c.value} ms`;
+    case 'timeToDieMs': return c.op === '<' || c.op === '<=' ? `${subj} dies within ${c.value} ms at this fight's rate` : `${subj} lives past ${c.value} ms at this fight's rate`;
+    case 'inCombat': return `${subj} is ${yes ? 'in' : 'out of'} combat`;
+    case 'comboPoints': return `combo points ${cmp} ${c.value}`;
+    case 'enemyCount': return `living enemies ${cmp} ${c.value}`;
+    case 'charmedHostileCount': return `charmed hostiles (possessed allies) ${cmp} ${c.value}`;
+    case 'deadAllyCount': return `dead allies ${cmp} ${c.value}`;
+    case 'meleeAllyCount': return `melee allies ${cmp} ${c.value}`;
+    case 'alliesBelowHpCount': return `allies under ${refOr(75)}% health ${cmp} ${c.value}`;
+    case 'nearbyAlliesBelowHpCount': return `hurt allies within ${refOr(30)} yd ${cmp} ${c.value}`;
+    case 'creatureTypeMask': return `${subj} ${isAre} ${yes ? '' : 'not '}${creatureMaskName(c.ref)}`;
+    case 'dispellablePresent': {
+      const who = c.subject === 'target' ? 'the enemy has' : 'an ally has';
+      const kind = DISPEL_TYPE_NAME.get(c.ref ?? -1);
+      if (!kind) return yes ? `${who} a dispellable aura` : `${who} no dispellable aura`;
+      return yes ? `${who} a dispellable ${kind} aura` : `${who} no dispellable ${kind} aura`;
+    }
+    case 'controlled': return `${subj} ${isAre} ${yes ? 'under crowd control' : 'free of crowd control'}`;
+    case 'rooted': return `${subj} ${isAre} ${yes ? '' : 'not '}rooted`;
+    case 'feared': return `${subj} ${isAre} ${yes ? '' : 'not '}feared`;
+    case 'stunned': return `${subj} ${isAre} ${yes ? '' : 'not '}stunned`;
+    case 'snared': return `${subj} ${isAre} ${yes ? '' : 'not '}snared`;
+    case 'hasFlag': return `${subj} ${isAre} ${yes ? '' : 'not '}carrying the flag`;
+    case 'isFlagCarrier': return `${subj} ${isAre} ${yes ? '' : 'not '}the flag carrier`;
+    case 'isHealer': return `${subj} ${isAre} ${yes ? 'a healer' : 'not a healer'}`;
+    case 'isCaster': return `${subj} ${isAre} ${yes ? 'a caster' : 'not a caster'}`;
+    case 'isHunter': return `${subj} ${isAre} ${yes ? 'a hunter' : 'not a hunter'}`;
+    case 'enemyCastingOnAlly': return yes ? 'an enemy is casting at an ally' : 'no enemy is casting at an ally';
+    case 'enemyCastingOnSelf': return yes ? 'an enemy is casting at you' : 'no enemy is casting at you';
+    case 'allyHasFlag': return yes ? 'our team has the flag' : 'our team does not have the flag';
+    case 'enemyHasFlag': return yes ? 'they have our flag' : 'they do not have our flag';
+    case 'enemiesWithinYd': return `enemies within ${refOr(10)} yd ${cmp} ${c.value}`;
+    case 'alliesWithinYd': return `allies within ${refOr(10)} yd ${cmp} ${c.value}`;
+    case 'healersWithinYd': return `our healers within ${refOr(30)} yd ${cmp} ${c.value}`;
+    case 'enemyHealersWithinYd': return `their healers within ${refOr(30)} yd ${cmp} ${c.value}`;
+    case 'objectiveContested': return `the objective is ${yes ? '' : 'not '}contested`;
+    case 'objectiveOwnedByUs': return yes ? 'we own the objective' : 'we do not own the objective';
+    case 'objectiveDistanceYd': return `yards to the objective ${cmp} ${c.value}`;
+    case 'hazardProximityYd': return `yards to nearest ground hazard ${cmp} ${c.value}`;
+    case 'targetDistanceYd': return `yards to the target ${cmp} ${c.value}`;
+    case 'creatureDistanceYd': return `yards to creature ${c.ref ?? 0} ${cmp} ${c.value}`;
+    case 'allyLowestHpPct': return `the most-hurt ally's health ${condHasCompare(c.op, c.value, '%')}`;
+    case 'allyLowestBuffPresent': return yes ? `the most-hurt ally has ${names.spell(c.ref)}` : `the most-hurt ally does not have ${names.spell(c.ref)}`;
+    case 'hasAggro': return yes ? 'an enemy is attacking you' : 'no enemy is attacking you';
+    case 'targetAttackingMe': return yes ? 'your target is attacking you' : 'your target is attacking someone else';
+    case 'aoeMode': {
+      const name = AOE_MODE_NAMES[c.value] ?? `mode ${c.value}`;
+      return c.op === '==' ? `AoE mode is ${name}` : c.op === '!=' ? `AoE mode is not ${name}` : `AoE mode ${cmp} ${name}`;
+    }
+    case 'offHealAllowed': return yes ? 'off-heal is on' : 'off-heal is off';
+    case 'partySeats': return c.op === '<=' && c.value === 1 ? 'you are solo' : `party size ${cmp} ${c.value}`;
+    case 'formId': {
+      const name = FORM_NAMES[c.value] ?? `form ${c.value}`;
+      return c.op === '!=' ? `not in ${name}` : c.op === '==' ? `in ${name}` : `form ${cmp} ${c.value}`;
+    }
+    case 'classId': {
+      const name = CLASS_NAMES[c.value] ?? `class ${c.value}`;
+      return c.op === '==' ? `${subj} ${isAre} a ${name}` : c.op === '!=' ? `${subj} ${isAre} not a ${name}` : `${subj} class ${cmp} ${c.value}`;
+    }
+    case 'isMainTank': return yes ? 'you are the main tank' : 'you are not the main tank';
+    case 'isOffTank': return yes ? 'you are an off-tank' : 'you are not an off-tank';
+    case 'myJob': {
+      const job = raidJobFromCode(c.value);
+      const name = job ? RAID_JOB_LABEL[job] : `job ${c.value}`;
+      return c.op === '!=' ? `your raid job is not ${name}` : c.op === '==' ? `your raid job is ${name}` : `your raid job ${cmp} ${c.value}`;
+    }
+    case 'myCamp': {
+      const name = c.value <= 0 ? 'unassigned' : `camp ${String.fromCharCode(96 + c.value)}`;
+      return c.op === '!=' ? `you are not ${name}` : c.op === '==' ? `you are ${name}` : `your camp ${cmp} ${c.value}`;
+    }
+    case 'assignedHealSubgroup': return c.op === '==' ? `you heal group ${c.value}` : `your heal group ${cmp} ${c.value}`;
+    case 'aggroHolderDebuffPresent': return yes ? `the tank has ${names.spell(c.ref)}` : `the tank does not have ${names.spell(c.ref)}`;
+    case 'aggroHolderDebuffStacks': return `the tank has ${cmp} ${c.value} stacks of ${names.spell(c.ref)}`;
+    case 'allyAuraPresent': return yes ? `anyone has ${names.spell(c.ref)}` : `nobody has ${names.spell(c.ref)}`;
+    case 'allyAuraStacks': return `anyone has ${cmp} ${c.value} stacks of ${names.spell(c.ref)}`;
+    case 'totemPresent': return `${TOTEM_ELEMENTS[c.ref ?? 0] ?? '?'} totem slot is ${yes ? 'occupied' : 'empty'}`;
+    case 'weaponImbuePresent': {
+      const r = c.ref ?? 0;
+      if (r === 2) return yes ? 'all weapon hands have an imbue' : 'a weapon hand has no imbue';
+      return `${r === 1 ? 'off hand' : 'main hand'} ${yes ? 'has an imbue' : 'has no imbue'}`;
+    }
+    default: return `${subj} ${COND_METRIC_LABEL[c.metric] ?? c.metric} ${cmp} ${c.value}`;
+  }
+}
+
+/** The condition list joined as the evaluator reads it: AND within a group, OR between groups. */
+export function conditionsSentence(conds, names) {
+  if (!conds?.length) return 'always';
+  const parts = [];
+  conds.forEach((c, i) => {
+    const s = condSentence(c, names);
+    parts.push(i === 0 ? s : `${c.join === 'or' ? 'OR' : 'and'} ${s}`);
+  });
+  return parts.join(' ');
+}
+
+/** What a rule does, without its conditions: "Cast Rend", "Use Minor Healing Potion", ... */
+export function actionSentence(action, names) {
+  switch (action.kind) {
+    case 'spell': {
+      const target = action.target && typeof action.target === 'object'
+        ? ('creatureEntry' in action.target ? ` on ${names.creature?.(action.target.creatureEntry) ?? `creature ${action.target.creatureEntry}`}` : ` on the ${ALLY_ROLE_LABEL[action.target.role] ?? action.target.role}`)
+        : action.target === 'other' ? ' on another enemy' : '';
+      return `Cast ${names.spell(action.spellId)}${target}`;
+    }
+    case 'item': return `Use ${names.item(action.itemEntry)}${action.family ? ' (best rank in bags)' : ''}${action.target === 'lowest_ally' ? ' on the most-hurt ally' : action.target === 'pet' ? ' on your pet' : ''}`;
+    case 'macro': return `Run macro ${names.macro?.(action.macroId) ?? action.macroId}`;
+    case 'move': {
+      const m = action.move;
+      switch (m.kind) {
+        case 'spread': return `Spread out to ${m.minYd} yd`;
+        case 'flee_raid': return `Run ${m.yd} yd from the raid`;
+        case 'stack_on': return `Stack on the ${m.role ? ALLY_ROLE_LABEL[m.role] : m.unit}`;
+        case 'behind_target': return 'Move behind the target';
+        case 'flank_target': return 'Move to the target\'s flank';
+        case 'move_to': return `Move to (${m.x}, ${m.y})`;
+        case 'avoid_zone': return `Avoid zone ${m.id}`;
+        default: return `Move (${m.kind})`;
+      }
+    }
+    case 'halt_dps': return `Stop ${action.school && action.school !== 'all' ? `${Array.isArray(action.school) ? action.school.join('/') : action.school} ` : ''}damage`;
+    case 'keep_aura': return `Keep ${names.spell(action.spellId)}`;
+    case 'kill_order': return `Kill order: ${action.entries.map((e) => (e < 0 ? `anything but ${names.creature?.(-e) ?? -e}` : names.creature?.(e) ?? e)).join(', ')}`;
+    case 'use_object': return `Use object ${names.object?.(action.goEntry) ?? action.goEntry}`;
+    default: return `${action.kind}`;
+  }
+}
+
+export function ruleSentence(rule, names) {
+  let s = actionSentence(rule.action, names);
+  if (rule.before) s = `${names.spell(rule.before.spellId)}, then ${s.charAt(0).toLowerCase()}${s.slice(1)}`;
+  const after = rule.after ?? rule.action.after;
+  if (after) {
+    const steps = after.steps?.length ? after.steps.map((st) => names.spell(st.spellId)) : after.spellId ? [names.spell(after.spellId)] : [];
+    if (after.stepBackYd) s += `, then step back ${after.stepBackYd} yd`;
+    if (steps.length) s += `, then ${steps.join(', then ')}`;
+  }
+  return s;
+}
+
+export const PHASE_LABEL = {
+  prebuff: 'Pre-buff (button-driven, before a pull)',
+  buffs: 'Buffs (kept up automatically)',
+  pull: 'Pull (the opener)',
+  combat: 'Combat (checked top to bottom every tick)',
+  recovery: 'Recovery (after the fight)',
+};

package/src/cli/squad.mjs

@@ -0,0 +1,105 @@
+// Companions in world fights, shared by the line game and the windowed one. The three squad modes write
+// the autopilot knobs phonecraft's squadModePicker.ts writes; squadJoinsPull is autopilotController.ts:1039;
+// prePull is its prepPartyBuffs pacing (:864) plus the weapon-coat refresh liveFloorRecovery.ts:226 makes.
+import { creatureRank } from '../autopilot/questPolicy.ts';
+import { allyIndexOfSide } from '../engine/core/events.ts';
+
+export const SQUAD_MODES = ['solo', 'elite', 'party'];
+export const SQUAD_MODE_LABEL = {
+  solo: { title: 'Solo', detail: 'You fight alone. Companions wait at the inn and skip your quests.' },
+  elite: { title: 'Solo with elite support', detail: 'Companions join only when the target is an elite.' },
+  party: { title: 'Party', detail: 'Companions fight every pull and do the same quests as you.' },
+};
+// `:squad` words for each mode, the plan's names first.
+export const SQUAD_MODE_WORDS = { solo: 'solo', elite: 'elite', elites: 'elite', party: 'party' };
+
+export function applySquadMode(cfg, mode) {
+  if (mode === 'solo') return { ...cfg, questEliteMode: 'solo', questSquadAlways: false, questSquadShare: false };
+  if (mode === 'party') return { ...cfg, questEliteMode: 'squad', questSquadAlways: true, questSquadShare: true };
+  return { ...cfg, questEliteMode: 'squad', questSquadAlways: false };
+}
+
+/** The mode the saved knobs spell, or null when they match none of the three. */
+export function squadModeOf(cfg) {
+  if (cfg.questSquadAlways) return cfg.questEliteMode === 'squad' ? 'party' : null;
+  if (cfg.questEliteMode === 'squad') return 'elite';
+  if (cfg.questEliteMode === 'solo') return 'solo';
+  return null;
+}
+
+export function setSquadMode(g, mode) { g.setAutopilotConfig(applySquadMode(g.autopilotConfig(), mode)); }
+
+/** Do the companions come on this pull? Elites (rank > 0) in elite mode, everything in party mode. */
+export function squadJoinsPull(g, ds, creatureEntry) {
+  if ((g.state.squad ?? []).length === 0) return false;
+  const cfg = g.autopilotConfig();
+  if (cfg.questSquadAlways) return true;
+  if (cfg.questEliteMode !== 'squad') return false;
+  return creatureRank(ds, creatureEntry) > 0;
+}
+
+const PARTY_BUFF_LEAD_MS = 20_000;
+const PARTY_BUFF_MIN_GAP_MS = 60_000;
+
+/** Before a squad pull: party buffs (paced by the shortest aura, since they drink elixirs) and fresh weapon
+ *  coats. Returns the lines worth printing. `pace` is a per-game `{ nextAt }` the caller keeps. */
+export function prePull(g, ds, pace, now = Date.now()) {
+  const out = [];
+  if ((g.state.squad ?? []).length === 0) return out;
+  if (now >= (pace.nextAt ?? 0)) {
+    const prep = g.applyPrePullBuffs();
+    let shortest = Infinity;
+    for (const b of prep.buffs) if (b.durationMs > 0 && b.durationMs < shortest) shortest = b.durationMs;
+    pace.nextAt = now + Math.max(PARTY_BUFF_MIN_GAP_MS, (Number.isFinite(shortest) ? shortest : PARTY_BUFF_MIN_GAP_MS) - PARTY_BUFF_LEAD_MS);
+    if (prep.buffs.length) out.push(`Buffed up: ${[...new Set(prep.buffs.map((b) => b.name))].join(', ')}`);
+    for (const h of prep.handouts) out.push(`${h.from} hands you ${h.count}x ${ds.item(h.item)?.name ?? `item ${h.item}`}`);
+  }
+  const coats = g.refreshPartyWeaponCoats();
+  if (coats > 0) out.push(`Weapon coatings renewed (${coats}).`);
+  return out;
+}
+
+/** beginFight / fight opts for this creature, after the pre-pull when the squad comes. */
+export function pullOpts(g, ds, pace, creatureEntry, say) {
+  if (!squadJoinsPull(g, ds, creatureEntry)) return undefined;
+  for (const line of prePull(g, ds, pace)) say(line);
+  return { withSquad: true };
+}
+
+/** Combat log names for a session: companions and their pets by name, pack members by theirs. */
+export function sessionLogNames(session, base) {
+  const nameOf = (list, side) => list.find((v) => v.side === side)?.name;
+  return {
+    ...base,
+    petName: session.petView()?.name ?? base.petName,
+    allyName: (side) => nameOf(session.alliesView(), side),
+    enemyNameOf: (side) => nameOf(session.enemiesView(), side),
+  };
+}
+
+/** The same names from the squad alone, for a fight that only left events (game.fight): ally_N is squad[N],
+ *  and companion pets sit after the humans (squadBattleParty().allyPetIndex, runFullDungeon.ts:358). */
+export function squadLogNames(g, creatureEntry, base) {
+  const squad = g.state.squad ?? [];
+  const petOwner = new Map();
+  if (squad.length) {
+    (g.squadBattleParty(creatureEntry).allyPetIndex ?? []).forEach((p, human) => { if (p != null) petOwner.set(p, human); });
+  }
+  return {
+    ...base,
+    petName: g.state.char.pet?.name ?? base.petName,
+    allyName: (side) => {
+      const i = allyIndexOfSide(side);
+      if (i < 0) return undefined;
+      if (i < squad.length) return squad[i].name;
+      const owner = squad[petOwner.get(i)];
+      return owner ? (owner.pet?.name ?? `${owner.name}'s pet`) : undefined;
+    },
+  };
+}
+
+// phonecraft companionHint.ts: the one-shot prompt when the run refuses an elite quest for an empty party.
+export const COMPANION_HINT_LINES = [
+  'Auto Quest leaves elite quests alone while your party is empty. Elites are what companions are for.',
+  'Hire them at an inn in a settlement, up to four, for a 5-man. A Naked one is free, and it still fights and gains levels off your kills.',
+];

package/src/cli/term.mjs

@@ -0,0 +1,144 @@
+// Terminal layer for the TUI. `RealTerm` owns the alternate screen, raw-mode keys and resize; `HeadlessTerm`
+// has a fixed size, takes scripted keys and keeps the last frame, so the UI can be driven from a check script.
+//
+// Keys are decoded here rather than by readline's keypress parser: that parser cannot tell a lone Esc from
+// the start of an escape sequence, so it holds Esc for half a second and, if another key lands first, folds
+// both into an Alt chord. Terminals deliver a whole sequence in one read, so a chunk that is exactly ESC is
+// the Esc key and is reported at once.
+import { stdin, stdout } from 'node:process';
+import { fit } from './text.mjs';
+
+const ESC = '\x1b[';
+const MIN_COLS = 60, MIN_ROWS = 20;
+
+const CSI_FINAL = { A: 'up', B: 'down', C: 'right', D: 'left', H: 'home', F: 'end', Z: 'shift-tab', P: 'f1', Q: 'f2', R: 'f3', S: 'f4' };
+const CSI_TILDE = { 1: 'home', 2: 'insert', 3: 'delete', 4: 'end', 5: 'pageup', 6: 'pagedown', 7: 'home', 8: 'end', 11: 'f1', 12: 'f2', 13: 'f3', 14: 'f4', 15: 'f5', 17: 'f6', 18: 'f7', 19: 'f8', 20: 'f9', 21: 'f10', 23: 'f11', 24: 'f12' };
+
+/** Decode one chunk of raw terminal input into key names: 'up', 'return', 'escape', 'ctrl-c', 'shift-tab', 'a', 'A', ':' ... */
+export function decodeKeys(chunk) {
+  const s = String(chunk);
+  const keys = [];
+  let i = 0;
+  while (i < s.length) {
+    const c = s[i];
+    if (c === '\x1b') {
+      const rest = s.slice(i + 1);
+      // CSI: ESC [ params final
+      let m = rest.match(/^\[([0-9;]*)([A-Za-z~])/);
+      if (m) {
+        i += 1 + m[0].length;
+        const [, params, final] = m;
+        if (final === '~') keys.push(CSI_TILDE[params.split(';')[0]] ?? 'unknown');
+        else {
+          const name = CSI_FINAL[final] ?? 'unknown';
+          const mod = Number(params.split(';')[1] ?? 1);
+          keys.push(mod === 2 ? `shift-${name}` : mod === 5 ? `ctrl-${name}` : mod === 3 ? `alt-${name}` : name);
+        }
+        continue;
+      }
+      // SS3: ESC O final (application cursor keys, F1-F4)
+      m = rest.match(/^O([A-Za-z])/);
+      if (m) { i += 1 + m[0].length; keys.push(CSI_FINAL[m[1]] ?? 'unknown'); continue; }
+      // ESC + printable = Alt chord; a lone ESC (or ESC ESC) is the Esc key.
+      if (rest.length && rest[0] !== '\x1b' && rest[0] >= ' ') { keys.push(`alt-${rest[0]}`); i += 2; continue; }
+      keys.push('escape'); i += 1;
+      continue;
+    }
+    i += 1;
+    if (c === '\r' || c === '\n') { if (c === '\n' && s[i - 2] === '\r') continue; keys.push('return'); continue; }
+    if (c === '\t') { keys.push('tab'); continue; }
+    if (c === '\x7f' || c === '\b') { keys.push('backspace'); continue; }
+    if (c === ' ') { keys.push('space'); continue; }
+    const code = c.charCodeAt(0);
+    if (code < 32) { keys.push(`ctrl-${String.fromCharCode(code + 96)}`); continue; }
+    // Surrogate pairs stay one key.
+    if (code >= 0xd800 && code <= 0xdbff && i < s.length) { keys.push(c + s[i]); i += 1; continue; }
+    keys.push(c);
+  }
+  return keys;
+}
+
+export class RealTerm {
+  constructor() {
+    this.onKey = () => {};
+    this.onResize = () => {};
+    this.isTTY = stdout.isTTY === true && stdin.isTTY === true;
+    this.last = [];
+  }
+  /** Layout size: never below the minimum the screens are laid out for (see `tooSmall`). */
+  get cols() { return Math.max(MIN_COLS, stdout.columns || 100); }
+  get rows() { return Math.max(MIN_ROWS, stdout.rows || 32); }
+  get tooSmall() { return (stdout.columns || 100) < MIN_COLS || (stdout.rows || 32) < MIN_ROWS; }
+  open() {
+    if (stdin.isTTY) stdin.setRawMode(true);
+    stdin.setEncoding('utf8');
+    stdin.resume();
+    // Autowrap off: a line a terminal measures wider than we do (an ambiguous-width glyph) is clipped
+    // instead of wrapping and scrolling the whole frame out of step with `last`.
+    stdout.write(`${ESC}?1049h${ESC}?25l${ESC}?7l${ESC}H${ESC}2J`);
+    // Ctrl-L forgets what is on screen and repaints everything, to recover from a terminal that moved it.
+    this._data = (chunk) => { for (const k of decodeKeys(chunk)) { if (k === 'ctrl-l') this.refresh(); else this.onKey(k); } };
+    this._resize = () => this.refresh();
+    stdin.on('data', this._data);
+    stdout.on('resize', this._resize);
+  }
+  close() {
+    stdin.off('data', this._data);
+    stdout.off('resize', this._resize);
+    stdout.write(`${ESC}0m${ESC}?7h${ESC}?25h${ESC}?1049l`);
+    if (stdin.isTTY) stdin.setRawMode(false);
+    stdin.pause();
+  }
+  refresh() { this.last = []; this.onResize(); }
+  /** Paint a whole frame. Lines are fitted to the width; unchanged lines are skipped, unless most of the frame
+   *  changed (a new screen), which repaints it all so a stale row cannot outlive a screen change. The last
+   *  column stays blank so a terminal without deferred wrap never scrolls when the bottom row is painted. */
+  draw(lines) {
+    if (this.tooSmall) { this.drawTooSmall(); return; }
+    const w = this.cols - 1, h = this.rows;
+    const next = [];
+    for (let i = 0; i < h; i++) next.push(fit(lines[i] ?? '', w));
+    const changed = next.filter((line, i) => this.last[i] !== line).length;
+    const full = !this.last.length || changed * 2 > h;
+    // Every row is padded to the width, so only a frame with nothing known on screen needs a clear first.
+    let out = this.last.length ? '' : `${ESC}0m${ESC}H${ESC}2J`;
+    next.forEach((line, i) => { if (full || this.last[i] !== line) out += `${ESC}${i + 1};1H${ESC}0m${line}`; });
+    this.last = next;
+    if (out) stdout.write(out);
+  }
+  /** The screens need MIN_COLS x MIN_ROWS; a smaller terminal gets a notice instead of a frame drawn off its edge. */
+  drawTooSmall() {
+    const c = stdout.columns || 100, r = stdout.rows || 32;
+    const msg = [`Terminal is ${c}x${r}.`, `azsh needs at least ${MIN_COLS}x${MIN_ROWS}.`, 'Make the window larger.'];
+    const top = Math.max(0, Math.floor((r - msg.length) / 2));
+    let out = `${ESC}0m${ESC}H${ESC}2J`;
+    msg.forEach((m, i) => { if (top + i < r) out += `${ESC}${top + i + 1};${Math.max(1, Math.floor((c - m.length) / 2) + 1)}H${m.slice(0, c)}`; });
+    this.last = [];
+    stdout.write(out);
+  }
+  /** Delay helper for real-time loops. */
+  setInterval(fn, ms) { return setInterval(fn, ms); }
+  clearInterval(h) { clearInterval(h); }
+}
+
+export class HeadlessTerm {
+  constructor(cols = 100, rows = 32) {
+    this.cols = cols; this.rows = rows;
+    this.onKey = () => {};
+    this.onResize = () => {};
+    this.frame = [];
+    this.frames = 0;
+    this.isTTY = false;
+  }
+  open() {}
+  close() {}
+  draw(lines) { this.frame = lines.slice(0, this.rows).map((l) => fit(l ?? '', this.cols)); this.frames++; }
+  /** Feed keys one at a time, as `decodeKeys` would produce them. */
+  press(...keys) { for (const k of keys) this.onKey(k); }
+  /** Type a string as individual character keys, then Enter. */
+  type(text) { for (const ch of text) this.onKey(ch === ' ' ? 'space' : ch); this.onKey('return'); }
+  text() { return this.frame.map((l) => l.replace(/\x1b\[[0-9;]*m/g, '').replace(/\s+$/, '')).join('\n'); }
+  // Headless loops do not run on timers: the check script steps them by hand through app hooks.
+  setInterval() { return null; }
+  clearInterval() {}
+}

package/src/cli/text.mjs

@@ -0,0 +1,122 @@
+// Text helpers shared by the line REPL and the windowed TUI: quest text codes, wrapping, fuzzy
+// picking, ANSI colour and visible-width maths. Nothing here touches game state.
+import { className, raceName } from '../domain/core/ids.ts';
+
+export const useColor = !process.env.NO_COLOR;
+// A reset inside the painted text (a coloured item name in a green sentence) re-opens this paint,
+// so the rest of the sentence keeps its colour.
+const sgr = (code) => (s) => (useColor ? `\x1b[${code}m${String(s).replace(/\x1b\[0m/g, `\x1b[0m\x1b[${code}m`)}\x1b[0m` : String(s));
+export const dim = sgr(2), bold = sgr(1), inverse = sgr(7), underline = sgr(4);
+export const red = sgr(31), green = sgr(32), yellow = sgr(33), blue = sgr(34), magenta = sgr(35), cyan = sgr(36), white = sgr(37), gray = sgr(90);
+export const brightRed = sgr(91), brightGreen = sgr(92), brightYellow = sgr(93), brightBlue = sgr(94), brightMagenta = sgr(95), brightCyan = sgr(96);
+export const bgBlue = sgr(44), bgGray = sgr(100), bgRed = sgr(41);
+/** 256-colour orange: the recipe difficulty that always grants a skill point. */
+export const orange = sgr('38;5;208');
+
+export const QUALITY = ['poor', 'common', 'uncommon', 'rare', 'epic', 'legendary', 'artifact'];
+// The client's item quality colours (24-bit): grey poor, white common, green uncommon, blue rare,
+// purple epic, orange legendary, light gold artifact.
+const rgb = (r, g, b) => sgr(`38;2;${r};${g};${b}`);
+const QUALITY_PAINT = [rgb(157, 157, 157), rgb(255, 255, 255), rgb(30, 255, 0), rgb(0, 112, 221), rgb(163, 53, 238), rgb(255, 128, 0), rgb(230, 204, 128)];
+/** An item name in its 1.12 quality colour. */
+export function qualityPaint(quality) { return QUALITY_PAINT[quality ?? 1] ?? white; }
+/** An item record's name in its quality colour; `fallback` when the record is missing. */
+export function itemText(it, fallback = 'item') { return qualityPaint(it?.quality)(it?.name ?? fallback); }
+
+const GENDER_TOKEN = /\$[Gg]\s*([^:]*):([^;]*);/g;
+/** $N name, $C class, $R race, $B break, $G male:female; (SharedDefines.h:26). Same codes as phonecraft questText. */
+export function questText(raw, ch) {
+  return String(raw ?? '')
+    .replace(GENDER_TOKEN, (_m, male, female) => (ch.gender === 1 ? female : male))
+    .replace(/\$[Bb]/g, '\n')
+    .replace(/\$[Nn]/g, () => ch.name)
+    .replace(/\$[Cc]/g, () => className(ch.cls))
+    .replace(/\$[Rr]/g, () => raceName(ch.race));
+}
+
+/** Wrap plain text to `width` visible columns; returns lines (no indent). Blank lines are kept. */
+export function wrapLines(text, width) {
+  const out = [];
+  for (const para of String(text ?? '').split('\n')) {
+    let line = '';
+    for (const w of para.split(/\s+/).filter(Boolean)) {
+      if (line && vis(line) + 1 + vis(w) > width) { out.push(line); line = w; }
+      else line = line ? `${line} ${w}` : w;
+    }
+    out.push(line);
+  }
+  // A paint still open at a break is closed there and re-opened on the next line, so a wrapped dim
+  // sentence neither bleeds into the screen row below nor loses its colour after the break.
+  if (!useColor) return out;
+  let open = '';
+  return out.map((l) => {
+    const line = open + l;
+    for (const m of l.match(SGR_RE) ?? []) open = m === '\x1b[0m' || m === '\x1b[m' ? '' : open + m;
+    return open ? `${line}\x1b[0m` : line;
+  });
+}
+
+/** Match `q` against a list: a number is an id, otherwise exact name, then prefix, then substring. */
+export function pick(list, q, nameOf, idOf) {
+  const query = String(q ?? '').trim().toLowerCase();
+  if (!query) return { many: list };
+  if (/^\d+$/.test(query)) {
+    const hit = list.find((x) => idOf(x) === Number(query));
+    return hit ? { one: hit } : { none: true };
+  }
+  const named = list.filter((x) => nameOf(x));
+  const exact = named.filter((x) => nameOf(x).toLowerCase() === query);
+  if (exact.length === 1) return { one: exact[0] };
+  const prefix = named.filter((x) => nameOf(x).toLowerCase().startsWith(query));
+  if (prefix.length === 1) return { one: prefix[0] };
+  const sub = named.filter((x) => nameOf(x).toLowerCase().includes(query));
+  if (sub.length === 1) return { one: sub[0] };
+  if (sub.length === 0) return { none: true };
+  return { many: sub };
+}
+
+const SGR_RE = /\x1b\[[0-9;]*m/g;
+/** Visible column count (SGR sequences stripped). Wide glyphs are not used in this UI. */
+export function vis(s) { return String(s).replace(SGR_RE, '').length; }
+export function strip(s) { return String(s).replace(SGR_RE, ''); }
+
+/** Cut `s` to at most `w` visible columns, keeping colour codes, and reset at the end. */
+export function cut(s, w) {
+  s = String(s);
+  if (vis(s) <= w) return s;
+  let out = '', n = 0, i = 0;
+  while (i < s.length && n < w) {
+    if (s[i] === '\x1b') {
+      const m = s.slice(i).match(/^\x1b\[[0-9;]*m/);
+      if (m) { out += m[0]; i += m[0].length; continue; }
+    }
+    out += s[i]; i++; n++;
+  }
+  return out + (useColor ? '\x1b[0m' : '');
+}
+
+/** Exactly `w` visible columns: cut or pad with spaces on the right (or left when `right`). */
+export function fit(s, w, right = false) {
+  s = cut(s, w);
+  const pad = ' '.repeat(Math.max(0, w - vis(s)));
+  return right ? pad + s : s + pad;
+}
+
+/** A horizontal gauge. `paint` colours the filled part. */
+export function bar(cur, max, width, paint = green) {
+  const ratio = max > 0 ? Math.max(0, Math.min(1, cur / max)) : 0;
+  const filled = Math.round(ratio * width);
+  const glyphs = process.env.AZSH_ASCII ? ['#', '-'] : ['█', '░'];
+  return paint(glyphs[0].repeat(filled)) + dim(glyphs[1].repeat(width - filled));
+}
+
+export function pct(cur, max) { return max > 0 ? Math.round((cur / max) * 100) : 0; }
+
+export function plural(n, word) { return `${n} ${word}${n === 1 ? '' : 's'}`; }
+
+export function secondsText(ms) {
+  const s = Math.ceil(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  return m < 60 ? `${m}m ${s % 60}s` : `${Math.floor(m / 60)}h ${m % 60}m`;
+}