@xivdyetools/core 1.3.7

package/dist/services/dye/DyeSearch.js

@@ -0,0 +1,196 @@
+/**
+ * Dye Search
+ * Per R-4: Focused class for dye search and matching operations
+ * Handles finding dyes by name, category, color distance, etc.
+ */
+import { ColorConverter } from '../color/ColorConverter.js';
+/**
+ * Dye search and matching utilities
+ * Per R-4: Single Responsibility - search operations only
+ */
+export class DyeSearch {
+    constructor(database) {
+        this.database = database;
+    }
+    /**
+     * Search dyes by name (case-insensitive, partial match)
+     */
+    searchByName(query) {
+        this.database.ensureLoaded();
+        const lowerQuery = query.toLowerCase().trim();
+        if (lowerQuery.length === 0) {
+            return [];
+        }
+        const dyes = this.database.getDyesInternal();
+        return dyes.filter((dye) => dye.name.toLowerCase().includes(lowerQuery));
+    }
+    /**
+     * Search dyes by category
+     */
+    searchByCategory(category) {
+        this.database.ensureLoaded();
+        const lowerCategory = category.toLowerCase();
+        const dyes = this.database.getDyesInternal();
+        return dyes.filter((dye) => dye.category.toLowerCase() === lowerCategory);
+    }
+    /**
+     * Filter dyes with optional exclusion list
+     */
+    filterDyes(filter = {}) {
+        this.database.ensureLoaded();
+        let results = [...this.database.getDyesInternal()];
+        if (filter.category) {
+            results = results.filter((dye) => dye.category === filter.category);
+        }
+        if (filter.excludeIds && filter.excludeIds.length > 0) {
+            const excludeSet = new Set(filter.excludeIds);
+            results = results.filter((dye) => !excludeSet.has(dye.id));
+        }
+        if (filter.minPrice !== undefined) {
+            // Defensively handle undefined/null cost values
+            results = results.filter((dye) => (dye.cost ?? 0) >= filter.minPrice);
+        }
+        if (filter.maxPrice !== undefined) {
+            // Defensively handle undefined/null cost values
+            results = results.filter((dye) => (dye.cost ?? 0) <= filter.maxPrice);
+        }
+        return results;
+    }
+    /**
+     * Find closest dye to a given hex color
+     * Per P-7: Uses k-d tree for O(log n) average case vs O(n) linear search
+     */
+    findClosestDye(hex, excludeIds = []) {
+        this.database.ensureLoaded();
+        try {
+            const targetRgb = ColorConverter.hexToRgb(hex);
+            const targetPoint = {
+                x: targetRgb.r,
+                y: targetRgb.g,
+                z: targetRgb.b,
+            };
+            // Per P-7: Use k-d tree if available
+            const kdTree = this.database.getKdTree();
+            if (kdTree && !kdTree.isEmpty()) {
+                const excludeSet = new Set(excludeIds);
+                // CORE-BUG-005: Also exclude Facewear dyes in k-d tree path for consistency with fallback
+                const nearest = kdTree.nearestNeighbor(targetPoint, (data) => {
+                    const dye = data;
+                    return excludeSet.has(dye.id) || dye.category === 'Facewear';
+                });
+                if (nearest && nearest.data) {
+                    return nearest.data;
+                }
+            }
+            // Fallback to linear search (shouldn't happen if k-d tree is built)
+            let closest = null;
+            let minDistance = Infinity;
+            const excludeSet = new Set(excludeIds);
+            const dyes = this.database.getDyesInternal();
+            for (const dye of dyes) {
+                if (excludeSet.has(dye.id) || dye.category === 'Facewear') {
+                    continue;
+                }
+                try {
+                    const distance = ColorConverter.getColorDistance(hex, dye.hex);
+                    if (distance < minDistance) {
+                        minDistance = distance;
+                        closest = dye;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            return closest;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Find dyes within a color distance threshold
+     * Per P-7: Uses k-d tree for efficient range queries
+     */
+    findDyesWithinDistance(hex, maxDistance, limit) {
+        this.database.ensureLoaded();
+        try {
+            const targetRgb = ColorConverter.hexToRgb(hex);
+            const targetPoint = {
+                x: targetRgb.r,
+                y: targetRgb.g,
+                z: targetRgb.b,
+            };
+            // Per P-7: Use k-d tree if available
+            const kdTree = this.database.getKdTree();
+            if (kdTree && !kdTree.isEmpty()) {
+                const kdResults = kdTree.pointsWithinDistance(targetPoint, maxDistance);
+                // Convert to Dye array and apply limit
+                const dyes = kdResults.map((item) => item.point.data);
+                if (limit && limit > 0) {
+                    return dyes.slice(0, limit);
+                }
+                return dyes;
+            }
+            // Fallback to linear search
+            const results = [];
+            const dyes = this.database.getDyesInternal();
+            for (const dye of dyes) {
+                try {
+                    if (dye.category === 'Facewear') {
+                        continue;
+                    }
+                    const distance = ColorConverter.getColorDistance(hex, dye.hex);
+                    if (distance <= maxDistance) {
+                        results.push({ dye, distance });
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            results.sort((a, b) => a.distance - b.distance);
+            if (limit) {
+                results.splice(limit);
+            }
+            return results.map((item) => item.dye);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Get dyes sorted by brightness
+     */
+    getDyesSortedByBrightness(ascending = true) {
+        this.database.ensureLoaded();
+        return [...this.database.getDyesInternal()].sort((a, b) => {
+            const brightnessA = a.hsv.v;
+            const brightnessB = b.hsv.v;
+            return ascending ? brightnessA - brightnessB : brightnessB - brightnessA;
+        });
+    }
+    /**
+     * Get dyes sorted by saturation
+     */
+    getDyesSortedBySaturation(ascending = true) {
+        this.database.ensureLoaded();
+        return [...this.database.getDyesInternal()].sort((a, b) => {
+            const satA = a.hsv.s;
+            const satB = b.hsv.s;
+            return ascending ? satA - satB : satB - satA;
+        });
+    }
+    /**
+     * Get dyes sorted by hue
+     */
+    getDyesSortedByHue(ascending = true) {
+        this.database.ensureLoaded();
+        return [...this.database.getDyesInternal()].sort((a, b) => {
+            const hueA = a.hsv.h;
+            const hueB = b.hsv.h;
+            return ascending ? hueA - hueB : hueB - hueA;
+        });
+    }
+}
+//# sourceMappingURL=DyeSearch.js.map

package/dist/services/dye/DyeSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DyeSearch.js","sourceRoot":"","sources":["../../../src/services/dye/DyeSearch.ts"],"names":[],"mappings":"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"}

package/dist/services/dye/HarmonyGenerator.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Harmony Generator
+ * Per R-4: Focused class for color harmony generation
+ * Handles triadic, analogous, complementary, and other harmony schemes
+ */
+import type { Dye } from '../../types/index.js';
+import type { DyeDatabase } from './DyeDatabase.js';
+import type { DyeSearch } from './DyeSearch.js';
+/**
+ * Color harmony generator
+ * Per R-4: Single Responsibility - harmony generation only
+ */
+export declare class HarmonyGenerator {
+    private database;
+    private search;
+    constructor(database: DyeDatabase, search: DyeSearch);
+    /**
+     * Find dyes that form a complementary color pair
+     * Excludes Facewear dyes (generic names like "Red", "Blue")
+     */
+    findComplementaryPair(hex: string): Dye | null;
+    /**
+     * Find the closest dye that is not Facewear
+     * Iteratively searches until a non-Facewear dye is found
+     * CORE-BUG-003: Removed hard-coded limit of 10 iterations
+     */
+    private findClosestNonFacewearDye;
+    /**
+     * Find analogous dyes (adjacent on color wheel)
+     * Returns dyes at ±angle degrees from the base color
+     *
+     * @remarks
+     * May return fewer dyes than expected if no suitable matches exist
+     * at the target hue positions or if all candidates are excluded.
+     */
+    findAnalogousDyes(hex: string, angle?: number): Dye[];
+    /**
+     * Find triadic color scheme (colors 120° apart on color wheel)
+     *
+     * @remarks
+     * May return 0, 1, or 2 dyes depending on available matches.
+     * Use the length of the returned array to determine actual results.
+     */
+    findTriadicDyes(hex: string): Dye[];
+    /**
+     * Find square color scheme (colors 90° apart on color wheel)
+     *
+     * @remarks
+     * May return fewer than 3 dyes if suitable matches are not found.
+     */
+    findSquareDyes(hex: string): Dye[];
+    /**
+     * Find tetradic color scheme (two complementary pairs)
+     *
+     * @remarks
+     * May return fewer than 3 dyes if suitable matches are not found.
+     */
+    findTetradicDyes(hex: string): Dye[];
+    /**
+     * Find monochromatic dyes (same hue, varying saturation/brightness)
+     * Excludes Facewear dyes (generic names like "Red", "Blue")
+     */
+    findMonochromaticDyes(hex: string, limit?: number): Dye[];
+    /**
+     * Find compound harmony (analogous + complementary)
+     *
+     * @remarks
+     * May return fewer than 3 dyes if suitable matches are not found.
+     */
+    findCompoundDyes(hex: string): Dye[];
+    /**
+     * Find split-complementary harmony (±30° from the complementary hue)
+     *
+     * @remarks
+     * May return 0, 1, or 2 dyes depending on available matches.
+     */
+    findSplitComplementaryDyes(hex: string): Dye[];
+    /**
+     * Find shades (similar tones, ±15°)
+     *
+     * @remarks
+     * May return 0, 1, or 2 dyes depending on available matches.
+     */
+    findShadesDyes(hex: string): Dye[];
+    /**
+     * Generic helper for hue-based harmonies
+     *
+     * @remarks
+     * This method may return fewer dyes than the number of offsets provided.
+     * This can happen when:
+     * - No dyes exist near the target hue position
+     * - All candidate dyes are in the 'Facewear' category (excluded)
+     * - The same dye would be selected multiple times (prevented by usedDyeIds)
+     *
+     * Consumers should check the returned array length rather than assuming
+     * a fixed number of results.
+     *
+     * @param hex - Base hex color
+     * @param offsets - Array of hue offsets in degrees
+     * @param options - Options including tolerance (default: 45°)
+     * @returns Array of matched dyes (may be shorter than offsets array)
+     */
+    private findHarmonyDyesByOffsets;
+    /**
+     * Find closest dye by hue difference with graceful fallback
+     * Per P-2: Uses hue-indexed map for 70-90% speedup
+     */
+    private findClosestDyeByHue;
+}
+//# sourceMappingURL=HarmonyGenerator.d.ts.map

package/dist/services/dye/HarmonyGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HarmonyGenerator.d.ts","sourceRoot":"","sources":["../../../src/services/dye/HarmonyGenerator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAEhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;GAGG;AACH,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,MAAM;gBADN,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,SAAS;IAG3B;;;OAGG;IACH,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI;IAa9C;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;IAoBjC;;;;;;;OAOG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,GAAG,EAAE;IAKzD;;;;;;OAMG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE;IAInC;;;;;OAKG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE;IAIlC;;;;;OAKG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE;IAKpC;;;OAGG;IACH,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,GAAG,GAAG,EAAE;IAkC5D;;;;;OAKG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE;IAKpC;;;;;OAKG;IACH,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE;IAI9C;;;;;OAKG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE;IAOlC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,wBAAwB;IA2BhC;;;OAGG;IACH,OAAO,CAAC,mBAAmB;CAsC5B"}

package/dist/services/dye/HarmonyGenerator.js

@@ -0,0 +1,221 @@
+/**
+ * Harmony Generator
+ * Per R-4: Focused class for color harmony generation
+ * Handles triadic, analogous, complementary, and other harmony schemes
+ */
+import { ColorManipulator } from '../color/ColorManipulator.js';
+/**
+ * Color harmony generator
+ * Per R-4: Single Responsibility - harmony generation only
+ */
+export class HarmonyGenerator {
+    constructor(database, search) {
+        this.database = database;
+        this.search = search;
+    }
+    /**
+     * Find dyes that form a complementary color pair
+     * Excludes Facewear dyes (generic names like "Red", "Blue")
+     */
+    findComplementaryPair(hex) {
+        this.database.ensureLoaded();
+        try {
+            const complementaryHex = ColorManipulator.invert(hex);
+            // Find closest dye, excluding Facewear
+            return this.findClosestNonFacewearDye(complementaryHex);
+        }
+        catch {
+            // Invalid hex color
+            return null;
+        }
+    }
+    /**
+     * Find the closest dye that is not Facewear
+     * Iteratively searches until a non-Facewear dye is found
+     * CORE-BUG-003: Removed hard-coded limit of 10 iterations
+     */
+    findClosestNonFacewearDye(hex, excludeIds = []) {
+        const allExcluded = [...excludeIds];
+        // Get total dye count to avoid infinite loops while ensuring we check all dyes if needed
+        const totalDyes = this.database.getDyesInternal().length;
+        for (let i = 0; i < totalDyes; i++) {
+            const candidate = this.search.findClosestDye(hex, allExcluded);
+            if (!candidate)
+                return null;
+            if (candidate.category !== 'Facewear') {
+                return candidate;
+            }
+            // This candidate is Facewear, exclude it and try again
+            allExcluded.push(candidate.id);
+        }
+        return null;
+    }
+    /**
+     * Find analogous dyes (adjacent on color wheel)
+     * Returns dyes at ±angle degrees from the base color
+     *
+     * @remarks
+     * May return fewer dyes than expected if no suitable matches exist
+     * at the target hue positions or if all candidates are excluded.
+     */
+    findAnalogousDyes(hex, angle = 30) {
+        // Use harmony helper to find dyes at +angle and -angle positions
+        return this.findHarmonyDyesByOffsets(hex, [angle, -angle]);
+    }
+    /**
+     * Find triadic color scheme (colors 120° apart on color wheel)
+     *
+     * @remarks
+     * May return 0, 1, or 2 dyes depending on available matches.
+     * Use the length of the returned array to determine actual results.
+     */
+    findTriadicDyes(hex) {
+        return this.findHarmonyDyesByOffsets(hex, [120, 240]);
+    }
+    /**
+     * Find square color scheme (colors 90° apart on color wheel)
+     *
+     * @remarks
+     * May return fewer than 3 dyes if suitable matches are not found.
+     */
+    findSquareDyes(hex) {
+        return this.findHarmonyDyesByOffsets(hex, [90, 180, 270]);
+    }
+    /**
+     * Find tetradic color scheme (two complementary pairs)
+     *
+     * @remarks
+     * May return fewer than 3 dyes if suitable matches are not found.
+     */
+    findTetradicDyes(hex) {
+        // Two adjacent hues + their complements (e.g., base+60 and base+240)
+        return this.findHarmonyDyesByOffsets(hex, [60, 180, 240]);
+    }
+    /**
+     * Find monochromatic dyes (same hue, varying saturation/brightness)
+     * Excludes Facewear dyes (generic names like "Red", "Blue")
+     */
+    findMonochromaticDyes(hex, limit = 6) {
+        this.database.ensureLoaded();
+        const baseDye = this.findClosestNonFacewearDye(hex);
+        if (!baseDye)
+            return [];
+        const baseHue = baseDye.hsv.h;
+        const results = [];
+        const dyes = this.database.getDyesInternal();
+        // Find dyes with similar hue but different saturation/value
+        for (const dye of dyes) {
+            // Skip Facewear dyes (generic names)
+            if (dye.category === 'Facewear')
+                continue;
+            const hueDiff = Math.min(Math.abs(dye.hsv.h - baseHue), 360 - Math.abs(dye.hsv.h - baseHue));
+            // Hue must be very close (within ±15°)
+            if (hueDiff <= 15 && dye.id !== baseDye.id) {
+                // Calculate difference in saturation and value
+                const satDiff = Math.abs(dye.hsv.s - baseDye.hsv.s);
+                const valDiff = Math.abs(dye.hsv.v - baseDye.hsv.v);
+                const satValDiff = satDiff + valDiff;
+                results.push({ dye, satValDiff });
+            }
+        }
+        // Sort by saturation/value difference (prefer more variety)
+        results.sort((a, b) => b.satValDiff - a.satValDiff);
+        return results.slice(0, limit).map((item) => item.dye);
+    }
+    /**
+     * Find compound harmony (analogous + complementary)
+     *
+     * @remarks
+     * May return fewer than 3 dyes if suitable matches are not found.
+     */
+    findCompoundDyes(hex) {
+        // ±30° from base + complement
+        return this.findHarmonyDyesByOffsets(hex, [30, -30, 180], { tolerance: 35 });
+    }
+    /**
+     * Find split-complementary harmony (±30° from the complementary hue)
+     *
+     * @remarks
+     * May return 0, 1, or 2 dyes depending on available matches.
+     */
+    findSplitComplementaryDyes(hex) {
+        return this.findHarmonyDyesByOffsets(hex, [150, 210]);
+    }
+    /**
+     * Find shades (similar tones, ±15°)
+     *
+     * @remarks
+     * May return 0, 1, or 2 dyes depending on available matches.
+     */
+    findShadesDyes(hex) {
+        this.database.ensureLoaded();
+        // Use tighter tolerance (5°) for shades to ensure results are close to target hue
+        return this.findHarmonyDyesByOffsets(hex, [15, -15], { tolerance: 5 });
+    }
+    /**
+     * Generic helper for hue-based harmonies
+     *
+     * @remarks
+     * This method may return fewer dyes than the number of offsets provided.
+     * This can happen when:
+     * - No dyes exist near the target hue position
+     * - All candidate dyes are in the 'Facewear' category (excluded)
+     * - The same dye would be selected multiple times (prevented by usedDyeIds)
+     *
+     * Consumers should check the returned array length rather than assuming
+     * a fixed number of results.
+     *
+     * @param hex - Base hex color
+     * @param offsets - Array of hue offsets in degrees
+     * @param options - Options including tolerance (default: 45°)
+     * @returns Array of matched dyes (may be shorter than offsets array)
+     */
+    findHarmonyDyesByOffsets(hex, offsets, options = {}) {
+        this.database.ensureLoaded();
+        const baseDye = this.search.findClosestDye(hex);
+        if (!baseDye)
+            return [];
+        const usedDyeIds = new Set([baseDye.id]);
+        const results = [];
+        const baseHue = baseDye.hsv.h;
+        const tolerance = options.tolerance ?? 45;
+        for (const offset of offsets) {
+            const targetHue = (baseHue + offset + 360) % 360;
+            const match = this.findClosestDyeByHue(targetHue, usedDyeIds, tolerance);
+            if (match) {
+                results.push(match);
+                usedDyeIds.add(match.id);
+            }
+        }
+        return results;
+    }
+    /**
+     * Find closest dye by hue difference with graceful fallback
+     * Per P-2: Uses hue-indexed map for 70-90% speedup
+     */
+    findClosestDyeByHue(targetHue, usedIds, tolerance) {
+        let withinTolerance = null;
+        let bestOverall = null;
+        // Per P-2: Only search relevant hue buckets instead of all dyes
+        const bucketsToSearch = this.database.getHueBucketsToSearch(targetHue, tolerance);
+        for (const bucket of bucketsToSearch) {
+            const dyesInBucket = this.database.getDyesByHueBucket(bucket);
+            for (const dye of dyesInBucket) {
+                if (usedIds.has(dye.id) || dye.category === 'Facewear') {
+                    continue;
+                }
+                const diff = Math.min(Math.abs(dye.hsv.h - targetHue), 360 - Math.abs(dye.hsv.h - targetHue));
+                if (!bestOverall || diff < bestOverall.diff) {
+                    bestOverall = { dye, diff };
+                }
+                if (diff <= tolerance) {
+                    if (!withinTolerance || diff < withinTolerance.diff) {
+                        withinTolerance = { dye, diff };
+                    }
+                }
+            }
+        }
+        return withinTolerance?.dye ?? bestOverall?.dye ?? null;
+    }
+}
+//# sourceMappingURL=HarmonyGenerator.js.map

package/dist/services/dye/HarmonyGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HarmonyGenerator.js","sourceRoot":"","sources":["../../../src/services/dye/HarmonyGenerator.ts"],"names":[],"mappings":"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"}

package/dist/services/localization/LocaleLoader.d.ts

@@ -0,0 +1,38 @@
+/**
+ * LocaleLoader - Loads locale JSON files
+ *
+ * Per R-4: Single Responsibility - locale file loading only
+ * Uses static imports for browser/bundler compatibility
+ *
+ * @module services/localization
+ */
+import type { LocaleCode, LocaleData } from '../../types/index.js';
+/**
+ * Loads locale data from pre-bundled JSON files
+ */
+export declare class LocaleLoader {
+    /**
+     * Load locale data from pre-bundled JSON
+     *
+     * @param locale - Locale code to load
+     * @returns Locale data
+     * @throws {AppError} If locale file fails to load or is invalid
+     *
+     * @example
+     * ```typescript
+     * const loader = new LocaleLoader();
+     * const jaData = loader.loadLocale('ja');
+     * console.log(jaData.labels.dye); // "カララント:"
+     * ```
+     */
+    loadLocale(locale: LocaleCode): LocaleData;
+    /**
+     * Validate locale data structure
+     *
+     * @param data - Unknown data to validate
+     * @returns true if data matches LocaleData interface
+     * @private
+     */
+    private isValidLocaleData;
+}
+//# sourceMappingURL=LocaleLoader.d.ts.map

package/dist/services/localization/LocaleLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocaleLoader.d.ts","sourceRoot":"","sources":["../../../src/services/localization/LocaleLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAqBnE;;GAEG;AACH,qBAAa,YAAY;IACvB;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU;IAuB1C;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;CAmB1B"}

package/dist/services/localization/LocaleLoader.js

@@ -0,0 +1,83 @@
+/**
+ * LocaleLoader - Loads locale JSON files
+ *
+ * Per R-4: Single Responsibility - locale file loading only
+ * Uses static imports for browser/bundler compatibility
+ *
+ * @module services/localization
+ */
+import { AppError, ErrorCode } from '../../types/index.js';
+// Static imports for all locale files (bundler-compatible)
+import enLocale from '../../data/locales/en.json' with { type: 'json' };
+import jaLocale from '../../data/locales/ja.json' with { type: 'json' };
+import deLocale from '../../data/locales/de.json' with { type: 'json' };
+import frLocale from '../../data/locales/fr.json' with { type: 'json' };
+import koLocale from '../../data/locales/ko.json' with { type: 'json' };
+import zhLocale from '../../data/locales/zh.json' with { type: 'json' };
+// Map of locale codes to pre-loaded data
+const localeMap = {
+    en: enLocale,
+    ja: jaLocale,
+    de: deLocale,
+    fr: frLocale,
+    ko: koLocale,
+    zh: zhLocale,
+};
+/**
+ * Loads locale data from pre-bundled JSON files
+ */
+export class LocaleLoader {
+    /**
+     * Load locale data from pre-bundled JSON
+     *
+     * @param locale - Locale code to load
+     * @returns Locale data
+     * @throws {AppError} If locale file fails to load or is invalid
+     *
+     * @example
+     * ```typescript
+     * const loader = new LocaleLoader();
+     * const jaData = loader.loadLocale('ja');
+     * console.log(jaData.labels.dye); // "カララント:"
+     * ```
+     */
+    loadLocale(locale) {
+        try {
+            const data = localeMap[locale];
+            if (!data) {
+                throw new Error(`Locale "${locale}" not found in bundled locales`);
+            }
+            // Validate structure
+            if (!this.isValidLocaleData(data)) {
+                throw new Error(`Invalid locale data structure for ${locale}`);
+            }
+            return data;
+        }
+        catch (error) {
+            throw new AppError(ErrorCode.LOCALE_LOAD_FAILED, `Failed to load locale "${locale}": ${error instanceof Error ? error.message : 'Unknown error'}`, 'error');
+        }
+    }
+    /**
+     * Validate locale data structure
+     *
+     * @param data - Unknown data to validate
+     * @returns true if data matches LocaleData interface
+     * @private
+     */
+    isValidLocaleData(data) {
+        if (!data || typeof data !== 'object') {
+            return false;
+        }
+        const localeData = data;
+        return (typeof localeData.locale === 'string' &&
+            typeof localeData.meta === 'object' &&
+            typeof localeData.labels === 'object' &&
+            typeof localeData.dyeNames === 'object' &&
+            typeof localeData.categories === 'object' &&
+            typeof localeData.acquisitions === 'object' &&
+            Array.isArray(localeData.metallicDyeIds) &&
+            typeof localeData.harmonyTypes === 'object' &&
+            typeof localeData.visionTypes === 'object');
+    }
+}
+//# sourceMappingURL=LocaleLoader.js.map