@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/templates/economy/inventory-service.ts

@@ -0,0 +1,170 @@
+import type { Result } from '../core/types';
+import type { EconomyRepository } from './repository';
+import type {
+  EconomyConfig,
+  EconomyState,
+  InventoryConfig,
+  InventoryItemDefinition,
+  InventoryReward,
+  RewardSummary,
+  ResourceStack,
+  TransactionChange,
+  TransactionReceipt,
+} from './types';
+import type { RandomSource } from './random';
+import { MathRandomSource } from './random';
+import { applyDelta, cloneEconomyState, resourceRewardsFromChanges } from './state-utils';
+
+export interface InventorySnapshot {
+  itemId: string;
+  definition: InventoryItemDefinition;
+  amount: number;
+}
+
+export interface InventoryService {
+  list(): Promise<InventorySnapshot[]>;
+  getAmount(itemId: string): Promise<number>;
+  grant(itemId: string, amount: number, transactionId: string): Promise<Result<TransactionReceipt>>;
+  open(itemId: string, amount: number, transactionId: string, selectedItemIds?: string[]): Promise<Result<TransactionReceipt>>;
+  sell(itemId: string, amount: number, transactionId: string): Promise<Result<TransactionReceipt>>;
+}
+
+export class DefaultInventoryService implements InventoryService {
+  constructor(
+    private readonly repository: EconomyRepository,
+    private readonly economyConfig: EconomyConfig,
+    private readonly config: InventoryConfig,
+    private readonly random: RandomSource = new MathRandomSource(),
+  ) {}
+
+  async list(): Promise<InventorySnapshot[]> {
+    const state = await this.repository.getSnapshot();
+    return Object.values(this.config.items).map((definition) => ({
+      itemId: definition.id,
+      definition,
+      amount: state.inventory?.[definition.id] ?? 0,
+    }));
+  }
+
+  async getAmount(itemId: string): Promise<number> {
+    const state = await this.repository.getSnapshot();
+    return state.inventory?.[itemId] ?? 0;
+  }
+
+  grant(itemId: string, amount: number, transactionId: string) {
+    return this.run(transactionId, (state) => {
+      this.definition(itemId);
+      this.positiveAmount(amount);
+      const next = cloneEconomyState(state);
+      next.inventory[itemId] = (next.inventory[itemId] ?? 0) + amount;
+      return { state: next, receipt: this.receipt(transactionId, 'inventory-grant', [], [{ type: 'item', itemId, amount }]) };
+    });
+  }
+
+  open(itemId: string, amount: number, transactionId: string, selectedItemIds: string[] = []) {
+    return this.run(transactionId, (state) => {
+      const definition = this.definition(itemId);
+      if (!definition.open) throw new Error(`Inventory item cannot be opened: ${itemId}`);
+      this.positiveAmount(amount);
+      this.requireOwned(state, itemId, amount);
+      const next = cloneEconomyState(state);
+      next.inventory[itemId] -= amount;
+      const changes: TransactionChange[] = [];
+      const rewards: RewardSummary[] = [];
+      for (let i = 0; i < amount; i += 1) {
+        for (const reward of this.pickRewards(definition.open, selectedItemIds)) {
+          this.applyReward(next, reward, changes, rewards);
+        }
+      }
+      rewards.unshift({ type: 'item', itemId, amount: -amount });
+      return { state: next, receipt: this.receipt(transactionId, 'inventory-open', changes, [...resourceRewardsFromChanges(changes), ...rewards]) };
+    });
+  }
+
+  sell(itemId: string, amount: number, transactionId: string) {
+    return this.run(transactionId, (state) => {
+      const definition = this.definition(itemId);
+      if (!definition.sell?.length) throw new Error(`Inventory item cannot be sold: ${itemId}`);
+      this.positiveAmount(amount);
+      this.requireOwned(state, itemId, amount);
+      const next = cloneEconomyState(state);
+      next.inventory[itemId] -= amount;
+      const changes: TransactionChange[] = [];
+      for (const reward of definition.sell) applyDelta(next, this.economyConfig, reward.resourceId, reward.amount * amount, 'grantable', changes);
+      const rewards: RewardSummary[] = [
+        { type: 'item', itemId, amount: -amount },
+        ...resourceRewardsFromChanges(changes),
+      ];
+      return { state: next, receipt: this.receipt(transactionId, 'inventory-sell', changes, rewards) };
+    });
+  }
+
+  private pickRewards(config: NonNullable<InventoryItemDefinition['open']>, selectedItemIds: string[]): InventoryReward[] {
+    const count = config.pickCount ?? config.entries.length;
+    if (config.mode === 'all') return config.entries.slice(0, count);
+    if (config.mode === 'select') {
+      const selected = config.entries.filter((entry) => selectedItemIds.includes(entry.type === 'item' ? entry.itemId : entry.resourceId));
+      if (selected.length === 0) throw new Error('Select at least one inventory reward');
+      return selected.slice(0, count);
+    }
+    const entries = config.entries;
+    const totalWeight = entries.reduce((sum, entry) => sum + Math.max(0, entry.weight ?? 0), 0);
+    if (totalWeight <= 0) throw new Error('Weighted inventory open has no positive weights');
+    const result: InventoryReward[] = [];
+    const pool = [...entries];
+    for (let i = 0; i < count; i += 1) {
+      const roll = this.random.next() * totalWeight;
+      let cursor = 0;
+      const selected = pool.find((entry) => {
+        cursor += Math.max(0, entry.weight ?? 0);
+        return roll < cursor;
+      }) ?? pool[pool.length - 1];
+      result.push(selected);
+      if (!config.allowDuplicatePicks) pool.splice(pool.indexOf(selected), 1);
+      if (pool.length === 0) break;
+    }
+    return result;
+  }
+
+  private applyReward(state: EconomyState, reward: InventoryReward, changes: TransactionChange[], summaries: RewardSummary[]): void {
+    this.positiveAmount(reward.amount);
+    if (reward.type === 'resource') {
+      applyDelta(state, this.economyConfig, reward.resourceId, reward.amount, 'grantable', changes);
+      return;
+    }
+    this.definition(reward.itemId);
+    state.inventory[reward.itemId] = (state.inventory[reward.itemId] ?? 0) + reward.amount;
+    summaries.push({ type: 'item', itemId: reward.itemId, amount: reward.amount });
+  }
+
+  private async run(
+    transactionId: string,
+    work: (state: EconomyState) => { state: EconomyState; receipt: TransactionReceipt },
+  ): Promise<Result<TransactionReceipt>> {
+    if (!transactionId.trim()) return { ok: false, error: new Error('transactionId is required') };
+    try {
+      const result = await this.repository.runAtomic(transactionId, async (state) => work(state));
+      return { ok: true, value: result.receipt };
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
+    }
+  }
+
+  private definition(itemId: string): InventoryItemDefinition {
+    const definition = this.config.items[itemId];
+    if (!definition) throw new Error(`Unknown inventory item: ${itemId}`);
+    return definition;
+  }
+
+  private requireOwned(state: EconomyState, itemId: string, amount: number): void {
+    if ((state.inventory[itemId] ?? 0) < amount) throw new Error(`Insufficient inventory item: ${itemId}`);
+  }
+
+  private positiveAmount(amount: number): void {
+    if (!Number.isInteger(amount) || amount <= 0) throw new Error('Amount must be a positive integer');
+  }
+
+  private receipt(transactionId: string, operationType: TransactionReceipt['operationType'], changes: TransactionChange[], rewards: RewardSummary[]): TransactionReceipt {
+    return { transactionId, operationType, applied: true, changes, rewards };
+  }
+}

package/plugins/phaser-casual-game-factory/templates/economy/item-service.ts

@@ -0,0 +1,220 @@
+import type { Result } from '../core/types';
+import type { RandomSource } from './random';
+import { MathRandomSource } from './random';
+import type { EconomyConfig, ItemChangeProposal, ItemInstance, ItemSnapshot, TransactionChange, TransactionReceipt } from './types';
+import type { EconomyRepository } from './repository';
+import { applyInput, cloneEconomyState, resourceRewardsFromChanges } from './state-utils';
+import { applyEffects, createItemFromTemplate, rollItemEffects } from './item-utils';
+
+export interface ItemService {
+  createItem(
+    itemId: string,
+    templateId: string,
+    transactionId: string,
+  ): Promise<Result<ItemInstance>>;
+
+  rollChange(
+    itemId: string,
+    configId: string,
+    proposalId: string,
+    transactionId: string,
+  ): Promise<Result<ItemChangeProposal>>;
+
+  /** @deprecated Use rollChange. */
+  previewChange(
+    itemId: string,
+    configId: string,
+    proposalId: string,
+    transactionId: string,
+  ): Promise<Result<ItemChangeProposal>>;
+
+  applyChange(
+    itemId: string,
+    proposalId: string,
+    transactionId: string,
+  ): Promise<Result<TransactionReceipt>>;
+
+  revertChange(
+    itemId: string,
+    proposalId: string,
+    transactionId: string,
+  ): Promise<Result<TransactionReceipt>>;
+}
+
+export class DefaultItemService implements ItemService {
+  constructor(
+    private readonly repository: EconomyRepository,
+    private readonly config: EconomyConfig,
+    private readonly random: RandomSource = new MathRandomSource(),
+    private readonly now: () => number = () => Date.now(),
+  ) {}
+
+  async createItem(itemId: string, templateId: string, transactionId: string) {
+    return this.runWithResult(transactionId, async (state) => {
+      if (state.items[itemId]) throw new Error(`Item already exists: ${itemId}`);
+      const template = this.config.itemTemplates[templateId];
+      if (!template) throw new Error(`Unknown item template: ${templateId}`);
+      const item = createItemFromTemplate(template, itemId, this.now(), this.random);
+      const next = cloneEconomyState(state);
+      next.items[itemId] = item;
+      return {
+        state: next,
+        receipt: this.receipt(transactionId, 'item-create', [], [
+          { type: 'item', itemId },
+        ]),
+        value: item,
+      };
+    }, () => this.repository.getSnapshot().then((state) => state.items[itemId]));
+  }
+
+  async rollChange(
+    itemId: string,
+    configId: string,
+    proposalId: string,
+    transactionId: string,
+  ) {
+    return this.runWithResult(transactionId, async (state) => {
+      if (state.itemProposals[proposalId]) throw new Error(`Proposal already exists: ${proposalId}`);
+      const item = state.items[itemId];
+      const config = this.config.itemChanges[configId];
+      const template = item && this.config.itemTemplates[item.templateId];
+      if (!item) throw new Error(`Unknown item: ${itemId}`);
+      if (!config) throw new Error(`Unknown item change config: ${configId}`);
+      if (!template) throw new Error(`Unknown item template: ${item.templateId}`);
+
+      const effects = rollItemEffects(
+        config.effects,
+        config.pickCount ?? config.effects.length,
+        false,
+        this.random,
+      );
+      const nextEffects = config.mode === 'replace-effects'
+        ? effects
+        : [...item.effects, ...effects];
+      const after = applyEffects(template.baseStats, template.baseSkills, nextEffects);
+      const next = cloneEconomyState(state);
+      const changes: TransactionChange[] = [];
+      applyInput(next, this.config, config.cost, 'spendable', changes);
+      const proposal: ItemChangeProposal = {
+        proposalId,
+        itemId,
+        configId,
+        before: this.snapshot(item),
+        after,
+        baseRevision: item.revision,
+        cost: config.cost.map((stack) => ({ ...stack })),
+        createdAt: this.now(),
+        status: 'pending',
+      };
+      next.itemProposals[proposalId] = proposal;
+      return {
+        state: next,
+        receipt: this.receipt(transactionId, 'item-reroll', changes),
+        value: proposal,
+      };
+    }, () => this.repository.getSnapshot().then((state) => state.itemProposals[proposalId]));
+  }
+
+  previewChange(
+    itemId: string,
+    configId: string,
+    proposalId: string,
+    transactionId: string,
+  ): Promise<Result<ItemChangeProposal>> {
+    return this.rollChange(itemId, configId, proposalId, transactionId);
+  }
+
+  async applyChange(itemId: string, proposalId: string, transactionId: string) {
+    return this.runWithResult(transactionId, async (state) => {
+      const proposal = state.itemProposals[proposalId];
+      const item = state.items[itemId];
+      const config = proposal && this.config.itemChanges[proposal.configId];
+      if (!proposal || proposal.itemId !== itemId) throw new Error(`Unknown item proposal: ${proposalId}`);
+      if (!item || proposal.status !== 'pending') throw new Error(`Proposal is not pending: ${proposalId}`);
+      if (!config) throw new Error(`Unknown item change config: ${proposal.configId}`);
+      if (item.revision !== proposal.baseRevision) throw new Error(`Item changed since proposal: ${itemId}`);
+      const next = cloneEconomyState(state);
+      next.items[itemId] = {
+        ...item,
+        ...proposal.after,
+        revision: item.revision + 1,
+      };
+      next.itemProposals[proposalId] = { ...proposal, status: 'applied' };
+      const receipt = this.receipt(transactionId, 'item-apply-change');
+      return {
+        state: next,
+        receipt,
+        value: receipt,
+      };
+    }, () => this.repository.getSnapshot().then((state) => state.transactions[transactionId]));
+  }
+
+  async revertChange(itemId: string, proposalId: string, transactionId: string) {
+    return this.runWithResult(transactionId, async (state) => {
+      const proposal = state.itemProposals[proposalId];
+      const item = state.items[itemId];
+      const config = proposal && this.config.itemChanges[proposal.configId];
+      if (!proposal || proposal.itemId !== itemId) throw new Error(`Unknown item proposal: ${proposalId}`);
+      if (!item || !['pending', 'applied'].includes(proposal.status)) throw new Error(`Proposal cannot be discarded: ${proposalId}`);
+      if (!config?.allowRevert) throw new Error(`Item change cannot be reverted: ${proposal.configId}`);
+      const next = cloneEconomyState(state);
+      if (proposal.status === 'applied') {
+        next.items[itemId] = {
+          ...item,
+          ...proposal.before,
+          revision: item.revision + 1,
+        };
+      }
+      next.itemProposals[proposalId] = { ...proposal, status: 'reverted' };
+      const receipt = this.receipt(transactionId, 'item-revert-change');
+      return {
+        state: next,
+        receipt,
+        value: receipt,
+      };
+    }, () => this.repository.getSnapshot().then((state) => state.transactions[transactionId]));
+  }
+
+  private async runWithResult<T>(
+    transactionId: string,
+    work: (state: Awaited<ReturnType<EconomyRepository['getSnapshot']>>) => Promise<{
+      state: Awaited<ReturnType<EconomyRepository['getSnapshot']>>;
+      receipt: TransactionReceipt;
+      value?: T;
+    }>,
+    duplicateValue?: () => Promise<T | undefined>,
+  ): Promise<Result<T>> {
+    try {
+      const result = await this.repository.runAtomic(transactionId, work);
+      if (result.value !== undefined) return { ok: true, value: result.value };
+      const value = await duplicateValue?.();
+      if (value === undefined) throw new Error(`Duplicate transaction result is unavailable: ${transactionId}`);
+      return { ok: true, value };
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
+    }
+  }
+
+  private snapshot(item: ItemInstance): ItemSnapshot {
+    return {
+      stats: { ...item.stats },
+      skills: { ...item.skills },
+      effects: item.effects.map((effect) => ({ ...effect })),
+    };
+  }
+
+  private receipt(
+    transactionId: string,
+    operationType: TransactionReceipt['operationType'],
+    changes: TransactionReceipt['changes'] = [],
+    rewards?: TransactionReceipt['rewards'],
+  ): TransactionReceipt {
+    return {
+      transactionId,
+      operationType,
+      applied: true,
+      changes,
+      rewards: rewards ?? resourceRewardsFromChanges(changes),
+    };
+  }
+}

package/plugins/phaser-casual-game-factory/templates/economy/item-utils.ts

@@ -0,0 +1,126 @@
+import type {
+  ItemEffect,
+  ItemEffectOption,
+  ItemInstance,
+  ItemSnapshot,
+  ItemTemplate,
+  QuantitySpec,
+} from './types';
+import type { RandomSource } from './random';
+import { randomInteger, weightedIndex } from './random';
+
+function resolveValue(
+  value: number | QuantitySpec,
+  random: RandomSource,
+): number {
+  if (typeof value === 'number') return value;
+  if (value.type === 'fixed') return value.amount;
+  return randomInteger(random, value.min, value.max);
+}
+
+export function rollItemEffects(
+  options: ItemEffectOption[],
+  pickCount: number,
+  allowDuplicatePicks: boolean,
+  random: RandomSource,
+): ItemEffect[] {
+  if (pickCount < 0 || !Number.isInteger(pickCount)) {
+    throw new Error(`Invalid item effect pickCount: ${pickCount}`);
+  }
+
+  const pool = [...options];
+  const selected: ItemEffectOption[] = [];
+  const hasWeights = pool.some((option) => (option.weight ?? 0) > 0);
+  for (let index = 0; index < pickCount; index += 1) {
+    if (pool.length === 0) throw new Error('Not enough item effect options');
+    const selectedIndex = hasWeights
+      ? weightedIndex(
+          random,
+          pool.map((option) => option.weight ?? 0),
+        )
+      : 0;
+    selected.push(pool[selectedIndex]);
+    if (!allowDuplicatePicks) pool.splice(selectedIndex, 1);
+  }
+
+  return selected.map((option) => {
+    if (option.target === 'stat') {
+      if (option.value === undefined) {
+        throw new Error(`Stat effect requires a value: ${option.id}`);
+      }
+      if (!['set', 'add', 'multiply'].includes(option.operation)) {
+        throw new Error(`Invalid stat effect operation: ${option.id}`);
+      }
+      return {
+        target: 'stat' as const,
+        key: option.key,
+        operation: option.operation as 'set' | 'add' | 'multiply',
+        value: resolveValue(option.value, random),
+      };
+    }
+
+    if (option.operation !== 'unlock' && option.operation !== 'set-level') {
+      throw new Error(`Invalid skill effect operation: ${option.id}`);
+    }
+    return {
+      target: 'skill' as const,
+      key: option.key,
+      operation: option.operation,
+      level: option.level === undefined
+        ? 1
+        : typeof option.level === 'number'
+          ? option.level
+          : resolveValue(option.level, random),
+    };
+  });
+}
+
+export function applyEffects(
+  baseStats: Record<string, number>,
+  baseSkills: Record<string, number>,
+  effects: ItemEffect[],
+): ItemSnapshot {
+  const stats = { ...baseStats };
+  const skills = { ...baseSkills };
+
+  for (const effect of effects) {
+    if (effect.target === 'stat') {
+      const current = stats[effect.key] ?? 0;
+      if (effect.operation === 'set') stats[effect.key] = effect.value;
+      if (effect.operation === 'add') stats[effect.key] = current + effect.value;
+      if (effect.operation === 'multiply') stats[effect.key] = current * effect.value;
+    } else if (effect.operation === 'unlock') {
+      skills[effect.key] = Math.max(skills[effect.key] ?? 0, effect.level);
+    } else {
+      skills[effect.key] = effect.level;
+    }
+  }
+
+  return { stats, skills, effects: effects.map((effect) => ({ ...effect })) };
+}
+
+export function createItemFromTemplate(
+  template: ItemTemplate,
+  itemId: string,
+  now: number,
+  random: RandomSource,
+): ItemInstance {
+  const creation = template.creation;
+  const effects = creation?.effects
+    ? rollItemEffects(
+        creation.effects,
+        creation.pickCount ?? creation.effects.length,
+        creation.allowDuplicatePicks ?? false,
+        random,
+      )
+    : [];
+  const snapshot = applyEffects(template.baseStats, template.baseSkills, effects);
+
+  return {
+    instanceId: itemId,
+    templateId: template.id,
+    createdAt: now,
+    revision: 1,
+    ...snapshot,
+  };
+}

package/plugins/phaser-casual-game-factory/templates/economy/merge-handler.ts

@@ -0,0 +1,42 @@
+import type { EconomyOperationContext, EconomyOperationHandler } from './operation-handler';
+import type { EconomyOperationRequest, TransactionChange } from './types';
+import {
+  applyInput,
+  applyRewards,
+  cloneEconomyState,
+  multiplyStacks,
+  resolveQuantity,
+} from './state-utils';
+
+type MergeRequest = Extract<EconomyOperationRequest, { type: 'merge' }>;
+
+export class MergeOperationHandler
+  implements EconomyOperationHandler<MergeRequest>
+{
+  readonly type = 'merge' as const;
+
+  execute(request: MergeRequest, context: EconomyOperationContext) {
+    const config = context.config.merges[request.configId];
+    if (!config) throw new Error(`Unknown merge config: ${request.configId}`);
+    const quantity = request.quantity ?? 1;
+    const state = cloneEconomyState(context.state);
+    const changes: TransactionChange[] = [];
+    applyInput(
+      state,
+      context.config,
+      multiplyStacks(config.input, quantity),
+      'mergeable',
+      changes,
+    );
+    applyRewards(
+      state,
+      context.config,
+      config.output.map((reward) => ({
+        resourceId: reward.resourceId,
+        amount: resolveQuantity(reward.quantity, context.random) * quantity,
+      })),
+      changes,
+    );
+    return { state, receipt: { applied: true, changes } };
+  }
+}

package/plugins/phaser-casual-game-factory/templates/economy/operation-handler.ts

@@ -0,0 +1,44 @@
+import type { EconomyConfig, EconomyOperationRequest, EconomyState, TransactionReceipt } from './types';
+import type { RandomSource } from './random';
+
+export interface EconomyOperationContext {
+  state: EconomyState;
+  config: EconomyConfig;
+  random: RandomSource;
+  now: number;
+}
+
+export interface OperationExecution {
+  state: EconomyState;
+  receipt: Omit<TransactionReceipt, 'transactionId' | 'operationType'>;
+}
+
+export interface EconomyOperationHandler<
+  T extends EconomyOperationRequest = EconomyOperationRequest,
+> {
+  readonly type: T['type'];
+  execute(request: T, context: EconomyOperationContext): OperationExecution;
+}
+
+export class OperationRegistry {
+  private readonly handlers = new Map<
+    EconomyOperationRequest['type'],
+    EconomyOperationHandler<any>
+  >();
+
+  register<T extends EconomyOperationRequest>(
+    handler: EconomyOperationHandler<T>,
+  ): this {
+    if (this.handlers.has(handler.type)) {
+      throw new Error(`Economy operation already registered: ${handler.type}`);
+    }
+    this.handlers.set(handler.type, handler);
+    return this;
+  }
+
+  get(type: EconomyOperationRequest['type']): EconomyOperationHandler {
+    const handler = this.handlers.get(type);
+    if (!handler) throw new Error(`Unsupported economy operation: ${type}`);
+    return handler;
+  }
+}

package/plugins/phaser-casual-game-factory/templates/economy/package-handler.ts

@@ -0,0 +1,41 @@
+import type { EconomyOperationContext, EconomyOperationHandler } from './operation-handler';
+import type { EconomyOperationRequest, TransactionChange } from './types';
+import { applyRewards, cloneEconomyState, resolveQuantity } from './state-utils';
+
+type PackageRequest = Extract<
+  EconomyOperationRequest,
+  { type: 'activate-package' }
+>;
+
+export class ActivatePackageHandler
+  implements EconomyOperationHandler<PackageRequest>
+{
+  readonly type = 'activate-package' as const;
+
+  execute(request: PackageRequest, context: EconomyOperationContext) {
+    const config = context.config.packages[request.configId];
+    if (!config) throw new Error(`Unknown package config: ${request.configId}`);
+    const state = cloneEconomyState(context.state);
+    const existing = state.activePackages[config.id];
+    if (existing?.permanent) throw new Error(`Package is permanently active: ${config.id}`);
+    const durationMs = (config.durationDays ?? 0) * 24 * 60 * 60 * 1000;
+    state.activePackages[config.id] = {
+      activatedAt: existing?.activatedAt ?? context.now,
+      entitlements: [...config.entitlements],
+      permanent: config.permanent ?? false,
+      expiresAt: config.permanent ? undefined : durationMs > 0 ? Math.max(existing?.expiresAt ?? context.now, context.now) + durationMs : undefined,
+    };
+    const changes: TransactionChange[] = [];
+    applyRewards(
+      state,
+      context.config,
+      (config.rewards ?? []).map((reward) => ({
+        resourceId: reward.resourceId,
+        amount: resolveQuantity(reward.quantity, context.random),
+      })),
+      changes,
+    );
+
+    return { state, receipt: { applied: true, changes } };
+  }
+}

package/plugins/phaser-casual-game-factory/templates/economy/random.ts

@@ -0,0 +1,33 @@
+export interface RandomSource {
+  next(): number;
+}
+
+export class MathRandomSource implements RandomSource {
+  next(): number {
+    return Math.random();
+  }
+}
+
+export function randomInteger(
+  random: RandomSource,
+  min: number,
+  max: number,
+): number {
+  return Math.floor(random.next() * (max - min + 1)) + min;
+}
+
+export function weightedIndex(
+  random: RandomSource,
+  weights: number[],
+): number {
+  const total = weights.reduce((sum, weight) => sum + weight, 0);
+  if (total <= 0) throw new Error('Weighted selection requires a positive total weight');
+
+  let cursor = random.next() * total;
+  for (let index = 0; index < weights.length; index += 1) {
+    cursor -= weights[index];
+    if (cursor < 0) return index;
+  }
+
+  return weights.length - 1;
+}