playlist-data-engine 1.1.0

package/dist/core/equipment/EquipmentValidator.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Equipment Validator
+ *
+ * Validates equipment data structures for the Advanced Equipment System.
+ * Checks equipment properties, feature/skill references, damage info,
+ * spawn weights, and modification structures.
+ */
+import type { EnhancedEquipment, EquipmentProperty, EquipmentCondition, EquipmentModification, EquipmentMiniFeature, EquipmentValidationResult, BoxContents, BoxOpenRequirement } from '../types/Equipment.js';
+/**
+ * EquipmentValidator - Validates equipment data structures
+ *
+ * This class provides static methods for validating:
+ * - Complete equipment objects
+ * - Individual equipment properties
+ * - Feature references (checks FeatureQuery)
+ * - Skill references (checks SkillQuery)
+ * - Damage information
+ * - Spawn weights
+ * - Equipment modifications
+ */
+export declare class EquipmentValidator {
+    /**
+     * Validate a complete equipment object
+     *
+     * Supports both legacy Equipment format and EnhancedEquipment format.
+     * Legacy format may have: damage as string, armor_class instead of acBonus, no source field
+     * Enhanced format has: damage as object, acBonus, source field
+     *
+     * @param equipment - Equipment to validate (any format)
+     * @returns Validation result with any errors
+     */
+    static validateEquipment(equipment: any): EquipmentValidationResult;
+    /**
+     * Validate a single equipment property
+     *
+     * @param property - Property to validate
+     * @returns Validation result with any errors
+     */
+    static validateProperty(property: EquipmentProperty): EquipmentValidationResult;
+    /**
+     * Validate a property value based on its type
+     */
+    private static validatePropertyValue;
+    /**
+     * Validate an equipment condition
+     *
+     * @param condition - Condition to validate
+     * @returns Validation result with any errors
+     */
+    static validateCondition(condition: EquipmentCondition): EquipmentValidationResult;
+    /**
+     * Validate an equipment feature reference
+     *
+     * Checks if string references exist in FeatureQuery or if inline
+     * mini-features are properly structured.
+     *
+     * @param featureRef - Feature reference (string ID or mini-feature object)
+     * @param index - Index in the grantsFeatures array (for error messages)
+     * @returns Validation result with any errors
+     */
+    static validateFeatureReference(featureRef: string | EquipmentMiniFeature, index: number): EquipmentValidationResult;
+    /**
+     * Validate if a feature ID exists in the FeatureQuery
+     *
+     * Convenience method for checking single feature references.
+     *
+     * @param featureId - Feature ID to validate
+     * @returns True if feature exists in registry
+     */
+    static validateEquipmentFeatureReference(featureId: string): boolean;
+    /**
+     * Validate an equipment skill reference
+     *
+     * Checks if the skill ID exists in SkillQuery.
+     *
+     * @param skillId - Skill ID to validate
+     * @param index - Index in the grantsSkills array (for error messages)
+     * @returns Validation result with any errors
+     */
+    static validateSkillReference(skillId: string, index?: number): EquipmentValidationResult;
+    /**
+     * Validate if a skill ID exists in the SkillQuery
+     *
+     * Convenience method for checking single skill references.
+     *
+     * @param skillId - Skill ID to validate
+     * @returns True if skill exists in registry
+     */
+    static validateEquipmentSkillReference(skillId: string): boolean;
+    /**
+     * Validate damage information
+     *
+     * Supports both string format (legacy) and object format (EnhancedEquipment).
+     * String format: "1d8 slashing"
+     * Object format: { dice: "1d8", damageType: "slashing", versatile?: "1d10" }
+     *
+     * @param damage - Damage object or string to validate
+     * @returns Validation result with any errors
+     */
+    static validateDamageInfo(damage: EnhancedEquipment['damage'] | string): EquipmentValidationResult;
+    /**
+     * Validate spawn weight
+     *
+     * Spawn weights must be non-negative numbers. A weight of 0 means
+     * the item will never be randomly generated but can still be used
+     * by game logic.
+     *
+     * @param weight - Spawn weight to validate
+     * @returns Validation result with any errors
+     */
+    static validateSpawnWeight(weight: number): EquipmentValidationResult;
+    /**
+     * Validate box contents configuration
+     *
+     * Validates the boxContents property for box-type equipment:
+     * - drops must be an array
+     * - each drop must have a non-empty pool array
+     * - each pool entry must have a valid weight
+     * - each pool entry must have either itemName or gold (not both)
+     * - pool weights should sum to 100 (warns but does not fail)
+     * - itemName references must exist in the equipment registry
+     *
+     * @param boxContents - BoxContents object to validate
+     * @returns Validation result with any errors
+     */
+    static validateBoxContents(boxContents: BoxContents): EquipmentValidationResult;
+    /**
+     * Validate a box open requirement
+     *
+     * Validates individual requirements for opening a box:
+     * - itemName must be a non-empty string (required)
+     * - itemName must exist in the equipment registry
+     * - quantity must be a positive integer if present (default: 1)
+     *
+     * @param requirement - BoxOpenRequirement object to validate
+     * @returns Validation result with any errors
+     */
+    static validateBoxOpenRequirement(requirement: BoxOpenRequirement): EquipmentValidationResult;
+    /**
+     * Validate an equipment modification
+     *
+     * Modifications are applied to equipment at runtime for enchanting,
+     * cursing, or upgrading items.
+     *
+     * @param modification - Modification to validate
+     * @returns Validation result with any errors
+     */
+    static validateModification(modification: EquipmentModification): EquipmentValidationResult;
+    /**
+     * Validate an equipment mini-feature
+     *
+     * Mini-features are inline feature definitions for equipment-specific abilities.
+     *
+     * @param miniFeature - Mini-feature to validate
+     * @returns Validation result with any errors
+     */
+    static validateMiniFeature(miniFeature: EquipmentMiniFeature): EquipmentValidationResult;
+    /**
+     * Validate AC bonus value
+     *
+     * @param acBonus - AC bonus to validate
+     * @returns Validation result with any errors
+     */
+    static validateACBonus(acBonus: number): EquipmentValidationResult;
+    /**
+     * Validate weapon properties array
+     *
+     * @param weaponProperties - Weapon properties to validate
+     * @returns Validation result with any errors
+     */
+    static validateWeaponProperties(weaponProperties: string[]): EquipmentValidationResult;
+}
+//# sourceMappingURL=EquipmentValidator.d.ts.map

package/dist/core/equipment/EquipmentValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EquipmentValidator.d.ts","sourceRoot":"","sources":["../../../src/core/equipment/EquipmentValidator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACR,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,yBAAyB,EACzB,WAAW,EACX,kBAAkB,EACrB,MAAM,uBAAuB,CAAC;AA2E/B;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAkB;IAC3B;;;;;;;;;OASG;IACH,MAAM,CAAC,iBAAiB,CAAC,SAAS,EAAE,GAAG,GAAG,yBAAyB;IAkKnE;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,yBAAyB;IAqD/E;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAuGpC;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,SAAS,EAAE,kBAAkB,GAAG,yBAAyB;IAyDlF;;;;;;;;;OASG;IACH,MAAM,CAAC,wBAAwB,CAC3B,UAAU,EAAE,MAAM,GAAG,oBAAoB,EACzC,KAAK,EAAE,MAAM,GACd,yBAAyB;IAyD5B;;;;;;;OAOG;IACH,MAAM,CAAC,iCAAiC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAOpE;;;;;;;;OAQG;IACH,MAAM,CAAC,sBAAsB,CACzB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GACf,yBAAyB;IAsB5B;;;;;;;OAOG;IACH,MAAM,CAAC,+BAA+B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIhE;;;;;;;;;OASG;IACH,MAAM,CAAC,kBAAkB,CACrB,MAAM,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAAG,MAAM,GAC7C,yBAAyB;IAmD5B;;;;;;;;;OASG;IACH,MAAM,CAAC,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,yBAAyB;IAiBrE;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,yBAAyB;IA6G/E;;;;;;;;;;OAUG;IACH,MAAM,CAAC,0BAA0B,CAAC,WAAW,EAAE,kBAAkB,GAAG,yBAAyB;IAkC7F;;;;;;;;OAQG;IACH,MAAM,CAAC,oBAAoB,CAAC,YAAY,EAAE,qBAAqB,GAAG,yBAAyB;IAoF3F;;;;;;;OAOG;IACH,MAAM,CAAC,mBAAmB,CAAC,WAAW,EAAE,oBAAoB,GAAG,yBAAyB;IAsCxF;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,yBAAyB;IAiBlE;;;;;OAKG;IACH,MAAM,CAAC,wBAAwB,CAAC,gBAAgB,EAAE,MAAM,EAAE,GAAG,yBAAyB;CAuCzF"}

package/dist/core/extensions/ExtensionManager.d.ts

@@ -0,0 +1,517 @@
+/**
+ * ExtensionManager - Core extensibility system for the Playlist Data Engine
+ *
+ * Provides runtime customization of ALL procedural generation lists with spawn rate control.
+ *
+ * Design Principles:
+ * - Hybrid spawn rates: Support both relative weights (added to pool) and absolute weights (replace distribution)
+ * - Runtime only: Custom data provided each session; characters save with custom items already included
+ * - Strict validation: Reject invalid data with clear errors
+ * - Consistent API: Same function pattern across all categories
+ * - Per-category spawn rates: Each expansion pack includes its own spawn rate weights for its content
+ *
+ * @module extensions/ExtensionManager
+ */
+/**
+ * Spawn modes for custom content
+ * - 'relative': Add custom weights to default weights (default)
+ * - 'absolute': Replace default weights entirely
+ * - 'default': Use default weights (1.0 for all items)
+ * - 'replace': Replace default items with custom items only
+ */
+export type SpawnMode = 'relative' | 'absolute' | 'default' | 'replace';
+/**
+ * All extensible categories in the system
+ */
+export type ExtensionCategory = 'equipment' | 'equipment.templates' | 'appearance.bodyTypes' | 'appearance.skinTones' | 'appearance.hairColors' | 'appearance.hairStyles' | 'appearance.eyeColors' | 'appearance.facialFeatures' | 'spells' | 'races' | 'races.data' | 'classes' | 'classes.data' | `spells.${string}` | 'classFeatures' | 'classFeatures.Barbarian' | 'classFeatures.Bard' | 'classFeatures.Cleric' | 'classFeatures.Druid' | 'classFeatures.Fighter' | 'classFeatures.Monk' | 'classFeatures.Paladin' | 'classFeatures.Ranger' | 'classFeatures.Rogue' | 'classFeatures.Sorcerer' | 'classFeatures.Warlock' | 'classFeatures.Wizard' | `classFeatures.${string}` | 'racialTraits' | 'racialTraits.Human' | 'racialTraits.Elf' | 'racialTraits.Dwarf' | 'racialTraits.Halfling' | 'racialTraits.Dragonborn' | 'racialTraits.Gnome' | 'racialTraits.Half-Elf' | 'racialTraits.Half-Orc' | 'racialTraits.Tiefling' | `racialTraits.${string}` | 'skills' | 'skills.STR' | 'skills.DEX' | 'skills.CON' | 'skills.INT' | 'skills.WIS' | 'skills.CHA' | 'skillLists' | 'skillLists.Barbarian' | 'skillLists.Bard' | 'skillLists.Cleric' | 'skillLists.Druid' | 'skillLists.Fighter' | 'skillLists.Monk' | 'skillLists.Paladin' | 'skillLists.Ranger' | 'skillLists.Rogue' | 'skillLists.Sorcerer' | 'skillLists.Warlock' | 'skillLists.Wizard' | `skillLists.${string}` | 'classSpellLists' | `classSpellLists.${string}` | 'classSpellSlots' | 'classStartingEquipment' | `classStartingEquipment.${string}`;
+/**
+ * Categories that support icon and image fields
+ * These entity types have optional icon and image URL properties
+ */
+export type ImageSupportedCategory = 'spells' | 'skills' | 'classFeatures' | 'racialTraits' | 'equipment' | 'races.data' | 'classes.data';
+/**
+ * Options for registering custom data
+ */
+export interface ExtensionOptions {
+    /**
+     * Spawn mode for this extension
+     * - 'relative': Add custom weights to default weights (default)
+     * - 'absolute': Replace default weights entirely
+     * - 'default': Use default weights (1.0 for all items)
+     * - 'replace': Replace default items with custom items only
+     */
+    mode?: SpawnMode;
+    /**
+     * Custom spawn weights for individual items
+     * Item name -> weight multiplier (1.0 = default, 2.0 = twice as likely, 0 = never spawns)
+     */
+    weights?: Record<string, number>;
+    /**
+     * Whether to validate items before registration
+     * @default true
+     */
+    validate?: boolean;
+}
+/**
+ * Entry for registering multiple extensions at once
+ */
+export interface RegistrationEntry {
+    /**
+     * The category to register items for
+     */
+    category: ExtensionCategory;
+    /**
+     * Custom items to add
+     */
+    items: any[];
+    /**
+     * Registration options
+     */
+    options?: ExtensionOptions;
+}
+/**
+ * Image override for a single item
+ * Stores only the icon/image fields to be patched onto default items
+ */
+export interface ImageOverride {
+    /** Item identifier (id for spells, name for others) */
+    identifier: string;
+    /** Icon URL */
+    icon?: string;
+    /** Image URL */
+    image?: string;
+    /** When this override was applied */
+    appliedAt: number;
+}
+/**
+ * Result of validation
+ */
+export interface ValidationResult {
+    /**
+     * Whether validation passed
+     */
+    valid: boolean;
+    /**
+     * Error messages (undefined if valid)
+     */
+    errors?: string[];
+    /**
+     * Warning messages for non-critical issues
+     */
+    warnings?: string[];
+}
+/**
+ * Content pack data exported from ExtensionManager
+ *
+ * This type represents the structure of data returned by `exportCustomData()`.
+ * It can be used to save, load, and share custom content packs.
+ */
+export interface ContentPackData {
+    /**
+     * All registered extensions by category
+     * Each category contains items, options, and registration timestamp
+     */
+    extensions: Record<string, {
+        items: any[];
+        options: ExtensionOptions;
+        registeredAt: number;
+    }>;
+    /**
+     * Custom spawn weights for each category
+     * Item name -> weight multiplier
+     */
+    weights: Record<string, Record<string, number>>;
+}
+/**
+ * ExtensionManager - Singleton class for managing runtime extensions
+ *
+ * Manages custom data for all procedural generation categories with:
+ * - Default data initialization
+ * - Custom data registration
+ * - Weight management
+ * - Merged data retrieval
+ * - Reset functionality
+ */
+export declare class ExtensionManager {
+    private static instance;
+    private defaultData;
+    private extensions;
+    private customWeights;
+    /**
+     * Image overrides per category - stores patches for icon/image fields only
+     * Key: category, Value: Map of identifier -> ImageOverride
+     */
+    private imageOverrides;
+    private constructor();
+    /**
+     * Get the singleton instance
+     */
+    static getInstance(): ExtensionManager;
+    /**
+     * Initialize default data for a category
+     * @param category - The category to initialize
+     * @param data - The default data array
+     */
+    initializeDefaults(category: ExtensionCategory, data: any[]): void;
+    /**
+     * Initialize all default data from constants
+     */
+    initializeAllDefaults(data: Record<string, any[]>): void;
+    /**
+     * Register custom data for a category
+     * @param category - The category to extend
+     * @param items - Custom items to add
+     * @param options - Registration options
+     */
+    register(category: ExtensionCategory, items: any[], options?: ExtensionOptions): void;
+    /**
+     * Register multiple categories in a single call
+     * @param registrations - Array of registration entries
+     */
+    registerMultiple(registrations: RegistrationEntry[]): void;
+    /**
+     * Get merged data (defaults + custom) for a category
+     * @param category - The category to get data for
+     * @returns Merged array of default and custom items
+     */
+    get(category: ExtensionCategory): any[];
+    /**
+     * Check if a category supports image fields
+     */
+    private isImageSupportedCategory;
+    /**
+     * Apply image overrides to items
+     * Patches icon/image fields onto items based on stored overrides
+     */
+    private applyImageOverrides;
+    /**
+     * Get default data only (no custom items)
+     * @param category - The category to get defaults for
+     * @returns Default items only
+     */
+    getDefaults(category: ExtensionCategory): any[];
+    /**
+     * Get custom items only (no defaults)
+     * @param category - The category to get custom items for
+     * @returns Custom items only
+     */
+    getCustom(category: ExtensionCategory): any[];
+    /**
+     * Set spawn weights for a category
+     * @param category - The category to set weights for
+     * @param weights - Record of item name to weight multiplier
+     */
+    setWeights(category: ExtensionCategory, weights: Record<string, number>): void;
+    /**
+     * Get spawn weights for a category
+     * @param category - The category to get weights for
+     * @returns Combined default and custom weights (all items have weights)
+     */
+    getWeights(category: ExtensionCategory): Record<string, number>;
+    /**
+     * Get default weights for a category (all 1.0)
+     * @param category - The category to get default weights for
+     * @returns Default weights (all items have weight 1.0)
+     */
+    getDefaultWeights(category: ExtensionCategory): Record<string, number>;
+    /**
+     * Check if a category has custom data registered
+     * @param category - The category to check
+     * @returns true if custom data is registered
+     */
+    hasCustomData(category: ExtensionCategory): boolean;
+    /**
+     * Set the registration mode for a category
+     * @param category - The category to set mode for
+     * @param mode - The spawn mode to set
+     */
+    setMode(category: ExtensionCategory, mode: SpawnMode): void;
+    /**
+     * Get the registration mode for a category
+     * @param category - The category to check
+     * @returns The mode ('relative', 'absolute', 'default', 'replace', or undefined if no custom data)
+     */
+    getMode(category: ExtensionCategory): 'relative' | 'absolute' | 'default' | 'replace' | undefined;
+    /**
+     * Get the registration options for a category
+     * @param category - The category to get options for
+     * @returns The options object or undefined if no custom data
+     */
+    getCurrentOptions(category: ExtensionCategory): ExtensionOptions | undefined;
+    /**
+     * Validate items for a category
+     * @param category - The category to validate against
+     * @param items - Items to validate
+     * @returns Validation result with any errors
+     */
+    validate(category: ExtensionCategory, items: any[]): ValidationResult;
+    /**
+     * Validate a single item
+     * @param category - The category to validate against
+     * @param item - The item to validate
+     * @param index - Index of the item in the array (for error messages)
+     * @returns Array of error messages (empty if valid)
+     */
+    private validateItem;
+    /**
+     * Reset a category to defaults (removes all custom data)
+     * @param category - The category to reset
+     */
+    reset(category: ExtensionCategory): void;
+    /**
+     * Reset all categories to defaults
+     */
+    resetAll(): void;
+    /**
+     * Get the registry type for a given category
+     *
+     * Maps extension categories to their corresponding registries for automatic cache invalidation.
+     *
+     * @param category - The extension category
+     * @returns Registry type ('spell', 'skill', 'feature') or null if no registry caching
+     * @private
+     */
+    private getRegistryForCategory;
+    /**
+     * Invalidate the appropriate registry cache for a category
+     *
+     * Automatically invalidates the registry cache based on the category being registered.
+     * This ensures that query methods return fresh data after registration.
+     *
+     * @param category - The extension category to invalidate cache for
+     * @private
+     */
+    private invalidateRegistryCache;
+    /**
+     * Get information about registered extensions
+     * @param category - Optional category to get info for (if omitted, returns all)
+     * @returns Object with extension information
+     */
+    getInfo(category?: ExtensionCategory): Record<string, any>;
+    /**
+     * Export all custom data (for debugging/saving)
+     * @returns Object with all custom extensions
+     */
+    exportCustomData(): Record<string, any>;
+    /**
+     * Export custom data for a single category
+     * @param category - The category to export
+     * @returns Array of custom items, or empty array if no custom data
+     */
+    exportCustomDataForCategory(category: ExtensionCategory): any[];
+    /**
+     * Get all registered categories
+     * @returns Array of all categories with default data
+     */
+    getRegisteredCategories(): ExtensionCategory[];
+    /**
+     * Get all data from categories matching a prefix pattern
+     *
+     * Aggregates data from all categories that start with the given prefix.
+     * Useful for getting all items from race-specific or class-specific categories.
+     *
+     * For example, prefix 'racialTraits' will match:
+     * - 'racialTraits' (general category)
+     * - 'racialTraits.Elf' (race-specific category)
+     * - 'racialTraits.Dragonkin' (custom race-specific category)
+     *
+     * @param prefix - Category prefix to match (e.g., 'racialTraits', 'classFeatures')
+     * @returns Array of all items from matching categories
+     */
+    getAllFromPrefix(prefix: string): any[];
+    /**
+     * Batch add icons to items in a category
+     *
+     * Updates the `icon` field for multiple items identified by name or custom key.
+     * Validates all URLs before applying any changes.
+     *
+     * @param category - The category to update (must support image fields)
+     * @param iconMap - Map of item identifier to icon URL
+     * @param identifierKey - Property to match items by (default: 'name' or 'id' for spells)
+     * @returns Number of items updated
+     * @throws Error if any URL is invalid or category doesn't support images
+     *
+     * @example
+     * // Add icons to specific spells
+     * manager.batchAddIcons('spells', {
+     *     'fireball': '/assets/spells/fireball.png',
+     *     'magic_missile': '/assets/spells/magic-missile.png'
+     * });
+     *
+     * // Add icons to equipment
+     * manager.batchAddIcons('equipment', {
+     *     'Longsword': '/assets/equipment/longsword.png'
+     * });
+     */
+    batchAddIcons(category: ImageSupportedCategory, iconMap: Record<string, string>, identifierKey?: string): number;
+    /**
+     * Batch add images to items in a category by identifier
+     *
+     * Adds or updates the `image` field on items that match the provided identifiers.
+     * All items not in the imageMap are preserved unchanged.
+     *
+     * @param category - The category to update (must support images)
+     * @param imageMap - Object mapping item identifiers to image URLs
+     * @param identifierKey - Optional property to use as identifier (defaults to 'id' for spells, 'name' for others)
+     * @returns Number of items updated
+     * @throws Error if any image URL is invalid
+     *
+     * @example
+     * // Add images to specific spells
+     * manager.batchAddImages('spells', {
+     *     'fireball': '/assets/spells/fireball-full.png',
+     *     'magic_missile': '/assets/spells/magic-missile-full.png'
+     * });
+     *
+     * // Add images to equipment
+     * manager.batchAddImages('equipment', {
+     *     'Longsword': '/assets/equipment/longsword-full.png'
+     * });
+     */
+    batchAddImages(category: ImageSupportedCategory, imageMap: Record<string, string>, identifierKey?: string): number;
+    /**
+     * Batch update icons and/or images for items matching a predicate
+     *
+     * Updates all items in a category that match the given predicate function
+     * with the specified icon and/or image URLs. Useful for bulk operations
+     * based on item properties (e.g., all cantrips, all rare equipment).
+     *
+     * @param category - The category to update (must support images)
+     * @param predicate - Function that returns true for items to update
+     * @param updates - Object containing icon and/or image URLs to apply
+     * @returns Number of items updated
+     * @throws Error if any URL is invalid
+     *
+     * @example
+     * // Add same icon to all cantrips
+     * manager.batchUpdateImages('spells',
+     *     spell => spell.level === 0,
+     *     { icon: '/assets/spells/cantrip-icon.png' }
+     * );
+     *
+     * // Add images to all rare equipment
+     * manager.batchUpdateImages('equipment',
+     *     item => item.rarity === 'rare',
+     *     { icon: '/assets/icons/rare.png', image: '/assets/images/rare-bg.png' }
+     * );
+     *
+     * // Update all evocation spells
+     * manager.batchUpdateImages('spells',
+     *     spell => spell.school === 'Evocation',
+     *     { icon: '/assets/icons/fire.png' }
+     * );
+     */
+    batchUpdateImages<T = any>(category: ImageSupportedCategory, predicate: (item: T) => boolean, updates: {
+        icon?: string;
+        image?: string;
+    }): number;
+    /**
+     * Batch update icons/images for items based on a property value mapping
+     *
+     * Updates items in a category where the specified property matches a key in the valueMap.
+     * Useful for bulk operations based on categories like spell school, equipment rarity, etc.
+     *
+     * @param category - The category to update (must support images)
+     * @param property - The property name to match against (e.g., 'school', 'rarity')
+     * @param valueMap - Map of property values to icon/image URLs. Values can be:
+     *                   - A string URL (will be applied as the icon)
+     *                   - An object with icon and/or image properties
+     * @returns Number of items updated
+     * @throws Error if any URL is invalid
+     *
+     * @example
+     * // Add icons by spell school
+     * manager.batchByCategory('spells', 'school', {
+     *     'Evocation': '/assets/icons/fire.png',
+     *     'Necromancy': '/assets/icons/skull.png',
+     *     'Abjuration': '/assets/icons/shield.png'
+     * });
+     *
+     * // Add icons by equipment rarity
+     * manager.batchByCategory('equipment', 'rarity', {
+     *     'legendary': '/assets/icons/star-gold.png',
+     *     'very_rare': '/assets/icons/star-purple.png',
+     *     'rare': '/assets/icons/star-blue.png'
+     * });
+     *
+     * // Add both icon and image by rarity
+     * manager.batchByCategory('equipment', 'rarity', {
+     *     'legendary': { icon: '/assets/icons/legendary.png', image: '/assets/images/legendary-bg.png' }
+     * });
+     */
+    batchByCategory<T = any>(category: ImageSupportedCategory, property: keyof T, valueMap: Record<string, string | {
+        icon?: string;
+        image?: string;
+    }>): number;
+    /**
+     * Get all image overrides for all categories
+     *
+     * Used by persistence layer to save overrides to localStorage.
+     *
+     * @returns Map of category to array of image overrides
+     */
+    getImageOverrides(): Map<ImageSupportedCategory, ImageOverride[]>;
+    /**
+     * Get image overrides for a specific category
+     *
+     * @param category - The category to get overrides for
+     * @returns Array of image overrides, or empty array if none
+     */
+    getImageOverridesForCategory(category: ImageSupportedCategory): ImageOverride[];
+    /**
+     * Restore image overrides from saved data
+     *
+     * Used by persistence layer to restore overrides from localStorage.
+     * Merges with existing overrides - new values override existing for same identifier.
+     *
+     * @param category - The category to restore overrides for
+     * @param overrides - Array of image overrides to restore
+     */
+    restoreImageOverrides(category: ImageSupportedCategory, overrides: ImageOverride[]): void;
+    /**
+     * Clear all image overrides for a category
+     *
+     * @param category - The category to clear overrides for
+     */
+    clearImageOverrides(category: ImageSupportedCategory): void;
+    /**
+     * Clear all image overrides for all categories
+     */
+    clearAllImageOverrides(): void;
+    /**
+     * Get the default identifier key for a category
+     *
+     * Different categories use different identifier properties:
+     * - Spells use 'id' (e.g., 'fireball', 'magic_missile')
+     * - Most other categories use 'name'
+     *
+     * @param category - The category to get the identifier key for
+     * @returns The default identifier property name
+     * @private
+     */
+    private getDefaultIdentifierKey;
+    /**
+     * Validate an image URL field
+     *
+     * Checks if a URL is valid for use as an icon or image field.
+     * Returns null if valid, or an error message string if invalid.
+     *
+     * @param url - The URL string to validate
+     * @param fieldName - Descriptive name for error messages (e.g., 'icon', 'image', 'Fireball.icon')
+     * @returns Error message if invalid, null if valid
+     * @private
+     */
+    private validateImageField;
+    /**
+     * Validate multiple image URLs and collect errors
+     *
+     * Convenience method that validates multiple URLs and returns
+     * all validation errors as an array.
+     *
+     * @param validations - Array of [url, fieldName] tuples to validate
+     * @returns Array of error messages (empty if all valid)
+     * @private
+     */
+    private validateImageFields;
+}
+//# sourceMappingURL=ExtensionManager.d.ts.map