azeroth-shell 0.0.0-stage → 0.1.1

package/src/domain/economy/money.ts

@@ -0,0 +1,42 @@
+// Money formatting shared by the engine's activity log and the UI. No DOM, no settings. The COIN
+// MARKERS are the point: PUA codepoints ride through esc() so a sink renders art or g/s/c letters.
+const MARK = { g: '\uE000', s: '\uE001', c: '\uE002' } as const;
+const MARK_KIND: Record<string, 'g' | 's' | 'c'> = { '\uE000': 'g', '\uE001': 's', '\uE002': 'c' };
+
+/** Matches any coin marker. Callers use it with String.replace, which resets lastIndex. */
+export const COIN_MARK_RE = /[\uE000-\uE002]/g;
+export const coinMarkKind = (ch: string): 'g' | 's' | 'c' => MARK_KIND[ch] ?? 'c';
+
+/** Gold/silver/copper fields → copper. Missing parts are 0. */
+export function copperFromCoins(gold: number, silver: number, copper: number): number {
+  return Math.max(0, (Math.floor(gold) || 0) * 10000 + (Math.floor(silver) || 0) * 100 + (Math.floor(copper) || 0));
+}
+
+/** Copper split the way a money string shows it: gold/silver hidden when zero, copper always. */
+export function coinParts(copper: number): Array<{ k: 'g' | 's' | 'c'; n: number }> {
+  // JS remainder keeps the dividend's sign, so a negative delta used to print as -1g -1s -Nc.
+  const n = Math.max(0, Math.floor(copper) || 0);
+  const g = Math.floor(n / 10000);
+  const s = Math.floor((n % 10000) / 100);
+  const out: Array<{ k: 'g' | 's' | 'c'; n: number }> = [];
+  if (g) out.push({ k: 'g', n: g });
+  if (s) out.push({ k: 's', n: s });
+  out.push({ k: 'c', n: n % 100 });
+  return out;
+}
+
+/** Copper -> "1g 20s 5c" (100 copper = 1 silver, 100 silver = 1 gold). Plain text only. */
+export function moneyText(copper: number): string {
+  return coinParts(copper).map((p) => `${p.n}${p.k}`).join(' ');
+}
+
+/** Copper -> the same string with coin markers instead of letters. For anything that reaches
+ *  HTML through esc() — the activity log, tooltip hints, flash lines, modal messages. */
+export function moneyMarked(copper: number): string {
+  return coinParts(copper).map((p) => `${p.n}${MARK[p.k]}`).join(' ');
+}
+
+/** Flatten coin markers back to g/s/c letters — attributes, aria-labels, bug reports. */
+export function coinsText(s: string): string {
+  return s.replace(COIN_MARK_RE, (m) => coinMarkKind(m));
+}

package/src/domain/economy/syntheticClassTrainers.ts

@@ -0,0 +1,62 @@
+// Synthetic class-trainer catalogs — full class spell pools, not creature_template rows. Entry is
+// 1000 * 1000 + cls; the legacy 1000 + cls collided with Mosshide 1007–1011 (KI-918).
+
+import type { TrainerDef, ZoneDef } from '../../data/schema.ts';
+
+/** Classic playable class ids that get synthetic trainer catalogs. */
+export const SYNTHETIC_CLASS_TRAINER_CLASSES = [1, 2, 3, 4, 5, 7, 8, 9, 11] as const;
+
+const CLASS_SET: ReadonlySet<number> = new Set(SYNTHETIC_CLASS_TRAINER_CLASSES);
+
+/** Pre-KI-918 bake base (`entry = 1000 + cls`). */
+export const LEGACY_SYNTHETIC_CLASS_TRAINER_BASE = 1000;
+
+/** entry = 1000 * 1000 + cls — derived from LEGACY base; free of vanilla creature_template ids. */
+export function syntheticClassTrainerEntry(cls: number): number {
+  return LEGACY_SYNTHETIC_CLASS_TRAINER_BASE * LEGACY_SYNTHETIC_CLASS_TRAINER_BASE + (cls | 0);
+}
+
+export function isSyntheticClassTrainerClass(cls: number): boolean {
+  return CLASS_SET.has(cls | 0);
+}
+
+/** True when `entry` is the current (or legacy) synthetic class-trainer id for a playable class. */
+export function isSyntheticClassTrainerEntry(entry: number): boolean {
+  const e = entry | 0;
+  const curCls = e - LEGACY_SYNTHETIC_CLASS_TRAINER_BASE * LEGACY_SYNTHETIC_CLASS_TRAINER_BASE;
+  if (CLASS_SET.has(curCls)) return true;
+  const legacyCls = e - LEGACY_SYNTHETIC_CLASS_TRAINER_BASE;
+  return CLASS_SET.has(legacyCls);
+}
+
+/** Map legacy bake ids (1001–1011) onto the non-colliding formula. Already-new ids pass through. */
+export function normalizeSyntheticTrainerEntry(entry: number): number {
+  const e = entry | 0;
+  const legacyCls = e - LEGACY_SYNTHETIC_CLASS_TRAINER_BASE;
+  if (CLASS_SET.has(legacyCls)) return syntheticClassTrainerEntry(legacyCls);
+  return e;
+}
+
+/** Load-time remap of trainer catalog + zone.trainers[] off legacy 1000+cls (KI-918). */
+export function remapSyntheticClassTrainers(
+  trainersIn: readonly TrainerDef[],
+  zones: readonly ZoneDef[] | undefined,
+): Map<number, TrainerDef> {
+  const trainers = new Map<number, TrainerDef>();
+  for (const t of trainersIn) {
+    const entry = normalizeSyntheticTrainerEntry(t.entry | 0);
+    trainers.set(entry, entry === (t.entry | 0) ? t : { ...t, entry });
+  }
+  for (const z of zones ?? []) {
+    if (!z.trainers?.length) continue;
+    let changed = false;
+    const next = z.trainers.map((tr) => {
+      const entry = normalizeSyntheticTrainerEntry(tr.entry | 0);
+      if (entry === (tr.entry | 0)) return tr;
+      changed = true;
+      return { ...tr, entry };
+    });
+    if (changed) z.trainers = next;
+  }
+  return trainers;
+}

package/src/domain/economy/trading.ts

@@ -0,0 +1,296 @@
+// Buying from and selling to NPC vendors. Pure: takes the item def and returns a NEW character and
+// inventory. Buyback is a 12-slot FIFO ring (Player.h BUYBACK_SLOT_START 69), owned by the caller.
+
+import type { Character } from '../character/character.ts';
+import type { Inventory } from '../items/inventory.ts';
+import { addItem, addInstance, removeItem, removeStack, canFit, countItem } from '../items/inventory.ts';
+import type { ItemDef } from '../../data/schema.ts';
+import type { Rng } from '../../engine/core/rng.ts';
+import { createItemInstance, type CreateItemData, type CreateItemOpts } from '../items/createItem.ts';
+import { applyBindToInstance, resolveBonding } from '../items/itemBonding.ts';
+import type { ItemInstance } from '../items/itemInstance.ts';
+
+// Hard cap on player coinage in copper. CMaNGOS: `#define MAX_MONEY_AMOUNT (0x7FFFFFFF-1)` in Player.h (≈
+// 2147483646). ModifyMoney / SetMoney clamp gains to this value.
+export const MAX_MONEY = 0x7FFFFFFF - 1;
+
+// Vendor buyback slot count. CMaNGOS Player.h: `BUYBACK_SLOT_START = 69`, `BUYBACK_SLOT_END = 81` → 12
+// slots.
+export const BUYBACK_SLOTS = 12;
+
+/** One sold stack the vendor will sell back at the refund price. */
+export interface BuybackEntry {
+  entry: number;
+  qty: number;
+  refundCopper: number;
+  /** Monotonic / wall-clock timestamp used for oldest-first eviction. */
+  soldAt: number;
+  /** Companion whose bags the stack was sold out of. Absent = your own bags. */
+  owner?: string;
+  ownerName?: string;
+}
+
+/** Fixed-capacity list of recent sales (max BUYBACK_SLOTS). Plain data for the caller to store. */
+export type BuybackState = BuybackEntry[];
+
+export function emptyBuyback(): BuybackState {
+  return [];
+}
+
+// Append a buyback entry, evicting the existing entry with the oldest soldAt when the list is
+// full. Cite: Player::AddItemToBuyBackSlot — the lowest buyback timestamp is replaced.
+export function pushBuyback(state: BuybackState, entry: BuybackEntry): BuybackState {
+  if (state.length < BUYBACK_SLOTS) return [...state, entry];
+  let oldestIdx = 0;
+  for (let i = 1; i < state.length; i++) {
+    if (state[i].soldAt < state[oldestIdx].soldAt) oldestIdx = i;
+  }
+  const next = state.filter((_, i) => i !== oldestIdx);
+  next.push(entry);
+  return next;
+}
+
+export interface TradeCheck {
+  ok: boolean;
+  reason?: string;
+}
+export interface TradeResult extends TradeCheck {
+  char: Character;
+  inventory: Inventory;
+  amount: number; // copper spent (buy) or earned (sell); 0 on failure
+}
+
+/** Clamp copper so player gold never exceeds MAX_MONEY (CMaNGOS ModifyMoney). */
+export function clampGold(copper: number): number {
+  if (copper < 0) return 0;
+  return copper > MAX_MONEY ? MAX_MONEY : copper;
+}
+
+// Vendor trade quantities must be positive integers: copper and stack counts are integers, and
+// NaN must not enter price math, since NaN < 1 is false so a bare qty < 1 check is not enough.
+export function isValidTradeQty(qty: number): boolean {
+  return Number.isInteger(qty) && qty >= 1;
+}
+
+// Unit buy cost in copper after the optional reputation price multiplier, which defaults to 1 and
+// is 0.9 at Honored+. Floors the total so copper stays integer.
+export function buyCostCopper(def: ItemDef, qty: number = 1, priceMultiplier: number = 1): number {
+  const base = def.buyPrice * qty;
+  return Math.floor(base * priceMultiplier);
+}
+
+export function canBuy(
+  char: Character,
+  inv: Inventory,
+  def: ItemDef,
+  qty: number = 1,
+  cap?: number,
+  priceMultiplier: number = 1,
+  unitsPerPurchase: number = 1,
+): TradeCheck {
+  if (!isValidTradeQty(qty)) return { ok: false, reason: 'Invalid quantity' };
+  if (def.buyPrice <= 0) return { ok: false, reason: 'Not for sale' };
+  const cost = buyCostCopper(def, qty, priceMultiplier);
+  if (char.gold < cost) return { ok: false, reason: 'Not enough money' };
+  const units = qty * Math.max(1, unitsPerPurchase);
+  if (!canFit(inv, def.entry, units, def.stackable, cap)) return { ok: false, reason: 'Not enough bag space' };
+  return { ok: true };
+}
+
+// Optional create-time deps for Wave Q P2 random-property rolls at vendor buy. When omitted, falls back to
+// plain `addItem` (mats / tests without a pool table).
+export interface BuyCreateCtx {
+  ds: CreateItemData;
+  rng: Rng;
+  lookupProp?: CreateItemOpts['lookupProp'];
+}
+
+// unitsPerPurchase is item_template.BuyCount: BuyPrice buys that many units, e.g. ammo 200-packs.
+// Pass `create` so rollable greens mint a randomPropertyId at purchase. Cite: Player.cpp:17516.
+export function buy(
+  char: Character,
+  inv: Inventory,
+  def: ItemDef,
+  qty: number = 1,
+  cap?: number,
+  priceMultiplier: number = 1,
+  unitsPerPurchase: number = 1,
+  create?: BuyCreateCtx,
+): TradeResult {
+  const check = canBuy(char, inv, def, qty, cap, priceMultiplier, unitsPerPurchase);
+  if (!check.ok) return { ok: false, reason: check.reason, char, inventory: inv, amount: 0 };
+  const cost = buyCostCopper(def, qty, priceMultiplier);
+  const units = qty * Math.max(1, unitsPerPurchase);
+  let inventory: Inventory;
+  if (create) {
+    // New-copy path: roll (or skip) random property once for the purchased stack.
+    // Classic: vendor BoP binds on buy (same trigger as loot / pick-up).
+    const inst = applyBindToInstance(
+      createItemInstance(def.entry, units, create.ds, create.rng, {
+        lookupProp: create.lookupProp,
+      }),
+      resolveBonding(def),
+      'loot',
+    );
+    inventory = addInstance(inv, inst, def.stackable);
+  } else {
+    // Bare path (tests / mats): stamp BoP/quest bind when the def binds on loot.
+    const base: ItemInstance = { item: def.entry, count: units };
+    const minted = applyBindToInstance(base, resolveBonding(def), 'loot');
+    inventory = minted.bound
+      ? addInstance(inv, minted, def.stackable)
+      : addItem(inv, def.entry, units, def.stackable);
+  }
+  return {
+    ok: true,
+    char: { ...char, gold: char.gold - cost },
+    inventory,
+    amount: cost,
+  };
+}
+
+export function canSell(_char: Character, inv: Inventory, def: ItemDef, qty: number = 1): TradeCheck {
+  if (!isValidTradeQty(qty)) return { ok: false, reason: 'Invalid quantity' };
+  if (def.sellPrice <= 0) return { ok: false, reason: 'No one will buy that' };
+  if (countItem(inv, def.entry) < qty) return { ok: false, reason: "You don't have that" };
+  return { ok: true };
+}
+
+// Max units of `def` that fit under MAX_MONEY before gold clamps. CMaNGOS removes items then
+// clamps, so items vanish for zero copper at the cap; sizing first keeps unsold units in bags.
+export function maxSellQtyForGold(char: Character, def: ItemDef, qty: number): number {
+  if (qty < 1 || def.sellPrice <= 0) return 0;
+  const room = MAX_MONEY - char.gold;
+  if (room <= 0) return 0;
+  return Math.min(qty, Math.floor(room / def.sellPrice));
+}
+
+// Vendor sell copper for `count` units, scaled by remaining/max charges when the item is
+// consume-on-empty (SpellCharges < 0). Cite: ItemHandler.cpp:545-556. Unused stacks stay full.
+export function sellCopperChargeRatio(
+  def: Pick<ItemDef, 'sellPrice' | 'charges'>,
+  count: number,
+  remainingCharges?: number | null,
+): number {
+  // Money = SellPrice * count, then scaled by remaining/max for a NEGATIVE charge row only: "the
+  // value of this item is relative to how many charges are remaining". Cite: ItemHandler.cpp:551-557.
+  let money = def.sellPrice * count;
+  const max = def.charges != null && def.charges < 0 ? Math.abs(def.charges) : 0;
+  if (max > 0 && remainingCharges != null) {
+    money = Math.floor(money * (remainingCharges / max));
+  }
+  return money;
+}
+
+export interface SellResult extends TradeResult {
+  /** Units actually sold (may be < requested near MAX_MONEY). Present on success. */
+  qty?: number;
+  /** Present on success so the caller can `pushBuyback` (caller owns buyback state). */
+  buybackEntry?: BuybackEntry;
+}
+
+// Sell items for charge-ratio copper × qty, reducing qty so gold never passes MAX_MONEY, and stamp
+// the caller's clock onto the buyback entry. Takes from the first matching stacks — see sellStack.
+export function sell(char: Character, inv: Inventory, def: ItemDef, qty: number = 1, soldAt: number = 0): SellResult {
+  const check = canSell(char, inv, def, qty);
+  if (!check.ok) return { ok: false, reason: check.reason, char, inventory: inv, amount: 0 };
+  const n = maxSellQtyForGold(char, def, qty);
+  if (n <= 0) {
+    return { ok: false, reason: 'You cannot carry any more money', char, inventory: inv, amount: 0 };
+  }
+
+  let earned = 0;
+  let remaining = n;
+  for (const s of inv.stacks) {
+    if (s.item === def.entry && remaining > 0) {
+      const take = Math.min(s.count, remaining);
+      earned += sellCopperChargeRatio(def, take, s.charges);
+      remaining -= take;
+    }
+  }
+
+  const [inventory] = removeItem(inv, def.entry, n);
+  return {
+    ok: true,
+    char: { ...char, gold: clampGold(char.gold + earned) },
+    inventory,
+    amount: earned,
+    qty: n,
+    buybackEntry: { entry: def.entry, qty: n, refundCopper: earned, soldAt },
+  };
+}
+
+// Sell up to `qty` from the specific stack at `slotIndex`, leaving other stacks of the same item
+// alone. Qty is also capped by the remaining gold room under MAX_MONEY, as in `sell`.
+export function sellStack(
+  char: Character,
+  inv: Inventory,
+  def: ItemDef,
+  slotIndex: number,
+  qty: number = 1,
+  soldAt: number = 0,
+): SellResult {
+  if (!isValidTradeQty(qty)) return { ok: false, reason: 'Invalid quantity', char, inventory: inv, amount: 0 };
+  if (def.sellPrice <= 0) return { ok: false, reason: 'No one will buy that', char, inventory: inv, amount: 0 };
+  if (slotIndex < 0 || slotIndex >= inv.stacks.length) {
+    return { ok: false, reason: 'Invalid slot', char, inventory: inv, amount: 0 };
+  }
+  const src = inv.stacks[slotIndex];
+  if (src.item !== def.entry) {
+    return { ok: false, reason: "You don't have that", char, inventory: inv, amount: 0 };
+  }
+  const want = Math.min(qty, src.count);
+  if (want <= 0) return { ok: false, reason: "You don't have that", char, inventory: inv, amount: 0 };
+  const n = maxSellQtyForGold(char, def, want);
+  if (n <= 0) {
+    return { ok: false, reason: 'You cannot carry any more money', char, inventory: inv, amount: 0 };
+  }
+
+  const earned = sellCopperChargeRatio(def, n, src.charges);
+
+  const [inventory] = removeStack(inv, slotIndex, n);
+  return {
+    ok: true,
+    char: { ...char, gold: clampGold(char.gold + earned) },
+    inventory,
+    amount: earned,
+    qty: n,
+    buybackEntry: { entry: def.entry, qty: n, refundCopper: earned, soldAt },
+  };
+}
+
+export interface BuyBackResult extends TradeResult {
+  buyback: BuybackState;
+}
+
+// Repurchase the buyback entry at `index` for its `refundCopper`, removing it from state and returning the
+// items to the bags. `maxStack` is the item's stackable (from ItemDef).
+export function buyBack(
+  char: Character,
+  inv: Inventory,
+  state: BuybackState,
+  index: number,
+  maxStack: number = 1,
+  cap?: number,
+): BuyBackResult {
+  if (index < 0 || index >= state.length) {
+    return { ok: false, reason: 'Nothing to buy back', char, inventory: inv, amount: 0, buyback: state };
+  }
+  const e = state[index];
+  if (char.gold < e.refundCopper) {
+    return { ok: false, reason: 'Not enough money', char, inventory: inv, amount: 0, buyback: state };
+  }
+  if (!canFit(inv, e.entry, e.qty, maxStack, cap)) {
+    return { ok: false, reason: 'Not enough bag space', char, inventory: inv, amount: 0, buyback: state };
+  }
+  const buyback = state.filter((_, i) => i !== index);
+  // Spending gold — no gain path; still clamp defensively after any future refund logic.
+  const gold = clampGold(char.gold - e.refundCopper);
+  return {
+    ok: true,
+    char: { ...char, gold },
+    inventory: addItem(inv, e.entry, e.qty, maxStack),
+    amount: e.refundCopper,
+    buyback,
+  };
+}

package/src/domain/economy/vendorSellAll.ts

@@ -0,0 +1,252 @@
+// Vendor Multi sell: pick quality colours, then the stacks (ItemHandler.cpp:539 / :545-556).
+// Confirm starts Never-sell categories off — listed, not hidden (appInteractBulkBags.ts:34-66).
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { Inventory } from '../items/inventory.ts';
+import type { JunkQuality } from '../items/junkFilter.ts';
+import {
+  DEFAULT_PROTECT_CATEGORIES,
+  JUNK_PROTECT_CATEGORIES,
+  itemProtectCategory,
+  junkProtectCategoryLabel,
+  protectLookupFor,
+  type JunkProtectCategory,
+} from '../items/junkCategories.ts';
+import { sellCopperChargeRatio } from './trading.ts';
+
+/** The five colours the picker offers. Cite: SharedDefines.h:250. */
+export const SELL_ALL_TIERS: ReadonlyArray<{ quality: JunkQuality; colour: string }> = [
+  { quality: 0, colour: 'Gray' },
+  { quality: 1, colour: 'White' },
+  { quality: 2, colour: 'Green' },
+  { quality: 3, colour: 'Blue' },
+  { quality: 4, colour: 'Purple' },
+];
+
+export type SellAllQualityMap = Record<JunkQuality, boolean>;
+
+/** What the confirm list's filter buttons slice by: a never-sell box, gear, or the rest. */
+export type SellAllFilter = JunkProtectCategory | 'gear' | 'other';
+
+const SELL_ALL_FILTERS = new Set<string>([...JUNK_PROTECT_CATEGORIES.map((c) => c.id), 'gear', 'other']);
+
+/** A dataset string off a filter button, or null when it names no filter. */
+export function asSellAllFilter(raw: string | undefined | null): SellAllFilter | null {
+  return raw != null && SELL_ALL_FILTERS.has(raw) ? (raw as SellAllFilter) : null;
+}
+
+export function sellAllFilterLabel(id: SellAllFilter): string {
+  if (id === 'gear') return 'Gear';
+  if (id === 'other') return 'Everything else';
+  return junkProtectCategoryLabel(id);
+}
+
+export interface VendorSellAllRow {
+  /** Bag slot index — the row IS this stack. */
+  slot: number;
+  /** Companion whose bags hold it. Absent = your own bags. */
+  owner?: string;
+  ownerName?: string;
+  entry: number;
+  qty: number;
+  quality: JunkQuality;
+  /** What the vendor pays for the whole stack, charge ratio included. */
+  copper: number;
+  /** Rolled suffix on this stack, so the confirm list names what it is about to sell. */
+  randomPropertyId?: number;
+  /** Never-sell category this stack belongs to, if any. Confirm starts these off. */
+  protectCategory?: JunkProtectCategory;
+  /** Which filter button owns this row. The category the item IS, even when a guard released it. */
+  filter: SellAllFilter;
+  /** Why this row starts switched OFF beyond a category (still an upgrade). Absent = on. */
+  warn?: string;
+  /** Sub-line for a row that is ON — why a guard let it through. */
+  note?: string;
+}
+
+export interface VendorSellAllPlan {
+  rows: VendorSellAllRow[];
+  /** Stacks no vendor will buy at all (SellPrice 0). */
+  noValue: number;
+}
+
+export interface PlanVendorSellAllGuards {
+  /** Entries findUpgrades still wants on you or a companion — listed, but off by default. */
+  upgradeEntries?: ReadonlySet<number>;
+  // Teach items the whole group has already read (learnAllRecipes.ts knownTeachEntries). The
+  // "Recipes, formulas and books" box cannot protect these: no reader is left to want them.
+  knownTeachEntries?: ReadonlySet<number>;
+  // Teach items no body in the group has the profession or class for (learnAllRecipes.ts
+  // unlearnableTeachEntries). Same box, same reason: no reader is coming.
+  unlearnableTeachEntries?: ReadonlySet<number>;
+  // Food and drink ranks the bags have outgrown (staleConsumables.ts outdatedFoodDrinkEntries).
+  // The "Food and drink" box still guards the best rank carried — this is what sits under it.
+  outdatedFoodEntries?: ReadonlySet<number>;
+  // Bags and quivers nobody would wear (spareContainers.ts spareContainerEntries): no bigger than
+  // what is already on, and not an upgrade for anyone.
+  spareContainerEntries?: ReadonlySet<number>;
+  /** Companion these bags belong to. Stamped on every row so the run knows whose stack to sell. */
+  owner?: { id: string; name: string };
+}
+
+// Why a never-sell box let this row through, or null when the box still owns it. Each answer is a
+// dead end the guard cannot come back from: the book has no reader, the rank has been outgrown, the
+// bag has nowhere to go. The row is still one click from being kept.
+function releaseNote(
+  cat: JunkProtectCategory | null,
+  entry: number,
+  guards?: PlanVendorSellAllGuards,
+): string | null {
+  if (cat == null || !guards) return null;
+  if (cat === 'teaches') {
+    if (guards.knownTeachEntries?.has(entry)) return 'Already known';
+    if (guards.unlearnableTeachEntries?.has(entry)) return 'Nobody can learn it';
+    return null;
+  }
+  if (cat === 'foodDrink') {
+    return guards.outdatedFoodEntries?.has(entry) ? 'Outgrown rank' : null;
+  }
+  if (cat === 'container' || cat === 'quiver') {
+    return guards.spareContainerEntries?.has(entry) ? 'Not an upgrade' : null;
+  }
+  return null;
+}
+
+/** Rows for every colour — the picker filters them, the confirm list toggles them. */
+export function planVendorSellAll(
+  inventory: Inventory,
+  ds: DataStore,
+  guards?: PlanVendorSellAllGuards,
+): VendorSellAllPlan {
+  const rows: VendorSellAllRow[] = [];
+  let noValue = 0;
+  const look = protectLookupFor(ds);
+
+  inventory.stacks.forEach((stk, slot) => {
+    const it = ds.item(stk.item);
+    if (!it) return;
+    const q = (it.quality ?? 0) as number;
+    // Legendary and artifact have no checkbox: they leave through the single Sell button.
+    if (q < 0 || q > 4) return;
+    if (!(it.sellPrice > 0)) { noValue++; return; }
+    const raw = itemProtectCategory(it, look);
+    const released = releaseNote(raw, it.entry, guards);
+    const cat = released ? null : raw;
+    const warn = guards?.upgradeEntries?.has(it.entry) ? 'Still an upgrade' : undefined;
+    rows.push({
+      slot,
+      entry: it.entry,
+      qty: stk.count,
+      quality: q as JunkQuality,
+      copper: sellCopperChargeRatio(it, stk.count, stk.charges),
+      filter: raw ?? (it.slot != null ? 'gear' : 'other'),
+      ...(stk.randomPropertyId != null && stk.randomPropertyId > 0
+        ? { randomPropertyId: stk.randomPropertyId }
+        : {}),
+      ...(cat ? { protectCategory: cat } : {}),
+      ...(warn ? { warn } : {}),
+      ...(released ? { note: released } : {}),
+      ...(guards?.owner ? { owner: guards.owner.id, ownerName: guards.owner.name } : {}),
+    });
+  });
+
+  return { rows, noValue };
+}
+
+/** Rows whose colour the player ticked. */
+export function sellAllRowsForQualities(
+  rows: readonly VendorSellAllRow[],
+  qualities: SellAllQualityMap,
+): VendorSellAllRow[] {
+  return rows.filter((r) => !!qualities[r.quality]);
+}
+
+export function sellAllRowKey(row: Pick<VendorSellAllRow, 'slot' | 'entry' | 'owner'>): string {
+  return `${row.owner ?? ''}:${row.slot}:${row.entry}`;
+}
+
+// Confirm starts these off. Same boxes as Settings → Never sell or destroy, plus any row the
+// upgrade guard flagged. Listed so a click still sells them.
+export function defaultSellAllBlocked(
+  rows: readonly VendorSellAllRow[],
+  qualities: SellAllQualityMap,
+  protect: readonly JunkProtectCategory[] = DEFAULT_PROTECT_CATEGORIES,
+): string[] {
+  const on = new Set(protect);
+  const out: string[] = [];
+  for (const r of sellAllRowsForQualities(rows, qualities)) {
+    if (r.warn != null) { out.push(sellAllRowKey(r)); continue; }
+    if (r.protectCategory != null && on.has(r.protectCategory)) out.push(sellAllRowKey(r));
+  }
+  return out;
+}
+
+/** Rows that will actually be sold: not switched off. */
+export function activeSellAllRows(
+  rows: readonly VendorSellAllRow[],
+  blocked: ReadonlySet<string> | readonly string[],
+): VendorSellAllRow[] {
+  const off = blocked instanceof Set ? blocked : new Set(blocked);
+  return rows.filter((r) => !off.has(sellAllRowKey(r)));
+}
+
+export function sellAllTotals(rows: readonly VendorSellAllRow[]): { count: number; copper: number } {
+  let count = 0;
+  let copper = 0;
+  for (const r of rows) { count += r.qty; copper += r.copper; }
+  return { count, copper };
+}
+
+// The item, not the stack: one click on a stack of Wool moves every stack of Wool. A rolled suffix
+// is part of the identity, so "of the Bear" and "of the Eagle" stay two items.
+export function sellAllStackKey(row: Pick<VendorSellAllRow, 'entry' | 'randomPropertyId'>): string {
+  return `${row.entry}:${row.randomPropertyId ?? 0}`;
+}
+
+/** Row keys of every stack of the same item as `key`, among the rows shown. */
+export function sellAllPeerKeys(rows: readonly VendorSellAllRow[], key: string): string[] {
+  const row = rows.find((r) => sellAllRowKey(r) === key);
+  if (!row) return [key];
+  const stack = sellAllStackKey(row);
+  return rows.filter((r) => sellAllStackKey(r) === stack).map((r) => sellAllRowKey(r));
+}
+
+export interface SellAllFilterGroup {
+  id: SellAllFilter;
+  label: string;
+  /** Stacks in this group among the rows shown. */
+  stacks: number;
+  /** Items still switched on, and what they pay. */
+  count: number;
+  copper: number;
+  /** False when every stack in the group is switched off. */
+  on: boolean;
+}
+
+/** One button per kind of item in the list, in the Never sell display order. */
+export function sellAllFilterGroups(
+  rows: readonly VendorSellAllRow[],
+  blocked: ReadonlySet<string> | readonly string[],
+): SellAllFilterGroup[] {
+  const off = blocked instanceof Set ? blocked : new Set(blocked);
+  const order: SellAllFilter[] = [...JUNK_PROTECT_CATEGORIES.map((c) => c.id), 'gear', 'other'];
+  const by = new Map<SellAllFilter, SellAllFilterGroup>();
+  for (const r of rows) {
+    let g = by.get(r.filter);
+    if (!g) {
+      g = { id: r.filter, label: sellAllFilterLabel(r.filter), stacks: 0, count: 0, copper: 0, on: false };
+      by.set(r.filter, g);
+    }
+    g.stacks++;
+    if (off.has(sellAllRowKey(r))) continue;
+    g.on = true;
+    g.count += r.qty;
+    g.copper += r.copper;
+  }
+  return order.filter((id) => by.has(id)).map((id) => by.get(id) as SellAllFilterGroup);
+}
+
+/** Row keys of every stack a filter button owns. */
+export function sellAllFilterKeys(rows: readonly VendorSellAllRow[], id: SellAllFilter): string[] {
+  return rows.filter((r) => r.filter === id).map((r) => sellAllRowKey(r));
+}