playlist-data-engine 1.1.0

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

@@ -0,0 +1,327 @@
+/**
+ * Equipment Modifier
+ *
+ * Handles equipment modification operations including enchanting, cursing,
+ * upgrading, and template application. Supports per-instance modifications
+ * that can be applied to individual equipment items.
+ */
+import type { CharacterSheet } from '../types/Character.js';
+import type { CharacterEquipment, EquipmentProperty, EquipmentModification, EquipmentMiniFeature } from '../types/Equipment.js';
+/**
+ * Modification result containing the updated equipment state
+ */
+export interface ModificationResult {
+    /** Updated equipment state */
+    equipment: CharacterEquipment;
+    /** Whether the modification was applied */
+    success: boolean;
+    /** Errors encountered (if any) */
+    errors?: string[];
+}
+/**
+ * EquipmentModifier - Equipment modification operations
+ *
+ * This class provides static methods for:
+ * - Enchanting equipment with new properties (per-instance)
+ * - Applying template modifications (creates new item based on template)
+ * - Cursing equipment with negative effects
+ * - Upgrading equipment (improve existing properties)
+ * - Removing modifications
+ * - Querying modification history
+ * - Checking for templates
+ * - Getting combined effects from base + modifications
+ *
+ * TEMPLATE VS INSTANCE:
+ * - Template modifications create new equipment based on a template definition
+ * - Per-instance modifications are stored in the modifications array
+ * - Both can coexist on the same item
+ */
+export declare class EquipmentModifier {
+    /**
+     * Enchant equipment with new properties (creates per-instance modification)
+     *
+     * Enchanting adds positive magical properties to an item. Each enchantment
+     * is stored as a per-instance modification that can be removed later.
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item to enchant
+     * @param enchantment - The enchantment to apply
+     * @param character - Optional character to reapply effects to
+     * @returns Updated equipment with enchantment applied
+     */
+    static enchant(equipment: CharacterEquipment, itemName: string, enchantment: EquipmentModification, character?: CharacterSheet): CharacterEquipment;
+    /**
+     * Apply a template modification to equipment
+     *
+     * Template-based modifications create new items based on template definitions
+     * stored in ExtensionManager under 'equipment.templates' category.
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item to modify
+     * @param templateId - ID of the template to apply
+     * @param character - Optional character to reapply effects to
+     * @returns Updated equipment with template applied
+     */
+    static applyTemplate(equipment: CharacterEquipment, itemName: string, templateId: string, character?: CharacterSheet): CharacterEquipment;
+    /**
+     * Curse equipment with negative effects
+     *
+     * Cursing adds negative properties to an item. Like enchantments,
+     * curses are stored as per-instance modifications that can be removed.
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item to curse
+     * @param curse - The curse to apply
+     * @param character - Optional character to reapply effects to
+     * @returns Updated equipment with curse applied
+     */
+    static curse(equipment: CharacterEquipment, itemName: string, curse: EquipmentModification, character?: CharacterSheet): CharacterEquipment;
+    /**
+     * Upgrade equipment (improve existing properties)
+     *
+     * Upgrading enhances existing properties on an item or adds new positive
+     * properties. This is a convenience wrapper around enchant().
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item to upgrade
+     * @param upgrade - The upgrade to apply
+     * @param character - Optional character to reapply effects to
+     * @returns Updated equipment with upgrade applied
+     */
+    static upgrade(equipment: CharacterEquipment, itemName: string, upgrade: EquipmentModification, character?: CharacterSheet): CharacterEquipment;
+    /**
+     * Remove a modification from equipment
+     *
+     * Removes a specific modification by ID from an item. If the item
+     * is equipped, effects are recalculated.
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @param modificationId - ID of the modification to remove
+     * @param character - Optional character to reapply effects to
+     * @returns Updated equipment with modification removed
+     */
+    static removeModification(equipment: CharacterEquipment, itemName: string, modificationId: string, character?: CharacterSheet): CharacterEquipment;
+    /**
+     * Get modification history for an item
+     *
+     * Returns all modifications that have been applied to an item,
+     * in the order they were applied.
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @returns Array of modifications (oldest first)
+     */
+    static getModificationHistory(equipment: CharacterEquipment, itemName: string): EquipmentModification[];
+    /**
+     * Get all active effects from an item (base + modifications)
+     *
+     * Combines the base equipment properties with all modification
+     * properties to give the complete set of active effects.
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @param instanceId - Optional instance ID for multi-item tracking
+     * @returns Array of all active equipment properties
+     */
+    static getCombinedEffects(equipment: CharacterEquipment, itemName: string, instanceId?: string): EquipmentProperty[];
+    /**
+     * Check if item has a specific template
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @param templateId - Template ID to check for
+     * @returns True if the item has the template
+     */
+    static hasTemplate(equipment: CharacterEquipment, itemName: string, templateId: string): boolean;
+    /**
+     * Get all templates applied to an item
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @returns Array of template IDs
+     */
+    static getAppliedTemplates(equipment: CharacterEquipment, itemName: string): string[];
+    /**
+     * Remove all modifications from an item
+     *
+     * Removes all modifications, effectively restoring the item to
+     * its base state.
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @param character - Optional character to reapply effects to
+     * @returns Updated equipment with all modifications removed
+     */
+    static removeAllModifications(equipment: CharacterEquipment, itemName: string, character?: CharacterSheet): CharacterEquipment;
+    /**
+     * Disenchant an item (remove all enchantments, keep curses)
+     *
+     * Removes only positive modifications (enchantments/upgrades), leaving
+     * curses intact. Useful for "remove curse" mechanics.
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @param character - Optional character to reapply effects to
+     * @returns Updated equipment with enchantments removed
+     */
+    static disenchant(equipment: CharacterEquipment, itemName: string, character?: CharacterSheet): CharacterEquipment;
+    /**
+     * Lift curse from an item (remove all curses, keep enchantments)
+     *
+     * Removes only negative modifications (curses), leaving enchantments
+     * intact.
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @param character - Optional character to reapply effects to
+     * @returns Updated equipment with curses removed
+     */
+    static liftCurse(equipment: CharacterEquipment, itemName: string, character?: CharacterSheet): CharacterEquipment;
+    /**
+     * Add a modification to equipment (internal implementation)
+     */
+    private static addModificationToEquipment;
+    /**
+     * Find an item in equipment by name
+     */
+    private static findItem;
+    /**
+     * Get equipment data from ExtensionManager
+     */
+    private static getEquipmentData;
+    /**
+     * Apply modification effects to character
+     */
+    private static applyModificationEffects;
+    /**
+     * Create a modification from properties
+     *
+     * Convenience factory for creating modification objects.
+     *
+     * @param id - Unique ID for the modification
+     * @param name - Display name of the modification
+     * @param properties - Properties to add
+     * @param source - Source type (enchantment, curse, upgrade, etc.)
+     * @returns EquipmentModification object
+     */
+    static createModification(id: string, name: string, properties: EquipmentProperty[], source: string): EquipmentModification;
+    /**
+     * Create a modification with feature grants
+     *
+     * Convenience factory for creating feature-granting modifications.
+     *
+     * @param id - Unique ID for the modification
+     * @param name - Display name of the modification
+     * @param properties - Properties to add
+     * @param addsFeatures - Features to grant
+     * @param source - Source type
+     * @returns EquipmentModification object
+     */
+    static createFeatureModification(id: string, name: string, properties: EquipmentProperty[], addsFeatures: Array<string | EquipmentMiniFeature>, source: string): EquipmentModification;
+    /**
+     * Create a modification with skill grants
+     *
+     * Convenience factory for creating skill-granting modifications.
+     *
+     * @param id - Unique ID for the modification
+     * @param name - Display name of the modification
+     * @param properties - Properties to add
+     * @param addsSkills - Skills to grant
+     * @param source - Source type
+     * @returns EquipmentModification object
+     */
+    static createSkillModification(id: string, name: string, properties: EquipmentProperty[], addsSkills: Array<{
+        skillId: string;
+        level: 'proficient' | 'expertise';
+    }>, source: string): EquipmentModification;
+    /**
+     * Create a modification with spell grants
+     *
+     * Convenience factory for creating spell-granting modifications.
+     *
+     * @param id - Unique ID for the modification
+     * @param name - Display name of the modification
+     * @param properties - Properties to add
+     * @param addsSpells - Spells to grant
+     * @param source - Source type
+     * @returns EquipmentModification object
+     */
+    static createSpellModification(id: string, name: string, properties: EquipmentProperty[], addsSpells: Array<{
+        spellId: string;
+        level?: number;
+        uses?: number;
+        recharge?: string;
+    }>, source: string): EquipmentModification;
+    /**
+     * Generate a unique modification ID
+     *
+     * @param prefix - Optional prefix for the ID
+     * @returns Unique modification ID
+     */
+    static generateModificationId(prefix?: string): string;
+    /**
+     * Get all modification sources on an item
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @returns Array of unique source types
+     */
+    static getModificationSources(equipment: CharacterEquipment, itemName: string): string[];
+    /**
+     * Count modifications by source type
+     *
+     * Returns a record mapping each source type to the count of modifications
+     * from that source.
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @returns Record of source type to modification count
+     */
+    static countModificationsBySource(equipment: CharacterEquipment, itemName: string): Record<string, number>;
+    /**
+     * Count modifications for a specific source type
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @param source - Source type to count
+     * @returns Number of modifications from the specified source
+     */
+    static countModificationsForSource(equipment: CharacterEquipment, itemName: string, source: string): number;
+    /**
+     * Check if item has any curses
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @returns True if item has any curse modifications
+     */
+    static isCursed(equipment: CharacterEquipment, itemName: string): boolean;
+    /**
+     * Check if item is enchanted
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @returns True if item has any enchantment modifications
+     */
+    static isEnchanted(equipment: CharacterEquipment, itemName: string): boolean;
+    /**
+     * Get item summary including modifications
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @returns Summary object with item info and modifications
+     */
+    static getItemSummary(equipment: CharacterEquipment, itemName: string): {
+        name: string;
+        quantity: number;
+        equipped: boolean;
+        instanceId?: string;
+        templateId?: string;
+        modificationCount: number;
+        isCursed: boolean;
+        isEnchanted: boolean;
+        sources: string[];
+        effects: EquipmentProperty[];
+    } | null;
+}
+//# sourceMappingURL=EquipmentModifier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EquipmentModifier.d.ts","sourceRoot":"","sources":["../../../src/core/equipment/EquipmentModifier.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,246 @@
+/**
+ * Equipment Spawn Helper
+ *
+ * Helper functions for spawning multiple equipment items at once.
+ * NOT a full loot system - provides batch spawning utilities for:
+ * - Spawning from lists of equipment names
+ * - Spawning by rarity (common, uncommon, rare, very_rare, legendary)
+ * - Spawning by tags (weapon, armor, fire, magic, etc.)
+ * - Spawning random equipment (respecting spawn weights)
+ * - Spawning from templates (e.g., Flaming Sword)
+ * - Spawning treasure hoards (simplified D&D 5e table)
+ * - Adding spawned equipment to characters
+ */
+import type { CharacterSheet } from '../types/Character.js';
+import type { EnhancedEquipment, SpawnRandomOptions, TreasureHoardResult, BoxOpenResult } from '../types/Equipment.js';
+import { SeededRNG } from '../../utils/random.js';
+/**
+ * EquipmentSpawnHelper - Batch spawning utilities for equipment
+ *
+ * This class provides static methods for:
+ * - Spawning multiple items from a list of names
+ * - Spawning items by rarity
+ * - Spawning items by tags
+ * - Spawning random equipment with weighted selection
+ * - Spawning from templates
+ * - Spawning treasure hoards
+ * - Adding spawned equipment to characters
+ *
+ * DESIGN NOTES:
+ * - Uses SeededRNG for deterministic results
+ * - Respects spawnWeight property (0 = never random, still usable by game logic)
+ * - Integrates with ExtensionManager for custom equipment
+ * - NOT a full loot system - just helper utilities
+ */
+export declare class EquipmentSpawnHelper {
+    /**
+     * Spawn multiple items from an array of equipment names
+     *
+     * @param itemNames - Array of equipment names to spawn
+     * @param rng - Optional SeededRNG for shuffling (deterministic order)
+     * @returns Array of spawned equipment (undefined for missing items)
+     *
+     * @example
+     * ```typescript
+     * const rng = new SeededRNG('starter_gear');
+     * const items = EquipmentSpawnHelper.spawnFromList(
+     *     ['Longsword', 'Shield', 'Scale Mail'],
+     *     rng
+     * );
+     * ```
+     */
+    static spawnFromList(itemNames: string[], rng?: SeededRNG): (EnhancedEquipment | undefined)[];
+    /**
+     * Spawn items by rarity level
+     *
+     * Returns up to `count` items of the specified rarity.
+     * If there aren't enough items of that rarity, returns all available.
+     * Selection is random and deterministic if RNG is provided.
+     *
+     * @param rarity - Rarity level to spawn
+     * @param count - Maximum number of items to spawn
+     * @param rng - Optional SeededRNG for deterministic selection
+     * @returns Array of spawned equipment
+     *
+     * @example
+     * ```typescript
+     * const rng = new SeededRNG('rare_loot');
+     * const rareItems = EquipmentSpawnHelper.spawnByRarity('rare', 3, rng);
+     * ```
+     */
+    static spawnByRarity(rarity: 'common' | 'uncommon' | 'rare' | 'very_rare' | 'legendary', count: number, rng?: SeededRNG): EnhancedEquipment[];
+    /**
+     * Spawn items by tags
+     *
+     * Returns items that match ANY of the provided tags.
+     * If multiple tags provided, items matching any tag are included.
+     *
+     * @param tags - Array of tags to filter by
+     * @param count - Maximum number of items to spawn
+     * @param rng - Optional SeededRNG for deterministic selection
+     * @param options - Additional options (excludeZeroWeight, includeTypes, min/max rarity)
+     * @returns Array of spawned equipment
+     *
+     * @example
+     * ```typescript
+     * const rng = new SeededRNG('fire_weapons');
+     * const fireItems = EquipmentSpawnHelper.spawnByTags(
+     *     ['fire', 'weapon'],
+     *     5,
+     *     rng
+     * );
+     * ```
+     */
+    static spawnByTags(tags: string[], count: number, rng?: SeededRNG, options?: SpawnRandomOptions): EnhancedEquipment[];
+    /**
+     * Spawn random equipment respecting spawn weights
+     *
+     * Uses weighted random selection where items with higher spawnWeight
+     * are more likely to be selected. Items with spawnWeight: 0 are
+     * excluded when excludeZeroWeight is true.
+     *
+     * @param count - Number of items to spawn
+     * @param rng - SeededRNG for deterministic results
+     * @param options - Optional filters for spawning
+     * @returns Array of spawned equipment
+     *
+     * @example
+     * ```typescript
+     * const rng = new SeededRNG('loot_drop');
+     * const items = EquipmentSpawnHelper.spawnRandom(
+     *     3,
+     *     rng,
+     *     { excludeZeroWeight: true, includeTypes: ['weapon', 'armor'] }
+     * );
+     * ```
+     */
+    static spawnRandom(count: number, rng: SeededRNG, options?: SpawnRandomOptions): EnhancedEquipment[];
+    /**
+     * Spawn equipment from a template
+     *
+     * Creates a new equipment item by applying a template to a base item.
+     * If no base item is specified, uses a default item for the template type.
+     *
+     * Templates can be registered in ExtensionManager under 'equipment.templates'
+     * or defined in magicItemExamples.ts.
+     *
+     * @param templateId - ID of the template to apply
+     * @param baseItemName - Optional base item name (uses default if not specified)
+     * @returns New equipment with template applied, or null if template not found
+     *
+     * @example
+     * ```typescript
+     * const flamingSword = EquipmentSpawnHelper.spawnFromTemplate(
+     *     'flaming_weapon_template',
+     *     'Longsword'
+     * );
+     * ```
+     */
+    static spawnFromTemplate(templateId: string, baseItemName?: string): EnhancedEquipment | null;
+    /**
+     * Spawn treasure hoard (simplified D&D 5e table)
+     *
+     * Generates a treasure hoard based on challenge rating.
+     * This is a simplified version, not the full D&D 5e treasure tables.
+     *
+     * @param cr - Challenge rating for scaling (0-20+)
+     * @param rng - SeededRNG for deterministic results
+     * @returns Treasure hoard with items and estimated value
+     *
+     * @example
+     * ```typescript
+     * const rng = new SeededRNG('dragon_hoard');
+     * const hoard = EquipmentSpawnHelper.spawnTreasureHoard(15, rng);
+     * console.log(`Generated ${hoard.items.length} items worth ~${hoard.totalValue} gp`);
+     * ```
+     */
+    static spawnTreasureHoard(cr: number, rng: SeededRNG): TreasureHoardResult;
+    /**
+     * Add spawned equipment to character
+     *
+     * Adds items to character's inventory. Optionally equips them.
+     *
+     * @param character - Character to add items to
+     * @param items - Equipment items to add
+     * @param equip - Whether to auto-equip the items (default: false)
+     * @returns Updated character
+     *
+     * @example
+     * ```typescript
+     * const items = EquipmentSpawnHelper.spawnByRarity('rare', 2, rng);
+     * character = EquipmentSpawnHelper.addToCharacter(character, items, false);
+     * ```
+     */
+    static addToCharacter(character: CharacterSheet, items: EnhancedEquipment[], equip?: boolean): CharacterSheet;
+    /**
+     * Open a box item in a character's inventory
+     *
+     * Finds the named box in the character's items, opens it using BoxOpener,
+     * removes it from inventory (if consumeOnOpen), and adds the box contents
+     * to the character's inventory.
+     *
+     * If the box has opening requirements:
+     * - Checks requirements using BoxOpener.checkRequirements()
+     * - If requirements not met, returns error result without modifying character
+     * - If requirements met, consumes required items from inventory before opening
+     *
+     * @param character - Character whose inventory contains the box
+     * @param boxName - Name of the box item to open
+     * @param rng - SeededRNG for deterministic results
+     * @returns Object with updated character and BoxOpenResult, or null if box not found
+     *
+     * @example
+     * ```typescript
+     * const rng = new SeededRNG('open_pack');
+     * const result = EquipmentSpawnHelper.openBoxForCharacter(character, "Explorer's Pack", rng);
+     * if (result) {
+     *     character = result.character;
+     *     console.log(`Received ${result.result.gold} gold`);
+     *     console.log(`Received ${result.result.items.length} items`);
+     * }
+     *
+     * // With requirements
+     * const lockedResult = EquipmentSpawnHelper.openBoxForCharacter(character, "Locked Chest", rng);
+     * if (lockedResult) {
+     *     if (lockedResult.result.success) {
+     *         console.log('Opened chest!', lockedResult.result.consumedItems);
+     *     } else {
+     *         console.log('Cannot open:', lockedResult.result.error?.message);
+     *     }
+     * }
+     * ```
+     */
+    static openBoxForCharacter(character: CharacterSheet, boxName: string, rng: SeededRNG): {
+        character: CharacterSheet;
+        result: BoxOpenResult;
+    } | null;
+    /**
+     * Consume items from a character's inventory
+     *
+     * Private helper that reduces the quantity of an item in the character's
+     * items inventory, or removes it entirely if quantity reaches 0.
+     * Updates totalWeight accordingly.
+     *
+     * @param character - Character to consume from
+     * @param itemName - Name of the item to consume
+     * @param quantity - Quantity to consume
+     * @returns Object with success status and updated character
+     */
+    private static consumeItemFromCharacter;
+    /**
+     * Get default item for a template based on template properties
+     */
+    private static getDefaultItemForTemplate;
+    /**
+     * Get treasure item counts by rarity based on CR
+     * Simplified D&D 5e treasure table
+     * Uses provided RNG for deterministic results
+     */
+    private static getTreasureItemCount;
+    /**
+     * Estimate gold piece value of an item
+     * Simplified value estimation based on rarity
+     */
+    private static estimateItemValue;
+}
+//# sourceMappingURL=EquipmentSpawnHelper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EquipmentSpawnHelper.d.ts","sourceRoot":"","sources":["../../../src/core/equipment/EquipmentSpawnHelper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EACR,iBAAiB,EAEjB,kBAAkB,EAClB,mBAAmB,EACnB,aAAa,EAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAgBlD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,oBAAoB;IAC7B;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,aAAa,CAChB,SAAS,EAAE,MAAM,EAAE,EACnB,GAAG,CAAC,EAAE,SAAS,GAChB,CAAC,iBAAiB,GAAG,SAAS,CAAC,EAAE;IAgBpC;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,aAAa,CAChB,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,EAClE,KAAK,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,SAAS,GAChB,iBAAiB,EAAE;IAkCtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,WAAW,CACd,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,SAAS,EACf,OAAO,CAAC,EAAE,kBAAkB,GAC7B,iBAAiB,EAAE;IAoEtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,WAAW,CACd,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,SAAS,EACd,OAAO,CAAC,EAAE,kBAAkB,GAC7B,iBAAiB,EAAE;IAgEtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,iBAAiB,CACpB,UAAU,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,GACtB,iBAAiB,GAAG,IAAI;IA0D3B;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,kBAAkB,CACrB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,SAAS,GACf,mBAAmB;IAmCtB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,cAAc,CACjB,SAAS,EAAE,cAAc,EACzB,KAAK,EAAE,iBAAiB,EAAE,EAC1B,KAAK,GAAE,OAAe,GACvB,cAAc;IA4CjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,MAAM,CAAC,mBAAmB,CACtB,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,SAAS,GACf;QAAE,SAAS,EAAE,cAAc,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IA+D9D;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;IA6CvC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;IAkBxC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IA6BnC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;CAyBnC"}