@xivdyetools/core 5.1.0 → 5.3.0

package/NOTICE

@@ -0,0 +1,26 @@
+Third-party data notices for @xivdyetools/core
+==============================================
+
+Munsell hue-wheel data
+----------------------
+The Munsell hue-angle table in src/data/munsell-hues.json is derived from
+the Munsell renotation data (real.dat) published by the Munsell Color
+Science Laboratory / Program of Color Science, Rochester Institute of
+Technology:
+  https://www.rit.edu/science/munsell-color-science-lab-educational-resources
+which in turn reproduces the tables of Newhall, S. M., Nickerson, D., &
+Judd, D. B. (1943). "Final Report of the O.S.A. Subcommittee on the
+Spacing of the Munsell Colors." JOSA 33(7), 385-418.
+doi:10.1364/JOSA.33.000385
+
+Only 40 derived hue-angle pairs (Value 6 / Chroma 8) are shipped; the
+renotation dataset itself is not redistributed. sRGB values were
+cross-checked against the R package `munsell`
+(https://github.com/cwickham/munsell), Copyright (c) 2016 Charlotte
+Wickham, MIT licence, and against munsell.js (MPL-2.0) as a development-time
+oracle.
+
+These values are computed colorimetric renotations, not measurements of
+any physical Munsell Book of Color, and are not endorsed by or affiliated
+with X-Rite, Pantone or Amazys Holding GmbH. MUNSELL is a registered
+trademark (USPTO Reg. No. 1570854) of Amazys Holding GmbH.

package/README.md

@@ -86,7 +86,7 @@ const harmonyDyes = dyeService.findComplementaryPair(baseDye.hex);
 
 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.
+> **Memory Note**: ColorService uses LRU caches (7 caches × 1000 entries each = up to 7000 cached entries — `hexToRgb`, `rgbToHex`, `rgbToHsv`, `hsvToRgb`, `hexToHsv`, `rgbToLab`, `rgbToOklab`) 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 ~700KB.
 
 ```typescript
 import { ColorService } from '@xivdyetools/core';
@@ -145,7 +145,8 @@ const dyeService = new DyeService(dyeDatabase);
 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', ...]
+const categories = dyeService.getCategories();
+// ['Neutral', 'Reds', 'Browns', 'Yellows', 'Greens', 'Blues', 'Purples', 'Special']
 
 // Color matching — matchingMethod is one of the 5.0 suite:
 // 'ciede2000' (default) | 'oklab' | 'cie76' | 'redmean' | 'rgb' | 'distinguish'
@@ -166,14 +167,13 @@ const triadicDeltaE = dyeService.findTriadicDyes('#FF6B6B', {
   deltaEFormula: 'ciede2000', // the default since 5.1.0; 'cie76' is faster, 'cie2000' a legacy alias
 });
 
-// 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' });
-// Available spaces: 'hsv' (default), 'oklch', 'lch', 'hsl'
+// DEPRECATED since 5.2.0: HarmonyOptions.colorSpace ('hsv' | 'oklch' | 'lch' | 'hsl').
+// It rotates hue WITHOUT carrying the base's saturation and value, which is a
+// different answer from the one every surface shows. Use `generateHarmonySlots`
+// with a `wheel` instead (see "Colour wheels" below).
 
 // Filtering
-const redDyes = dyeService.searchByCategory('Red');
+const redDyes = dyeService.searchByCategory('Reds'); // exact match against DYE_CATEGORIES
 const searchResults = dyeService.searchByName('black');
 const filtered = dyeService.filterDyes({
   category: 'Special',
@@ -183,6 +183,50 @@ const filtered = dyeService.filterDyes({
 });
 ```
 
+#### Colour wheels
+
+Harmony slot selection goes through `generateHarmonySlots(baseHex, harmonyType, candidates, config, options?)` — the one implementation the web app, the Discord bot and the OG card share. `config.wheel` chooses which wheel the offsets are measured on; `'rgb'` is the default and is today's behaviour bit for bit.
+
+```typescript
+import {
+  generateHarmonySlots,
+  COLOR_WHEEL_IDS,       // ['rgb', 'ryb', 'munsell', 'oklch-hue', 'oklch-lightness']
+  DEFAULT_COLOR_WHEEL,   // 'rgb'
+  getColorWheel,
+  normalizeColorWheelId,
+  HARMONY_OFFSETS,
+  isKnownHarmonyType,
+  DyeService,
+  dyeDatabase,
+} from '@xivdyetools/core';
+
+const dyeService = new DyeService(dyeDatabase);
+
+const slots = generateHarmonySlots(
+  '#FF6B6B',
+  'triadic',                        // any key of HARMONY_OFFSETS (10 of them)
+  dyeService.getAllDyes(),           // callers pre-filter the candidate pool
+  {
+    usePerceptualMatching: true,
+    matchingMethod: 'ciede2000',
+    wheel: 'ryb',
+    companionCount: 2,
+    preventDuplicates: true,
+  },
+);
+// HarmonySlot[]: { index, offset, targetHue, wheelHue, targetHex, dye, deviance, companions }
+```
+
+Read the wheel list from `COLOR_WHEEL_IDS` and normalise anything arriving off
+the wire with `normalizeColorWheelId(value)` (or `parseColorWheelId` when
+"unknown" must stay distinguishable from `'rgb'`) — never hand-roll a
+`toLowerCase()` + membership test. `getColorWheel(id)` returns the `ColorWheel`
+itself (`hueOf`, `target`, `ringStops`, `carriesBaseHsv`).
+
+`oklch-lightness` keeps the base's OKLab L and C rather than its HSV S/V
+(`carriesBaseHsv === false`), so the selector forces ΔE ranking for it whatever
+`usePerceptualMatching` says.
+
 ### PaletteService
 
 Multi-color palette extraction from images using K-means++ clustering.
@@ -390,7 +434,7 @@ Since **Patch 7.5**, 105 of the 125 dyes share three consolidated market itemIDs
 
 ## Requirements
 
-- **Node.js** 22.0.0 or higher
+- **Node.js** 18.0.0 or higher (`engines.node: ">=18.0.0"`)
 - **TypeScript** 5.9 or higher (for development)
 
 ## Browser Compatibility
@@ -408,9 +452,10 @@ This package lives in the [xivdyetools monorepo](https://github.com/FlashGalatin
 - [`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/)
 
+(`apps/stoat-worker` reaches core only indirectly, through `@xivdyetools/bot-logic`.)
+
 ## Support
 
 - **Issues**: [GitHub Issues](https://github.com/FlashGalatine/xivdyetools/issues)
@@ -442,6 +487,8 @@ This package lives in the [xivdyetools monorepo](https://github.com/FlashGalatin
 
 MIT © 2025-2026 Flash Galatine — see [LICENSE](./LICENSE).
 
+Third-party data attributions (the Munsell hue wheel) are in [NOTICE](./NOTICE).
+
 ## Legal Notice
 
 **FINAL FANTASY is a registered trademark of Square Enix Holdings Co., Ltd.**

package/dist/data/locales/de.json

@@ -2,7 +2,7 @@
   "locale": "de",
   "meta": {
     "version": "1.0.0",
-    "generated": "2026-09-03T12:01:42.834Z",
+    "generated": "2026-09-05T13:38:20.760Z",
     "dyeCount": 125
   },
   "labels": {
@@ -186,6 +186,13 @@
     "compound": "Zusammengesetzt",
     "shades": "Schattierungen"
   },
+  "colorWheels": {
+    "rgb": "RGB (Bildschirm)",
+    "ryb": "RYB (Malerfarbkreis)",
+    "munsell": "Munsell (JIS)",
+    "oklch-hue": "OKLCH-Farbton (wahrnehmungsgleiche Abstände)",
+    "oklch-lightness": "OKLCH-Helligkeit (behält die Helligkeit)"
+  },
   "visionTypes": {
     "normal": "Normales Sehen",
     "deuteranopia": "Deuteranopie (Rot-Grün-Farbenblindheit)",

package/dist/data/locales/en.json

@@ -2,7 +2,7 @@
   "locale": "en",
   "meta": {
     "version": "1.0.0",
-    "generated": "2026-09-03T12:01:42.830Z",
+    "generated": "2026-09-05T13:38:20.756Z",
     "dyeCount": 125
   },
   "labels": {
@@ -186,6 +186,13 @@
     "compound": "Compound",
     "shades": "Shades"
   },
+  "colorWheels": {
+    "rgb": "RGB (screen)",
+    "ryb": "RYB (artist's)",
+    "munsell": "Munsell (JIS)",
+    "oklch-hue": "OKLCH hue (perceptual spacing)",
+    "oklch-lightness": "OKLCH lightness (keeps brightness)"
+  },
   "visionTypes": {
     "normal": "Normal Vision",
     "deuteranopia": "Deuteranopia (Red-Green Colorblindness)",

package/dist/data/locales/fr.json

@@ -2,7 +2,7 @@
   "locale": "fr",
   "meta": {
     "version": "1.0.0",
-    "generated": "2026-09-03T12:01:42.835Z",
+    "generated": "2026-09-05T13:38:20.761Z",
     "dyeCount": 125
   },
   "labels": {
@@ -186,6 +186,13 @@
     "compound": "Composé",
     "shades": "Nuances"
   },
+  "colorWheels": {
+    "rgb": "RVB (écran)",
+    "ryb": "RJB (roue des peintres)",
+    "munsell": "Munsell (JIS)",
+    "oklch-hue": "Teinte OKLCH (espacement perceptuel)",
+    "oklch-lightness": "Luminosité OKLCH (conserve la luminosité)"
+  },
   "visionTypes": {
     "normal": "Vision normale",
     "deuteranopia": "Deutéranopie (Daltonisme rouge-vert)",

package/dist/data/locales/ja.json

@@ -2,7 +2,7 @@
   "locale": "ja",
   "meta": {
     "version": "1.0.0",
-    "generated": "2026-09-03T12:01:42.833Z",
+    "generated": "2026-09-05T13:38:20.759Z",
     "dyeCount": 125
   },
   "labels": {
@@ -186,6 +186,13 @@
     "compound": "複合",
     "shades": "シェード"
   },
+  "colorWheels": {
+    "rgb": "RGB（画面）",
+    "ryb": "RYB（画家の色相環）",
+    "munsell": "マンセル（JIS）",
+    "oklch-hue": "OKLCH 色相（知覚的な間隔）",
+    "oklch-lightness": "OKLCH 明度（明るさを保持）"
+  },
   "visionTypes": {
     "normal": "正常視覚",
     "deuteranopia": "2型色覚（赤緑色盲）",

package/dist/data/locales/ko.json

@@ -2,7 +2,7 @@
   "locale": "ko",
   "meta": {
     "version": "1.0.0",
-    "generated": "2026-09-03T12:01:42.836Z",
+    "generated": "2026-09-05T13:38:20.762Z",
     "dyeCount": 125
   },
   "labels": {
@@ -186,6 +186,13 @@
     "compound": "복합",
     "shades": "명암"
   },
+  "colorWheels": {
+    "rgb": "RGB (화면)",
+    "ryb": "RYB (화가의 색상환)",
+    "munsell": "먼셀 (JIS)",
+    "oklch-hue": "OKLCH 색상 (지각적 간격)",
+    "oklch-lightness": "OKLCH 명도 (밝기 유지)"
+  },
   "visionTypes": {
     "normal": "정상 시력",
     "deuteranopia": "제2색맹 (적록색맹)",

package/dist/data/locales/zh.json

@@ -2,7 +2,7 @@
   "locale": "zh",
   "meta": {
     "version": "1.0.0",
-    "generated": "2026-09-03T12:01:42.837Z",
+    "generated": "2026-09-05T13:38:20.763Z",
     "dyeCount": 125
   },
   "labels": {
@@ -186,6 +186,13 @@
     "compound": "复合",
     "shades": "明暗"
   },
+  "colorWheels": {
+    "rgb": "RGB（屏幕）",
+    "ryb": "RYB（画家色环）",
+    "munsell": "孟塞尔（JIS）",
+    "oklch-hue": "OKLCH 色相（感知均匀间距）",
+    "oklch-lightness": "OKLCH 明度（保持亮度）"
+  },
   "visionTypes": {
     "normal": "正常视觉",
     "deuteranopia": "绿色盲（红绿色盲）",

package/dist/data/munsell-hues.json

@@ -0,0 +1,175 @@
+{
+    "$comment": "Generated by scripts/build-munsell-hues.ts from the Munsell renotation data (RIT MCSL real.dat, Newhall, Nickerson & Judd 1943) at Value 6 / Chroma 8. Attribution: packages/core/NOTICE. Do not edit by hand.",
+    "value": 6,
+    "chroma": 8,
+    "table": [
+        [
+            0,
+            0
+        ],
+        [
+            3.989034915710647,
+            2.5139081249797073
+        ],
+        [
+            12.989034915710647,
+            8.447104607433062
+        ],
+        [
+            21.989034915710647,
+            14.803285189702649
+        ],
+        [
+            30.989034915710647,
+            20.191397337216358
+        ],
+        [
+            39.98903491571065,
+            26.275952042041865
+        ],
+        [
+            48.98903491571065,
+            31.383193267820104
+        ],
+        [
+            57.98903491571065,
+            37.05876235203499
+        ],
+        [
+            66.98903491571065,
+            42.398535896728106
+        ],
+        [
+            75.98903491571065,
+            47.9926554960407
+        ],
+        [
+            84.98903491571065,
+            53.017624252769565
+        ],
+        [
+            93.98903491571065,
+            57.90986372546996
+        ],
+        [
+            102.98903491571065,
+            65.62918717399259
+        ],
+        [
+            111.98903491571065,
+            75.0580027667944
+        ],
+        [
+            120.98903491571065,
+            93.22570091949439
+        ],
+        [
+            129.98903491571065,
+            116.51033176907356
+        ],
+        [
+            138.98903491571065,
+            144.6266917947504
+        ],
+        [
+            147.98903491571065,
+            157.24722825147705
+        ],
+        [
+            156.98903491571065,
+            163.457850437341
+        ],
+        [
+            165.98903491571065,
+            168.78816045754945
+        ],
+        [
+            174.98903491571065,
+            173.49142938669547
+        ],
+        [
+            183.98903491571065,
+            177.19320475875236
+        ],
+        [
+            192.98903491571065,
+            179.92793432347787
+        ],
+        [
+            201.98903491571065,
+            182.82865339190766
+        ],
+        [
+            210.98903491571065,
+            185.32791575269118
+        ],
+        [
+            219.98903491571065,
+            188.87511992237626
+        ],
+        [
+            228.98903491571065,
+            194.98672174211083
+        ],
+        [
+            237.98903491571065,
+            200.12467673015738
+        ],
+        [
+            246.98903491571065,
+            207.13552720434132
+        ],
+        [
+            255.98903491571065,
+            214.70895708520516
+        ],
+        [
+            264.98903491571065,
+            228.6615786246757
+        ],
+        [
+            273.98903491571065,
+            245.80502994636265
+        ],
+        [
+            282.98903491571065,
+            262.31165473110855
+        ],
+        [
+            291.98903491571065,
+            276.7201487217782
+        ],
+        [
+            300.98903491571065,
+            297.98603038444935
+        ],
+        [
+            309.98903491571065,
+            313.76831747322956
+        ],
+        [
+            318.98903491571065,
+            326.1458328240501
+        ],
+        [
+            327.98903491571065,
+            337.3234172322137
+        ],
+        [
+            336.98903491571065,
+            344.4367466165168
+        ],
+        [
+            345.98903491571065,
+            350.917143032286
+        ],
+        [
+            354.98903491571065,
+            356.8420667891947
+        ],
+        [
+            360,
+            360
+        ]
+    ]
+}