azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/bots/runSupply.ts

@@ -0,0 +1,251 @@
+// Pre-run food and water, pure domain: who is short, what the vendor ladder sells at their level, what
+// it costs, whether it fits. A mage conjures both mid-run (liveFloorRecovery.ts conjureFor); no mage asks.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { ItemDef } from '../../data/schema.ts';
+import { CLASS } from '../../data/schema.ts';
+import type { Character } from '../character/character.ts';
+import { powerType } from '../character/character.ts';
+import { addItem, canFit, type Inventory } from '../items/inventory.ts';
+import { foodDrinkReqLevel } from '../items/staleConsumables.ts';
+import { buyCostCopper } from '../economy/trading.ts';
+import { unlimitedVendorFor } from '../professions/vendorReagents.ts';
+import { vendorsSelling } from '../../world/world.ts';
+import { listAutoConsumableOptions } from './autoConsumables.ts';
+import { clampTarget, DEFAULT_RUN_SUPPLY_PREFS, type RunSupplyPrefs } from './runSupplyPrefs.ts';
+
+export {
+  clampTarget, DEFAULT_RUN_SUPPLY_PREFS, normalizeRunSupplyPrefs, RUN_SUPPLY_TARGET, type RunSupplyPrefs,
+} from './runSupplyPrefs.ts';
+
+export type SupplyKind = 'food' | 'drink';
+export const SUPPLY_KINDS: readonly SupplyKind[] = ['drink', 'food'];
+
+/** One party member as the check sees them: a body, its own bags, and the room those bags have. */
+export interface SupplyMember {
+  /** 'player', or the companion id. */
+  id: string;
+  name: string;
+  char: Character;
+  bags: Inventory;
+  cap: number;
+}
+
+/** One vendor row on the ladder for a kind. */
+export interface SupplyRung {
+  item: ItemDef;
+  reqLevel: number;
+  vendorEntry: number;
+  price: number;
+  buyCount: number;
+  vendors: number;
+}
+
+const ladderMemo = new WeakMap<DataStore, Map<string, SupplyRung[]>>();
+
+// One vendor row per gate this race can buy, best gate first, the cheapest then most stocked inside a
+// gate. Bandages bake as food and are not a meal (consumables.ts isOocFoodOrDrinkItem); a 1-unit row is pet food.
+export function runSupplyLadder(ds: DataStore, race: number, kind: SupplyKind): SupplyRung[] {
+  let memo = ladderMemo.get(ds);
+  if (!memo) {
+    memo = new Map();
+    ladderMemo.set(ds, memo);
+  }
+  const key = `${race}:${kind}`;
+  const hit = memo.get(key);
+  if (hit) return hit;
+  const out: SupplyRung[] = [];
+  for (const it of ds.items()) {
+    const c = it.consumable;
+    if (!c || c.effect !== kind || it.useBuff != null || it.conjured === true) continue;
+    if (it.buyPrice <= 0 || (it.stackable ?? 1) <= 1) continue;
+    const sp = it.useSpell != null ? ds.spell(it.useSpell) : undefined;
+    if (sp?.mechanic === 'bandage') continue;
+    const vendorEntry = unlimitedVendorFor(ds, it.entry, race);
+    if (vendorEntry == null) continue;
+    out.push({
+      item: it,
+      reqLevel: foodDrinkReqLevel(it),
+      vendorEntry,
+      price: it.buyPrice,
+      buyCount: Math.max(1, it.buyCount ?? 1),
+      vendors: vendorsSelling(ds, it.entry).length,
+    });
+  }
+  out.sort((a, b) => b.reqLevel - a.reqLevel
+    || a.price - b.price
+    || b.vendors - a.vendors
+    || a.item.entry - b.item.entry);
+  // One rung per gate: "a rank down" is the next gate, never a sibling at the same price.
+  const ladder = out.filter((r, i) => i === 0 || out[i - 1]!.reqLevel !== r.reqLevel);
+  memo.set(key, ladder);
+  return ladder;
+}
+
+export interface SupplyRow {
+  memberId: string;
+  memberName: string;
+  kind: SupplyKind;
+  /** Usable units of this kind already in their bags. */
+  have: number;
+  short: number;
+  /** Rungs this member can use, best first; `rung` indexes it. */
+  ladder: SupplyRung[];
+  rung: number;
+  item: number;
+  purchases: number;
+  units: number;
+  cost: number;
+  /** Units their bags take right now, after the rows before this one landed. */
+  fitUnits: number;
+  fitPurchases: number;
+  fitCost: number;
+}
+
+export interface RunSupplyPlan {
+  /** A mage is in the party: nothing to buy, the mage conjures both kinds mid-run. */
+  mage: boolean;
+  rows: SupplyRow[];
+  cost: number;
+  gold: number;
+  /** Stepped down to the bottom rung and the purse is still short. */
+  unaffordable: boolean;
+  /** Members whose bags could not take every row. */
+  full: { id: string; name: string }[];
+}
+
+export const supplyRowKey = (row: Pick<SupplyRow, 'memberId' | 'kind'>): string => `${row.memberId}:${row.kind}`;
+
+export function partyHasMage(members: readonly Pick<SupplyMember, 'char'>[]): boolean {
+  return members.some((m) => m.char.cls === CLASS.MAGE);
+}
+
+/** Usable units of one kind in a member's own bags, the same read the rest picks from. */
+export function supplyHave(member: SupplyMember, kind: SupplyKind, ds: DataStore): number {
+  let n = 0;
+  for (const o of listAutoConsumableOptions(member.char, member.bags, ds)) {
+    if (o.kind === kind) n += o.count;
+  }
+  return n;
+}
+
+function priceRow(row: SupplyRow): SupplyRow {
+  const r = row.ladder[row.rung]!;
+  const purchases = Math.ceil(row.short / r.buyCount);
+  return {
+    ...row,
+    item: r.item.entry,
+    purchases,
+    units: purchases * r.buyCount,
+    cost: buyCostCopper(r.item, purchases),
+  };
+}
+
+const total = (rows: readonly SupplyRow[]): number => rows.reduce((s, r) => s + r.cost, 0);
+
+// Every row opens on the best rung its member can use; while the purse is short, the dearest row
+// that still has a cheaper rung below it steps down one. The bottom of every ladder is where it stops.
+export function planRunSupply(args: {
+  ds: DataStore;
+  members: readonly SupplyMember[];
+  gold: number;
+  race: number;
+  prefs?: RunSupplyPrefs;
+}): RunSupplyPlan {
+  const { ds, members, gold, race } = args;
+  const prefs = args.prefs ?? DEFAULT_RUN_SUPPLY_PREFS;
+  const target = clampTarget(prefs.target);
+  const none: RunSupplyPlan = { mage: false, rows: [], cost: 0, gold, unaffordable: false, full: [] };
+  if (partyHasMage(members)) return { ...none, mage: true };
+  let rows: SupplyRow[] = [];
+  for (const m of members) {
+    for (const kind of SUPPLY_KINDS) {
+      if (!prefs[kind]) continue;
+      if (kind === 'drink' && powerType(m.char) !== 'mana') continue;
+      const have = supplyHave(m, kind, ds);
+      const short = target - have;
+      if (short <= 0) continue;
+      const ladder = runSupplyLadder(ds, race, kind).filter((r) => r.reqLevel <= m.char.level);
+      if (!ladder.length) continue;
+      rows.push(priceRow({
+        memberId: m.id, memberName: m.name, kind, have, short, ladder, rung: 0,
+        item: 0, purchases: 0, units: 0, cost: 0, fitUnits: 0, fitPurchases: 0, fitCost: 0,
+      }));
+    }
+  }
+  let unaffordable = false;
+  while (total(rows) > gold) {
+    let pick = -1;
+    for (let i = 0; i < rows.length; i++) {
+      const r = rows[i]!;
+      const next = r.ladder[r.rung + 1];
+      if (!next || next.price >= r.ladder[r.rung]!.price) continue;
+      if (pick < 0 || r.cost > rows[pick]!.cost) pick = i;
+    }
+    if (pick < 0) { unaffordable = true; break; }
+    rows[pick] = priceRow({ ...rows[pick]!, rung: rows[pick]!.rung + 1 });
+  }
+  rows = fitRows(rows, members, ds);
+  const full = members
+    .filter((m) => rows.some((r) => r.memberId === m.id && r.fitUnits < r.units))
+    .map((m) => ({ id: m.id, name: m.name }));
+  return { mage: false, rows, cost: total(rows), gold, unaffordable, full };
+}
+
+/** How much of each row the member's bags take, rows landing in order on a copy of the bags. */
+function fitRows(rows: readonly SupplyRow[], members: readonly SupplyMember[], ds: DataStore): SupplyRow[] {
+  const working = new Map<string, Inventory>();
+  const capOf = new Map(members.map((m) => [m.id, m.cap]));
+  for (const m of members) working.set(m.id, m.bags);
+  return rows.map((row) => {
+    const rung = row.ladder[row.rung]!;
+    const stack = Math.max(1, rung.item.stackable ?? 1);
+    const inv = working.get(row.memberId) ?? { stacks: [] };
+    const cap = capOf.get(row.memberId) ?? 0;
+    let p = row.purchases;
+    while (p > 0 && !canFit(inv, row.item, p * rung.buyCount, stack, cap)) p--;
+    const fitUnits = p * rung.buyCount;
+    if (fitUnits > 0) working.set(row.memberId, addItem(inv, row.item, fitUnits, stack));
+    return { ...row, fitUnits, fitPurchases: p, fitCost: buyCostCopper(rung.item, p) };
+  });
+}
+
+/** One purchase the engine lands: `units` of `item` into this member's bags for `cost`. */
+export interface SupplyBuy {
+  memberId: string;
+  memberName: string;
+  kind: SupplyKind;
+  item: number;
+  purchases: number;
+  units: number;
+  cost: number;
+  vendorEntry: number;
+}
+
+// The buys the purse covers, in row order, sized to what fits when `fitOnly`. A row the gold runs
+// out on is trimmed to the purchases still affordable, so "buy what we can" is one pass.
+export function supplyBuys(rows: readonly SupplyRow[], gold: number, fitOnly: boolean): SupplyBuy[] {
+  const out: SupplyBuy[] = [];
+  let left = gold;
+  for (const row of rows) {
+    const rung = row.ladder[row.rung]!;
+    const want = fitOnly ? row.fitPurchases : row.purchases;
+    const purchases = Math.min(want, Math.floor(left / Math.max(1, rung.price)));
+    if (purchases <= 0) continue;
+    const cost = buyCostCopper(rung.item, purchases);
+    left -= cost;
+    out.push({
+      memberId: row.memberId,
+      memberName: row.memberName,
+      kind: row.kind,
+      item: row.item,
+      purchases,
+      units: purchases * rung.buyCount,
+      cost,
+      vendorEntry: rung.vendorEntry,
+    });
+  }
+  return out;
+}
+
+export const supplyKindLabel = (kind: SupplyKind): string => (kind === 'drink' ? 'Water' : 'Food');

package/src/domain/bots/runSupplyPrefs.ts

@@ -0,0 +1,28 @@
+// The remembered Start-the-run food and water prefs. Import-free so ui/core/settings.ts can hold it.
+
+/** Units of each kind every member walks in with. Operator, 2026-09-10: "at least 40+ water". */
+export const RUN_SUPPLY_TARGET = 40;
+export const RUN_SUPPLY_TARGET_MIN = 5;
+export const RUN_SUPPLY_TARGET_MAX = 100;
+
+export interface RunSupplyPrefs {
+  target: number;
+  food: boolean;
+  drink: boolean;
+}
+
+export const DEFAULT_RUN_SUPPLY_PREFS: RunSupplyPrefs = { target: RUN_SUPPLY_TARGET, food: true, drink: true };
+
+export function clampTarget(n: number): number {
+  return Math.max(RUN_SUPPLY_TARGET_MIN, Math.min(RUN_SUPPLY_TARGET_MAX, Math.round(n)));
+}
+
+export function normalizeRunSupplyPrefs(raw: unknown): RunSupplyPrefs {
+  const out = { ...DEFAULT_RUN_SUPPLY_PREFS };
+  if (!raw || typeof raw !== 'object') return out;
+  const r = raw as Record<string, unknown>;
+  if (typeof r.target === 'number' && Number.isFinite(r.target)) out.target = clampTarget(r.target);
+  if (typeof r.food === 'boolean') out.food = r.food;
+  if (typeof r.drink === 'boolean') out.drink = r.drink;
+  return out;
+}

package/src/domain/bots/sendTradeGoods.ts

@@ -0,0 +1,394 @@
+// Plan a dump of trade goods into companion bags. A companion takes a stack when a recipe consumes
+// it, or when it is a gather mat for a craft they run. Cite: Spell.cpp CheckItems; ItemPrototype.h.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { EquipSlot, RecipeDef } from '../../data/schema.ts';
+import type { Character } from '../character/character.ts';
+import { bagCapacity } from '../items/equipment.ts';
+import {
+  addItem,
+  emptyInventory,
+  freeSlots,
+  transferItem,
+  type Inventory,
+} from '../items/inventory.ts';
+import { hasIdentity } from '../items/itemInstance.ts';
+import {
+  companionCharacter,
+  companionLevel,
+  companionSkillMap,
+  type Companion,
+} from './squad.ts';
+
+/** item_template.class 7 — Trade Goods. Cite: ItemPrototype.h ITEM_CLASS_TRADE_GOODS. */
+export const ITEM_CLASS_TRADE_GOODS = 7;
+
+/** Cite: ItemPrototype.h ItemSubclassTradeGoods. */
+const ITEM_SUBCLASS_LEATHER = 6;
+const ITEM_SUBCLASS_METAL_STONE = 7;
+const ITEM_SUBCLASS_HERB = 9;
+
+type GatherLine = 'mining' | 'herbalism' | 'skinning';
+
+export interface TradeGoodsGift {
+  companionId: string;
+  companionName: string;
+  entry: number;
+  qty: number;
+}
+
+/** Same shape as Game.squadUpgradePlan. Cite: engine/game/types.ts SquadUpgradeRow. */
+export interface SendGoodsUpgradeRow {
+  companionId: string;
+  companionName: string;
+  benched: boolean;
+  entry: number;
+  targetSlot: EquipSlot;
+  currentEntry?: number;
+  delta: number;
+  from: 'theirs' | 'you' | 'bank';
+}
+
+/** Bag-bar confirm: trade goods, roster upgrades, and the keys the player clicked off. */
+export interface SendGoodsModalState {
+  rows: TradeGoodsGift[];
+  blocked: string[];
+  upgrades: SendGoodsUpgradeRow[];
+  blockedGear: string[];
+}
+
+/** Matches applySquadUpgrades skip keys (`companionId|entry|targetSlot`). */
+export function sendGoodsUpgradeKey(
+  r: Pick<SendGoodsUpgradeRow, 'companionId' | 'entry' | 'targetSlot'>,
+): string {
+  return `${r.companionId}|${r.entry}|${r.targetSlot}`;
+}
+
+export function activeSendGoodsUpgrades(
+  rows: readonly SendGoodsUpgradeRow[],
+  blocked: ReadonlySet<string> | readonly string[],
+): SendGoodsUpgradeRow[] {
+  const skip = blocked instanceof Set ? blocked : new Set(blocked);
+  return rows.filter((r) => !skip.has(sendGoodsUpgradeKey(r)));
+}
+
+export function planCompanionShare(
+  args: PlanSendTradeGoodsArgs & { upgrades: readonly SendGoodsUpgradeRow[] },
+): SendGoodsModalState | null {
+  const rows = planSendTradeGoods(args);
+  const upgrades = [...args.upgrades];
+  if (!rows.length && !upgrades.length) return null;
+  return { rows, blocked: [], upgrades, blockedGear: [] };
+}
+
+export function applyCompanionShare(
+  game: {
+    applySquadUpgrades(max?: number, allowKeys?: Iterable<string>): { ok: boolean; equipped?: number };
+    giveItemToBot(id: string, entry: number, qty?: number): { ok: boolean; moved?: number };
+  },
+  modal: SendGoodsModalState,
+): { equipped: number; moved: number; lastGoodsEntry?: number } {
+  const upgrades = activeSendGoodsUpgrades(modal.upgrades ?? [], modal.blockedGear ?? []);
+  const gifts = activeTradeGoodsGifts(modal.rows, modal.blocked);
+  let equipped = 0;
+  if (upgrades.length) {
+    const r = game.applySquadUpgrades(40, upgrades.map(sendGoodsUpgradeKey));
+    if (r.ok) equipped = r.equipped ?? 0;
+  }
+  let moved = 0;
+  let lastGoodsEntry: number | undefined;
+  for (const g of gifts) {
+    const r = game.giveItemToBot(g.companionId, g.entry, g.qty);
+    if (r.ok) {
+      moved += r.moved ?? 0;
+      lastGoodsEntry = g.entry;
+    }
+  }
+  return lastGoodsEntry != null ? { equipped, moved, lastGoodsEntry } : { equipped, moved };
+}
+
+export function companionShareResultLine(r: { equipped: number; moved: number }): string {
+  if (r.equipped && r.moved) return `Equipped ${r.equipped}, sent ${r.moved}`;
+  if (r.equipped) return `Equipped ${r.equipped} upgrade${r.equipped === 1 ? '' : 's'}`;
+  if (r.moved) return `Sent ${r.moved} item${r.moved === 1 ? '' : 's'} to companions`;
+  return 'Nothing applied';
+}
+
+export function tradeGoodsGiftKey(g: Pick<TradeGoodsGift, 'companionId' | 'entry'>): string {
+  return `${g.companionId}:${g.entry}`;
+}
+
+export function activeTradeGoodsGifts(
+  rows: readonly TradeGoodsGift[],
+  blocked: ReadonlySet<string> | readonly string[],
+): TradeGoodsGift[] {
+  const skip = blocked instanceof Set ? blocked : new Set(blocked);
+  return rows.filter((g) => !skip.has(tradeGoodsGiftKey(g)));
+}
+
+export interface PlanSendTradeGoodsArgs {
+  inventory: Inventory;
+  squad: readonly Companion[];
+  playerLevel: number;
+  ds: DataStore;
+  /** When set, mining/herb/skinning mats dump to the matching crafter even with no recipe. */
+  playerSkills?: Character['skills'];
+}
+
+/** Squad plus benched roster, first-seen order. Raid-bench bodies stay out. */
+export function goodsCompanions(state: {
+  squad?: readonly Companion[] | null;
+  botRoster?: Record<string, Companion> | null;
+}): Companion[] {
+  const seen = new Set<string>();
+  const out: Companion[] = [];
+  for (const c of state.squad ?? []) {
+    if (seen.has(c.id)) continue;
+    seen.add(c.id);
+    out.push(c);
+  }
+  for (const c of Object.values(state.botRoster ?? {})) {
+    if (seen.has(c.id)) continue;
+    seen.add(c.id);
+    out.push(c);
+  }
+  return out;
+}
+
+/** How many of `item` still fit in `inv` under `cap` (partial stacks first). */
+function spaceFor(inv: Inventory, item: number, maxStack: number, cap: number): number {
+  const capStack = Math.max(1, maxStack);
+  let room = 0;
+  for (const s of inv.stacks) {
+    if (s.item === item && s.count < capStack && !hasIdentity(s)) {
+      room += capStack - s.count;
+    }
+  }
+  room += freeSlots(inv, cap) * capStack;
+  return room;
+}
+
+function recipeIsUsable(
+  recipe: RecipeDef,
+  skillCurrent: number,
+  known: ReadonlySet<number>,
+): boolean {
+  if (skillCurrent < recipe.orange) return false;
+  if (known.has(recipe.id)) return true;
+  return recipe.source === 'trainer' || recipe.source === 'vendor';
+}
+
+function reagentEntriesFor(
+  skills: ReturnType<typeof companionSkillMap>,
+  knownRecipes: readonly number[] | undefined,
+  ds: DataStore,
+): Set<number> {
+  const known = new Set(knownRecipes ?? []);
+  const out = new Set<number>();
+  for (const recipe of ds.recipes()) {
+    const sk = skills[recipe.skill];
+    if (!sk || !recipeIsUsable(recipe, sk.current, known)) continue;
+    for (const rg of recipe.reagents) {
+      if (rg.item > 0) out.add(rg.item);
+    }
+  }
+  return out;
+}
+
+function miningMaterialEntries(ds: DataStore): Set<number> {
+  const out = new Set<number>();
+  for (const recipe of ds.recipes()) {
+    if (recipe.skill !== 'mining') continue;
+    if (recipe.product.item > 0) out.add(recipe.product.item);
+    for (const rg of recipe.reagents) {
+      if (rg.item > 0) out.add(rg.item);
+    }
+  }
+  return out;
+}
+
+function gatherMaterialSets(
+  ds: DataStore,
+  playerLines: Set<GatherLine>,
+): Record<GatherLine, Set<number>> {
+  const mining = playerLines.has('mining') ? miningMaterialEntries(ds) : new Set<number>();
+  const herbalism = new Set<number>();
+  const skinning = new Set<number>();
+  if (playerLines.size === 0) return { mining, herbalism, skinning };
+  for (const n of ds.gatherNodes()) {
+    if (n.skill !== 'mining' && n.skill !== 'herbalism' && n.skill !== 'skinning') continue;
+    if (!playerLines.has(n.skill)) continue;
+    const dest = n.skill === 'mining' ? mining : n.skill === 'herbalism' ? herbalism : skinning;
+    for (const y of n.yield) {
+      if (y.item > 0) dest.add(y.item);
+    }
+  }
+  return { mining, herbalism, skinning };
+}
+
+function playerGatherLines(skills: Character['skills'] | undefined): Set<GatherLine> {
+  const out = new Set<GatherLine>();
+  if (!skills) return out;
+  if (skills.mining) out.add('mining');
+  if (skills.herbalism) out.add('herbalism');
+  if (skills.skinning) out.add('skinning');
+  return out;
+}
+
+function gatherCraftsOf(skills: ReturnType<typeof companionSkillMap>): Record<GatherLine, boolean> {
+  return {
+    mining: !!(skills.blacksmithing || skills.engineering),
+    herbalism: !!skills.alchemy,
+    skinning: !!skills.leatherworking,
+  };
+}
+
+function gatherLineOf(
+  it: { entry: number; itemClass?: number; itemSubclass?: number; questItem?: boolean },
+  sets: Record<GatherLine, Set<number>>,
+): GatherLine | null {
+  if (it.itemClass !== ITEM_CLASS_TRADE_GOODS || it.questItem) return null;
+  if (it.itemSubclass === ITEM_SUBCLASS_METAL_STONE || sets.mining.has(it.entry)) return 'mining';
+  if (it.itemSubclass === ITEM_SUBCLASS_HERB || sets.herbalism.has(it.entry)) return 'herbalism';
+  if (it.itemSubclass === ITEM_SUBCLASS_LEATHER || sets.skinning.has(it.entry)) return 'skinning';
+  return null;
+}
+
+type GoodsMode = 'all' | 'gather';
+
+type Bucket = {
+  id: string;
+  name: string;
+  reagents: Set<number>;
+  crafts: Record<GatherLine, boolean>;
+  bags: Inventory;
+  cap: number;
+};
+
+function planGifts(args: PlanSendTradeGoodsArgs, mode: GoodsMode): TradeGoodsGift[] {
+  const { inventory, squad, playerLevel, ds, playerSkills } = args;
+  if (!squad.length) return [];
+
+  const remaining = new Map<number, number>();
+  const order: number[] = [];
+  for (const stk of inventory.stacks) {
+    const it = ds.item(stk.item);
+    if (!it || it.itemClass !== ITEM_CLASS_TRADE_GOODS || it.questItem) continue;
+    if (!remaining.has(stk.item)) order.push(stk.item);
+    remaining.set(stk.item, (remaining.get(stk.item) ?? 0) + stk.count);
+  }
+  if (!order.length) return [];
+
+  const playerLines = playerGatherLines(playerSkills);
+  const gatherSets = gatherMaterialSets(ds, playerLines);
+  const buckets: Bucket[] = [];
+  for (const comp of squad) {
+    if (comp.mission) continue;
+    const lvl = companionLevel(comp, playerLevel);
+    const skills = companionSkillMap(comp, lvl);
+    const crafts = gatherCraftsOf(skills);
+    const reagents = mode === 'gather' ? new Set<number>() : reagentEntriesFor(skills, comp.knownRecipes, ds);
+    if (mode === 'gather') {
+      if (!crafts.mining && !crafts.herbalism && !crafts.skinning) continue;
+    } else if (reagents.size === 0 && !crafts.mining && !crafts.herbalism && !crafts.skinning) {
+      continue;
+    }
+    const shell = companionCharacter(comp, lvl, ds);
+    buckets.push({
+      id: comp.id,
+      name: comp.name,
+      reagents,
+      crafts,
+      bags: { stacks: (comp.bags ?? emptyInventory()).stacks.map((s) => ({ ...s })) },
+      cap: bagCapacity(shell, ds),
+    });
+  }
+  if (!buckets.length) return [];
+
+  const gifts: TradeGoodsGift[] = [];
+  for (const entry of order) {
+    let left = remaining.get(entry) ?? 0;
+    if (left <= 0) continue;
+    const it = ds.item(entry);
+    if (!it) continue;
+    const itemLine = gatherLineOf(it, gatherSets);
+    const stackable = Math.max(1, it.stackable || 1);
+    for (const b of buckets) {
+      if (left <= 0) break;
+      const recipeHit = mode !== 'gather' && b.reagents.has(entry);
+      const gatherHit = !!itemLine && playerLines.has(itemLine) && b.crafts[itemLine];
+      if (!recipeHit && !gatherHit) continue;
+      const n = Math.min(left, spaceFor(b.bags, entry, stackable, b.cap));
+      if (n <= 0) continue;
+      b.bags = addItem(b.bags, entry, n, stackable);
+      left -= n;
+      gifts.push({ companionId: b.id, companionName: b.name, entry, qty: n });
+    }
+  }
+  return gifts;
+}
+
+// Greedy squad-order allocation: each player trade-good stack goes to the first companion who can craft
+// with it and still has room, then the next, until gone.
+export function planSendTradeGoods(args: PlanSendTradeGoodsArgs): TradeGoodsGift[] {
+  return planGifts(args, 'all');
+}
+
+/** Gather mats only — mining → BS/eng, herbs → alchemy, leather → LW. */
+export function planSendGatherGoods(args: PlanSendTradeGoodsArgs): TradeGoodsGift[] {
+  return planGifts(args, 'gather');
+}
+
+export function tradeGoodsGiftCount(rows: readonly TradeGoodsGift[]): number {
+  let n = 0;
+  for (const g of rows) n += g.qty;
+  return n;
+}
+
+export function dumpGatherGoodsToCompanions(
+  args: PlanSendTradeGoodsArgs & { log?: (msg: string) => void },
+): { inventory: Inventory; moved: number } {
+  const gifts = planSendGatherGoods(args);
+  if (!gifts.length) return { inventory: args.inventory, moved: 0 };
+  const byId = new Map<string, Companion>();
+  for (const c of args.squad) byId.set(c.id, c);
+  let inv = args.inventory;
+  let moved = 0;
+  for (const g of gifts) {
+    const comp = byId.get(g.companionId);
+    if (!comp) continue;
+    const it = args.ds.item(g.entry);
+    if (!it) continue;
+    const lvl = companionLevel(comp, args.playerLevel);
+    const cap = bagCapacity(companionCharacter(comp, lvl, args.ds), args.ds);
+    const xfer = transferItem(inv, comp.bags ?? emptyInventory(), g.entry, g.qty, it.stackable ?? 1, cap);
+    if (xfer.moved <= 0) continue;
+    inv = xfer.from;
+    comp.bags = xfer.to;
+    moved += xfer.moved;
+    args.log?.(`You give ${it.name}${xfer.moved > 1 ? ` ×${xfer.moved}` : ''} to ${comp.name}.`);
+  }
+  return { inventory: inv, moved };
+}
+
+export function dumpGatherGoodsFromState(
+  state: {
+    inventory: Inventory;
+    squad?: readonly Companion[] | null;
+    botRoster?: Record<string, Companion> | null;
+    char: { level: number; skills: Character['skills'] };
+  },
+  ds: DataStore,
+  log?: (msg: string) => void,
+): number {
+  const result = dumpGatherGoodsToCompanions({
+    inventory: state.inventory,
+    squad: goodsCompanions(state),
+    playerLevel: state.char.level,
+    playerSkills: state.char.skills,
+    ds,
+    log,
+  });
+  state.inventory = result.inventory;
+  return result.moved;
+}