azeroth-shell 0.0.0-stage → 0.1.1

package/src/domain/items/loot.ts

@@ -0,0 +1,221 @@
+// Loot rolling, faithful to CMaNGOS LootTemplate: group 0 rows roll independently, every non-zero
+// group yields at most one, and reference rows expand recursively. Pure, with an injected Rng.
+
+import type { LootEntryDef } from '../../data/schema.ts';
+import type { Rng } from '../../engine/core/rng.ts';
+
+export interface LootDrop {
+  item: number;
+  count: number;
+  /** ItemRandomProperties id when this drop was minted with a suffix. */
+  randomPropertyId?: number;
+}
+
+// A loot row that may point at reference_loot_template. When referenceLootId is set, the row is no
+// item drop: after its chance succeeds the referenced table is processed maxCount times.
+export type LootEntryWithRef = LootEntryDef & {
+  referenceLootId?: number;
+};
+
+/** Safety depth for nested reference expansion (CMaNGOS validates cycles at load). */
+export const DEFAULT_REFERENCE_LOOT_DEPTH = 8;
+
+/** Optional gate for FQ3 quest-required rows + QI2.5 conditionId rows during a production roll. */
+export type LootRollContext = {
+  // True when the player may receive this entry's quest-required drop — any active quest listing
+  // the item as an objective. When omitted, quest-required rows are skipped entirely.
+  allowsQuestDrop?: (entry: LootEntryDef) => boolean;
+  // When entry.conditionId is non-zero the row rolls only if this returns true, as LootMgr consults
+  // conditions per row. When omitted, conditionId-bearing rows are skipped: fail closed.
+  allowsCondition?: (conditionId: number, entry: LootEntryDef) => boolean;
+  // Item-level veto, checked before either gate above and whatever the chance sign is: "this
+  // looter may not have this item at all". Alterac's faction-locked quest items are the case.
+  // When omitted, nothing is vetoed.
+  allowsItem?: (itemId: number) => boolean;
+};
+
+/** CMaNGOS ChanceOrQuestChance: negative chance or explicit flag → quest-gated. */
+export function isQuestRequiredLootEntry(e: LootEntryDef): boolean {
+  return e.questRequired === true || e.chance < 0;
+}
+
+/** Exclusive quest-container row (gated or |chance| ≥ 100). World-chest group loot is not. */
+export function isExclusiveQuestLootRow(e: LootEntryDef): boolean {
+  return isQuestRequiredLootEntry(e) || Math.abs(e.chance) >= 100;
+}
+
+/** Dedicated quest-container row for this item. Cite: buildItemDropperMap questGatedOnly. */
+export function lootRowIsQuestItemSource(e: LootEntryDef, itemId: number): boolean {
+  return e.item === itemId && isExclusiveQuestLootRow(e);
+}
+
+/** Roll weight / percent magnitude (always non-negative). */
+export function lootChanceMagnitude(e: LootEntryDef): number {
+  return Math.abs(e.chance);
+}
+
+/** Whether this entry may participate in the current roll. */
+export function isLootEntryEligible(e: LootEntryDef, ctx?: LootRollContext): boolean {
+  // QI2.5 conditionId gate (independent of signed quest-chance). Fail closed when
+  // conditionId present and no allowsCondition, or when allowsCondition returns false.
+  const cid = (e.conditionId ?? 0) | 0;
+  if (cid !== 0) {
+    if (ctx?.allowsCondition?.(cid, e) !== true) return false;
+  }
+  // A drop the looter may not have AT ALL, whatever its chance sign. Alterac's Storm Crystal is
+  // a plain +80 row in ClassicDB while its Horde twin is a -100 quest row, so the quest gate below
+  // cannot express "the other faction's quest item" — this can. Absent predicate = allow.
+  if (ctx?.allowsItem && ctx.allowsItem(e.item) !== true) return false;
+  if (!isQuestRequiredLootEntry(e)) return true;
+  return ctx?.allowsQuestDrop?.(e) === true;
+}
+
+export function isReferenceLootEntry(e: LootEntryWithRef): boolean {
+  return (e.referenceLootId ?? 0) > 0;
+}
+
+// Lookup for any loot store by id — creature loot, pickpocket, reference. The live bake uses
+// namespaced string keys like pickpocket:<n>; fixtures may use bare numbers.
+export type LootTableLookup = (lootId: number | string) => readonly LootEntryWithRef[] | undefined;
+
+export function rollLoot(
+  entries: readonly LootEntryDef[],
+  rng: Rng,
+  ctx?: LootRollContext,
+): LootDrop[] {
+  return rollLootDeep(entries, () => undefined, rng, 0, DEFAULT_REFERENCE_LOOT_DEPTH, ctx);
+}
+
+// Roll a table with recursive reference expansion. Plain entries behave as `rollLoot`; reference rows that
+// pass their chance process the referenced template `maxCount` times (default 1).
+export function rollLootDeep(
+  entries: readonly LootEntryWithRef[],
+  getTable: LootTableLookup,
+  rng: Rng,
+  depth: number = 0,
+  maxDepth: number = DEFAULT_REFERENCE_LOOT_DEPTH,
+  ctx?: LootRollContext,
+): LootDrop[] {
+  if (depth > maxDepth) return [];
+
+  const out: LootDrop[] = [];
+  const groups = new Map<number, LootEntryWithRef[]>();
+
+  for (const e of entries) {
+    if (!isLootEntryEligible(e, ctx)) continue;
+
+    if (e.groupId === 0) {
+      const mag = lootChanceMagnitude(e);
+      if (isReferenceLootEntry(e)) {
+        // Ungrouped reference: independent chance, then expand (LootMgr.cpp:2624–2645).
+        if (mag > 0 && rng.chance(mag / 100)) {
+          pushReference(out, e, getTable, rng, depth, maxDepth, ctx);
+        }
+      } else if (mag > 0 && rng.chance(mag / 100)) {
+        out.push(rollCount(e, rng));
+      }
+    } else {
+      const g = groups.get(e.groupId);
+      if (g) g.push(e);
+      else groups.set(e.groupId, [e]);
+    }
+  }
+
+  for (const group of groups.values()) {
+    const picked = rollGroup(group, rng);
+    if (!picked) continue;
+    if (isReferenceLootEntry(picked)) {
+      pushReference(out, picked, getTable, rng, depth, maxDepth, ctx);
+    } else {
+      out.push(rollCount(picked, rng));
+    }
+  }
+  return out;
+}
+
+function pushReference(
+  out: LootDrop[],
+  ref: LootEntryWithRef,
+  getTable: LootTableLookup,
+  rng: Rng,
+  depth: number,
+  maxDepth: number,
+  ctx?: LootRollContext,
+): void {
+  const refId = ref.referenceLootId!;
+  const table = getTable(refId);
+  if (!table) return;
+  // maxCount is the reference multiplicator (at least 1).
+  const loops = Math.max(1, ref.maxCount || 1);
+  for (let i = 0; i < loops; i++) {
+    const nested = rollLootDeep(table, getTable, rng, depth + 1, maxDepth, ctx);
+    for (const d of nested) out.push(d);
+  }
+}
+
+function rollCount(e: LootEntryDef, rng: Rng): LootDrop {
+  return { item: e.item, count: rng.int(e.minCount, e.maxCount) };
+}
+
+// Pick at most one item from a group: explicitly-chanced rows are tried first against one 0..100
+// roll, then an equal-chanced (chance 0) row uniformly. Chances summing under 100 can yield none.
+function rollGroup(entries: readonly LootEntryWithRef[], rng: Rng): LootEntryWithRef | null {
+  // Explicit weight: non-zero chance (positive or negative signed quest rows that passed gate).
+  const explicit = entries.filter((e) => lootChanceMagnitude(e) > 0);
+  if (explicit.length) {
+    let roll = rng.next() * 100;
+    for (const e of explicit) {
+      const mag = lootChanceMagnitude(e);
+      if (mag >= 100) return e;
+      roll -= mag;
+      if (roll < 0) return e;
+    }
+  }
+  // Equal-chance fallback: chance === 0 only (FQ3 — not negative quest rows).
+  const equal = entries.filter((e) => e.chance === 0);
+  return equal.length ? equal[rng.int(0, equal.length - 1)]! : null;
+}
+
+// Structurally expand reference rows into a flat list of plain entries for previews. Does NOT
+// roll chances — each reference expands maxCount times into copies of its rows, depth-capped.
+export function resolveReferenceLoot(
+  entries: readonly LootEntryWithRef[],
+  getTable: LootTableLookup,
+  maxDepth: number = DEFAULT_REFERENCE_LOOT_DEPTH,
+  depth: number = 0,
+  visited: ReadonlySet<number> = new Set(),
+): LootEntryWithRef[] {
+  if (depth > maxDepth) return [];
+
+  const out: LootEntryWithRef[] = [];
+  for (const e of entries) {
+    if (!isReferenceLootEntry(e)) {
+      out.push(e);
+      continue;
+    }
+    const refId = e.referenceLootId!;
+    if (visited.has(refId)) continue; // cycle guard (load-time in CMaNGOS)
+    const child = getTable(refId);
+    if (!child) continue;
+    const nextVisited = new Set(visited);
+    nextVisited.add(refId);
+    const loops = Math.max(1, e.maxCount || 1);
+    for (let i = 0; i < loops; i++) {
+      const expanded = resolveReferenceLoot(child, getTable, maxDepth, depth + 1, nextVisited);
+      for (const row of expanded) out.push(row);
+    }
+  }
+  return out;
+}
+
+// Load a loot chain by id (creature loot, pickpocket, reference root, …). Pickpocket tables are just
+// another lootId — same processor (LootMgr stores).
+export function resolveLootChain(
+  lootId: number,
+  getTable: LootTableLookup,
+  maxDepth: number = DEFAULT_REFERENCE_LOOT_DEPTH,
+): LootEntryWithRef[] {
+  const root = getTable(lootId);
+  if (!root) return [];
+  return resolveReferenceLoot(root, getTable, maxDepth, 0, new Set([lootId]));
+}

package/src/domain/items/mounts.ts

@@ -0,0 +1,190 @@
+// Mounts and Riding skill. Pure domain: a gold sink plus a travel-time fraction ported from the
+// mount auras — aura 32 gives 60 or 100%, and travelMs = baseMs / (1 + pct/100). One mount only.
+
+import type { Character } from '../character/character.ts';
+import type { ItemDef } from '../../data/schema.ts';
+import { raceClassMaskMatches } from '../character/combatSkills.ts';
+
+/** SharedDefines.h SKILL_RIDING = 762 (unified riding line). */
+export const SKILL_RIDING = 762;
+
+/** Apprentice Riding skill value (SkillTiers maximized; archive 3296_spell_learn_skill). */
+export const RIDING_RANK_APPRENTICE = 75;
+
+/** Journeyman Riding skill value. */
+export const RIDING_RANK_JOURNEYMAN = 150;
+
+// Phonecraft text-RPG pacing for one zone hop. This base is authoring for a readable delay; the
+// FRACTION under mount speed is what is sourced. Not a CMaNGOS travel-ms value.
+export const BASE_TRAVEL_MS = 10_000;
+
+/** Baked DataBundle.ridingSpells row (skill-GRANT spells, not SpellDefs). */
+export interface RidingSpellRow {
+  id: number;
+  trainerSpell: number;
+  rank: number;
+  step: number;
+  cost: number;
+  reqLevel: number;
+}
+
+export interface Check {
+  ok: boolean;
+  reason?: string;
+}
+
+export interface CharResult extends Check {
+  char: Character;
+}
+
+export interface CanTrainRidingInput {
+  level: number;
+  gold: number;
+  /** Current riding skill value (0 if untrained). */
+  currentRank: number;
+  spell: RidingSpellRow;
+  /** GetReputationPriceDiscount; default 1 so existing callers stay undiscounted. */
+  discountMod?: number;
+}
+
+// Whether the character may purchase this riding rank from a trainer. Journeyman requires Apprentice first
+// (npc_trainer reqskill 762 on 33392).
+export function canTrainRiding(input: CanTrainRidingInput): Check {
+  const { level, gold, currentRank, spell } = input;
+  if (currentRank >= spell.rank) {
+    return { ok: false, reason: 'Already trained' };
+  }
+  // Step order: cannot train 150 without 75 (reqskill 762 on Journeyman).
+  if (spell.step > 1 && currentRank < RIDING_RANK_APPRENTICE) {
+    return { ok: false, reason: 'Requires Apprentice Riding first' };
+  }
+  if (level < spell.reqLevel) {
+    return { ok: false, reason: `Requires level ${spell.reqLevel}` };
+  }
+  const cost = Math.floor(spell.cost * (input.discountMod ?? 1));
+  if (gold < cost) {
+    return { ok: false, reason: 'Not enough money' };
+  }
+  return { ok: true };
+}
+
+// Train a riding rank: deduct gold, snap skill to rank (SkillTiers maximized). Cite: Player.cpp
+// SetSkillStep + SKILL_FLAG_MAXIMIZED.
+export function trainRiding(char: Character, spell: RidingSpellRow, discountMod = 1): CharResult {
+  const currentRank = char.ridingSkill ?? 0;
+  const chk = canTrainRiding({
+    level: char.level,
+    gold: char.gold,
+    currentRank,
+    spell,
+    discountMod,
+  });
+  if (!chk.ok) return { ok: false, reason: chk.reason, char };
+  const cost = Math.floor(spell.cost * discountMod);
+  return {
+    ok: true,
+    char: {
+      ...char,
+      gold: char.gold - cost,
+      ridingSkill: spell.rank,
+    },
+  };
+}
+
+// AllowableRace mask gate (Player.cpp CanUseItem). mask 0 / absent = unrestricted; else bit (1 << (race -
+// 1)). Cite: raceClassMaskMatches / unitRaceOrClassMask.
+export function raceAllowedForMount(race: number, allowableRace?: number): boolean {
+  if (allowableRace == null || allowableRace === 0) return true;
+  return raceClassMaskMatches(allowableRace, race);
+}
+
+export interface CanUseMountOpts {
+  /** Text-RPG: mounts only out of combat (non-combat cast with damage interrupt). */
+  inCombat?: boolean;
+}
+
+// CanUseItem-shaped mount gate: level, riding rank, race mask and out-of-combat. Ownership is the
+// caller's. Re-using the same mount is idempotent, and a different one replaces it.
+export function canUseMount(
+  char: Character,
+  item: ItemDef,
+  opts: CanUseMountOpts = {},
+): Check {
+  if (item.mountSpell == null && item.mountSpeedPct == null && item.requiredRidingRank == null) {
+    return { ok: false, reason: 'Not a mount' };
+  }
+  if (opts.inCombat) {
+    return { ok: false, reason: 'Cannot mount in combat' };
+  }
+  if (item.requiredLevel != null && char.level < item.requiredLevel) {
+    return { ok: false, reason: `Requires level ${item.requiredLevel}` };
+  }
+  const needRank = item.requiredRidingRank ?? 0;
+  const have = char.ridingSkill ?? 0;
+  if (have < needRank) {
+    return {
+      ok: false,
+      reason: needRank > 0
+        ? `Requires Riding skill ${needRank}`
+        : 'Requires Riding skill',
+    };
+  }
+  if (!raceAllowedForMount(char.race, item.allowableRace)) {
+    return { ok: false, reason: 'Your race cannot use this mount' };
+  }
+  return { ok: true };
+}
+
+// Mount: one mount only (never-stack). Replaces any previous mount item. Cite: SpellStacking.cpp
+// SPELL_AURA_MOUNTED never stacking; Unit::Mount.
+export function mount(char: Character, item: ItemDef, opts: CanUseMountOpts = {}): CharResult {
+  const chk = canUseMount(char, item, opts);
+  if (!chk.ok) return { ok: false, reason: chk.reason, char };
+  return {
+    ok: true,
+    char: { ...char, mountedItem: item.entry },
+  };
+}
+
+/** Clear mounted state. Cite: Unit::Unmount. */
+export function dismount(char: Character): CharResult {
+  if (char.mountedItem == null) {
+    return { ok: false, reason: 'Not mounted', char };
+  }
+  const next = { ...char };
+  delete next.mountedItem;
+  return { ok: true, char: next };
+}
+
+// Effective zone-hop travel time under mounted speed: baseMs / (1 + speedPct/100), so +60% is
+// ×1/1.6. Unmounted is identity. Cite: Unit.cpp UpdateSpeed mounted bucket.
+export function travelTimeMs(baseMs: number, mountedSpeedPct: number | null | undefined): number {
+  if (mountedSpeedPct == null || mountedSpeedPct <= 0) return baseMs;
+  return baseMs / (1 + mountedSpeedPct / 100);
+}
+
+/** Resolve travel ms for a character given the mounted item's speed (or walk). */
+export function travelTimeForChar(
+  baseMs: number,
+  char: Character,
+  itemOf: (entry: number) => ItemDef | undefined,
+): number {
+  const entry = char.mountedItem;
+  if (entry == null) return travelTimeMs(baseMs, null);
+  const pct = itemOf(entry)?.mountSpeedPct;
+  return travelTimeMs(baseMs, pct ?? null);
+}
+
+// Pick a riding spell row by rank, skill-grant id, or trainer wrapper id. Prefer reading bake rows over
+// hardcoding ids in callers.
+export function findRidingSpell(
+  spells: readonly RidingSpellRow[],
+  rankOrSpellId: number,
+): RidingSpellRow | undefined {
+  return spells.find(
+    (s) =>
+      s.rank === rankOrSpellId
+      || s.id === rankOrSpellId
+      || s.trainerSpell === rankOrSpellId,
+  );
+}

package/src/domain/items/onUsePayload.ts

@@ -0,0 +1,102 @@
+// An on-use payload flattened through its trigger chain, plus implicit-target hostility.
+// 134 items (every Protection Potion, the BG talismans, both rocket helms) matched no branch.
+
+import type { SpellDef, SpellEffect } from '../../data/schema.ts';
+import { resolveCombatSpell } from '../../engine/spells/interpreter/item-triggers.ts';
+
+export type OnUseSpellLookup = { spell(id: number): SpellDef | undefined };
+
+/** SpellTargetInfoTable rows whose filter is TARGET_HARMFUL. Cite: SpellTargets.cpp:33-91. */
+const HARMFUL_IMPLICIT_TARGETS: ReadonlySet<number> = new Set([2, 6, 13, 15, 16, 24, 28, 36, 54]);
+
+/** An effect slot that aims at an enemy — the server's own hostility answer for a cast. */
+export function onUseAimsAtEnemy(spell: SpellDef | undefined): boolean {
+  return (spell?.rawEffects ?? []).some(
+    (e) => HARMFUL_IMPLICIT_TARGETS.has(e.targetA | 0)
+      || HARMFUL_IMPLICIT_TARGETS.has(e.targetB | 0),
+  );
+}
+
+// The spell an effect casts IMMEDIATELY. Cite: SpellEffects.cpp EffectTriggerSpell (64). A proc
+// aura (42/23) fires later off the holder, so following it read Chili's breath as offensive.
+function triggeredIds(e: SpellEffect): number[] {
+  return e.kind === 'trigger_spell' ? [e.spellId] : [];
+}
+
+// effects[] plus everything a trigger reaches, breadth-first with a visited set. The cast path
+// already follows these hops (applySpell.ts:1658); the two classifiers did not.
+export function onUseEffects(
+  spell: SpellDef,
+  ds: OnUseSpellLookup,
+  maxDepth = 3,
+): SpellEffect[] {
+  const out: SpellEffect[] = [];
+  const seen = new Set<number>([spell.id | 0]);
+  let frontier: SpellDef[] = [spell];
+  for (let depth = 0; depth <= maxDepth && frontier.length; depth++) {
+    const next: SpellDef[] = [];
+    for (const sp of frontier) {
+      const effs = sp.effects?.length ? sp.effects : (resolveCombatSpell(sp).effects ?? []);
+      for (const e of effs) {
+        out.push(e);
+        if (depth === maxDepth) continue;
+        for (const id of triggeredIds(e)) {
+          if (!id || seen.has(id)) continue;
+          seen.add(id);
+          const trig = ds.spell(id);
+          if (trig) next.push(trig);
+        }
+      }
+    }
+    frontier = next;
+  }
+  return out;
+}
+
+/** A beneficial speed aura — a hostile slow shares the kind. */
+export function isBeneficialSpeed(e: SpellEffect): boolean {
+  return e.kind === 'speed' && e.hostile !== true && (e.pct ?? 0) > 0;
+}
+
+export function hasFriendlyPayload(effects: readonly SpellEffect[]): boolean {
+  return effects.some(
+    (e) => e.kind === 'buff' || e.kind === 'heal' || e.kind === 'energize' || isBeneficialSpeed(e)
+      || e.kind === 'reflect' || e.kind === 'summon_guardian',
+  );
+}
+
+export function hasHostilePayload(effects: readonly SpellEffect[]): boolean {
+  return effects.some(
+    (e) => e.kind === 'direct_damage'
+      || e.kind === 'dot'
+      || (e.kind === 'cc' && !!e.mechanic)
+      || e.kind === 'health_leech'
+      || e.kind === 'root'
+      || e.kind === 'power_burn'
+      || e.kind === 'power_drain',
+  );
+}
+
+// Self payloads the cast path lands that no combatItems branch names. Cite: applySpell.ts:2456
+// school_absorb, :1751 proc_trigger_spell; applySpellLate.ts:1842 owned_spell_mods.
+const COMBAT_SELF_PAYLOAD: ReadonlySet<SpellEffect['kind']> = new Set([
+  'school_absorb', 'mana_shield', 'damage_shield', 'resist', 'proc_trigger_spell',
+  'owned_spell_mods', 'next_cast_mod', 'extra_attacks', 'threat', 'modify_threat_pct',
+  'combustion', 'sweeping_strikes', 'vampiric_embrace', 'magic_absorption', 'cheat_death',
+  'eye_for_an_eye', 'split_damage', 'split_damage_flat', 'mod_mechanic_resistance',
+  'resist_pushback', 'adaptive_warding', 'obsidian_armor', 'feign_death', 'stealth',
+]);
+
+export function hasCombatSelfPayload(effects: readonly SpellEffect[]): boolean {
+  return effects.some((e) => COMBAT_SELF_PAYLOAD.has(e.kind));
+}
+
+// A meal, not a kit row: POSITIVE restore only (Skull of Impending Doom 5024's is a self-drain
+// cost). The BG rations hide theirs two triggers down.
+export function isFoodDrinkPayload(effects: readonly SpellEffect[]): boolean {
+  return effects.some((e) => {
+    if (e.kind !== 'restore_health' && e.kind !== 'restore_power') return false;
+    const r = e as { min?: number; max?: number; amountPerTick?: number };
+    return Math.max(r.min ?? 0, r.max ?? 0, r.amountPerTick ?? 0) > 0;
+  });
+}

package/src/domain/items/pendingLoot.ts

@@ -0,0 +1,107 @@
+// The open loot container — the haul a corpse, chest, vein or bag-item HOLDS while the window is
+// up. Outdoor leftovers despawn on close; an inventory container's remainder stays claimable.
+
+import type { ItemInstance } from './itemInstance.ts';
+import type { Inventory } from './inventory.ts';
+import {
+  GAMEOBJECT_TYPE_CHEST, GAMEOBJECT_TYPE_FISHINGNODE, GAMEOBJECT_TYPE_FISHINGHOLE,
+} from '../world/gameObjects.ts';
+
+/** One row of held loot. `instance` carries a rolled suffix/enchant so taking never re-rolls it. */
+export interface PendingLootRow {
+  item: number;
+  count: number;
+  /** Wave Q identity, rolled when the loot was generated (LOCK 1: never re-rolled on take). */
+  instance?: ItemInstance;
+  /** True once a take attempt failed for space — the UI shows why instead of silently no-oping. */
+  blocked?: boolean;
+}
+
+/** What kind of thing is holding the loot. Drives the portrait, the title and the open cue. */
+export type PendingLootKind =
+  | 'corpse' | 'chest' | 'object' | 'mining' | 'herbalism' | 'fishing' | 'skinning' | 'container';
+
+export interface PendingLoot {
+  kind: PendingLootKind;
+  /** Frame title — the creature / object / node / container name. */
+  title: string;
+  rows: PendingLootRow[];
+  /** Copper still in the container (corpse gold). Taken as its own click, like WoW's coin row. */
+  copper: number;
+  /** Icon name for the portrait when there is no creature to draw. */
+  icon?: string;
+  /** Creature entry for a corpse — the portrait uses its baked sprite. */
+  creatureEntry?: number;
+  /** Item entry of the container that was opened (picks the open cue: clam vs lockbox vs crate). */
+  containerItem?: number;
+  /** A key/lockpick was consumed opening this — the metal click leads the cue. */
+  keyUsed?: boolean;
+  /** Footer line: skill-up, charges left, "bags full", "nothing usable". */
+  note?: string;
+}
+
+/** Bags plus still-held loot rows so findUpgrades can score the corpse before take. */
+export function inventoryPlusPending(
+  inv: Inventory,
+  pending: PendingLoot | null | undefined,
+): Inventory {
+  if (!pending?.rows.length) return inv;
+  return {
+    stacks: [
+      ...inv.stacks,
+      ...pending.rows.map((r) => r.instance ?? { item: r.item, count: r.count }),
+    ],
+  };
+}
+
+/** Nothing left to take: no rows and no money. An emptied container closes itself. */
+export function isLootEmpty(loot: PendingLoot | null | undefined): boolean {
+  if (!loot) return true;
+  return loot.copper <= 0 && loot.rows.length === 0;
+}
+
+/** How many separate things are still in there (money counts as one), for badges/labels. */
+export function lootRowCount(loot: PendingLoot | null | undefined): number {
+  if (!loot) return 0;
+  return loot.rows.length + (loot.copper > 0 ? 1 : 0);
+}
+
+/** Drop the row at `index`, keeping the rest in order. Out-of-range returns the list unchanged. */
+export function removeLootRow(loot: PendingLoot, index: number): PendingLoot {
+  if (index < 0 || index >= loot.rows.length) return loot;
+  return { ...loot, rows: loot.rows.filter((_, i) => i !== index) };
+}
+
+/** Mark the row at `index` as blocked (bags full) or clear that mark on every row. */
+export function markLootBlocked(loot: PendingLoot, index: number, blocked: boolean): PendingLoot {
+  return {
+    ...loot,
+    rows: loot.rows.map((r, i) => {
+      if (i !== index) return r;
+      const next = { ...r };
+      if (blocked) next.blocked = true; else delete next.blocked;
+      return next;
+    }),
+  };
+}
+
+/** Loot-container kind for a gather node, by its profession line. */
+export function gatherLootKind(skill: string | undefined): PendingLootKind {
+  if (skill === 'mining') return 'mining';
+  if (skill === 'herbalism') return 'herbalism';
+  if (skill === 'fishing') return 'fishing';
+  if (skill === 'skinning') return 'skinning';
+  return 'object';
+}
+
+// Loot-container kind for a GameObject: a chest or anything locked gets the lid cue, a fishing
+// node the water cue, everything else clickable is a plain object.
+export function goLootKind(go: {
+  type?: number; lockId?: number; chest?: unknown; fishnode?: unknown; fishinghole?: unknown;
+} | undefined): PendingLootKind {
+  if (!go) return 'object';
+  if (go.type === GAMEOBJECT_TYPE_FISHINGNODE || go.type === GAMEOBJECT_TYPE_FISHINGHOLE
+    || go.fishnode != null || go.fishinghole != null) return 'fishing';
+  if (go.type === GAMEOBJECT_TYPE_CHEST || go.chest != null || (go.lockId ?? 0) > 0) return 'chest';
+  return 'object';
+}