@xivdyetools/core 2.6.0 → 4.0.1

package/README.md

@@ -1,16 +1,16 @@
-# xivdyetools-core
+# @xivdyetools/core
 
-> Core color algorithms and dye database for XIV Dye Tools - Environment-agnostic TypeScript library for FFXIV dye color matching, harmony generation, and accessibility checking.
+> Core color algorithms and dye database for XIV Dye Tools — environment-agnostic TypeScript library for FFXIV dye color matching, harmony generation, and accessibility checking.
 
-[![npm version](https://img.shields.io/npm/v/xivdyetools-core)](https://www.npmjs.com/package/xivdyetools-core)
+[![npm version](https://img.shields.io/npm/v/@xivdyetools/core)](https://www.npmjs.com/package/@xivdyetools/core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.3%2B-blue)](https://www.typescriptlang.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9%2B-blue)](https://www.typescriptlang.org/)
 
 ## Features
 
-✨ **Color Conversion** - RGB ↔ HSV ↔ Hex ↔ LAB ↔ RYB ↔ OKLAB ↔ OKLCH ↔ LCH ↔ HSL
-🎨 **136 FFXIV Dyes** - Complete database with RGB/HSV/metadata
-🖌️ **Advanced Color Mixing** - RYB, OKLAB, HSL, and Spectral (Kubelka-Munk)
+✨ **Color Conversion** - RGB ↔ HSV ↔ Hex ↔ LAB ↔ RYB ↔ OKLAB ↔ OKLCH ↔ LCH ↔ HSL ↔ CMYK
+🎨 **125 FFXIV Dyes** - Complete database (schema v2, stainID-keyed) plus 11 Facewear colors
+🖌️ **Advanced Color Mixing** - RYB, OKLAB, HSL, and Spectral (Kubelka-Munk); six blending modes via `@xivdyetools/core/blending`
 🔬 **Spectral.js Integration** - Physics-based paint mixing (Blue + Yellow = Green!)
 🎯 **Dye Matching** - Find closest dyes to any color
 🌈 **Color Harmonies** - Triadic, complementary, analogous, and more
@@ -24,7 +24,7 @@
 ## Installation
 
 ```bash
-npm install xivdyetools-core
+npm install @xivdyetools/core
 ```
 
 ## Quick Start
@@ -32,7 +32,7 @@ npm install xivdyetools-core
 ### Browser (with bundler)
 
 ```typescript
-import { ColorService, DyeService, dyeDatabase } from 'xivdyetools-core';
+import { ColorService, DyeService, dyeDatabase } from '@xivdyetools/core';
 
 // Initialize services
 const dyeService = new DyeService(dyeDatabase);
@@ -57,18 +57,22 @@ console.log(hsv); // { h: 0, s: 58.04, v: 100 }
 import {
   DyeService,
   APIService,
-  dyeDatabase
-} from 'xivdyetools-core';
+  dyeDatabase,
+  getMarketItemID
+} from '@xivdyetools/core';
 import Redis from 'ioredis';
+// RedisCacheBackend is your own ICacheBackend implementation — see "Custom Cache Backends" below
 
 // Initialize with Redis cache (for Discord bots)
 const redis = new Redis();
 const cacheBackend = new RedisCacheBackend(redis);
-const apiService = new APIService(cacheBackend);
+const apiService = new APIService({ cacheBackend });
 const dyeService = new DyeService(dyeDatabase);
 
-// Fetch live market prices
-const priceData = await apiService.getPriceData(5752); // Jet Black Dye
+// Fetch live market prices.
+// NOTE: since Patch 7.5, most dyes share a consolidated market itemID —
+// use getMarketItemID(dye) rather than a hard-coded legacy itemID.
+const priceData = await apiService.getPriceData(getMarketItemID(jetBlack));
 console.log(`${priceData.currentMinPrice} Gil`);
 
 // Find harmony with pricing
@@ -85,7 +89,7 @@ Pure color conversion and manipulation algorithms.
 > **Memory Note**: ColorService uses LRU caches (5 caches × 1000 entries each = up to 5000 cached entries) for performance optimization. For long-running applications or memory-constrained environments, call `ColorService.clearCaches()` periodically to free memory. Each cache entry is approximately 50-100 bytes, so maximum memory usage is ~500KB.
 
 ```typescript
-import { ColorService } from 'xivdyetools-core';
+import { ColorService } from '@xivdyetools/core';
 
 // Hex ↔ RGB
 const rgb = ColorService.hexToRgb('#FF6B6B');
@@ -107,7 +111,8 @@ const distance = ColorService.getColorDistance('#FF0000', '#00FF00');
 // LAB color space and DeltaE (perceptual color difference)
 const lab = ColorService.hexToLab('#FF6B6B');
 const deltaE = ColorService.getDeltaE('#FF0000', '#FF6B6B'); // CIE76 by default
-const deltaE2000 = ColorService.getDeltaE('#FF0000', '#FF6B6B', 'cie2000'); // CIEDE2000
+const deltaE2000 = ColorService.getDeltaE('#FF0000', '#FF6B6B', 'ciede2000'); // CIEDE2000
+// 'cie2000' is accepted as a legacy alias of 'ciede2000' and returns the same value
 
 // Color inversion
 const inverted = ColorService.invert('#FF6B6B');
@@ -132,19 +137,21 @@ const hex = ColorService.rybToHex(255, 255, 0); // Red+Yellow = Orange
 FFXIV dye database management and color matching.
 
 ```typescript
-import { DyeService, dyeDatabase } from 'xivdyetools-core';
+import { DyeService, dyeDatabase } from '@xivdyetools/core';
 
 const dyeService = new DyeService(dyeDatabase);
 
 // Database access
-const allDyes = dyeService.getAllDyes(); // 136 dyes
-const dyeById = dyeService.getDyeById(5752); // By itemID - Jet Black Dye
-const dyeByStain = dyeService.getByStainId(1); // By stainID - Snow White
+const allDyes = dyeService.getAllDyes(); // 125 dyes
+const dyeById = dyeService.getDyeById(13115); // By itemID (= Dye.id) - Jet Black; prefer getByStainId(102)
+const dyeByStain = dyeService.getByStainId(1); // By stainID (canonical key) - Snow White
 const categories = dyeService.getCategories(); // ['Neutral', 'Red', 'Blue', ...]
 
-// Color matching
+// Color matching — matchingMethod is one of the 5.0 suite:
+// 'ciede2000' (default) | 'oklab' | 'cie76' | 'redmean' | 'rgb' | 'distinguish'
 const closest = dyeService.findClosestDye('#FF6B6B');
-const nearby = dyeService.findDyesWithinDistance('#FF6B6B', 50, 5);
+const closestOk = dyeService.findClosestDye('#FF6B6B', { matchingMethod: 'oklab' });
+const nearby = dyeService.findDyesWithinDistance('#FF6B6B', { maxDistance: 50, limit: 5 });
 
 // Harmony generation (default: fast hue-based matching)
 const triadic = dyeService.findTriadicDyes('#FF6B6B');
@@ -156,10 +163,10 @@ const splitComplementary = dyeService.findSplitComplementaryDyes('#FF6B6B');
 // DeltaE-based harmony (perceptually accurate matching)
 const triadicDeltaE = dyeService.findTriadicDyes('#FF6B6B', {
   algorithm: 'deltaE',
-  deltaEFormula: 'cie2000', // or 'cie76' (faster, default)
+  deltaEFormula: 'ciede2000', // or 'cie76' (faster, default); 'cie2000' is a legacy alias
 });
 
-// Color space selection for hue rotation (v1.16.0+)
+// Color space selection for hue rotation
 // OKLCH produces more perceptually balanced harmonies
 const triadicOklch = dyeService.findTriadicDyes('#FF6B6B', { colorSpace: 'oklch' });
 const compLch = dyeService.findComplementaryPair('#FF6B6B', { colorSpace: 'lch' });
@@ -181,7 +188,7 @@ const filtered = dyeService.filterDyes({
 Multi-color palette extraction from images using K-means++ clustering.
 
 ```typescript
-import { PaletteService, DyeService, dyeDatabase } from 'xivdyetools-core';
+import { PaletteService, DyeService, dyeDatabase } from '@xivdyetools/core';
 
 const paletteService = new PaletteService();
 const dyeService = new DyeService(dyeDatabase);
@@ -203,9 +210,6 @@ const matches = paletteService.extractAndMatchPalette(pixels, dyeService, {
 });
 // Returns: Array<{ extracted: RGB, matchedDye: Dye, distance: number, dominance: number }>
 
-// Helper: Convert raw pixel buffer (RGB, 3 bytes per pixel)
-const pixelsFromBuffer = PaletteService.pixelDataToRGB(buffer);
-
 // Helper: Convert RGBA ImageData, filtering transparent pixels
 const pixelsFromCanvas = PaletteService.pixelDataToRGBFiltered(imageData.data);
 ```
@@ -215,32 +219,30 @@ const pixelsFromCanvas = PaletteService.pixelDataToRGBFiltered(imageData.data);
 Universalis API integration with pluggable cache backends.
 
 ```typescript
-import { APIService, MemoryCacheBackend } from 'xivdyetools-core';
+import { APIService, MemoryCacheBackend } from '@xivdyetools/core';
 
 // With memory cache (default)
 const apiService = new APIService();
 
 // With custom cache backend
 const cache = new MemoryCacheBackend();
-const apiService = new APIService(cache);
+const apiService = new APIService({ cacheBackend: cache });
 
 // Fetch price data
 const priceData = await apiService.getPriceData(5752); // itemID
 const pricesWithDC = await apiService.getPriceData(5752, undefined, 'Aether');
 
-// Batch operations
-const prices = await apiService.getPricesForItems([5752, 5753, 5754]);
+// Batch operations (per data center)
+const prices = await apiService.getPricesForDataCenter([5752, 5753, 5754], 'Aether');
 
 // Cache management
 await apiService.clearCache();
-const stats = await apiService.getCacheStats();
 
 // API health check
 const { available, latency } = await apiService.getAPIStatus();
 
 // Utility methods
 const formatted = APIService.formatPrice(123456); // "123,456G"
-const trend = APIService.getPriceTrend(100, 80); // { trend: 'up', ... }
 ```
 
 ## Custom Cache Backends
@@ -248,7 +250,7 @@ const trend = APIService.getPriceTrend(100, 80); // { trend: 'up', ... }
 Implement the `ICacheBackend` interface for custom storage:
 
 ```typescript
-import { ICacheBackend, CachedData, PriceData } from 'xivdyetools-core';
+import { ICacheBackend, CachedData, PriceData } from '@xivdyetools/core';
 import Redis from 'ioredis';
 
 class RedisCacheBackend implements ICacheBackend {
@@ -279,7 +281,7 @@ class RedisCacheBackend implements ICacheBackend {
 // Use with APIService
 const redis = new Redis();
 const cache = new RedisCacheBackend(redis);
-const apiService = new APIService(cache);
+const apiService = new APIService({ cacheBackend: cache });
 ```
 
 ## TypeScript Types
@@ -303,7 +305,7 @@ import type {
   HarmonyMatchingAlgorithm,
   HarmonyColorSpace,
   DeltaEFormula
-} from 'xivdyetools-core';
+} from '@xivdyetools/core';
 ```
 
 ## Constants
@@ -314,11 +316,10 @@ Access color theory and API configuration constants:
 import {
   RGB_MAX,
   HUE_MAX,
-  VISION_TYPES,
   BRETTEL_MATRICES,
   UNIVERSALIS_API_BASE,
   API_CACHE_TTL
-} from 'xivdyetools-core';
+} from '@xivdyetools/core';
 ```
 
 ## Utilities
@@ -328,20 +329,18 @@ Helper functions for common tasks:
 ```typescript
 import {
   clamp,
-  lerp,
   isValidHexColor,
   isValidRGB,
   retry,
   sleep,
   generateChecksum
-} from 'xivdyetools-core';
+} from '@xivdyetools/core';
 
 // Validation
 const isValid = isValidHexColor('#FF6B6B'); // true
 
 // Math
 const clamped = clamp(150, 0, 100); // 100
-const interpolated = lerp(0, 100, 0.5); // 50
 
 // Async utilities
 await sleep(1000); // Wait 1 second
@@ -353,7 +352,7 @@ const result = await retry(() => fetchData(), 3, 1000); // Retry with backoff
 ### Discord Bot
 ```typescript
 // Implement /harmony command
-import { DyeService, dyeDatabase } from 'xivdyetools-core';
+import { DyeService, dyeDatabase } from '@xivdyetools/core';
 
 const dyeService = new DyeService(dyeDatabase);
 const baseDye = dyeService.findClosestDye(userColor);
@@ -364,27 +363,35 @@ const harmonyDyes = dyeService.findTriadicDyes(userColor);
 ### Web App
 ```typescript
 // Color matcher tool
-import { DyeService, dyeDatabase } from 'xivdyetools-core';
+import { DyeService, dyeDatabase } from '@xivdyetools/core';
 
 const dyeService = new DyeService(dyeDatabase);
-const matchingDyes = dyeService.findDyesWithinDistance(imageColor, 50, 10);
+const matchingDyes = dyeService.findDyesWithinDistance(imageColor, { maxDistance: 50, limit: 10 });
 // Display results in UI
 ```
 
 ### CLI Tool
 ```typescript
 // Color conversion utility
-import { ColorService } from 'xivdyetools-core';
+import { ColorService } from '@xivdyetools/core';
 
 const hex = process.argv[2];
 const rgb = ColorService.hexToRgb(hex);
 console.log(`RGB: ${rgb.r}, ${rgb.g}, ${rgb.b}`);
 ```
 
+## Dye Database Composition
+
+The database is **125 standard dyes** (`src/data/dyes.json`, schema v2) keyed by `stainID`. Seven fields are stored per entry — `stainID`, `name`, `hex`, `category`, `acquisition`, `consolidationType`, `legacyItemID` — and everything else (`rgb` / `hsv` / `lab`, `cost` / `currency`, the `is*` flags) is **derived** at `DyeDatabase.initialize()`. The runtime `Dye` object still has its full shape, and `Dye.itemID` is always a `number`.
+
+The **11 Facewear colors are not dyes.** They live separately in `facewear_colors.json` / the `facewearColors` export as `FacewearColor` objects (string slug `id`, `name`, `hex`) and are excluded from the k-d tree, since they are not market-tradeable.
+
+Since **Patch 7.5**, 105 of the 125 dyes share three consolidated market itemIDs (Type-A `52254`, Type-B `52255`, Type-C `52256`). Use `getMarketItemID(dye)` for any market-board lookup — a hard-coded legacy itemID will not price correctly.
+
 ## Requirements
 
-- **Node.js** 18.0.0 or higher
-- **TypeScript** 5.3 or higher (for development)
+- **Node.js** 22.0.0 or higher
+- **TypeScript** 5.9 or higher (for development)
 
 ## Browser Compatibility
 
@@ -393,44 +400,55 @@ Works in all modern browsers with ES6 module support:
 - Firefox 88+
 - Safari 15+
 
-## License
-
-MIT © 2025-2026 Flash Galatine
-
-See [LICENSE](./LICENSE) for full details.
-
-## Legal Notice
-
-**This is a fan-made tool and is not affiliated with or endorsed by Square Enix Co., Ltd. FINAL FANTASY is a registered trademark of Square Enix Holdings Co., Ltd.**
+## Related Projects
 
-## Coming Soon
+This package lives in the [xivdyetools monorepo](https://github.com/FlashGalatine/xivdyetools). Its direct consumers:
 
-**Budget-Aware Dye Suggestions** - Find affordable alternatives to expensive dyes based on current market prices. See [specification](../xivdyetools-docs/BUDGET_AWARE_SUGGESTIONS.md) for details.
+- [`apps/web-app`](../../apps/web-app/) — interactive color tools for FFXIV
+- [`apps/discord-worker`](../../apps/discord-worker/) — Cloudflare Worker Discord bot
+- [`apps/api-worker`](../../apps/api-worker/) — public REST API
+- [`apps/og-worker`](../../apps/og-worker/) — OpenGraph cards (stateless localization trio)
+- [`apps/stoat-worker`](../../apps/stoat-worker/) — Revolt bot (parked)
+- [`@xivdyetools/svg`](../svg/), [`@xivdyetools/bot-logic`](../bot-logic/)
 
-## Related Projects
+## Support
 
-- [XIV Dye Tools Web App](https://github.com/FlashGalatine/xivdyetools-web-app) - Interactive color tools for FFXIV
-- [XIV Dye Tools Discord Worker](https://github.com/FlashGalatine/xivdyetools-discord-worker) - Cloudflare Worker Discord bot using this package
+- **Issues**: [GitHub Issues](https://github.com/FlashGalatine/xivdyetools/issues)
+- **NPM Package**: [@xivdyetools/core](https://www.npmjs.com/package/@xivdyetools/core)
+- **API Docs**: [developers.xivdyetools.app](https://developers.xivdyetools.app)
 
-## Support
+## Credits & Acknowledgements
 
-- **Issues**: [GitHub Issues](https://github.com/FlashGalatine/xivdyetools-core/issues)
-- **NPM Package**: [xivdyetools-core](https://www.npmjs.com/package/xivdyetools-core)
-- **Documentation**: [Full Docs](https://github.com/FlashGalatine/xivdyetools-core#readme)
+- **[XIVAPI](https://xivapi.com/)** — dye names in English, Japanese, German, and French. Korean and Chinese names are manually sourced; XIVAPI does not serve them.
+- **[Universalis](https://universalis.app/)** (MIT) — market board price data consumed by `APIService`.
+- **[spectral.js](https://github.com/rvanwijnen/spectral.js)** (MIT) — Kubelka-Munk spectral paint mixing.
+- Color-vision deficiency simulation uses the matrices from **Brettel, Viénot & Mollon (1997)**, *"Computerized simulation of color appearance for dichromats"*, JOSA A 14(10).
+- Perceptual color difference uses **CIE76** and **CIEDE2000** as published by the International Commission on Illumination.
 
 ## Connect With Me
 
 **Flash Galatine** | Midgardsormr (Aether)
 
 🎮 **FFXIV**: [Lodestone Character](https://na.finalfantasyxiv.com/lodestone/character/7677106/)
-📝 **Blog**: [Project Galatine](https://blog.projectgalatine.com/)
 💻 **GitHub**: [@FlashGalatine](https://github.com/FlashGalatine)
+🐦 **X/Twitter**: [@AsheJunius](https://x.com/AsheJunius)
 📺 **Twitch**: [flashgalatine](https://www.twitch.tv/flashgalatine)
 🌐 **BlueSky**: [projectgalatine.com](https://bsky.app/profile/projectgalatine.com)
 ❤️ **Patreon**: [ProjectGalatine](https://patreon.com/ProjectGalatine)
 ☕ **Ko-Fi**: [flashgalatine](https://ko-fi.com/flashgalatine)
 💬 **Discord**: [Join Server](https://discord.gg/5VUSKTZCe5)
 
+## License
+
+MIT © 2025-2026 Flash Galatine — see [LICENSE](./LICENSE).
+
+## Legal Notice
+
+**FINAL FANTASY is a registered trademark of Square Enix Holdings Co., Ltd.**
+**FINAL FANTASY XIV © SQUARE ENIX CO., LTD.**
+
+XIV Dye Tools is an unofficial fan project and is **not affiliated with, endorsed by, or sponsored by Square Enix Co., Ltd.** All FINAL FANTASY XIV content, including dye names and color values, is the property of Square Enix.
+
 ---
 
 **Made with ❤️ for the FFXIV community**

package/dist/blending/blending.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Color Blending — Six algorithms for mixing two colors.
+ *
+ * Blending Modes:
+ * - RGB:      Simple additive channel averaging
+ * - LAB:      Perceptually uniform CIELAB blending
+ * - OKLAB:    Modern perceptual (fixes LAB blue→purple issue)
+ * - RYB:      Traditional artist's color wheel
+ * - HSL:      Hue-Saturation-Lightness interpolation
+ * - Spectral: Kubelka-Munk physics simulation
+ */
+import type { BlendResult, BlendingMode } from './types.js';
+/**
+ * Blend two colors using the specified blending mode.
+ *
+ * @param hex1  - First color hex code (with or without #)
+ * @param hex2  - Second color hex code (with or without #)
+ * @param mode  - Blending algorithm to use
+ * @param ratio - 0.0 = all hex1, 0.5 = equal mix, 1.0 = all hex2
+ */
+export declare function blendColors(hex1: string, hex2: string, mode: BlendingMode, ratio?: number): BlendResult;
+//# sourceMappingURL=blending.d.ts.map

package/dist/blending/blending.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blending.d.ts","sourceRoot":"","sources":["../../src/blending/blending.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAiB,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAsB3E;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,YAAY,EAClB,KAAK,GAAE,MAAY,GAClB,WAAW,CAmCb"}

package/dist/blending/blending.js

@@ -0,0 +1,129 @@
+/**
+ * Color Blending — Six algorithms for mixing two colors.
+ *
+ * Blending Modes:
+ * - RGB:      Simple additive channel averaging
+ * - LAB:      Perceptually uniform CIELAB blending
+ * - OKLAB:    Modern perceptual (fixes LAB blue→purple issue)
+ * - RYB:      Traditional artist's color wheel
+ * - HSL:      Hue-Saturation-Lightness interpolation
+ * - Spectral: Kubelka-Munk physics simulation
+ */
+import { rgbToLab, labToRgb, rgbToOklab, oklabToRgb, rgbToRyb, rybToRgb, rgbToHsl, hslToRgb, rgbToReflectance, reflectanceToRgb, reflectanceToKS, ksToReflectance, rgbToHex, hexToRgb, } from './conversions.js';
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Blend two colors using the specified blending mode.
+ *
+ * @param hex1  - First color hex code (with or without #)
+ * @param hex2  - Second color hex code (with or without #)
+ * @param mode  - Blending algorithm to use
+ * @param ratio - 0.0 = all hex1, 0.5 = equal mix, 1.0 = all hex2
+ */
+export function blendColors(hex1, hex2, mode, ratio = 0.5) {
+    const h1 = hex1.startsWith('#') ? hex1 : `#${hex1}`;
+    const h2 = hex2.startsWith('#') ? hex2 : `#${hex2}`;
+    const t = Math.max(0, Math.min(1, ratio));
+    // REFACTOR-005: local parser — no more dependency on all of core
+    const rgb1 = hexToRgb(h1);
+    const rgb2 = hexToRgb(h2);
+    let blendedRgb;
+    switch (mode) {
+        case 'rgb':
+            blendedRgb = blendRGB(rgb1, rgb2, t);
+            break;
+        case 'lab':
+            blendedRgb = blendLAB(rgb1, rgb2, t);
+            break;
+        case 'oklab':
+            blendedRgb = blendOKLAB(rgb1, rgb2, t);
+            break;
+        case 'ryb':
+            blendedRgb = blendRYB(rgb1, rgb2, t);
+            break;
+        case 'hsl':
+            blendedRgb = blendHSL(rgb1, rgb2, t);
+            break;
+        case 'spectral':
+            blendedRgb = blendSpectral(rgb1, rgb2, t);
+            break;
+        default:
+            blendedRgb = blendRGB(rgb1, rgb2, t);
+    }
+    return { hex: rgbToHex(blendedRgb), rgb: blendedRgb };
+}
+// ============================================================================
+// Blend Implementations
+// ============================================================================
+function blendRGB(rgb1, rgb2, t) {
+    return {
+        r: Math.round(rgb1.r * (1 - t) + rgb2.r * t),
+        g: Math.round(rgb1.g * (1 - t) + rgb2.g * t),
+        b: Math.round(rgb1.b * (1 - t) + rgb2.b * t),
+    };
+}
+function blendLAB(rgb1, rgb2, t) {
+    const lab1 = rgbToLab(rgb1);
+    const lab2 = rgbToLab(rgb2);
+    const blended = {
+        l: lab1.l * (1 - t) + lab2.l * t,
+        a: lab1.a * (1 - t) + lab2.a * t,
+        b: lab1.b * (1 - t) + lab2.b * t,
+    };
+    return labToRgb(blended);
+}
+function blendOKLAB(rgb1, rgb2, t) {
+    const ok1 = rgbToOklab(rgb1);
+    const ok2 = rgbToOklab(rgb2);
+    return oklabToRgb({
+        L: ok1.L * (1 - t) + ok2.L * t,
+        a: ok1.a * (1 - t) + ok2.a * t,
+        b: ok1.b * (1 - t) + ok2.b * t,
+    });
+}
+function blendRYB(rgb1, rgb2, t) {
+    const ryb1 = rgbToRyb(rgb1);
+    const ryb2 = rgbToRyb(rgb2);
+    return rybToRgb({
+        r: ryb1.r * (1 - t) + ryb2.r * t,
+        y: ryb1.y * (1 - t) + ryb2.y * t,
+        b: ryb1.b * (1 - t) + ryb2.b * t,
+    });
+}
+function blendHSL(rgb1, rgb2, t) {
+    const hsl1 = rgbToHsl(rgb1);
+    const hsl2 = rgbToHsl(rgb2);
+    // Shortest-arc hue interpolation
+    let hueDiff = hsl2.h - hsl1.h;
+    if (hueDiff > 180)
+        hueDiff -= 360;
+    if (hueDiff < -180)
+        hueDiff += 360;
+    let blendedH = hsl1.h + hueDiff * t;
+    if (blendedH < 0)
+        blendedH += 360;
+    if (blendedH >= 360)
+        blendedH -= 360;
+    const blended = {
+        h: blendedH,
+        s: hsl1.s * (1 - t) + hsl2.s * t,
+        l: hsl1.l * (1 - t) + hsl2.l * t,
+    };
+    return hslToRgb(blended);
+}
+function blendSpectral(rgb1, rgb2, t) {
+    const ref1 = rgbToReflectance(rgb1);
+    const ref2 = rgbToReflectance(rgb2);
+    return reflectanceToRgb({
+        r: kubelkaMunkMix(ref1.r, ref2.r, t),
+        g: kubelkaMunkMix(ref1.g, ref2.g, t),
+        b: kubelkaMunkMix(ref1.b, ref2.b, t),
+    });
+}
+function kubelkaMunkMix(r1, r2, t) {
+    const ks1 = reflectanceToKS(r1);
+    const ks2 = reflectanceToKS(r2);
+    return ksToReflectance(ks1 * (1 - t) + ks2 * t);
+}
+//# sourceMappingURL=blending.js.map

package/dist/blending/blending.js.map

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

package/dist/blending/conversions.d.ts

@@ -0,0 +1,53 @@
+import type { RGB, LAB, HSL } from './types.js';
+/**
+ * RGB to CIELAB conversion.
+ * Exported for use in SVG generators that display LAB values.
+ */
+export declare function rgbToLab(rgb: RGB): LAB;
+export declare function labToRgb(lab: LAB): RGB;
+export declare function rgbToOklab(rgb: RGB): {
+    L: number;
+    a: number;
+    b: number;
+};
+export declare function oklabToRgb(oklab: {
+    L: number;
+    a: number;
+    b: number;
+}): RGB;
+export declare function rgbToRyb(rgb: RGB): {
+    r: number;
+    y: number;
+    b: number;
+};
+export declare function rybToRgb(ryb: {
+    r: number;
+    y: number;
+    b: number;
+}): RGB;
+export declare function rgbToHsl(rgb: RGB): HSL;
+export declare function hslToRgb(hsl: HSL): RGB;
+export declare function rgbToReflectance(rgb: RGB): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function reflectanceToRgb(ref: {
+    r: number;
+    g: number;
+    b: number;
+}): RGB;
+export declare function reflectanceToKS(r: number): number;
+export declare function ksToReflectance(ks: number): number;
+/**
+ * Parse a hex color string into RGB channels.
+ *
+ * REFACTOR-005 (2026-07-18 audit): local implementation replacing the sole use
+ * of `@xivdyetools/core`'s ColorService — the entire core package (dye
+ * database, k-d tree, i18n) was a dependency for these ~10 lines. Matches
+ * core's strict behavior: throws on malformed input; accepts #RGB and #RRGGBB
+ * (leading # optional).
+ */
+export declare function hexToRgb(hex: string): RGB;
+export declare function rgbToHex(rgb: RGB): string;
+//# sourceMappingURL=conversions.d.ts.map

package/dist/blending/conversions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversions.d.ts","sourceRoot":"","sources":["../../src/blending/conversions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAOhD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CAyBtC;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CA8BtC;AAMD,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAwBxE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,GAAG,CAuB1E;AAMD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAwBtE;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,GAAG,CA0BtE;AAMD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CA8BtC;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CA2BtC;AAMD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAE9E;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,GAAG,CAM9E;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAGlD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAiBzC;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAGzC"}