@jgengine/core 0.30.0 → 0.32.0

package/dist/loot/haul.d.ts

@@ -0,0 +1,78 @@
+import { type WeightLookup } from "../inventory/carryLoad.js";
+import type { InventorySet, InventoryState } from "../inventory/inventoryModel.js";
+import type { ItemStack } from "../inventory/storageTier.js";
+import type { KeyValueStorage } from "../game/keyValueStore.js";
+/** What a carry attempt returns: the new load, or the rule that refused it. */
+export type CarryOutcome = {
+    ok: true;
+    mass: number;
+    remaining: number;
+} | {
+    ok: false;
+    reason: "over-capacity" | "no-space" | "invalid-count";
+    mass: number;
+    remaining: number;
+};
+/** Stacks moved between a run and its stash, or lost when the run fails. */
+export interface HaulTransfer {
+    /** Stacks that reached the stash, or were lost, in slot order. */
+    stacks: readonly ItemStack[];
+    /** Stacks the stash had no room for; they stay in the run inventory. */
+    refused: readonly ItemStack[];
+}
+/** Detached run and stash contents, for a save or a debug readout. */
+export interface RunHaulState {
+    run: InventoryState;
+    stash: InventoryState;
+}
+/** What a run haul needs: two inventories, a weight rule and an optional save cell. */
+export interface RunHaulConfig<TId extends string> {
+    /** The keyed inventory set that owns both the run and stash inventories. */
+    inventories: InventorySet<TId>;
+    /** Inventory carried during the run; its contents are lost on `fail`. */
+    runId: TId;
+    /** Inventories that survive a failed run; left out of the carry weight. */
+    stashId: TId;
+    /** Per-instance mass in the caller's weight unit; unknown ids weigh 0 only if the caller says so. */
+    weightOf: WeightLookup;
+    /** Carrying capacity in the same unit as `weightOf`. */
+    capacity: number;
+    /** Worn item ids, one unit each; they weigh against capacity. */
+    worn?: readonly string[];
+    /** Fraction of worn weight that counts (default `1`). */
+    wornFactor?: number;
+    /** Save backend for the stash; `null` keeps it in memory for the session only. */
+    storage?: KeyValueStorage | null;
+    /** Storage key; defaults to `"jgengine.items.stash"`. */
+    key?: string;
+}
+/** A run's carried loot and the stash that outlives it. */
+export interface RunHaul {
+    /** Add `count` of `itemId` to the run if the carrier can take its weight and there is slot room. */
+    carry(itemId: string, count?: number): CarryOutcome;
+    /** Move everything the stash fits out of the run and save; returns what moved and what did not. */
+    bank(): HaulTransfer;
+    /** Discard the run's haul and save the untouched stash; returns the lost stacks. */
+    fail(): HaulTransfer;
+    /** Load the stash from storage; false when absent or malformed. */
+    load(): boolean;
+    /** Write the stash to storage. */
+    save(): void;
+    state(): RunHaulState;
+    /** Replace run and stash contents; false without mutation when either is malformed. */
+    restore(next: RunHaulState): boolean;
+    /** Carried and stashed mass plus capacity left, for the HUD. */
+    mass(): {
+        run: number;
+        stash: number;
+        remaining: number;
+    };
+}
+/**
+ * A run's haul beside a persistent stash. Carrying is gated by the shared encumbrance rules;
+ * `bank` moves what the stash fits and saves; `fail` throws the run's haul away and leaves the
+ * stash as it was. The game decides when a run succeeds or fails and calls one of them.
+ *
+ * @capability item-run-haul carry loot with a weight gate, bank it into a persistent stash, or lose it when the run fails
+ */
+export declare function createRunHaul<TId extends string>(config: RunHaulConfig<TId>): RunHaul;

package/dist/loot/haul.js

@@ -0,0 +1,126 @@
+import { canCarry, characterLoad } from "../inventory/carryLoad.js";
+const DEFAULT_KEY = "jgengine.items.stash";
+function emptyLike(state) {
+    return { slots: new Array(state.slots.length).fill(null) };
+}
+function stacksOf(state) {
+    const out = [];
+    for (const slot of state.slots)
+        if (slot !== null)
+            out.push({ itemId: slot.itemId, count: slot.count });
+    return out;
+}
+/**
+ * A run's haul beside a persistent stash. Carrying is gated by the shared encumbrance rules;
+ * `bank` moves what the stash fits and saves; `fail` throws the run's haul away and leaves the
+ * stash as it was. The game decides when a run succeeds or fails and calls one of them.
+ *
+ * @capability item-run-haul carry loot with a weight gate, bank it into a persistent stash, or lose it when the run fails
+ */
+export function createRunHaul(config) {
+    const { inventories, runId, stashId } = config;
+    const key = config.key ?? DEFAULT_KEY;
+    const storage = config.storage ?? null;
+    const runMass = () => characterLoad({
+        carried: [inventories.state(runId)],
+        worn: config.worn,
+        wornFactor: config.wornFactor,
+        weightOf: config.weightOf,
+        capacity: config.capacity,
+    });
+    const persist = () => {
+        if (storage === null)
+            return;
+        try {
+            storage.setItem(key, JSON.stringify({ stash: inventories.snapshot()[stashId] }));
+        }
+        catch {
+            // A full or blocked save cell must not lose the live stash; the next save retries.
+        }
+    };
+    return {
+        carry(itemId, count = 1) {
+            const load = runMass();
+            if (!Number.isFinite(count) || count <= 0) {
+                return { ok: false, reason: "invalid-count", mass: load.mass, remaining: load.remaining };
+            }
+            const added = config.weightOf(itemId) * count;
+            if (!canCarry(load, added)) {
+                return { ok: false, reason: "over-capacity", mass: load.mass, remaining: load.remaining };
+            }
+            const put = inventories.put(runId, itemId, count);
+            if (put.status !== "ok") {
+                return { ok: false, reason: "no-space", mass: load.mass, remaining: load.remaining };
+            }
+            const after = runMass();
+            return { ok: true, mass: after.mass, remaining: after.remaining };
+        },
+        bank() {
+            const moved = [];
+            const refused = [];
+            const run = inventories.state(runId);
+            for (let slot = 0; slot < run.slots.length; slot += 1) {
+                const stack = inventories.state(runId).slots[slot];
+                if (stack === null)
+                    continue;
+                const put = inventories.put(stashId, stack.itemId, stack.count);
+                if (put.status !== "ok") {
+                    refused.push({ itemId: stack.itemId, count: stack.count });
+                    continue;
+                }
+                inventories.take(runId, stack.itemId, stack.count);
+                moved.push({ itemId: stack.itemId, count: stack.count });
+            }
+            persist();
+            return { stacks: moved, refused };
+        },
+        fail() {
+            const lost = stacksOf(inventories.state(runId));
+            inventories.replaceState(runId, emptyLike(inventories.state(runId)));
+            persist();
+            return { stacks: lost, refused: [] };
+        },
+        load() {
+            if (storage === null)
+                return false;
+            try {
+                const raw = storage.getItem(key);
+                if (raw === null)
+                    return false;
+                const saved = JSON.parse(raw);
+                if (saved === null || typeof saved !== "object" || saved.stash === undefined)
+                    return false;
+                const next = inventories.snapshot();
+                next[stashId] = saved.stash;
+                return inventories.restore(next);
+            }
+            catch {
+                return false;
+            }
+        },
+        save: persist,
+        state() {
+            const saved = inventories.snapshot();
+            return { run: saved[runId], stash: saved[stashId] };
+        },
+        restore(next) {
+            const attempt = inventories.snapshot();
+            attempt[runId] = next.run;
+            attempt[stashId] = next.stash;
+            return inventories.restore(attempt);
+        },
+        mass() {
+            const load = runMass();
+            let stash = 0;
+            for (const slot of inventories.state(stashId).slots) {
+                if (slot !== null)
+                    stash += config.weightOf(slot.itemId) * slot.count;
+            }
+            return {
+                run: load.carriedMass,
+                stash,
+                remaining: load.remaining,
+            };
+        },
+    };
+}

package/dist/loot/lootGen.d.ts

@@ -13,6 +13,10 @@ export interface LootPartDef extends PartDef {
 export interface LootBaseDef extends ItemBaseDef {
     /** Relative pick weight among bases a manufacturer can produce (default `1`). */
     weight?: number;
+    /** Lowest item level a roll may pick this base at; omitted means every level. */
+    minLevel?: number;
+    /** Mass at item level 1 in the caller's weight unit (default `1`); grows 10% per level. */
+    mass?: number;
     /** Free-form tags for caller filters and UI. */
     tags?: readonly string[];
     /** Mount slots a roll fills; every declared slot receives one part. */
@@ -69,6 +73,8 @@ export interface LootItem {
     parts: readonly LootInstalledPart[];
     affixes: readonly RolledAffix[];
     stats: Readonly<Record<string, number>>;
+    /** Carried mass from the base def at this level; absent on saves made before mass existed. */
+    mass?: number;
 }
 /** Pin any part of a roll; omitted fields are drawn from the catalog. */
 export interface LootRollOptions {
@@ -79,7 +85,7 @@ export interface LootRollOptions {
     rarity?: string;
 }
 /** A defect found by {@link validateLootItem}. */
-export type LootIssueCode = "invalid-level" | "unknown-base" | "unknown-manufacturer" | "manufacturer-base" | "unknown-rarity" | "duplicate-slot" | "unknown-slot" | "missing-slot-part" | "unknown-part" | "part-category" | "unknown-affix" | "duplicate-affix" | "invalid-affix" | "non-finite-stat" | "empty-name";
+export type LootIssueCode = "invalid-level" | "unknown-base" | "level-gated-base" | "unknown-manufacturer" | "manufacturer-base" | "unknown-rarity" | "duplicate-slot" | "unknown-slot" | "missing-slot-part" | "unknown-part" | "part-category" | "unknown-affix" | "duplicate-affix" | "invalid-affix" | "non-finite-stat" | "invalid-mass" | "empty-name";
 /** One reason a rolled item is not legal against its catalog, with the offending value named. */
 export interface LootValidationIssue {
     code: LootIssueCode;

package/dist/loot/lootGen.js

@@ -18,6 +18,10 @@ export function assertLootCatalog(catalog) {
         baseIds.add(base.id);
         if (base.weight !== undefined)
             check(base.weight > 0, `Loot base "${base.id}" weight must be positive`);
+        if (base.minLevel !== undefined)
+            check(Number.isInteger(base.minLevel) && base.minLevel >= 1, `Loot base "${base.id}" minLevel must be an integer >= 1`);
+        if (base.mass !== undefined)
+            check(Number.isFinite(base.mass) && base.mass > 0, `Loot base "${base.id}" mass must be positive`);
     }
     const poolIds = new Set();
     const affixIds = new Set();
@@ -29,6 +33,8 @@ export function assertLootCatalog(catalog) {
             check(!affixIds.has(affix.id), `Loot affix "${affix.id}" is declared twice`);
             affixIds.add(affix.id);
             check(affix.weight > 0, `Loot affix "${affix.id}" weight must be positive`);
+            if (affix.minLevel !== undefined)
+                check(Number.isInteger(affix.minLevel) && affix.minLevel >= 1, `Loot affix "${affix.id}" minLevel must be an integer >= 1`);
             if (typeof affix.roll === "number") {
                 check(Number.isFinite(affix.roll), `Loot affix "${affix.id}" roll must be finite`);
                 if (affix.op === "mul")
@@ -148,7 +154,7 @@ function weighted(rng, items, weightOf, field) {
         throw new Error(`Loot catalog has no eligible ${field}`);
     return picked;
 }
-function candidateAffixes(catalog, base, rarity) {
+function candidateAffixes(catalog, base, rarity, level) {
     const out = [];
     for (const poolId of base.pools) {
         if (rarity.pools !== undefined && !rarity.pools.includes(poolId))
@@ -156,8 +162,11 @@ function candidateAffixes(catalog, base, rarity) {
         const pool = catalog.pools.find((entry) => entry.id === poolId);
         if (pool === undefined)
             continue;
-        for (const affix of pool.affixes)
+        for (const affix of pool.affixes) {
+            if (affix.minLevel !== undefined && affix.minLevel > level)
+                continue;
             out.push({ affix, poolId });
+        }
     }
     return out;
 }
@@ -192,11 +201,13 @@ export function rollLoot(catalog, rng, options = {}) {
     const manufacturer = options.manufacturer === undefined
         ? weighted(rng, catalog.manufacturers.filter((maker) => options.baseId === undefined || maker.bases === undefined || maker.bases.includes(options.baseId)), (maker) => maker.weight ?? 1, "manufacturer")
         : findOrThrow(catalog.manufacturers, options.manufacturer, "manufacturer");
-    const basePool = catalog.bases.filter((base) => manufacturer.bases === undefined || manufacturer.bases.includes(base.id));
+    const basePool = catalog.bases.filter((base) => (base.minLevel === undefined || base.minLevel <= level)
+        && (manufacturer.bases === undefined || manufacturer.bases.includes(base.id)));
     const base = options.baseId === undefined
         ? weighted(rng, basePool, (entry) => entry.weight ?? 1, "base")
         : findOrThrow(catalog.bases, options.baseId, "base");
     check(manufacturer.bases === undefined || manufacturer.bases.includes(base.id), `Loot manufacturer "${manufacturer.id}" does not produce base "${base.id}"`);
+    check(base.minLevel === undefined || base.minLevel <= level, `Loot base "${base.id}" needs item level ${base.minLevel}, got ${level}`);
     const rarity = options.rarity === undefined
         ? weighted(rng, catalog.rarities, (tier) => tier.weight, "rarity")
         : findOrThrow(catalog.rarities, options.rarity, "rarity");
@@ -206,7 +217,7 @@ export function rollLoot(catalog, rng, options = {}) {
         const part = weighted(rng, eligible, (entry) => entry.weight ?? 1, `part for slot "${slot.id}"`);
         parts.push({ slotId: slot.id, partId: part.id, category: part.category });
     }
-    const candidates = candidateAffixes(catalog, base, rarity);
+    const candidates = candidateAffixes(catalog, base, rarity, level);
     const favors = manufacturer.favoredPools ?? [];
     const favorWeight = manufacturer.favoredWeight ?? 3;
     const remaining = candidates.slice();
@@ -254,6 +265,7 @@ export function rollLoot(catalog, rng, options = {}) {
     }
     for (const stat of Object.keys(stats))
         stats[stat] = Math.round(stats[stat] * 1000) / 1000;
+    const mass = Math.round((base.mass ?? 1) * (1 + 0.1 * (level - 1)) * 100) / 100;
     return {
         baseId: base.id,
         manufacturer: manufacturer.id,
@@ -263,6 +275,7 @@ export function rollLoot(catalog, rng, options = {}) {
         parts,
         affixes,
         stats,
+        mass,
     };
 }
 /**
@@ -280,6 +293,9 @@ export function validateLootItem(item, catalog) {
     if (base === undefined) {
         issues.push({ code: "unknown-base", detail: `base "${item.baseId}" is not in the catalog` });
     }
+    else if (base.minLevel !== undefined && base.minLevel > item.level) {
+        issues.push({ code: "level-gated-base", detail: `base "${base.id}" needs item level ${base.minLevel}, got ${item.level}` });
+    }
     const manufacturer = catalog.manufacturers.find((entry) => entry.id === item.manufacturer);
     if (manufacturer === undefined) {
         issues.push({ code: "unknown-manufacturer", detail: `manufacturer "${item.manufacturer}" is not in the catalog` });
@@ -316,7 +332,7 @@ export function validateLootItem(item, catalog) {
         if (!seenSlots.has(slot.id))
             issues.push({ code: "missing-slot-part", detail: `slot "${slot.id}" has no part` });
     }
-    const allowed = base === undefined || rarity === undefined ? null : candidateAffixes(catalog, base, rarity);
+    const allowed = base === undefined || rarity === undefined ? null : candidateAffixes(catalog, base, rarity, item.level);
     const seenAffixes = new Set();
     for (const affix of item.affixes) {
         if (seenAffixes.has(affix.id)) {
@@ -335,6 +351,9 @@ export function validateLootItem(item, catalog) {
         if (!Number.isFinite(value))
             issues.push({ code: "non-finite-stat", detail: `stat "${stat}" is ${String(value)}` });
     }
+    if (item.mass !== undefined && (!Number.isFinite(item.mass) || item.mass <= 0)) {
+        issues.push({ code: "invalid-mass", detail: `mass ${String(item.mass)} is not a positive number` });
+    }
     if (item.name.trim() === "")
         issues.push({ code: "empty-name", detail: "item has no name" });
     return issues;

package/dist/loot/salvage.d.ts

@@ -0,0 +1,74 @@
+/** Where an item instance stands: still usable, broken down, or sold. */
+export type ItemLifecycle = "owned" | "salvaged" | "sold";
+/** Items that have left play, keyed by instance id; anything absent is still `owned`. */
+export type ItemLedgerState = Readonly<Record<string, Exclude<ItemLifecycle, "owned">>>;
+/**
+ * One record of what happened to rolled item instances. Every path that removes an item - salvage,
+ * sale, granting a duplicate - claims it here first, so a second claim returns false and the item
+ * cannot be equipped, sold or broken down twice.
+ */
+export interface ItemLedger {
+    status(id: string): ItemLifecycle;
+    /** True only while the instance is `owned`; a salvaged or sold item is no longer usable. */
+    canUse(id: string): boolean;
+    /** Claim `id` for `salvaged` or `sold`; false when it already left play. */
+    spend(id: string, how: Exclude<ItemLifecycle, "owned">): boolean;
+    snapshot(): ItemLedgerState;
+    /** Replace the ledger; false without mutation when an entry names an unknown outcome. */
+    restore(next: ItemLedgerState): boolean;
+    reset(): void;
+}
+/**
+ * Build an item ledger. Ids are consumed once: the first successful {@link ItemLedger.spend} wins,
+ * every later call fails, which is what makes salvage and sale mutually exclusive.
+ *
+ * @capability item-ledger track which rolled item instances are still owned, salvaged or sold
+ */
+export declare function createItemLedger(initial?: ItemLedgerState): ItemLedger;
+/** The currency and amount one salvage yields. `currency` is the game's key, never interpreted. */
+export interface SalvageYield {
+    currency: string;
+    amount: number;
+}
+/** What a broken-down item is worth: a game-authored currency, rate and per-rarity multiplier. */
+export interface SalvageTable {
+    /** Wallet currency key the yield is granted in, e.g. `"cores"`. */
+    currency: string;
+    /** Units paid per item level at multiplier `1`. */
+    perLevel: number;
+    /** Multiplier per rarity id; omitted rarities use `1`. */
+    rarityMultiplier?: Readonly<Record<string, number>>;
+    /** Floor for the yield (default `1`). */
+    minimum?: number;
+}
+/**
+ * The yield an item of this level and rarity breaks down into. The formula is
+ * `round(perLevel x level x rarityMultiplier)`, floored by `minimum`, so the same item always yields
+ * the same amount and a higher level never yields less.
+ *
+ * @capability item-salvage-value compute the currency an item of a level and rarity breaks down into
+ */
+export declare function salvageValue(item: Pick<ItemDropLike, "level" | "rarity">, table: SalvageTable): SalvageYield;
+/** The fields salvage reads; an `ItemDrop` from `./drop` satisfies it. */
+export interface ItemDropLike {
+    id: string;
+    level: number;
+    rarity: string;
+}
+/** Salvage outcome: the yield, or the reason the instance could not be broken down. */
+export type SalvageResult = {
+    ok: true;
+    id: string;
+    yield: SalvageYield;
+} | {
+    ok: false;
+    reason: "already-spent" | "invalid-item";
+};
+/**
+ * Break one item down through its ledger. The ledger is claimed before the yield is computed, so a
+ * salvaged item cannot be salvaged, equipped or sold again; pass the game's own wallet update from
+ * `yield`.
+ *
+ * @capability item-salvage break an item down for the currency its level and rarity say, once
+ */
+export declare function salvageItem(item: ItemDropLike, table: SalvageTable, ledger: ItemLedger): SalvageResult;

package/dist/loot/salvage.js

@@ -0,0 +1,68 @@
+/**
+ * Build an item ledger. Ids are consumed once: the first successful {@link ItemLedger.spend} wins,
+ * every later call fails, which is what makes salvage and sale mutually exclusive.
+ *
+ * @capability item-ledger track which rolled item instances are still owned, salvaged or sold
+ */
+export function createItemLedger(initial = {}) {
+    const spent = new Map();
+    for (const [id, how] of Object.entries(initial)) {
+        if (how === "salvaged" || how === "sold")
+            spent.set(id, how);
+    }
+    return {
+        status: (id) => spent.get(id) ?? "owned",
+        canUse: (id) => !spent.has(id),
+        spend(id, how) {
+            if (spent.has(id))
+                return false;
+            spent.set(id, how);
+            return true;
+        },
+        snapshot: () => Object.fromEntries(spent),
+        restore(next) {
+            if (next === null || typeof next !== "object")
+                return false;
+            const staged = new Map();
+            for (const [id, how] of Object.entries(next)) {
+                if (how !== "salvaged" && how !== "sold")
+                    return false;
+                if (id.trim() === "")
+                    return false;
+                staged.set(id, how);
+            }
+            spent.clear();
+            for (const [id, how] of staged)
+                spent.set(id, how);
+            return true;
+        },
+        reset: () => spent.clear(),
+    };
+}
+/**
+ * The yield an item of this level and rarity breaks down into. The formula is
+ * `round(perLevel x level x rarityMultiplier)`, floored by `minimum`, so the same item always yields
+ * the same amount and a higher level never yields less.
+ *
+ * @capability item-salvage-value compute the currency an item of a level and rarity breaks down into
+ */
+export function salvageValue(item, table) {
+    const multiplier = table.rarityMultiplier?.[item.rarity] ?? 1;
+    const amount = Math.max(table.minimum ?? 1, Math.round(table.perLevel * Math.max(1, item.level) * multiplier));
+    return { currency: table.currency, amount };
+}
+/**
+ * Break one item down through its ledger. The ledger is claimed before the yield is computed, so a
+ * salvaged item cannot be salvaged, equipped or sold again; pass the game's own wallet update from
+ * `yield`.
+ *
+ * @capability item-salvage break an item down for the currency its level and rarity say, once
+ */
+export function salvageItem(item, table, ledger) {
+    if (!Number.isFinite(item.level) || item.level < 1 || item.id.trim() === "") {
+        return { ok: false, reason: "invalid-item" };
+    }
+    if (!ledger.spend(item.id, "salvaged"))
+        return { ok: false, reason: "already-spent" };
+    return { ok: true, id: item.id, yield: salvageValue(item, table) };
+}

package/dist/loot/vendor.d.ts

@@ -0,0 +1,76 @@
+import type { ShopStock, ShopStockEntry } from "../economy/shopStock.js";
+import { type LootCatalog, type LootItem } from "./lootGen.js";
+import type { ItemDrop } from "./drop.js";
+/** How a vendor price is derived from an item: a base, a per-level rate and a rarity multiplier. */
+export interface VendorPriceRule {
+    /** Wallet currency key the stock is priced in, e.g. `"credits"`. */
+    currency: string;
+    /** Price floor at level 1 before the rarity multiplier. */
+    base: number;
+    /** Added per item level. */
+    perLevel: number;
+    /** Multiplier per rarity id; omitted rarities use `1`. */
+    rarityMultiplier?: Readonly<Record<string, number>>;
+    /** Buy-back fraction of the buy price; omitted means the vendor does not buy this stock back. */
+    sellFactor?: number;
+}
+/** One stocked item and the shop entry that prices it. */
+export interface VendorOffer {
+    item: ItemDrop;
+    entry: ShopStockEntry;
+}
+/** What stocking a vendor reads: the roll catalog, a seeded rng and the pricing policy. */
+export interface StockVendorOptions {
+    catalog: LootCatalog;
+    /** Injected random source; pass a seeded generator so the shelf is reproducible. */
+    rng: () => number;
+    /** Item level rolled onto the shelf. */
+    level: number;
+    /** How many items to roll. */
+    count: number;
+    price: VendorPriceRule;
+    /** Stable id prefix for this vendor, e.g. `"harbor.guns"`. */
+    idPrefix: string;
+    /** Whole units on hand; `null` means unlimited (default `1`). */
+    qty?: number | null;
+}
+/**
+ * The price of one item under a `VendorPriceRule`: `round(base + perLevel x level)` times the
+ * rarity multiplier, never below 1. Sell-back is `floor(price x sellFactor)` when the rule sets one.
+ *
+ * @capability item-vendor-price price an item from its level and rarity through the economy's currency
+ */
+export declare function itemPrice(item: Pick<LootItem, "level" | "rarity">, rule: VendorPriceRule): {
+    buy: number;
+    sell: number | null;
+};
+/**
+ * Roll a vendor's shelf and add it to an existing {@link ShopStock}. Entries added by a previous
+ * call with the same `idPrefix` are removed first, so a refresh replaces the shelf instead of
+ * throwing on duplicate ids. Buying, selling and wallet charging stay in the economy owner.
+ *
+ * @capability item-vendor stock a vendor with rolled items priced through the shared economy
+ */
+export declare function stockVendor(shop: ShopStock, options: StockVendorOptions): VendorOffer[];
+/** Where a vendor shelf stands: the run number it was last stocked on. */
+export interface VendorRotationState {
+    refreshedAt: number;
+}
+/** A run-count refresh rule; the game owns how many runs between restocks. */
+export interface VendorRotation {
+    /** True when `run` is at least `everyRuns` past the last refresh. */
+    due(run: number): boolean;
+    /** Record that the shelf was stocked on `run`. */
+    mark(run: number): void;
+    state(): VendorRotationState;
+    restore(next: VendorRotationState): boolean;
+    reset(run?: number): void;
+}
+/**
+ * A restock rule the game authors as "every N runs". It only answers when a refresh is due; the
+ * game calls {@link stockVendor} and then `mark`. No timer, so a paused or reloaded save keeps the
+ * same shelf until the run count moves.
+ *
+ * @capability item-vendor-rotation decide when a vendor's shelf is due for a restock
+ */
+export declare function createVendorRotation(everyRuns: number, start?: number): VendorRotation;

package/dist/loot/vendor.js

@@ -0,0 +1,72 @@
+import { rollLoot } from "./lootGen.js";
+/**
+ * The price of one item under a `VendorPriceRule`: `round(base + perLevel x level)` times the
+ * rarity multiplier, never below 1. Sell-back is `floor(price x sellFactor)` when the rule sets one.
+ *
+ * @capability item-vendor-price price an item from its level and rarity through the economy's currency
+ */
+export function itemPrice(item, rule) {
+    const multiplier = rule.rarityMultiplier?.[item.rarity] ?? 1;
+    const buy = Math.max(1, Math.round((rule.base + rule.perLevel * Math.max(1, item.level)) * multiplier));
+    const sell = rule.sellFactor === undefined ? null : Math.max(0, Math.floor(buy * rule.sellFactor));
+    return { buy, sell };
+}
+/**
+ * Roll a vendor's shelf and add it to an existing {@link ShopStock}. Entries added by a previous
+ * call with the same `idPrefix` are removed first, so a refresh replaces the shelf instead of
+ * throwing on duplicate ids. Buying, selling and wallet charging stay in the economy owner.
+ *
+ * @capability item-vendor stock a vendor with rolled items priced through the shared economy
+ */
+export function stockVendor(shop, options) {
+    for (const entry of shop.list()) {
+        if (entry.id.startsWith(`${options.idPrefix}:`))
+            shop.remove(entry.id);
+    }
+    const offers = [];
+    for (let i = 0; i < Math.max(0, Math.floor(options.count)); i += 1) {
+        const item = {
+            ...rollLoot(options.catalog, options.rng, { level: options.level }),
+            id: `${options.idPrefix}:${i}`,
+        };
+        const price = itemPrice(item, options.price);
+        const entry = {
+            id: item.id,
+            kind: item.baseId,
+            price: { currency: options.price.currency, amount: price.buy },
+            qty: options.qty === undefined ? 1 : options.qty,
+            ...(price.sell === null ? {} : { sellPrice: { currency: options.price.currency, amount: price.sell } }),
+        };
+        shop.add(entry);
+        offers.push({ item, entry });
+    }
+    return offers;
+}
+/**
+ * A restock rule the game authors as "every N runs". It only answers when a refresh is due; the
+ * game calls {@link stockVendor} and then `mark`. No timer, so a paused or reloaded save keeps the
+ * same shelf until the run count moves.
+ *
+ * @capability item-vendor-rotation decide when a vendor's shelf is due for a restock
+ */
+export function createVendorRotation(everyRuns, start = 0) {
+    if (!Number.isFinite(everyRuns) || everyRuns < 1)
+        throw new RangeError("everyRuns must be >= 1");
+    let refreshedAt = start;
+    return {
+        due: (run) => run - refreshedAt >= everyRuns,
+        mark: (run) => {
+            refreshedAt = run;
+        },
+        state: () => ({ refreshedAt }),
+        restore(next) {
+            if (next === null || typeof next !== "object" || !Number.isFinite(next.refreshedAt))
+                return false;
+            refreshedAt = next.refreshedAt;
+            return true;
+        },
+        reset(run = 0) {
+            refreshedAt = run;
+        },
+    };
+}

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.30.0";
+export declare const VERSION = "0.32.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];