chromonym 3.1.1 → 3.2.0

package/NOTICE.md

@@ -67,7 +67,7 @@ Crayola's published approximations.
 
 ### Scope
 
-The shipped set is ~85 entries — the current 64-standard box, the
+The shipped set is 84 entries: the current 64-standard box, the
 iconic fluorescent "Neon" range, and widely-recognized modern
 additions. It is not exhaustive: historical, retired, specialty-box
 (Gem Tones, Heads 'N Tails, Multicultural, etc.), and regional-variant
@@ -93,6 +93,248 @@ the public domain.
 The `web` palette mirrors the CSS Color Module Level 4 named-color
 set, which is a public specification.
 
+## Resene
+
+The `resene` palette (1378 entries) is derived from the Raku
+module **`Color::Names::Resene`** in the
+[`thundergnat/Color-Names`](https://github.com/thundergnat/Color-Names)
+repository, which digitizes the named-color catalog published by
+**Resene Paints Ltd.** (New Zealand). Resene's naming system has
+distinctly local flavor, including te reo Māori and New Zealand
+place names ("Pohutukawa," "Acapulco," "Afghan Tan").
+
+- Chromonym uses **nominative references** to Resene's published
+  color names; no trademark claim or endorsement is implied.
+- Canonical keys are the lowercase single-word form the source
+  module uses (`treepoppy` for "Tree Poppy"); the display form
+  and Resene's own Munsell-style code (e.g. `BR32-011-076`) are
+  captured as trailing comments on each palette entry for human
+  readers.
+- sRGB hex values are taken verbatim from the upstream module's
+  RGB byte triplets. Resene's physical paint samples under
+  their own published lighting conditions are the authoritative
+  reference; this digital approximation is provided for
+  comparative / tooling use, not for paint specification.
+- If Resene Paints Ltd. objects to this palette's inclusion,
+  open an issue and we will revisit.
+
+## Natural Colour System (NCS)
+
+The `ncs` palette (1950 entries) is derived from the Raku module
+**`Color::Names::NCS`** in the
+[`thundergnat/Color-Names`](https://github.com/thundergnat/Color-Names)
+repository, which digitizes the **Natural Colour System®** Atlas.
+NCS is a Swedish perceptual color system based on Hering's
+opponent-process theory; its notation (e.g. `S 2030-R80B`)
+describes each color by its blackness, chromaticness, and hue
+position between the four elementary chromatics.
+
+- **NCS® is a registered trademark of NCS Colour AB** (Stockholm).
+  Chromonym is **not affiliated with, endorsed by, licensed by,
+  or certified by NCS Colour AB**. The shipped palette is a
+  community approximation intended for on-screen reference and
+  nearest-name identification; it is **not suitable for paint
+  specification or color matching** against the official NCS
+  Atlas.
+- NCS is **device-independent by design**. Any sRGB approximation
+  is lossy by construction. The values shipped here come from
+  thundergnat's Raku module's own digitization; different NCS
+  publications give slightly different sRGB values for the same
+  code.
+- Canonical keys are the NCS codes themselves (e.g. `2030-R80B`).
+  The palette's custom normalizer accepts optional `NCS ` and
+  `S ` prefixes, so `NCS S 2030-R80B`, `S 2030-R80B`,
+  `2030-R80B`, and `2030r80b` all resolve identically. `S` is
+  only treated as a prefix when followed by a digit, so inputs
+  that don't match an NCS code aren't silently rewritten.
+
+### Accuracy envelope
+
+NCS specifies colors by percentages on an opponent-process model;
+those percentages must be translated to sRGB through a calibration
+that differs between publications. As a rough guide for the
+digitization chromonym ships:
+
+- **Mid-chroma / mid-value codes** (blackness and chromaticness
+  both between ~20 and ~60) are the best-behaved; the upstream
+  digitization is usually within a few ΔE2000 of any reasonable
+  alternate rendering.
+- **High chromaticness, low blackness** codes (e.g. `S 1080-Y90R`,
+  `S 0580-G`) sit at or outside the sRGB gamut boundary. The hex
+  shipped here is gamut-clipped; a different digitization may
+  clip differently, producing visibly different hex values for
+  the same NCS code.
+- **Very low-blackness neutrals** (e.g. the `0300-N` / `0500-N`
+  range) are close to sRGB white; fine-grained differences between
+  digitizations are largely imperceptible.
+
+If brand-critical or specification-critical NCS matching is needed,
+consult NCS Colour AB directly: <https://ncscolour.com/>.
+
+## NBS (thundergnat digitization)
+
+The `nbs` palette (267 entries) is a **second digitization of the
+same 1955 NBS Method of Designating Colors** covered by the
+`isccNbs` palette above; it is sourced from the Raku module
+**`Color::Names::NBS`** in
+[`thundergnat/Color-Names`](https://github.com/thundergnat/Color-Names).
+Ships alongside `isccNbs` (not as a replacement) because the two
+digitizations produce materially different sRGB values for the
+same named blocks: average ΔE2000 of ~4.6 across the 260 shared
+names, max ΔE2000 of 31 for the most saturated blocks like
+"Vivid bluish green."
+
+The two palettes serve different reference workflows:
+
+- **`isccNbs`** (Paul Centore) computes Munsell-centroid CIELAB
+  then maps to sRGB. "Vivid" blocks land near the sRGB saturation
+  edge; seven blocks are left as gaps because their centroids
+  fall outside the sRGB gamut.
+- **`nbs`** (thundergnat) appears to use the sample chip RGBs
+  from the original NBS publication, which were already gamut-
+  compressed by the physical chip material. "Vivid" blocks read
+  as more muted, and all 267 entries are covered — including
+  the seven blocks whose Munsell centroids fall outside the sRGB
+  gamut and are therefore omitted from `isccNbs`. `nbs` does not
+  "recover" the out-of-gamut centroids; it ships the already-
+  compressed physical chip approximation instead, which is a
+  different kind of lossy.
+
+Pick `nbs` for historical / swatch-book matching; pick `isccNbs`
+for modern digital design work. The name vocabulary (the 1955
+NBS publication itself) is a US-government document not subject
+to copyright restrictions when faithfully reproduced; the
+specific sRGB values in each palette are credited to their
+respective digitizers.
+
+## ISCC-NBS Colour System
+
+The `isccNbs` palette (260 entries) is the **ISCC-NBS Method of
+Designating Colors**, a 1955 joint publication of the
+**Inter-Society Color Council** and the US **National Bureau of
+Standards** (now NIST). The system partitions the Munsell color
+solid into 267 named blocks at Level 3 resolution with canonical
+names like "Vivid pink," "Strong purplish red," and "Dark
+yellowish brown."
+
+sRGB centroids for each named block are scraped from **Paul
+Centore's** digitization at
+<https://www.munsellcolorscienceforpainters.com/ISCCNBS/ISCCNBSSystem.html>,
+part of his *Munsell Colour Science for Painters* site.
+
+**Why 260 and not 267:** Seven ISCC-NBS blocks sit outside the
+sRGB gamut (notably the most-saturated greens, blues, and
+orange-yellows): `Deep green`, `Deep bluish green`, `Vivid
+greenish blue`, `Deep greenish blue`, `Brilliant orange`, `Deep
+olive green`, and `Vivid orange yellow`. Centore's source marks
+these as `rgb(NaN,NaN,NaN)`; chromonym skips them rather than
+ship a fabricated sRGB approximation.
+
+The ISCC-NBS name system itself is a US-government publication
+and is not subject to copyright restrictions when faithfully
+reproduced. Paul Centore's specific sRGB-centroid computations
+are credited here; if the author objects to Chromonym's use of
+his digitization, open an issue and we will revisit or redo the
+centroids from the primary Munsell data.
+
+## Federal Standard 595 (FS595B and FS595C)
+
+The `fs595b` (209 entries) and `fs595c` (589 entries) palettes
+are derived from the Raku modules **`Color::Names::FS595B`** and
+**`Color::Names::FS595C`** in the
+[`thundergnat/Color-Names`](https://github.com/thundergnat/Color-Names)
+repository, which digitize the US Federal Government's
+**Federal Standard 595** paint-color specification (used for
+military, aviation, and government-equipment coatings). FS595B
+is the 1989 revision, superseded by FS595C in 2008. Both are
+still in active use depending on which revision a given piece of
+documentation or equipment references. The Federal Standard
+itself is a US-government-published specification and is not
+subject to copyright restrictions when faithfully reproduced.
+
+- Canonical keys in both palettes are the 5-digit FS codes
+  prefixed with `FS ` (e.g. `FS 11136`). Common names attached
+  to many chips in the source (e.g. "Insignia Red") are captured
+  as trailing code comments on each palette entry for human
+  readers but are **not** used as lookup keys because the spec
+  reuses many across multiple chips with different hex values
+  (18–20 different "Green"s, 11 "Tan"s, etc., depending on
+  revision).
+- Same-coded chips can differ in hex between the B and C
+  revisions; for example `FS 11136` ("Insignia Red") is
+  `#9b2f25` in FS595B versus `#a32b25` in FS595C. Pick the
+  palette that matches your reference documentation.
+- sRGB hex values are taken verbatim from the upstream modules'
+  RGB byte triplets; the published standard specifies color
+  chips under controlled lighting, and all digital sRGB
+  approximations including these are necessarily simplified.
+- Chromonym is **not affiliated with** any US Government agency
+  or defense contractor; no endorsement is implied.
+
+## XKCD color survey
+
+The `xkcd` palette (923 entries after normalization-collision
+dedupe) is derived from **Randall Munroe's 2010 XKCD color
+survey results**, published at <https://xkcd.com/color/rgb.txt>
+and released to the **public domain under CC0 1.0 Universal**.
+Chromonym reproduces the dataset verbatim apart from:
+
+- Hex casing normalized to lowercase.
+- Entries whose names collapse to the same canonical key under
+  `standardNormalize` are deduped first-seen wins (e.g. the
+  survey's `darkblue` and `dark blue` entries both normalize to
+  `darkblue`; only the first is retained).
+
+The XKCD color-survey names are crowd-sourced and include
+colorful non-standard descriptors. Chromonym takes no editorial
+stance on the names and ships them as-is.
+
+## Name That Color (NTC)
+
+The `ntc` palette (1566 entries) is derived from Chirag Mehta's
+**"Name That Color"** dataset, first published at
+<https://chir.ag/projects/ntc/>. Chromonym consumes the dataset via
+the MIT-licensed **`colorjs/color-namer`** npm package
+(<https://github.com/colorjs/color-namer>), which redistributes the
+list in a machine-readable form. The shipped palette was generated
+against commit `abb3d184ab63db9327908319cc45b55c91493bb7` of the
+upstream repository, so the entry set is deterministic and
+reproducible.
+
+- Names are used as **nominative references** to the publicly
+  distributed NTC dataset; no endorsement or trademark claim is
+  implied.
+- sRGB hex values are taken verbatim from the upstream list.
+- No modifications are made beyond casing normalization of the hex
+  string and sorting by display name.
+
+The NTC dataset has been widely redistributed since 2006 under
+terms allowing free reuse with attribution. If the upstream author
+objects to Chromonym's inclusion of the list, open an issue and we
+will revisit.
+
+## Bauhaus Modern (demo site typeface)
+
+The demo site at <https://simiancraft.github.io/chromonym/> embeds
+**Bauhaus Modern**, a display typeface designed by **Nils Kähler**
+(2016). The font file is hosted under
+[`demo/public/fonts/`](./demo/public/fonts/) and is used only as
+display type for the demo wordmark.
+
+- Source: <https://www.dafont.com/bauhaus-modern.font>
+- License terms: "Free for personal use" (per the dafont listing)
+- Use for this demo was arranged with the designer's knowledge via
+  email; a donation was made, and the use case (MIT-licensed library
+  demo, display-type only, with visible attribution) was described.
+  See [`demo/public/fonts/README.txt`](./demo/public/fonts/README.txt)
+  for the full note.
+
+The font is not part of the published npm package (`files` allowlist
+ships only the library, not the demo site). Downstream users of the
+`chromonym` package do not redistribute Bauhaus Modern by installing
+the library. Please do not repackage or redistribute the font file
+outside this demo without following up with the designer directly.
+
 ## Upstream dependencies
 
 See `package.json` for runtime and development dependencies. All are MIT

package/README.md

@@ -20,7 +20,11 @@
   <code>identify</code> &nbsp;•&nbsp; <code>resolve</code> &nbsp;•&nbsp; <code>convert</code>
 </p>
 
-**The last color-naming library you'll ever need.** One API — `identify`, `resolve`, `convert` — works against any palette you throw at it. Ships CSS, X11, Pantone, and Crayola out of the box; bring your own (brand colors, paint chips, game factions, chart themes) with full TypeScript inference and zero registration. Six distance metrics — from fast Euclidean to industry-standard CIEDE2000 and OKLAB. Tree-shakes to the bone — you only pay for palettes you import.
+**The last color-naming library you'll ever need.** One API — `identify`, `resolve`, `convert` — works against any palette you throw at it. Ships twelve palettes out of the box (CSS, X11, Pantone, Crayola, NTC, XKCD, Resene, NCS, ISCC-NBS, NBS, FS 595 B, FS 595 C); bring your own (brand colors, paint chips, game factions, chart themes) with full TypeScript inference and zero registration. Six distance metrics — from fast Euclidean to industry-standard CIEDE2000 and OKLAB. Tree-shakes to the bone — you only pay for palettes you import.
+
+<sub>*chromonym* (n.): a name for a color; *chroma* + *-onym*. Also the library.</sub>
+
+<sub>Every public export ships with JSDoc and a runnable `@example`; autocomplete and hover do the teaching.</sub>
 
 <p align="center">
   <a href="https://simiancraft.github.io/chromonym/">
@@ -80,18 +84,6 @@ yarn add chromonym
 npm install chromonym
 ```
 
-## Migrating from 1.x
-
-v2 collapsed the five-verb draft API (`identify`, `identifyAll`, `translate`, `resolve`, `convert`) into **three verbs** by folding the duplicates into options on existing verbs. Mechanical rewrites:
-
-```ts
-// v1 → v2
-identifyAll(color, { palette, k: 3 })          // → identify(color, { palette, k: 3 })
-translate(name, { from: web, to: pantone })    // → identify(name, { palette: pantone, source: web })
-```
-
-`resolve` and `convert` are unchanged. If you were only using those two, no edits are needed. See [`CHANGELOG.md`](CHANGELOG.md) for the full list of v3.0 breaking changes.
-
 ## API
 
 Three verbs. All accept an optional `opts` object; defaults fire when omitted.
@@ -273,22 +265,24 @@ type Palette<Name extends string = string> = {
 
 The primary shape. Any object matching `Palette<Name>` works — no registry, no plugin, no side effects. Bundlers only include the palettes you actually import.
 
+The recommended pattern is `defineColorPalette`: it accepts mixed color-value formats (paste whatever came out of your design tool), normalizes everything to hex once at module load, and preserves the literal-key union for full narrowing through `identify` / `resolve` / `convert`.
+
 ```ts
-import { identify, resolve, type Palette } from 'chromonym';
+import { defineColorPalette, identify, resolve } from 'chromonym';
 
-const warhammer = {
+const warhammer = defineColorPalette({
   name: 'warhammer40k',
   colors: {
-    'world eaters red': '#8b1a1a',
-    'adeptus red': '#652022',
-    'sons of malice white': '#e8e4d8',
-    'the flawless host purple': '#6b2d7d',
-    'nurgle green': '#748c3f',
+    'world eaters red': '#8b1a1a',                  // hex
+    'adeptus red': 'rgb(101, 32, 34)',              // rgb string
+    'sons of malice white': { r: 232, g: 228, b: 216 }, // rgb object
+    'the flawless host purple': [107, 45, 125],     // rgb tuple
+    'nurgle green': 'hsl(78, 38%, 39%)',            // hsl string
     'alpha legion teal': '#2a6d7a',
   },
-  normalize: (s: string) => s.toLowerCase().replace(/[^a-z0-9]/g, ''),
+  normalize: (s) => s.toLowerCase().replace(/[^a-z0-9]/g, ''),
   defaultMetric: 'deltaE2000',
-} as const satisfies Palette;
+});
 
 identify('#750c0c', { palette: warhammer })
 // → 'world eaters red'  (return type narrows to the palette's key union)
@@ -297,14 +291,26 @@ resolve('Nurgle Green', { palette: warhammer })
 // → '#748c3f'           (your normalizer handles case + punctuation)
 ```
 
-### The four we ship
+Unparseable values are dropped with a `console.warn` naming the palette, the offending key, and the bad value; the rest of the palette loads normally. This keeps a single typo out of your brand kit from taking down the whole module.
+
+If you prefer zero runtime and already have hex-only values, the `as const satisfies Palette<'A' | 'B' | ...>` pattern still works — list the key union once in the generic and it narrows identically.
+
+### The twelve we ship
 
 | Name | Entries | Source |
 |---|---|---|
 | `web` (default) | 148 | CSS Color Module Level 4 named colors |
 | `x11` | 658 | X.Org `rgb.txt` (public domain) |
 | `pantone` | 907 | Pantone Coated (C) — community approximations (not Pantone-licensed) |
-| `crayola` | ~85 | Crayola crayon colors — community approximations (not Crayola-licensed) |
+| `crayola` | 84 | Crayola crayon colors — community approximations (not Crayola-licensed) |
+| `ntc` | 1566 | Chirag Mehta's "Name That Color" dataset (broad coverage of design / UI / hardware names) |
+| `xkcd` | 923 | XKCD 2010 color-survey results (CC0; crowd-sourced common-speech names) |
+| `fs595b` | 209 | Federal Standard 595B paint chips (1989 revision; modelers / historical equipment) |
+| `fs595c` | 589 | Federal Standard 595C paint chips (US Government spec; military / aviation coatings) |
+| `isccNbs` | 260 | ISCC-NBS Method of Designating Colors (1955 US standard; Munsell-partitioned named blocks) |
+| `nbs` | 267 | Second digitization of the same 1955 standard; different sRGB (matches 1955 chip book; covers the 7 blocks `isccNbs` leaves as gaps) |
+| `resene` | 1378 | Resene Paints (NZ) catalog; te reo Māori and NZ place-names in the naming |
+| `ncs` | 1950 | Natural Colour System (Sweden) — perceptual, structured notation (`2030-R80B`), not NCS-licensed |
 
 Importable directly, or via subpath exports for stricter tree-shaking:
 
@@ -321,7 +327,7 @@ crayola.colors['Granny Smith Apple']  // '#a8e4a0'
 
 Each palette's keys follow its own domain convention — so `identify`'s output pastes back into whatever ecosystem the name came from. `web` uses the CSS spec's single-word form (`rebeccapurple`), `x11` uses the X.Org docs' spaced form (`'antique white 1'`), `pantone` uses the official print notation (`'185 C'`), `crayola` uses the Title Case form printed on the crayon wrapper (`'Granny Smith Apple'`).
 
-*Trivia:* `web.colors.rebeccapurple` (`#663399`) entered CSS Color 4 in 2014 in memory of [Rebecca Meyer](https://meyerweb.com/eric/thoughts/2014/06/19/rebeccapurple/). The X11 set ships every gray name twice (`gray`, `grey`) plus numbered variants up to 99, so `x11.colors['gray 73']` is a real key (`#bababa`). Yes, these are Greys. No, not the kind that visit during sleep paralysis.
+*Trivia:* `web.colors.rebeccapurple` (`#663399`) entered CSS Color 4 in 2014 in memory of [Rebecca Meyer](https://meyerweb.com/eric/thoughts/2014/06/19/rebeccapurple/). The X11 set ships every gray name twice (`gray`, `grey`) plus numbered variants up to 100, so `x11.colors['gray 73']` is a real key (`#bababa`). Yes, these are Greys. No, not the kind that visit during sleep paralysis.
 
 ### Cross-palette translation
 
@@ -382,7 +388,7 @@ Rule of thumb: use `source` when you want one clean call and `null` on miss; use
 
 Each metric trades cost for accuracy — the full scan over 907 Pantone entries is well under 1 ms even with ΔE2000. For interactive UIs, cost is usually irrelevant; drop to a cheaper metric when batch-processing millions of colors or when you need specific tie-breaking behavior.
 
-> **Note on x11's default (ΔE76):** x11 has 658 entries, many of them saturated blue/purple ramps where ΔE76 is a known weak spot. The default optimizes for UI scrubbing speed (~5 µs vs ~90 µs for ΔE2000). If perceptual accuracy matters more than latency, override per call with `{ metric: 'deltaEok' }` — same cost as ΔE76 on cached Lab/OKLAB indexes, better separation in blues.
+> **Note on x11's default (ΔE76):** x11 has 658 entries, many of them saturated blue/purple ramps where ΔE76 is a known weak spot. The default optimizes for UI scrubbing speed (~5 µs vs ~90 µs for ΔE2000). If perceptual accuracy matters more than latency, override per call with `{ metric: 'deltaEok' }` for better separation in the blue and purple region.
 
 ```ts
 // Defaults: read from the palette's own `defaultMetric`.
@@ -443,6 +449,20 @@ const tryConvert = (input: ColorInput, opts = {}) => {
 - BYO palettes have zero library cost beyond your own data.
 - Subpath exports (`chromonym/web`, `chromonym/x11`, `chromonym/pantone`, `chromonym/conversions/hex`, `chromonym/math/deltaE`, etc.) let you import a single palette or converter without going through the root barrel.
 
+### What you actually ship
+
+The published tarball is **~557 kB gzipped / ~2.5 MB unpacked** because it carries twelve palettes and ~9000 named-color entries. That's the number `packagephobia` reports — it measures the install footprint on disk. Your **bundle** pays only for what you actually import, measured with `esbuild --minify`:
+
+| Import | min | gzip |
+|---|---|---|
+| `import { identify, web } from 'chromonym'` | 10.9 kB | **4.7 kB** |
+| `import { identify, pantone } from 'chromonym'` | 27 kB | **11.3 kB** |
+| `import { identify, ntc } from 'chromonym'` (one of the bigger palettes) | 43 kB | **20 kB** |
+| `import { defineColorPalette } from 'chromonym'` (pure BYO; no built-in) | 3.8 kB | **1.5 kB** |
+| `import { pantoneToRgba } from 'chromonym'` (single conversion) | 17.5 kB | **6.8 kB** |
+
+The install-size number is a shipping concern, not a bundle-size one. If you're evaluating chromonym against a size budget, the gzip column above is what actually lands in your production build.
+
 ## Types
 
 Re-exported from the root barrel — `import type { ... } from 'chromonym'`:
@@ -466,17 +486,6 @@ bun test
 bun run build
 ```
 
-Regenerating palette data:
-
-```sh
-bun run scripts/generate-x11.ts        # reads /usr/share/X11/rgb.txt
-bun run scripts/generate-pantone.ts    # reads the color_library npm package (MIT © Radu Dragan)
-```
-
-## Coverage
-
-[![Coverage sunburst](https://codecov.io/github/simiancraft/chromonym/graphs/sunburst.svg?token=HYWM6G66YE)](https://codecov.io/github/simiancraft/chromonym)
-
 ## See also
 
 chromonym deliberately limits its scope to color *naming* (resolving and identifying) and lightweight conversions. For other color-related work, reach for tools that do those things well:
@@ -491,8 +500,4 @@ MIT © [the-simian](https://github.com/the-simian)
 
 <p align="center"><sub>Crafted with care by <a href="https://simiancraft.com">Simiancraft</a>.</sub></p>
 
----
-
-> ### Pantone® trademark notice
->
-> **Pantone®** is a registered trademark of **Pantone LLC**. Chromonym is **not affiliated with, endorsed by, or certified by Pantone LLC**. The `pantone` palette ships **community-derived sRGB approximations** of the Pantone Coated (C) set. Values will **not** match a licensed Pantone reference exactly and are unsuitable for print color specification. See [`NOTICE.md`](./NOTICE.md) for full text.
+<p align="center"><sub>Pantone® and Crayola® are trademarks of their respective owners; Chromonym is not affiliated. Palette values are community approximations. Demo typeface <a href="https://www.dafont.com/bauhaus-modern.font">Bauhaus Modern</a> © Nils Kähler. Full attributions: <a href="./NOTICE.md">NOTICE.md</a>.</sub></p>

package/dist/convert.d.ts

@@ -1,29 +1,34 @@
 import { type DetectedFormat } from './detectFormat.js';
-import type { ColorFormat, ColorInput, ColorValue, Palette, Rgba } from './types.js';
+import type { ColorFormat, ColorInput, ColorValue, Palette, PaletteKey, Rgba } from './types.js';
 /**
  * Normalize any recognized color input to canonical `Rgba`.
  * Pass `knownFormat` when the caller has already run `detectFormat` to skip
  * the redundant detection. Throws on `UNKNOWN` input.
  *
- * Palette names (Pantone codes, BYO keys) are not accepted here — they
+ * Palette names (Pantone codes, BYO keys) are not accepted here; they
  * require palette data to parse. Use `convert(name, { palette })` or
  * `resolve(name, { palette })` at the higher level.
+ *
+ * @example
+ * toRgba('#ff0000');               // { r: 255, g: 0, b: 0, a: 1 }
+ * toRgba('rgb(255, 0, 0)');        // { r: 255, g: 0, b: 0, a: 1 }
+ * toRgba([255, 0, 0]);             // { r: 255, g: 0, b: 0, a: 1 }
+ * toRgba({ h: 0, s: 100, l: 50 }); // { r: 255, g: 0, b: 0, a: 1 }
  */
 export declare function toRgba(input: ColorInput, knownFormat?: DetectedFormat): Rgba;
 /**
  * Emit a canonical `Rgba` in the target structural format. Palette-independent.
  *
  * For palette-key output (e.g. nearest Pantone code, brand name), use
- * `convert(rgba, { format: 'NAME', palette })` — or `identify` for fuzzy,
+ * `convert(rgba, { format: 'NAME', palette })`; or `identify` for fuzzy,
  * `rgbaToPantone` for the low-level Pantone-only path.
+ *
+ * @example
+ * fromRgba({ r: 255, g: 0, b: 0, a: 1 });          // '#ff0000'
+ * fromRgba({ r: 255, g: 0, b: 0, a: 1 }, 'HSL');   // 'hsl(0, 100%, 50%)'
+ * fromRgba({ r: 255, g: 0, b: 0, a: 0.5 }, 'RGB'); // 'rgb(255, 0, 0)' (alpha dropped)
  */
 export declare function fromRgba(rgba: Rgba, format?: ColorFormat): ColorValue;
-/**
- * Extract string keys from a Palette's `colors` map.
- * Matches the `PaletteKey<P>` helper in `identify.ts` — kept local so
- * `convert` doesn't depend on `identify`.
- */
-type PaletteKey<P extends Palette> = Extract<keyof P['colors'], string>;
 /**
  * Detect the input color format, normalize to Rgba, and emit the result
  * in the requested output format.
@@ -46,16 +51,63 @@ type PaletteKey<P extends Palette> = Extract<keyof P['colors'], string>;
  * Throws on unrecognized input (parser-flavored — `identify`/`resolve`
  * are the `null`-returning alternatives).
  */
-export declare function convert(input: ColorInput, opts?: {
-    format?: ColorFormat;
-}): ColorValue;
-export declare function convert<P extends Palette>(input: ColorInput | string, opts: {
-    palette: P;
-    format: 'NAME';
-}): PaletteKey<P>;
-export declare function convert<P extends Palette>(input: ColorInput | string, opts: {
-    palette: P;
-    format?: ColorFormat;
-}): ColorValue;
-export {};
+/**
+ * Options for the structural (palette-free) variant of {@link convert}.
+ * Use when you only need to translate between HEX / RGB / RGBA / HSL / HSV.
+ *
+ * @example
+ * convert('#ff0000', { format: 'HSL' }); // 'hsl(0, 100%, 50%)'
+ */
+export type ConvertStructuralOptions = {
+    /**
+     * Target output format. Defaults to `'HEX'`.
+     */
+    readonly format?: ColorFormat;
+};
+/**
+ * Options for {@link convert} when reverse-looking-up a palette name
+ * from an exact color value. Generic so the return narrows to the
+ * palette's literal-key union.
+ *
+ * Throws at runtime if the input isn't a pixel-exact match in the
+ * palette; use `identify` for nearest-match semantics.
+ *
+ * @example
+ * convert('#e4002b', { palette: pantone, format: 'NAME' }); // '185 C'
+ * convert('#663399', { palette: web,     format: 'NAME' }); // 'rebeccapurple'
+ */
+export type ConvertNameOptions<P extends Palette> = {
+    /**
+     * Palette to reverse-look-up against. Required when `format` is `'NAME'`.
+     */
+    readonly palette: P;
+    /**
+     * Output discriminator. `'NAME'` returns the palette's canonical key
+     * for the input color.
+     */
+    readonly format: 'NAME';
+};
+/**
+ * Options for {@link convert} when a palette is provided but the output
+ * is a structural format (HEX / RGB / HSL / HSV). Unlocks palette-name
+ * *input*: the `input` may be `'185 C'`, `'Acme Red'`, etc., which is
+ * resolved through `palette.normalize` before conversion.
+ *
+ * @example
+ * convert('185 C', { palette: pantone });                // '#e4002b'
+ * convert('185 C', { palette: pantone, format: 'HSL' }); // 'hsl(349, 100%, 45%)'
+ */
+export type ConvertPaletteOptions<P extends Palette> = {
+    /**
+     * Palette used to parse name-shaped inputs.
+     */
+    readonly palette: P;
+    /**
+     * Target output format. Defaults to `'HEX'`.
+     */
+    readonly format?: ColorFormat;
+};
+export declare function convert(input: ColorInput, opts?: ConvertStructuralOptions): ColorValue;
+export declare function convert<P extends Palette>(input: ColorInput | string, opts: ConvertNameOptions<P>): PaletteKey<P>;
+export declare function convert<P extends Palette>(input: ColorInput | string, opts: ConvertPaletteOptions<P>): ColorValue;
 //# sourceMappingURL=convert.d.ts.map

package/dist/convert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,cAAc,EAAgB,MAAM,mBAAmB,CAAC;AAEtE,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,UAAU,EAIV,OAAO,EACP,IAAI,EAGL,MAAM,YAAY,CAAC;AAYpB;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,cAAc,GAAG,IAAI,CAgB5E;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,GAAE,WAAmB,GAAG,UAAU,CAqB5E;AAED;;;;GAIG;AACH,KAAK,UAAU,CAAC,CAAC,SAAS,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAAG,UAAU,CAAC;AAGxF,wBAAgB,OAAO,CAAC,CAAC,SAAS,OAAO,EACvC,KAAK,EAAE,UAAU,GAAG,MAAM,EAC1B,IAAI,EAAE;IAAE,OAAO,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC,UAAU,CAAC,CAAC,CAAC,CAAC;AAGjB,wBAAgB,OAAO,CAAC,CAAC,SAAS,OAAO,EACvC,KAAK,EAAE,UAAU,GAAG,MAAM,EAC1B,IAAI,EAAE;IAAE,OAAO,EAAE,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GACzC,UAAU,CAAC","sourcesContent":["import { hexToRgba, rgbaToHex } from './conversions/hex.js';\nimport { hslToRgba, rgbaToHsl } from './conversions/hsl.js';\nimport { hsvToRgba, rgbaToHsv } from './conversions/hsv.js';\nimport { rgbaToRgb, rgbToRgba } from './conversions/rgb.js';\nimport { type DetectedFormat, detectFormat } from './detectFormat.js';\nimport { getNameIndex, getReverseNameIndex } from './indexing.js';\nimport type {\n  ColorFormat,\n  ColorInput,\n  ColorValue,\n  HexColor,\n  HslInput,\n  HsvInput,\n  Palette,\n  Rgba,\n  RgbaInput,\n  RgbInput,\n} from './types.js';\n\nfunction safeStringify(x: unknown): string {\n  if (x === undefined) return 'undefined';\n  try {\n    const s = JSON.stringify(x);\n    return s === undefined ? String(x) : s;\n  } catch {\n    return Object.prototype.toString.call(x);\n  }\n}\n\n/**\n * Normalize any recognized color input to canonical `Rgba`.\n * Pass `knownFormat` when the caller has already run `detectFormat` to skip\n * the redundant detection. Throws on `UNKNOWN` input.\n *\n * Palette names (Pantone codes, BYO keys) are not accepted here — they\n * require palette data to parse. Use `convert(name, { palette })` or\n * `resolve(name, { palette })` at the higher level.\n */\nexport function toRgba(input: ColorInput, knownFormat?: DetectedFormat): Rgba {\n  const format = knownFormat ?? detectFormat(input);\n  switch (format) {\n    case 'HEX':\n      return hexToRgba(input as HexColor);\n    case 'RGB':\n      return rgbToRgba(input as RgbInput);\n    case 'RGBA':\n      return rgbToRgba(input as RgbaInput);\n    case 'HSL':\n      return hslToRgba(input as HslInput);\n    case 'HSV':\n      return hsvToRgba(input as HsvInput);\n    default:\n      throw new Error(`Unrecognized color input: ${safeStringify(input)}`);\n  }\n}\n\n/**\n * Emit a canonical `Rgba` in the target structural format. Palette-independent.\n *\n * For palette-key output (e.g. nearest Pantone code, brand name), use\n * `convert(rgba, { format: 'NAME', palette })` — or `identify` for fuzzy,\n * `rgbaToPantone` for the low-level Pantone-only path.\n */\nexport function fromRgba(rgba: Rgba, format: ColorFormat = 'HEX'): ColorValue {\n  switch (format) {\n    case 'HEX':\n      return rgbaToHex(rgba);\n    case 'RGB':\n      return rgbaToRgb(rgba);\n    case 'RGBA':\n      return rgba;\n    case 'HSL':\n      return rgbaToHsl(rgba);\n    case 'HSV':\n      return rgbaToHsv(rgba);\n    default: {\n      // Runtime safety for JS callers bypassing the ColorFormat union.\n      const hint =\n        format === ('PANTONE' as unknown)\n          ? ` — use convert(rgba, { palette: pantone, format: 'NAME' }) or rgbaToPantone from 'chromonym/conversions/pantone'`\n          : '';\n      throw new Error(`Unsupported format: ${safeStringify(format)}${hint}`);\n    }\n  }\n}\n\n/**\n * Extract string keys from a Palette's `colors` map.\n * Matches the `PaletteKey<P>` helper in `identify.ts` — kept local so\n * `convert` doesn't depend on `identify`.\n */\ntype PaletteKey<P extends Palette> = Extract<keyof P['colors'], string>;\n\n/**\n * Detect the input color format, normalize to Rgba, and emit the result\n * in the requested output format.\n *\n * Without a `palette` option, `convert` is strictly structural —\n * HEX ↔ RGB ↔ RGBA ↔ HSL ↔ HSV, no palette data ever touched, tree-shakes\n * to the bone.\n *\n * With a `palette` option, `convert` understands the palette's naming\n * scheme both ways:\n * - Input can be a palette name (`'185 C'`, `'Acme Red'`) — parsed via\n *   `palette.normalize` and looked up in `palette.colors`.\n * - Output can be `format: 'NAME'` — the exact canonical key from\n *   `palette.colors`, throws if the color isn't a pixel-exact match (use\n *   `identify` for nearest-match).\n *\n * The palette data comes from the caller's own import, so tree-shaking\n * is preserved: callers who don't pass `palette` never pull a palette.\n *\n * Throws on unrecognized input (parser-flavored — `identify`/`resolve`\n * are the `null`-returning alternatives).\n */\n\n// Overload 1: no palette — structural only. Input is strictly ColorInput.\nexport function convert(input: ColorInput, opts?: { format?: ColorFormat }): ColorValue;\n\n// Overload 2: palette present, format 'NAME' — returns a palette key.\nexport function convert<P extends Palette>(\n  input: ColorInput | string,\n  opts: { palette: P; format: 'NAME' },\n): PaletteKey<P>;\n\n// Overload 3: palette present, structural format — returns ColorValue.\nexport function convert<P extends Palette>(\n  input: ColorInput | string,\n  opts: { palette: P; format?: ColorFormat },\n): ColorValue;\n\n// Implementation\nexport function convert(\n  input: ColorInput | string,\n  opts: { format?: ColorFormat | 'NAME'; palette?: Palette } = {},\n): ColorValue | string {\n  const { format = 'HEX', palette } = opts;\n\n  // --- Parse input → Rgba ---\n  // Structural detection first; palette lookup only as a fallback. This\n  // way `convert('#ff0000', { palette: brand })` always means \"parse hex,\"\n  // even if the brand palette happens to have a key that normalizes to\n  // \"ff0000\".\n  const detected = detectFormat(input as ColorInput);\n  let rgba: Rgba;\n  if (detected !== 'UNKNOWN') {\n    rgba = toRgba(input as ColorInput, detected);\n  } else if (palette !== undefined && typeof input === 'string') {\n    const canonical = getNameIndex(palette).get(palette.normalize(input));\n    if (canonical === undefined) {\n      throw new Error(\n        `Unrecognized color input: ${safeStringify(input)} (not structural, and not found in palette '${palette.name}')`,\n      );\n    }\n    const hex = (palette.colors as Record<string, HexColor>)[canonical];\n    if (hex === undefined) {\n      throw new Error(`Unrecognized color input: ${safeStringify(input)}`);\n    }\n    rgba = hexToRgba(hex);\n  } else {\n    throw new Error(`Unrecognized color input: ${safeStringify(input)}`);\n  }\n\n  // --- Emit ---\n  if (format === 'NAME') {\n    if (palette === undefined) {\n      throw new Error(`convert(_, { format: 'NAME' }) requires a 'palette' option`);\n    }\n    // Palette colors are alpha = 1 by construction; a partially-transparent\n    // input isn't \"that named color\" in the strict-convert sense. Reject\n    // here rather than silently drop alpha during the reverse lookup.\n    if (rgba.a !== 1) {\n      throw new Error(\n        `format: 'NAME' requires fully-opaque input (a === 1). Got a=${rgba.a}. ` +\n          `Strip alpha first or use identify() for fuzzy matching.`,\n      );\n    }\n    const hex = rgbaToHex(rgba).toLowerCase();\n    const name = getReverseNameIndex(palette).get(hex);\n    if (name === undefined) {\n      throw new Error(\n        `No exact match for ${hex} in palette '${palette.name}'. Use identify() for nearest-match semantics.`,\n      );\n    }\n    return name;\n  }\n  return fromRgba(rgba, format);\n}\n"]}
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,cAAc,EAAgB,MAAM,mBAAmB,CAAC;AAEtE,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,UAAU,EAIV,OAAO,EACP,UAAU,EACV,IAAI,EAGL,MAAM,YAAY,CAAC;AAYpB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,cAAc,GAAG,IAAI,CAgB5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,GAAE,WAAmB,GAAG,UAAU,CAqB5E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,OAAO,IAAI;IAClD;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,OAAO,IAAI;IACrD;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B,CAAC;AAGF,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,wBAAwB,GAAG,UAAU,CAAC;AAGxF,wBAAgB,OAAO,CAAC,CAAC,SAAS,OAAO,EACvC,KAAK,EAAE,UAAU,GAAG,MAAM,EAC1B,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC1B,UAAU,CAAC,CAAC,CAAC,CAAC;AAGjB,wBAAgB,OAAO,CAAC,CAAC,SAAS,OAAO,EACvC,KAAK,EAAE,UAAU,GAAG,MAAM,EAC1B,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC7B,UAAU,CAAC","sourcesContent":["import { hexToRgba, rgbaToHex } from './conversions/hex.js';\nimport { hslToRgba, rgbaToHsl } from './conversions/hsl.js';\nimport { hsvToRgba, rgbaToHsv } from './conversions/hsv.js';\nimport { rgbaToRgb, rgbToRgba } from './conversions/rgb.js';\nimport { type DetectedFormat, detectFormat } from './detectFormat.js';\nimport { getNameIndex, getReverseNameIndex } from './indexing.js';\nimport type {\n  ColorFormat,\n  ColorInput,\n  ColorValue,\n  HexColor,\n  HslInput,\n  HsvInput,\n  Palette,\n  PaletteKey,\n  Rgba,\n  RgbaInput,\n  RgbInput,\n} from './types.js';\n\nfunction safeStringify(x: unknown): string {\n  if (x === undefined) return 'undefined';\n  try {\n    const s = JSON.stringify(x);\n    return s === undefined ? String(x) : s;\n  } catch {\n    return Object.prototype.toString.call(x);\n  }\n}\n\n/**\n * Normalize any recognized color input to canonical `Rgba`.\n * Pass `knownFormat` when the caller has already run `detectFormat` to skip\n * the redundant detection. Throws on `UNKNOWN` input.\n *\n * Palette names (Pantone codes, BYO keys) are not accepted here; they\n * require palette data to parse. Use `convert(name, { palette })` or\n * `resolve(name, { palette })` at the higher level.\n *\n * @example\n * toRgba('#ff0000');               // { r: 255, g: 0, b: 0, a: 1 }\n * toRgba('rgb(255, 0, 0)');        // { r: 255, g: 0, b: 0, a: 1 }\n * toRgba([255, 0, 0]);             // { r: 255, g: 0, b: 0, a: 1 }\n * toRgba({ h: 0, s: 100, l: 50 }); // { r: 255, g: 0, b: 0, a: 1 }\n */\nexport function toRgba(input: ColorInput, knownFormat?: DetectedFormat): Rgba {\n  const format = knownFormat ?? detectFormat(input);\n  switch (format) {\n    case 'HEX':\n      return hexToRgba(input as HexColor);\n    case 'RGB':\n      return rgbToRgba(input as RgbInput);\n    case 'RGBA':\n      return rgbToRgba(input as RgbaInput);\n    case 'HSL':\n      return hslToRgba(input as HslInput);\n    case 'HSV':\n      return hsvToRgba(input as HsvInput);\n    default:\n      throw new Error(`Unrecognized color input: ${safeStringify(input)}`);\n  }\n}\n\n/**\n * Emit a canonical `Rgba` in the target structural format. Palette-independent.\n *\n * For palette-key output (e.g. nearest Pantone code, brand name), use\n * `convert(rgba, { format: 'NAME', palette })`; or `identify` for fuzzy,\n * `rgbaToPantone` for the low-level Pantone-only path.\n *\n * @example\n * fromRgba({ r: 255, g: 0, b: 0, a: 1 });          // '#ff0000'\n * fromRgba({ r: 255, g: 0, b: 0, a: 1 }, 'HSL');   // 'hsl(0, 100%, 50%)'\n * fromRgba({ r: 255, g: 0, b: 0, a: 0.5 }, 'RGB'); // 'rgb(255, 0, 0)' (alpha dropped)\n */\nexport function fromRgba(rgba: Rgba, format: ColorFormat = 'HEX'): ColorValue {\n  switch (format) {\n    case 'HEX':\n      return rgbaToHex(rgba);\n    case 'RGB':\n      return rgbaToRgb(rgba);\n    case 'RGBA':\n      return rgba;\n    case 'HSL':\n      return rgbaToHsl(rgba);\n    case 'HSV':\n      return rgbaToHsv(rgba);\n    default: {\n      // Runtime safety for JS callers bypassing the ColorFormat union.\n      const hint =\n        format === ('PANTONE' as unknown)\n          ? ` — use convert(rgba, { palette: pantone, format: 'NAME' }) or rgbaToPantone from 'chromonym/conversions/pantone'`\n          : '';\n      throw new Error(`Unsupported format: ${safeStringify(format)}${hint}`);\n    }\n  }\n}\n\n/**\n * Detect the input color format, normalize to Rgba, and emit the result\n * in the requested output format.\n *\n * Without a `palette` option, `convert` is strictly structural —\n * HEX ↔ RGB ↔ RGBA ↔ HSL ↔ HSV, no palette data ever touched, tree-shakes\n * to the bone.\n *\n * With a `palette` option, `convert` understands the palette's naming\n * scheme both ways:\n * - Input can be a palette name (`'185 C'`, `'Acme Red'`) — parsed via\n *   `palette.normalize` and looked up in `palette.colors`.\n * - Output can be `format: 'NAME'` — the exact canonical key from\n *   `palette.colors`, throws if the color isn't a pixel-exact match (use\n *   `identify` for nearest-match).\n *\n * The palette data comes from the caller's own import, so tree-shaking\n * is preserved: callers who don't pass `palette` never pull a palette.\n *\n * Throws on unrecognized input (parser-flavored — `identify`/`resolve`\n * are the `null`-returning alternatives).\n */\n\n/**\n * Options for the structural (palette-free) variant of {@link convert}.\n * Use when you only need to translate between HEX / RGB / RGBA / HSL / HSV.\n *\n * @example\n * convert('#ff0000', { format: 'HSL' }); // 'hsl(0, 100%, 50%)'\n */\nexport type ConvertStructuralOptions = {\n  /**\n   * Target output format. Defaults to `'HEX'`.\n   */\n  readonly format?: ColorFormat;\n};\n\n/**\n * Options for {@link convert} when reverse-looking-up a palette name\n * from an exact color value. Generic so the return narrows to the\n * palette's literal-key union.\n *\n * Throws at runtime if the input isn't a pixel-exact match in the\n * palette; use `identify` for nearest-match semantics.\n *\n * @example\n * convert('#e4002b', { palette: pantone, format: 'NAME' }); // '185 C'\n * convert('#663399', { palette: web,     format: 'NAME' }); // 'rebeccapurple'\n */\nexport type ConvertNameOptions<P extends Palette> = {\n  /**\n   * Palette to reverse-look-up against. Required when `format` is `'NAME'`.\n   */\n  readonly palette: P;\n  /**\n   * Output discriminator. `'NAME'` returns the palette's canonical key\n   * for the input color.\n   */\n  readonly format: 'NAME';\n};\n\n/**\n * Options for {@link convert} when a palette is provided but the output\n * is a structural format (HEX / RGB / HSL / HSV). Unlocks palette-name\n * *input*: the `input` may be `'185 C'`, `'Acme Red'`, etc., which is\n * resolved through `palette.normalize` before conversion.\n *\n * @example\n * convert('185 C', { palette: pantone });                // '#e4002b'\n * convert('185 C', { palette: pantone, format: 'HSL' }); // 'hsl(349, 100%, 45%)'\n */\nexport type ConvertPaletteOptions<P extends Palette> = {\n  /**\n   * Palette used to parse name-shaped inputs.\n   */\n  readonly palette: P;\n  /**\n   * Target output format. Defaults to `'HEX'`.\n   */\n  readonly format?: ColorFormat;\n};\n\n// Overload 1: no palette — structural only. Input is strictly ColorInput.\nexport function convert(input: ColorInput, opts?: ConvertStructuralOptions): ColorValue;\n\n// Overload 2: palette present, format 'NAME' — returns a palette key.\nexport function convert<P extends Palette>(\n  input: ColorInput | string,\n  opts: ConvertNameOptions<P>,\n): PaletteKey<P>;\n\n// Overload 3: palette present, structural format — returns ColorValue.\nexport function convert<P extends Palette>(\n  input: ColorInput | string,\n  opts: ConvertPaletteOptions<P>,\n): ColorValue;\n\n// Implementation\nexport function convert(\n  input: ColorInput | string,\n  opts: { format?: ColorFormat | 'NAME'; palette?: Palette } = {},\n): ColorValue | string {\n  const { format = 'HEX', palette } = opts;\n\n  // --- Parse input → Rgba ---\n  // Structural detection first; palette lookup only as a fallback. This\n  // way `convert('#ff0000', { palette: brand })` always means \"parse hex,\"\n  // even if the brand palette happens to have a key that normalizes to\n  // \"ff0000\".\n  const detected = detectFormat(input as ColorInput);\n  let rgba: Rgba;\n  if (detected !== 'UNKNOWN') {\n    rgba = toRgba(input as ColorInput, detected);\n  } else if (palette !== undefined && typeof input === 'string') {\n    const canonical = getNameIndex(palette).get(palette.normalize(input));\n    if (canonical === undefined) {\n      throw new Error(\n        `Unrecognized color input: ${safeStringify(input)} (not structural, and not found in palette '${palette.name}')`,\n      );\n    }\n    const hex = (palette.colors as Record<string, HexColor>)[canonical];\n    if (hex === undefined) {\n      throw new Error(`Unrecognized color input: ${safeStringify(input)}`);\n    }\n    rgba = hexToRgba(hex);\n  } else {\n    throw new Error(`Unrecognized color input: ${safeStringify(input)}`);\n  }\n\n  // --- Emit ---\n  if (format === 'NAME') {\n    if (palette === undefined) {\n      throw new Error(`convert(_, { format: 'NAME' }) requires a 'palette' option`);\n    }\n    // Palette colors are alpha = 1 by construction; a partially-transparent\n    // input isn't \"that named color\" in the strict-convert sense. Reject\n    // here rather than silently drop alpha during the reverse lookup.\n    if (rgba.a !== 1) {\n      throw new Error(\n        `format: 'NAME' requires fully-opaque input (a === 1). Got a=${rgba.a}. ` +\n          `Strip alpha first or use identify() for fuzzy matching.`,\n      );\n    }\n    const hex = rgbaToHex(rgba).toLowerCase();\n    const name = getReverseNameIndex(palette).get(hex);\n    if (name === undefined) {\n      throw new Error(\n        `No exact match for ${hex} in palette '${palette.name}'. Use identify() for nearest-match semantics.`,\n      );\n    }\n    return name;\n  }\n  return fromRgba(rgba, format);\n}\n"]}

package/dist/convert.js

@@ -20,9 +20,15 @@ function safeStringify(x) {
  * Pass `knownFormat` when the caller has already run `detectFormat` to skip
  * the redundant detection. Throws on `UNKNOWN` input.
  *
- * Palette names (Pantone codes, BYO keys) are not accepted here — they
+ * Palette names (Pantone codes, BYO keys) are not accepted here; they
  * require palette data to parse. Use `convert(name, { palette })` or
  * `resolve(name, { palette })` at the higher level.
+ *
+ * @example
+ * toRgba('#ff0000');               // { r: 255, g: 0, b: 0, a: 1 }
+ * toRgba('rgb(255, 0, 0)');        // { r: 255, g: 0, b: 0, a: 1 }
+ * toRgba([255, 0, 0]);             // { r: 255, g: 0, b: 0, a: 1 }
+ * toRgba({ h: 0, s: 100, l: 50 }); // { r: 255, g: 0, b: 0, a: 1 }
  */
 export function toRgba(input, knownFormat) {
     const format = knownFormat ?? detectFormat(input);
@@ -45,8 +51,13 @@ export function toRgba(input, knownFormat) {
  * Emit a canonical `Rgba` in the target structural format. Palette-independent.
  *
  * For palette-key output (e.g. nearest Pantone code, brand name), use
- * `convert(rgba, { format: 'NAME', palette })` — or `identify` for fuzzy,
+ * `convert(rgba, { format: 'NAME', palette })`; or `identify` for fuzzy,
  * `rgbaToPantone` for the low-level Pantone-only path.
+ *
+ * @example
+ * fromRgba({ r: 255, g: 0, b: 0, a: 1 });          // '#ff0000'
+ * fromRgba({ r: 255, g: 0, b: 0, a: 1 }, 'HSL');   // 'hsl(0, 100%, 50%)'
+ * fromRgba({ r: 255, g: 0, b: 0, a: 0.5 }, 'RGB'); // 'rgb(255, 0, 0)' (alpha dropped)
  */
 export function fromRgba(rgba, format = 'HEX') {
     switch (format) {