@xivdyetools/core 2.7.0 → 4.0.1

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

@@ -0,0 +1,299 @@
+/**
+ * `.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 { AppError, ErrorCode } from '@xivdyetools/types';
+import { clamp } from '../../utils/index.js';
+import { isWornCharaModel, isCharaWeaponSlot } from './chara-models.js';
+const GEAR_SLOTS = [
+    'MainHand',
+    'OffHand',
+    'HeadGear',
+    'Body',
+    'Hands',
+    'Legs',
+    'Feet',
+    'Ears',
+    'Neck',
+    'Wrists',
+    'LeftRing',
+    'RightRing',
+];
+/** File tribe spellings → SubRace. Files use the game's plural "Helions". */
+const TRIBE_MAP = {
+    Midlander: 'Midlander',
+    Highlander: 'Highlander',
+    Wildwood: 'Wildwood',
+    Duskwight: 'Duskwight',
+    Plainsfolk: 'Plainsfolk',
+    Dunesfolk: 'Dunesfolk',
+    SeekerOfTheSun: 'SeekerOfTheSun',
+    KeeperOfTheMoon: 'KeeperOfTheMoon',
+    SeaWolf: 'SeaWolf',
+    Hellsguard: 'Hellsguard',
+    Raen: 'Raen',
+    Xaela: 'Xaela',
+    Helions: 'Helions',
+    // Pre-5.0 identifier — accepted on read, stored as the game's plural
+    Helion: 'Helions',
+    TheLost: 'TheLost',
+    Rava: 'Rava',
+    Veena: 'Veena',
+};
+/** File race spellings → Race (Anamnesis serializes "Miqote" and "AuRa"). */
+const RACE_MAP = {
+    Hyur: 'Hyur',
+    Elezen: 'Elezen',
+    Lalafell: 'Lalafell',
+    Miqote: "Miqo'te",
+    "Miqo'te": "Miqo'te",
+    Roegadyn: 'Roegadyn',
+    AuRa: 'AuRa',
+    Hrothgar: 'Hrothgar',
+    Viera: 'Viera',
+};
+const GENDER_MAP = {
+    Masculine: 'Male',
+    Feminine: 'Female',
+    Male: 'Male',
+    Female: 'Female',
+};
+/** Linear-light → sRGB gamma encoding, clamped, 0-255. */
+function linearToSrgb255(c) {
+    const clamped = clamp(c, 0, 1);
+    const encoded = clamped <= 0.0031308 ? clamped * 12.92 : 1.055 * Math.pow(clamped, 1 / 2.4) - 0.055;
+    return Math.round(clamp(encoded, 0, 1) * 255);
+}
+/**
+ * Parse an extended-appearance float string ("r, g, b" or "r, g, b, a",
+ * linear RGB). Throws loudly on a malformed value — a wrong-but-plausible
+ * colour is worse than a failure that names the field.
+ */
+function parseFloatColor(field, value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'string') {
+        throw new AppError(ErrorCode.INVALID_INPUT, `.chara field ${field}: expected a comma-separated float string, got ${typeof value}`, 'error');
+    }
+    const parts = value.split(',').map((p) => Number(p.trim()));
+    if ((parts.length !== 3 && parts.length !== 4) || parts.some((n) => Number.isNaN(n))) {
+        throw new AppError(ErrorCode.INVALID_INPUT, `.chara field ${field}: unparseable float colour "${value}"`, 'error');
+    }
+    const [r, g, b] = parts;
+    return {
+        srgb: { r: linearToSrgb255(r), g: linearToSrgb255(g), b: linearToSrgb255(b) },
+        linear: [r, g, b],
+        alpha: parts.length === 4 ? parts[3] : null,
+    };
+}
+/**
+ * Every character colour field — the eight palette indices plus the extended
+ * appearance floats. Presence of at least one is what makes a JSON document
+ * a `.chara` file; an extended-only file (floats, no indices) is legitimate
+ * and resolves as `floatOnly`. See the key-presence rule in `parseCharaFile`.
+ */
+const COLOR_KEYS = [
+    'REyeColor',
+    'LEyeColor',
+    'HairTone',
+    'Highlights',
+    'Skintone',
+    'LimbalEyes',
+    'LipsToneFurPattern',
+    'FacePaintColor',
+    'SkinColor',
+    'LeftEyeColor',
+    'RightEyeColor',
+    'LimbalRingColor',
+    'HairColor',
+    'HairHighlight',
+    'MouthColor',
+];
+function readIndex(record, key) {
+    const value = record[key];
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new AppError(ErrorCode.INVALID_INPUT, `.chara field ${key}: expected a numeric palette index, got ${JSON.stringify(value)}`, 'error');
+    }
+    return value;
+}
+function mapNamed(table, field, value) {
+    if (value === null || value === undefined)
+        return { mapped: null, raw: null };
+    if (typeof value !== 'string') {
+        throw new AppError(ErrorCode.INVALID_INPUT, `.chara field ${field}: expected a string, got ${typeof value}`, 'error');
+    }
+    // FINDING-027 (2026-08-21 audit): own-property lookup only — `table[value]`
+    // on a plain object literal let "constructor" / "__proto__" / "toString"
+    // pass validation with a Function or Object.prototype as the mapped value
+    const mapped = Object.hasOwn(table, value) ? table[value] : undefined;
+    if (mapped === undefined) {
+        throw new AppError(ErrorCode.INVALID_INPUT, `.chara field ${field}: unrecognised value "${value}" (expected one of: ${Object.keys(table).join(', ')})`, 'error');
+    }
+    return { mapped, raw: value };
+}
+/**
+ * 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 function parseCharaFile(text) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new AppError(ErrorCode.INVALID_INPUT, '.chara file is not valid JSON', 'error');
+    }
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        throw new AppError(ErrorCode.INVALID_INPUT, '.chara file is not a JSON object', 'error');
+    }
+    const record = data;
+    // Identity fields first: a file that names a bad tribe deserves that
+    // message, not the generic refusal below.
+    const { mapped: race } = mapNamed(RACE_MAP, 'Race', record['Race']);
+    const { mapped: tribe, raw: tribeRaw } = mapNamed(TRIBE_MAP, 'Tribe', record['Tribe']);
+    const { mapped: gender } = mapNamed(GENDER_MAP, 'Gender', record['Gender']);
+    // Parse by key presence: a JSON carrying no colour field at all is some
+    // other document that happens to be JSON, not a sparse character. Refuse
+    // it rather than resolving eight dashed slots that read as a valid
+    // character wearing nothing.
+    if (!COLOR_KEYS.some((key) => key in record)) {
+        throw new AppError(ErrorCode.INVALID_INPUT, `.chara file carries no character colour fields (expected at least one of: ${COLOR_KEYS.join(', ')})`, 'error');
+    }
+    const extendedDeclared = 'IsExtendedAppearanceValid' in record;
+    const extendedValid = record['IsExtendedAppearanceValid'] === true;
+    const isHrothgar = race === 'Hrothgar';
+    const enableHighlights = record['EnableHighlights'] !== false;
+    const facePaintValue = readIndex(record, 'FacePaint');
+    const facePaintNone = facePaintValue === 0;
+    const skinFloat = parseFloatColor('SkinColor', record['SkinColor']);
+    // Crossed keys: the index REyeColor pairs with the float LeftEyeColor.
+    const leftEyeFloat = parseFloatColor('LeftEyeColor', record['LeftEyeColor']);
+    const rightEyeFloat = parseFloatColor('RightEyeColor', record['RightEyeColor']);
+    const limbalFloat = parseFloatColor('LimbalRingColor', record['LimbalRingColor']);
+    const hairFloat = parseFloatColor('HairColor', record['HairColor']);
+    const highlightFloat = parseFloatColor('HairHighlight', record['HairHighlight']);
+    const mouthFloat = parseFloatColor('MouthColor', record['MouthColor']);
+    const slot = (id, index, float, options = {}) => ({
+        slot: id,
+        index,
+        indexActive: options.indexActive ?? true,
+        ...(options.inertReason !== undefined ? { inertReason: options.inertReason } : {}),
+        float: float?.srgb ?? null,
+        floatLinear: float?.linear ?? null,
+        alpha: options.alpha !== undefined ? options.alpha : null,
+    });
+    const slots = [
+        slot('leftEye', readIndex(record, 'REyeColor'), leftEyeFloat),
+        slot('rightEye', readIndex(record, 'LEyeColor'), rightEyeFloat),
+        slot('hair', readIndex(record, 'HairTone'), hairFloat),
+        slot('highlights', readIndex(record, 'Highlights'), highlightFloat, {
+            indexActive: enableHighlights,
+            ...(enableHighlights ? {} : { inertReason: 'highlightsDisabled' }),
+        }),
+        slot('skin', readIndex(record, 'Skintone'), skinFloat),
+        slot('limbal', readIndex(record, 'LimbalEyes'), limbalFloat),
+        slot('lip', readIndex(record, 'LipsToneFurPattern'), mouthFloat, {
+            // On Hrothgar the key is a fur-pattern enum, not a colour index.
+            indexActive: !isHrothgar,
+            ...(isHrothgar ? { inertReason: 'furPattern' } : {}),
+            alpha: mouthFloat ? mouthFloat.alpha : null,
+        }),
+        slot('facePaint', readIndex(record, 'FacePaintColor'), null, {
+            indexActive: !facePaintNone,
+            ...(facePaintNone ? { inertReason: 'facePaintNone' } : {}),
+        }),
+    ];
+    const gearDyes = [];
+    const gearModels = [];
+    for (const gearSlot of GEAR_SLOTS) {
+        const gear = record[gearSlot];
+        if (typeof gear !== 'object' || gear === null)
+            continue;
+        const gearRecord = gear;
+        for (const [channel, key] of [
+            [1, 'DyeId'],
+            [2, 'DyeId2'],
+        ]) {
+            const value = gearRecord[key];
+            if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+                gearDyes.push({ slot: gearSlot, channel, stainId: value });
+            }
+        }
+        const set = readModelLane(gearRecord['ModelSet']);
+        const base = readModelLane(gearRecord['ModelBase']);
+        const variant = readModelLane(gearRecord['ModelVariant']);
+        if (isWornCharaModel(gearSlot, set, base)) {
+            gearModels.push(isCharaWeaponSlot(gearSlot)
+                ? { slot: gearSlot, set, base, variant }
+                : { slot: gearSlot, base, variant });
+        }
+    }
+    return {
+        producer: typeof record['TypeName'] === 'string' ? record['TypeName'] : null,
+        race,
+        tribe,
+        tribeRaw,
+        gender,
+        nickname: typeof record['Nickname'] === 'string' ? record['Nickname'] : null,
+        extendedValid,
+        extendedDeclared,
+        slots,
+        gearDyes,
+        gearModels,
+        glassesId: readGlassesId(record['Glasses']),
+    };
+}
+/** A model lane is a non-negative integer; anything else reads as 0 (empty). */
+function readModelLane(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : 0;
+}
+/**
+ * `Glasses` is `{ GlassesId: n }` (Anamnesis, Ktisis) or a bare integer
+ * (Brio-era "Ktisis/Anamnesis Character File"). Row 0 is "none".
+ */
+function readGlassesId(value) {
+    const raw = typeof value === 'object' && value !== null
+        ? value['GlassesId']
+        : value;
+    return typeof raw === 'number' && Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : null;
+}
+//# sourceMappingURL=chara-parser.js.map

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

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

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

@@ -0,0 +1,103 @@
+/**
+ * `.chara` slot resolution — arbitrates palette index vs extended float and
+ * resolves everything against the character colour sheets and dye database.
+ *
+ * Confirmed rules (Swatch Matcher 10A):
+ * - **Index wins where index and float agree**; past ~6 ΔE2000 the float wins
+ *   and the slot is OFF GRID, with both hexes named.
+ * - Floats count as live only when `IsExtendedAppearanceValid` is present and
+ *   true — a missing flag means the index wins, and the UI says so
+ *   (`indexWinNote: 'extendedMissing'`).
+ * - **Dark/light palettes split 0-95 dark / 128-223 light; 96-127 fails
+ *   loudly, never clamps** — one rule for every dark/light palette.
+ * - A Hrothgar lip can hold a colour with no index → the same OFF-GRID path
+ *   (`floatOnly`).
+ * - Lip alpha 0 = no lip; the lip swatch composites over skin — both the raw
+ *   colour and the blend are provided.
+ * - Gear dye stain IDs resolve through the dye database
+ *   (`stainID`/`legacyItemID`), never derived from ranges.
+ * - Shared-index eyes (84% of files) merge into one badge — `eyesShareIndex`.
+ */
+import type { Dye, Gender, SubRace } from '@xivdyetools/types';
+import type { CharacterColorService } from '../CharacterColorService.js';
+import type { CharaGearSlotId, CharaSlotId, CharaSlotInertReason, ParsedCharaFile } from './chara-parser.js';
+import type { CharaGearModel } from './chara-models.js';
+/** ΔE2000 beyond which a live float overrides the palette index (OFF GRID). */
+export declare const OFF_GRID_DELTA_E2000 = 6;
+export type CharaSlotVerdict = 
+/** The palette index is the answer (float absent, not live, or agreeing) */
+'index'
+/** Live float disagrees past the threshold — float wins, both hexes named */
+ | 'offGrid'
+/** A colour with no index (e.g. Hrothgar lip) — the OFF-GRID path */
+ | 'floatOnly'
+/** A flag gates this slot off (reason on the slot) */
+ | 'inert'
+/** Loud failure state — code + message name the field and value */
+ | 'error';
+export type CharaSlotErrorCode = 'midRangeIndex' | 'indexOutOfRange' | 'noTribe';
+export interface ResolvedCharaSlot {
+    slot: CharaSlotId;
+    /** The limbal slot is a limbal ring on Au Ra and a tattoo otherwise */
+    kind: CharaSlotId | 'tattoo';
+    verdict: CharaSlotVerdict;
+    inertReason?: CharaSlotInertReason;
+    error?: {
+        code: CharaSlotErrorCode;
+        message: string;
+    };
+    /** Raw palette index from the file */
+    index: number | null;
+    /** Index within the resolved sheet (light sheets subtract 128) */
+    sheetIndex: number | null;
+    /** Sheet variant for dark/light palettes */
+    sheetVariant: 'dark' | 'light' | null;
+    /** Grid address like "R6·C3" (8 columns), when the index resolved */
+    gridAddress: string | null;
+    /** Hex from the palette sheet, when the index resolved */
+    indexHex: string | null;
+    /** Hex from the extended float (gamma-encoded), when present */
+    floatHex: string | null;
+    /** ΔE2000 between indexHex and floatHex, when both exist */
+    deltaE: number | null;
+    /** Set when a float existed but was not live — the UI must say so */
+    indexWinNote?: 'extendedMissing';
+    /** Lip only: continuous opacity (null = not declared, ≠ 0) */
+    alpha: number | null;
+    /** Lip only: winning colour composited over the winning skin colour */
+    blendHex: string | null;
+}
+export interface ResolvedGearDye {
+    slot: CharaGearSlotId;
+    channel: 1 | 2;
+    stainId: number;
+    /** Resolved dye, or null when the stain ID is unknown to the database */
+    dye: Dye | null;
+}
+export interface ResolvedCharaCharacter {
+    producer: string | null;
+    race: ParsedCharaFile['race'];
+    tribe: SubRace | null;
+    gender: Gender | null;
+    nickname: string | null;
+    extendedValid: boolean;
+    extendedDeclared: boolean;
+    slots: ResolvedCharaSlot[];
+    /** True when both eyes carry the same palette index — merge into one badge */
+    eyesShareIndex: boolean;
+    gearDyes: ResolvedGearDye[];
+    /** Worn pieces' model keys (undyed included) — item names resolve off-device */
+    gearModels: CharaGearModel[];
+    /** Facewear `Glasses` sheet row; null when none */
+    glassesId: number | null;
+}
+/** Minimal dye lookup the resolver needs (DyeService satisfies this). */
+export interface StainIdLookup {
+    getByStainId(stainId: number): Dye | null | undefined;
+}
+/**
+ * Resolve a parsed `.chara` file against the character colour sheets and
+ * (optionally) the dye database for gear dye names.
+ */
+export declare function resolveCharaColors(parsed: ParsedCharaFile, characterColors: CharacterColorService, dyeLookup?: StainIdLookup): Promise<ResolvedCharaCharacter>;
+//# sourceMappingURL=chara-resolver.d.ts.map

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

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

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

@@ -0,0 +1,233 @@
+/**
+ * `.chara` slot resolution — arbitrates palette index vs extended float and
+ * resolves everything against the character colour sheets and dye database.
+ *
+ * Confirmed rules (Swatch Matcher 10A):
+ * - **Index wins where index and float agree**; past ~6 ΔE2000 the float wins
+ *   and the slot is OFF GRID, with both hexes named.
+ * - Floats count as live only when `IsExtendedAppearanceValid` is present and
+ *   true — a missing flag means the index wins, and the UI says so
+ *   (`indexWinNote: 'extendedMissing'`).
+ * - **Dark/light palettes split 0-95 dark / 128-223 light; 96-127 fails
+ *   loudly, never clamps** — one rule for every dark/light palette.
+ * - A Hrothgar lip can hold a colour with no index → the same OFF-GRID path
+ *   (`floatOnly`).
+ * - Lip alpha 0 = no lip; the lip swatch composites over skin — both the raw
+ *   colour and the blend are provided.
+ * - Gear dye stain IDs resolve through the dye database
+ *   (`stainID`/`legacyItemID`), never derived from ranges.
+ * - Shared-index eyes (84% of files) merge into one badge — `eyesShareIndex`.
+ */
+import { ColorConverter } from '../color/ColorConverter.js';
+import { clamp } from '../../utils/index.js';
+/** ΔE2000 beyond which a live float overrides the palette index (OFF GRID). */
+export const OFF_GRID_DELTA_E2000 = 6;
+const GRID_COLUMNS = 8;
+function gridAddress(sheetIndex) {
+    const row = Math.floor(sheetIndex / GRID_COLUMNS) + 1;
+    const col = (sheetIndex % GRID_COLUMNS) + 1;
+    return `R${row}·C${col}`;
+}
+function rgbToHex(rgb) {
+    return ColorConverter.rgbToHex(rgb.r, rgb.g, rgb.b);
+}
+function srgbToLinear(c) {
+    const n = c / 255;
+    return n <= 0.04045 ? n / 12.92 : Math.pow((n + 0.055) / 1.055, 2.4);
+}
+function linearToSrgb255(c) {
+    const clamped = clamp(c, 0, 1);
+    const encoded = clamped <= 0.0031308 ? clamped * 12.92 : 1.055 * Math.pow(clamped, 1 / 2.4) - 0.055;
+    return Math.round(clamp(encoded, 0, 1) * 255);
+}
+/** Composite `top` over `base` at `alpha`, in linear light. */
+function compositeHex(topHex, baseHex, alpha) {
+    const top = ColorConverter.hexToRgb(topHex);
+    const base = ColorConverter.hexToRgb(baseHex);
+    const mix = (t, b) => linearToSrgb255(srgbToLinear(t) * alpha + srgbToLinear(b) * (1 - alpha));
+    return ColorConverter.rgbToHex(mix(top.r, base.r), mix(top.g, base.g), mix(top.b, base.b));
+}
+/**
+ * Resolve the sheet + in-sheet index for a slot. Dark/light palettes apply
+ * the one split rule: 0-95 dark, 128-223 light, 96-127 loud failure.
+ */
+async function resolveSheet(slot, index, parsed, characterColors) {
+    const splitRange = (dark, light, field) => {
+        if (index >= 0 && index <= 95) {
+            return { sheet: dark, variant: 'dark', sheetIndex: index };
+        }
+        if (index >= 128 && index <= 223) {
+            return { sheet: light, variant: 'light', sheetIndex: index - 128 };
+        }
+        if (index >= 96 && index <= 127) {
+            return {
+                sheet: null,
+                variant: null,
+                sheetIndex: null,
+                error: {
+                    code: 'midRangeIndex',
+                    message: `${field} index ${index} falls in the 96-127 gap between the dark (0-95) and light (128-223) ranges`,
+                },
+            };
+        }
+        return {
+            sheet: null,
+            variant: null,
+            sheetIndex: null,
+            error: {
+                code: 'indexOutOfRange',
+                message: `${field} index ${index} is outside the dark (0-95) and light (128-223) ranges`,
+            },
+        };
+    };
+    switch (slot) {
+        case 'leftEye':
+        case 'rightEye':
+            return { sheet: characterColors.getEyeColors(), variant: null, sheetIndex: index };
+        case 'highlights':
+            return { sheet: characterColors.getHighlightColors(), variant: null, sheetIndex: index };
+        case 'limbal':
+            return { sheet: characterColors.getTattooColors(), variant: null, sheetIndex: index };
+        case 'lip':
+            return splitRange(characterColors.getLipColorsDark(), characterColors.getLipColorsLight(), 'LipsToneFurPattern');
+        case 'facePaint':
+            return splitRange(characterColors.getFacePaintColorsDark(), characterColors.getFacePaintColorsLight(), 'FacePaintColor');
+        case 'hair':
+        case 'skin': {
+            if (!parsed.tribe || !parsed.gender) {
+                return {
+                    sheet: null,
+                    variant: null,
+                    sheetIndex: null,
+                    error: {
+                        code: 'noTribe',
+                        message: `${slot} needs Tribe and Gender to resolve its race-specific sheet`,
+                    },
+                };
+            }
+            const sheet = slot === 'hair'
+                ? await characterColors.getHairColors(parsed.tribe, parsed.gender)
+                : await characterColors.getSkinColors(parsed.tribe, parsed.gender);
+            return { sheet, variant: null, sheetIndex: index };
+        }
+    }
+}
+/**
+ * Resolve a parsed `.chara` file against the character colour sheets and
+ * (optionally) the dye database for gear dye names.
+ */
+export async function resolveCharaColors(parsed, characterColors, dyeLookup) {
+    const slots = [];
+    for (const raw of parsed.slots) {
+        const kind = raw.slot === 'limbal' ? (parsed.race === 'AuRa' ? 'limbal' : 'tattoo') : raw.slot;
+        const floatHex = raw.float ? rgbToHex(raw.float) : null;
+        const floatLive = parsed.extendedValid && floatHex !== null;
+        const base = {
+            slot: raw.slot,
+            kind,
+            verdict: 'index',
+            ...(raw.inertReason !== undefined ? { inertReason: raw.inertReason } : {}),
+            index: raw.index,
+            sheetIndex: null,
+            sheetVariant: null,
+            gridAddress: null,
+            indexHex: null,
+            floatHex,
+            deltaE: null,
+            alpha: raw.alpha,
+            blendHex: null,
+        };
+        // Lip alpha 0 = no lip (absent ≠ 0 — an absent key leaves the index valid)
+        if (raw.slot === 'lip' && raw.alpha === 0) {
+            slots.push({ ...base, verdict: 'inert', inertReason: 'noLip' });
+            continue;
+        }
+        if (!raw.indexActive) {
+            // A fur-pattern lip can still hold a live colour → the OFF-GRID path.
+            if (raw.inertReason === 'furPattern' && floatLive) {
+                slots.push({ ...base, verdict: 'floatOnly' });
+            }
+            else {
+                slots.push({ ...base, verdict: 'inert' });
+            }
+            continue;
+        }
+        if (raw.index === null) {
+            slots.push(floatLive ? { ...base, verdict: 'floatOnly' } : { ...base, verdict: 'inert' });
+            continue;
+        }
+        const resolution = await resolveSheet(raw.slot, raw.index, parsed, characterColors);
+        if (resolution.error || !resolution.sheet || resolution.sheetIndex === null) {
+            slots.push({
+                ...base,
+                verdict: 'error',
+                ...(resolution.error ? { error: resolution.error } : {}),
+            });
+            continue;
+        }
+        const entry = resolution.sheet.find((c) => c.index === resolution.sheetIndex);
+        if (!entry) {
+            slots.push({
+                ...base,
+                verdict: 'error',
+                sheetIndex: resolution.sheetIndex,
+                sheetVariant: resolution.variant,
+                error: {
+                    code: 'indexOutOfRange',
+                    message: `${raw.slot} index ${raw.index} has no entry in its ${resolution.sheet.length}-colour sheet`,
+                },
+            });
+            continue;
+        }
+        const resolved = {
+            ...base,
+            sheetIndex: resolution.sheetIndex,
+            sheetVariant: resolution.variant,
+            gridAddress: gridAddress(resolution.sheetIndex),
+            indexHex: entry.hex,
+        };
+        if (floatLive && floatHex) {
+            const deltaE = ColorConverter.getDeltaE(entry.hex, floatHex, 'ciede2000');
+            resolved.deltaE = deltaE;
+            resolved.verdict = deltaE > OFF_GRID_DELTA_E2000 ? 'offGrid' : 'index';
+        }
+        else {
+            resolved.verdict = 'index';
+            if (floatHex && !parsed.extendedValid) {
+                // Float present but not live — the index wins and the UI says so.
+                resolved.indexWinNote = 'extendedMissing';
+            }
+        }
+        slots.push(resolved);
+    }
+    // Lip blend: winning lip colour composited over the winning skin colour.
+    const lip = slots.find((s) => s.slot === 'lip');
+    const skin = slots.find((s) => s.slot === 'skin');
+    if (lip && skin && lip.alpha !== null && lip.alpha > 0) {
+        const lipHex = lip.verdict === 'offGrid' || lip.verdict === 'floatOnly' ? lip.floatHex : lip.indexHex;
+        const skinHex = skin.verdict === 'offGrid' || skin.verdict === 'floatOnly' ? skin.floatHex : skin.indexHex;
+        if (lipHex && skinHex) {
+            lip.blendHex = compositeHex(lipHex, skinHex, clamp(lip.alpha, 0, 1));
+        }
+    }
+    const leftEye = slots.find((s) => s.slot === 'leftEye');
+    const rightEye = slots.find((s) => s.slot === 'rightEye');
+    return {
+        producer: parsed.producer,
+        race: parsed.race,
+        tribe: parsed.tribe,
+        gender: parsed.gender,
+        nickname: parsed.nickname,
+        extendedValid: parsed.extendedValid,
+        extendedDeclared: parsed.extendedDeclared,
+        slots,
+        eyesShareIndex: leftEye?.index !== null && leftEye?.index !== undefined && leftEye.index === rightEye?.index,
+        gearDyes: parsed.gearDyes.map((g) => ({
+            ...g,
+            dye: dyeLookup?.getByStainId(g.stainId) ?? null,
+        })),
+        gearModels: parsed.gearModels,
+        glassesId: parsed.glassesId,
+    };
+}
+//# sourceMappingURL=chara-resolver.js.map