@xivdyetools/core 2.6.0 → 4.0.1

package/dist/services/PresetService.js

@@ -116,17 +116,6 @@ export class PresetService {
     getPreset(id) {
         return this.presetById.get(id);
     }
-    /**
-     * Get preset count by category
-     * @returns Map of category to preset count
-     */
-    getPresetCountByCategory() {
-        const counts = new Map();
-        for (const preset of this.data.palettes) {
-            counts.set(preset.category, (counts.get(preset.category) ?? 0) + 1);
-        }
-        return counts;
-    }
     // ============================================================================
     // Search Operations
     // ============================================================================
@@ -146,23 +135,22 @@ export class PresetService {
      * // Returns: Paladin, Warrior, Dark Knight, Gunbreaker
      * ```
      */
-    searchPresets(query) {
+    searchPresets(query, dyeService) {
         const lowerQuery = query.toLowerCase().trim();
         if (!lowerQuery) {
             return [];
         }
+        // With a dye service, a palette also matches on the names of the dyes it
+        // contains — "search presets, dyes, tags" is only true if dyes count.
+        const matchesDye = (p) => {
+            if (!dyeService)
+                return false;
+            return p.dyes.some((stainId) => dyeService.getByStainId(stainId)?.name.toLowerCase().includes(lowerQuery));
+        };
         return this.data.palettes.filter((p) => p.name.toLowerCase().includes(lowerQuery) ||
             p.description.toLowerCase().includes(lowerQuery) ||
-            p.tags.some((tag) => tag.toLowerCase().includes(lowerQuery)));
-    }
-    /**
-     * Search presets by tag (exact match)
-     * @param tag - Tag to search for (case-insensitive)
-     * @returns Array of presets with that tag
-     */
-    getPresetsByTag(tag) {
-        const lowerTag = tag.toLowerCase().trim();
-        return this.data.palettes.filter((p) => p.tags.some((t) => t.toLowerCase() === lowerTag));
+            p.tags.some((tag) => tag.toLowerCase().includes(lowerQuery)) ||
+            matchesDye(p));
     }
     // ============================================================================
     // Random Selection
@@ -220,44 +208,9 @@ export class PresetService {
         }
         return {
             ...preset,
-            resolvedDyes: preset.dyes.map((dyeId) => dyeService.getDyeById(dyeId)),
+            // 5.0: presets.json 2.0.0 stores stainIDs (never derived from ranges)
+            resolvedDyes: preset.dyes.map((stainId) => dyeService.getByStainId(stainId)),
         };
     }
-    /**
-     * Resolve multiple presets with their Dye objects
-     * @param presets - Array of presets to resolve
-     * @param dyeService - DyeService instance for resolving dye IDs
-     * @returns Array of resolved presets
-     */
-    resolvePresets(presets, dyeService) {
-        return presets.map((preset) => ({
-            ...preset,
-            resolvedDyes: preset.dyes.map((dyeId) => dyeService.getDyeById(dyeId)),
-        }));
-    }
-    // ============================================================================
-    // Metadata
-    // ============================================================================
-    /**
-     * Get data version
-     * @returns Version string from preset data
-     */
-    getVersion() {
-        return this.data.version;
-    }
-    /**
-     * Get last update timestamp
-     * @returns ISO date string of last update
-     */
-    getLastUpdated() {
-        return this.data.lastUpdated;
-    }
-    /**
-     * Get total number of presets
-     * @returns Total preset count
-     */
-    getPresetCount() {
-        return this.data.palettes.length;
-    }
 }
 //# sourceMappingURL=PresetService.js.map

package/dist/services/PresetService.js.map

@@ -1 +1 @@
-{"version":3,"file":"PresetService.js","sourceRoot":"","sources":["../../src/services/PresetService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA4BH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,aAAa;IAChB,IAAI,CAAa;IACjB,UAAU,CAA6B;IAE/C;;;OAGG;IACH,YAAY,UAAsB;QAChC,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,yCAAyC;QACzC,IAAI,CAAC,UAAU,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,+EAA+E;IAC/E,sBAAsB;IACtB,+EAA+E;IAE/E;;;;;;;;;OASG;IACH,aAAa;QACX,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;YAC/D,EAAE;YACF,GAAG,IAAI;SACR,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;;OAIG;IACH,eAAe,CAAC,QAAwB;QACtC,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,+EAA+E;IAC/E,mBAAmB;IACnB,+EAA+E;IAE/E;;;OAGG;IACH,aAAa;QACX,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,QAAwB;QAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;IACnE,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAU;QAClB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,wBAAwB;QACtB,MAAM,MAAM,GAAG,IAAI,GAAG,EAA0B,CAAC;QACjD,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACxC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,+EAA+E;IAC/E,oBAAoB;IACpB,+EAA+E;IAE/E;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,KAAa;QACzB,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;QAC9C,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAC9B,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC;YACzC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC;YAChD,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAC/D,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,eAAe,CAAC,GAAW;QACzB,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC;IAC5F,CAAC;IAED,+EAA+E;IAC/E,mBAAmB;IACnB,+EAA+E;IAE/E;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,QAAyB;QACvC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;QAEjF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,+EAA+E;IAC/E,uCAAuC;IACvC,+EAA+E;IAE/E;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,iBAAiB,CAAC,EAAU,EAAE,UAAuB;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO;YACL,GAAG,MAAM;YACT,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;SACvE,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,OAAwB,EAAE,UAAuB;QAC9D,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC9B,GAAG,MAAM;YACT,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;SACvE,CAAC,CAAC,CAAC;IACN,CAAC;IAED,+EAA+E;IAC/E,WAAW;IACX,+EAA+E;IAE/E;;;OAGG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IACnC,CAAC;CACF"}
+{"version":3,"file":"PresetService.js","sourceRoot":"","sources":["../../src/services/PresetService.ts"],"names":[],"mappings":"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"}

package/dist/services/chara/chara-models.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `.chara` equipment identity — the model keys a character file carries and
+ * how they pack into the Item sheet's `ModelMain` / `ModelSub` values.
+ *
+ * Measured rules (docs/research/chara-equipment-resolution, 47-file corpus,
+ * resolved live against XIVAPI v2 — 273/273 gear keys, 41/41 weapons):
+ * - The Item sheet stores a model reference as one `uint64`, four
+ *   little-endian 16-bit lanes (SaintCoinach `Quad`). The `.chara` fields are
+ *   those lanes: armour/accessories `ModelMain = base | variant << 16`,
+ *   weapons `ModelMain = set | base << 16 | variant << 32`.
+ * - The slot is a mandatory second key: one gear *set* shares a `ModelMain`
+ *   across head/body/hands/legs/feet, so a search must also filter on the
+ *   `EquipSlotCategory` boolean column (rings: `FingerL` / `FingerR`).
+ * - `ModelBase == 0` (weapons: `ModelSet == 0` too) means the slot is empty.
+ * - Off-hands resolve THROUGH the main hand — see the resolver on api-worker.
+ *
+ * Nothing here touches the network; these are the pure packing helpers the
+ * parser, the api-worker resolver and the web-app client all share.
+ */
+import type { CharaGearSlotId } from './chara-parser.js';
+/** A worn piece's model identity, as the `.chara` file spells it. */
+export interface CharaGearModel {
+    slot: CharaGearSlotId;
+    /** Weapon slots only — the `w0634` set number. Absent on armour/accessories. */
+    set?: number;
+    /** Armour: the `e0361` set. Weapons: the `b0019` body. */
+    base: number;
+    /** Material variant */
+    variant: number;
+}
+/** The two slots whose model is a weapon triple rather than a gear pair. */
+export declare const CHARA_WEAPON_SLOTS: readonly CharaGearSlotId[];
+export declare function isCharaWeaponSlot(slot: CharaGearSlotId): boolean;
+/**
+ * `.chara` slot → `EquipSlotCategory` boolean column. This is the mandatory
+ * second search key: `+EquipSlotCategory.<field>=1`.
+ */
+export declare const CHARA_SLOT_SEARCH_FIELD: Record<CharaGearSlotId, string>;
+/**
+ * Armour / accessory `ModelMain`: `base | variant << 16`. Computed with
+ * arithmetic rather than `<<` so a variant above 0x7FFF cannot overflow the
+ * signed 32-bit shift — the value is an unsigned 32-bit lane pair.
+ *
+ * Beech Mask of Casting: `gearModelKey(361, 5) === 328041` (Item#18085).
+ */
+export declare function gearModelKey(base: number, variant: number): number;
+/**
+ * Weapon `ModelMain`: `set | base << 16 | variant << 32`. Exceeds 2^32, so it
+ * is a BigInt — serialise with `String()` for JSON / cache keys.
+ *
+ * Runaway Bow: `weaponModelKey(634, 19, 1) === 4296213114n` (Item#49486);
+ * its quiver `{698, 149, 1}` is that item's `ModelSub`.
+ */
+export declare function weaponModelKey(set: number, base: number, variant: number): bigint;
+/**
+ * The packed key as a decimal string — the form used on the wire and in
+ * cache keys (weapon values do not fit a JS number exactly past 2^53 only in
+ * theory, but a BigInt never round-trips JSON, so everything is a string).
+ */
+export declare function charaModelKey(model: CharaGearModel): string;
+/**
+ * The human label for a model with no Item row: `set·base·variant` for a
+ * weapon, `base·variant` otherwise (the design's "MODEL 9903·1").
+ */
+export declare function formatCharaModelLabel(model: CharaGearModel): string;
+/** True when the record describes a worn piece rather than an empty slot. */
+export declare function isWornCharaModel(slot: CharaGearSlotId, set: number, base: number): boolean;
+//# sourceMappingURL=chara-models.d.ts.map

package/dist/services/chara/chara-models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chara-models.d.ts","sourceRoot":"","sources":["../../../src/services/chara/chara-models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,eAAe,CAAC;IACtB,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,EAAE,SAAS,eAAe,EAA4B,CAAC;AAEtF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAEhE;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAanE,CAAC;AAIF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAI3D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAInE;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GACX,OAAO,CAET"}

package/dist/services/chara/chara-models.js

@@ -0,0 +1,87 @@
+/**
+ * `.chara` equipment identity — the model keys a character file carries and
+ * how they pack into the Item sheet's `ModelMain` / `ModelSub` values.
+ *
+ * Measured rules (docs/research/chara-equipment-resolution, 47-file corpus,
+ * resolved live against XIVAPI v2 — 273/273 gear keys, 41/41 weapons):
+ * - The Item sheet stores a model reference as one `uint64`, four
+ *   little-endian 16-bit lanes (SaintCoinach `Quad`). The `.chara` fields are
+ *   those lanes: armour/accessories `ModelMain = base | variant << 16`,
+ *   weapons `ModelMain = set | base << 16 | variant << 32`.
+ * - The slot is a mandatory second key: one gear *set* shares a `ModelMain`
+ *   across head/body/hands/legs/feet, so a search must also filter on the
+ *   `EquipSlotCategory` boolean column (rings: `FingerL` / `FingerR`).
+ * - `ModelBase == 0` (weapons: `ModelSet == 0` too) means the slot is empty.
+ * - Off-hands resolve THROUGH the main hand — see the resolver on api-worker.
+ *
+ * Nothing here touches the network; these are the pure packing helpers the
+ * parser, the api-worker resolver and the web-app client all share.
+ */
+/** The two slots whose model is a weapon triple rather than a gear pair. */
+export const CHARA_WEAPON_SLOTS = ['MainHand', 'OffHand'];
+export function isCharaWeaponSlot(slot) {
+    return CHARA_WEAPON_SLOTS.includes(slot);
+}
+/**
+ * `.chara` slot → `EquipSlotCategory` boolean column. This is the mandatory
+ * second search key: `+EquipSlotCategory.<field>=1`.
+ */
+export const CHARA_SLOT_SEARCH_FIELD = {
+    MainHand: 'MainHand',
+    OffHand: 'OffHand',
+    HeadGear: 'Head',
+    Body: 'Body',
+    Hands: 'Gloves',
+    Legs: 'Legs',
+    Feet: 'Feet',
+    Ears: 'Ears',
+    Neck: 'Neck',
+    Wrists: 'Wrists',
+    LeftRing: 'FingerL',
+    RightRing: 'FingerR',
+};
+const LANE = 65536;
+/**
+ * Armour / accessory `ModelMain`: `base | variant << 16`. Computed with
+ * arithmetic rather than `<<` so a variant above 0x7FFF cannot overflow the
+ * signed 32-bit shift — the value is an unsigned 32-bit lane pair.
+ *
+ * Beech Mask of Casting: `gearModelKey(361, 5) === 328041` (Item#18085).
+ */
+export function gearModelKey(base, variant) {
+    return base + variant * LANE;
+}
+/**
+ * Weapon `ModelMain`: `set | base << 16 | variant << 32`. Exceeds 2^32, so it
+ * is a BigInt — serialise with `String()` for JSON / cache keys.
+ *
+ * Runaway Bow: `weaponModelKey(634, 19, 1) === 4296213114n` (Item#49486);
+ * its quiver `{698, 149, 1}` is that item's `ModelSub`.
+ */
+export function weaponModelKey(set, base, variant) {
+    return BigInt(set) + (BigInt(base) << 16n) + (BigInt(variant) << 32n);
+}
+/**
+ * The packed key as a decimal string — the form used on the wire and in
+ * cache keys (weapon values do not fit a JS number exactly past 2^53 only in
+ * theory, but a BigInt never round-trips JSON, so everything is a string).
+ */
+export function charaModelKey(model) {
+    return isCharaWeaponSlot(model.slot)
+        ? String(weaponModelKey(model.set ?? 0, model.base, model.variant))
+        : String(gearModelKey(model.base, model.variant));
+}
+/**
+ * The human label for a model with no Item row: `set·base·variant` for a
+ * weapon, `base·variant` otherwise (the design's "MODEL 9903·1").
+ */
+export function formatCharaModelLabel(model) {
+    return isCharaWeaponSlot(model.slot)
+        ? `${model.set ?? 0}·${model.base}·${model.variant}`
+        : `${model.base}·${model.variant}`;
+}
+/** True when the record describes a worn piece rather than an empty slot. */
+export function isWornCharaModel(slot, set, base) {
+    return isCharaWeaponSlot(slot) ? set > 0 || base > 0 : base > 0;
+}
+//# sourceMappingURL=chara-models.js.map

package/dist/services/chara/chara-models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chara-models.js","sourceRoot":"","sources":["../../../src/services/chara/chara-models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAeH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,kBAAkB,GAA+B,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AAEtF,MAAM,UAAU,iBAAiB,CAAC,IAAqB;IACrD,OAAO,kBAAkB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAoC;IACtE,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,MAAM;IAChB,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,QAAQ;IACf,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,SAAS;IACnB,SAAS,EAAE,SAAS;CACrB,CAAC;AAEF,MAAM,IAAI,GAAG,KAAK,CAAC;AAEnB;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,OAAe;IACxD,OAAO,IAAI,GAAG,OAAO,GAAG,IAAI,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,IAAY,EAAE,OAAe;IACvE,OAAO,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC;AACxE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAqB;IACjD,OAAO,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC;QAClC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACnE,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAqB;IACzD,OAAO,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC;QAClC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,EAAE;QACpD,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;AACvC,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB,CAC9B,IAAqB,EACrB,GAAW,EACX,IAAY;IAEZ,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;AAClE,CAAC"}

package/dist/services/chara/chara-parser.d.ts

@@ -0,0 +1,95 @@
+/**
+ * `.chara` character-file parser — the 5.0 Swatch Matcher import.
+ *
+ * Rules measured across 112 sample files (design register, Swatch Matcher
+ * 10A, confirmed):
+ * - **Parse by key presence, never the declared `TypeName`** — producers
+ *   (Anamnesis versions, Ktisis) write different key sets. `TypeName` is
+ *   captured only to *show* the producer.
+ * - **`REyeColor` holds the LEFT eye and `LEyeColor` the right** — crossed
+ *   against the extended floats (`LeftEyeColor`/`RightEyeColor`); trust the
+ *   extended naming. Never "fix" this by swapping — 16% of samples are
+ *   heterochromia and a swap corrupts them silently.
+ * - **Extended floats are linear RGB** — gamma-encode before use or every
+ *   colour is wrong-but-plausible.
+ * - **Flags gate live-looking data**: `EnableHighlights: false` inerts the
+ *   highlight index (54% of samples, 47 of those with a live-looking index);
+ *   `FacePaint: 0` inerts `FacePaintColor` (only 0 is load-bearing — values
+ *   ≥128 exist, do not range-validate `FacePaint` itself).
+ * - **`LipsToneFurPattern` is a fur-pattern enum on Hrothgar**, not a colour.
+ * - **`MouthColor` alpha is a continuous opacity**: `0` = no lip; an absent
+ *   key ≠ 0 (Ktisis omits it and the index stays valid).
+ * - **`IsExtendedAppearanceValid` is unreliable** (declared in 16 of 96
+ *   float-bearing files): the floats count as live only when it is present
+ *   and true — a missing flag means the index wins, and the UI says so.
+ * - **Gear dyes are stain IDs** (`DyeId`/`DyeId2` per slot, 0 = undyed; 35%
+ *   of dyed channels are the second one).
+ * - **Gear models are emitted beside the dyes** (`gearModels`): the
+ *   `ModelBase`/`ModelVariant` pair (weapons add `ModelSet`) of every WORN
+ *   slot — `ModelBase == 0` (weapons: `ModelSet == 0` too) is an empty slot
+ *   and is skipped. `null` hand records (one Anamnesis file) are empty.
+ *   `Glasses` is `{ GlassesId }` or, on Brio-era Ktisis, a bare integer —
+ *   both are accepted; 0 = no facewear. Resolution to item names happens
+ *   off-device (api-worker) — the parser only carries the keys.
+ * - **Never read `Base64Image`.**
+ * - An unrecognised tribe/race/gender fails loudly (name got vs expected),
+ *   never an empty palette.
+ */
+import type { Gender, Race, RGB, SubRace } from '@xivdyetools/types';
+import { type CharaGearModel } from './chara-models.js';
+/** Colour slots a `.chara` file can populate. */
+export type CharaSlotId = 'leftEye' | 'rightEye' | 'hair' | 'highlights' | 'skin' | 'limbal' | 'lip' | 'facePaint';
+/** Equipment slots that can carry dye channels. */
+export type CharaGearSlotId = 'MainHand' | 'OffHand' | 'HeadGear' | 'Body' | 'Hands' | 'Legs' | 'Feet' | 'Ears' | 'Neck' | 'Wrists' | 'LeftRing' | 'RightRing';
+export type CharaSlotInertReason = 'highlightsDisabled' | 'facePaintNone' | 'furPattern' | 'noLip';
+export interface CharaColorSlotRaw {
+    slot: CharaSlotId;
+    /** Raw palette index; null = key absent from the file */
+    index: number | null;
+    /** False when a flag gates the index off (see inertReason) */
+    indexActive: boolean;
+    inertReason?: CharaSlotInertReason;
+    /** Extended float colour, gamma-encoded to sRGB; null = key absent */
+    float: RGB | null;
+    /** The raw linear-RGB float triple as stored in the file */
+    floatLinear: [number, number, number] | null;
+    /** Lip only: continuous opacity. null = key absent (absent ≠ 0) */
+    alpha: number | null;
+}
+export interface CharaGearDye {
+    slot: CharaGearSlotId;
+    /** Which dye channel (1 = DyeId, 2 = DyeId2) */
+    channel: 1 | 2;
+    /** Stain ID as stored (1-254); 0/undyed channels are not emitted */
+    stainId: number;
+}
+export interface ParsedCharaFile {
+    /** Declared producer (`TypeName`), shown in UI — never used for parsing */
+    producer: string | null;
+    race: Race | null;
+    tribe: SubRace | null;
+    /** The tribe string exactly as the file spelled it */
+    tribeRaw: string | null;
+    gender: Gender | null;
+    /** Ktisis nickname — the default name for exported palettes */
+    nickname: string | null;
+    /** True only when IsExtendedAppearanceValid is present AND true */
+    extendedValid: boolean;
+    /** Whether the IsExtendedAppearanceValid key was present at all */
+    extendedDeclared: boolean;
+    slots: CharaColorSlotRaw[];
+    /** Dyed gear channels only (stainId > 0), in file slot order */
+    gearDyes: CharaGearDye[];
+    /** Worn pieces only (model base > 0), in file slot order — undyed pieces included */
+    gearModels: CharaGearModel[];
+    /** Facewear `Glasses` sheet row; null when none / absent */
+    glassesId: number | null;
+}
+/**
+ * Parse a `.chara` file's text content. Structural problems (invalid JSON,
+ * unrecognised tribe/race/gender, malformed colour values) throw AppError
+ * naming field and value; per-slot range problems are left to the resolver,
+ * which reports them as loud slot states.
+ */
+export declare function parseCharaFile(text: string): ParsedCharaFile;
+//# sourceMappingURL=chara-parser.d.ts.map

package/dist/services/chara/chara-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chara-parser.d.ts","sourceRoot":"","sources":["../../../src/services/chara/chara-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGrE,OAAO,EAAuC,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE7F,iDAAiD;AACjD,MAAM,MAAM,WAAW,GACrB,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,WAAW,CAAC;AAE3F,mDAAmD;AACnD,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,SAAS,GACT,UAAU,GACV,MAAM,GACN,OAAO,GACP,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,QAAQ,GACR,UAAU,GACV,WAAW,CAAC;AAEhB,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,GAAG,eAAe,GAAG,YAAY,GAAG,OAAO,CAAC;AAEnG,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,WAAW,CAAC;IAClB,yDAAyD;IACzD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,8DAA8D;IAC9D,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC,sEAAsE;IACtE,KAAK,EAAE,GAAG,GAAG,IAAI,CAAC;IAClB,4DAA4D;IAC5D,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC7C,mEAAmE;IACnE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,eAAe,CAAC;IACtB,gDAAgD;IAChD,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;IACf,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,mEAAmE;IACnE,aAAa,EAAE,OAAO,CAAC;IACvB,mEAAmE;IACnE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,qFAAqF;IACrF,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,4DAA4D;IAC5D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAuKD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAiI5D"}