chromonym 3.1.1 → 3.3.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

@@ -14,13 +14,18 @@
 [![Types: included](https://img.shields.io/npm/types/chromonym?color=3178c6&logo=typescript)](https://www.npmjs.com/package/chromonym)
 [![CI](https://github.com/simiancraft/chromonym/actions/workflows/ci.yml/badge.svg)](https://github.com/simiancraft/chromonym/actions/workflows/ci.yml)
 [![Coverage](https://img.shields.io/codecov/c/github/simiancraft/chromonym?logo=codecov)](https://codecov.io/github/simiancraft/chromonym)
-[![Bundle size](https://img.shields.io/bundlephobia/minzip/chromonym?label=bundle%20size)](https://bundlephobia.com/package/chromonym)
+[![Bundle size](https://img.shields.io/badge/bundle-1.5--20%20kB%20gz-informational)](#what-you-actually-ship)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/simiancraft/chromonym/badge)](https://securityscorecards.dev/viewer/?uri=github.com/simiancraft/chromonym)
 
 <p align="center">
   <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 +85,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 +266,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 +292,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 +328,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 +389,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 +450,22 @@ 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
+
+**Install size and bundle size are not the same number.** Install size is what lands in your `node_modules/` after `npm install`; bundle size is what ships to your users after tree-shaking, minification, and gzip. For chromonym the gap is roughly two orders of magnitude.
+
+The published tarball is **~2.5 MB unpacked / ~557 kB gzipped** because it carries twelve palettes and ~9000 named-color entries; that's the install-size figure `packagephobia` reports. Your **production bundle** pays only for what you actually import, measured with `esbuild --minify`:
+
+| Import | min | gzip |
+|---|---|---|
+| `import { defineColorPalette } from 'chromonym'` (pure BYO; no built-in) | 3.8 kB | **1.5 kB** |
+| `import { identify, web } from 'chromonym'` | 10.9 kB | **4.7 kB** |
+| `import { pantoneToRgba } from 'chromonym'` (single conversion) | 17.5 kB | **6.8 kB** |
+| `import { identify, pantone } from 'chromonym'` | 27 kB | **11.3 kB** |
+| `import { identify, ntc } from 'chromonym'` | 43 kB | **20 kB** |
+
+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 +489,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 +503,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/conversions/rgb.d.ts

@@ -3,7 +3,13 @@ import type { Rgba, RgbaInput, RgbInput, RgbString } from '../types.js';
  * Normalize any RGB/RGBA input shape (string, tuple, or object) into
  * the canonical Rgba representation. Alpha defaults to 1 when absent.
  * Rejects non-finite numeric inputs; clamps r/g/b to [0,255] and a to [0,1].
- * Throws on malformed strings.
+ * Throws on malformed strings. String parsing is linear-time; no polynomial
+ * backtracking on pathological input. Leading-dot alpha (e.g. `.5`) is
+ * accepted per the CSS Color spec.
+ *
+ * @example
+ * rgbToRgba('rgba(255, 0, 0, .5)');
+ * // => { r: 255, g: 0, b: 0, a: 0.5 }
  */
 export declare function rgbToRgba(input: RgbInput | RgbaInput): Rgba;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"rgb.d.ts","sourceRoot":"","sources":["../../src/conversions/rgb.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAa,SAAS,EAAE,MAAM,aAAa,CAAC;AAanF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI,CA+B3D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAK/C","sourcesContent":["import { clamp, requireFinite } from '../math/clamp.js';\nimport type { Rgba, RgbaInput, RgbInput, RgbObject, RgbString } from '../types.js';\n\nconst RGB_RE =\n  /^rgba?\\s*\\(\\s*(-?\\d+(?:\\.\\d+)?)\\s*,\\s*(-?\\d+(?:\\.\\d+)?)\\s*,\\s*(-?\\d+(?:\\.\\d+)?)\\s*(?:,\\s*(\\d*\\.?\\d+)\\s*)?\\)$/i;\n\nfunction sanitizeChannel(n: unknown, label: string): number {\n  return clamp(requireFinite(n, label), 0, 255);\n}\n\nfunction sanitizeAlpha(n: unknown): number {\n  return clamp(requireFinite(n, 'alpha'), 0, 1);\n}\n\n/**\n * Normalize any RGB/RGBA input shape (string, tuple, or object) into\n * the canonical Rgba representation. Alpha defaults to 1 when absent.\n * Rejects non-finite numeric inputs; clamps r/g/b to [0,255] and a to [0,1].\n * Throws on malformed strings.\n */\nexport function rgbToRgba(input: RgbInput | RgbaInput): Rgba {\n  if (Array.isArray(input)) {\n    const rawA = input.length === 4 ? input[3] : 1;\n    return {\n      r: sanitizeChannel(input[0], 'r'),\n      g: sanitizeChannel(input[1], 'g'),\n      b: sanitizeChannel(input[2], 'b'),\n      a: sanitizeAlpha(rawA),\n    };\n  }\n\n  if (typeof input === 'string') {\n    const match = RGB_RE.exec(input);\n    if (!match) throw new Error(`Invalid rgb(a) string: ${input}`);\n    return {\n      r: sanitizeChannel(Number(match[1]), 'r'),\n      g: sanitizeChannel(Number(match[2]), 'g'),\n      b: sanitizeChannel(Number(match[3]), 'b'),\n      a: sanitizeAlpha(match[4] !== undefined ? Number(match[4]) : 1),\n    };\n  }\n\n  // Object form — TypeScript's Array.isArray narrowing doesn't exclude\n  // readonly tuple types from the union, so cast after the guards.\n  const obj = input as RgbObject | Rgba;\n  return {\n    r: sanitizeChannel(obj.r, 'r'),\n    g: sanitizeChannel(obj.g, 'g'),\n    b: sanitizeChannel(obj.b, 'b'),\n    a: sanitizeAlpha('a' in obj ? obj.a : 1),\n  };\n}\n\n/**\n * Emit an `rgb(r, g, b)` string. Alpha is dropped; values are\n * already-clamped by rgbToRgba, but we re-clamp defensively for direct\n * Rgba-object callers who bypass the input normalizer.\n */\nexport function rgbaToRgb(rgba: Rgba): RgbString {\n  const r = clamp(Math.round(rgba.r), 0, 255);\n  const g = clamp(Math.round(rgba.g), 0, 255);\n  const b = clamp(Math.round(rgba.b), 0, 255);\n  return `rgb(${r}, ${g}, ${b})` as RgbString;\n}\n"]}
+{"version":3,"file":"rgb.d.ts","sourceRoot":"","sources":["../../src/conversions/rgb.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAa,SAAS,EAAE,MAAM,aAAa,CAAC;AAgBnF;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI,CA+B3D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAK/C","sourcesContent":["import { clamp, requireFinite } from '../math/clamp.js';\nimport type { Rgba, RgbaInput, RgbInput, RgbObject, RgbString } from '../types.js';\n\n// Alpha group split into two unambiguous alternatives to avoid polynomial\n// backtracking (CodeQL js/polynomial-redos) on malformed inputs like\n// `rgb(9,9,9,99...9`.\nconst RGB_RE =\n  /^rgba?\\s*\\(\\s*(-?\\d+(?:\\.\\d+)?)\\s*,\\s*(-?\\d+(?:\\.\\d+)?)\\s*,\\s*(-?\\d+(?:\\.\\d+)?)\\s*(?:,\\s*(\\d+(?:\\.\\d+)?|\\.\\d+)\\s*)?\\)$/i;\n\nfunction sanitizeChannel(n: unknown, label: string): number {\n  return clamp(requireFinite(n, label), 0, 255);\n}\n\nfunction sanitizeAlpha(n: unknown): number {\n  return clamp(requireFinite(n, 'alpha'), 0, 1);\n}\n\n/**\n * Normalize any RGB/RGBA input shape (string, tuple, or object) into\n * the canonical Rgba representation. Alpha defaults to 1 when absent.\n * Rejects non-finite numeric inputs; clamps r/g/b to [0,255] and a to [0,1].\n * Throws on malformed strings. String parsing is linear-time; no polynomial\n * backtracking on pathological input. Leading-dot alpha (e.g. `.5`) is\n * accepted per the CSS Color spec.\n *\n * @example\n * rgbToRgba('rgba(255, 0, 0, .5)');\n * // => { r: 255, g: 0, b: 0, a: 0.5 }\n */\nexport function rgbToRgba(input: RgbInput | RgbaInput): Rgba {\n  if (Array.isArray(input)) {\n    const rawA = input.length === 4 ? input[3] : 1;\n    return {\n      r: sanitizeChannel(input[0], 'r'),\n      g: sanitizeChannel(input[1], 'g'),\n      b: sanitizeChannel(input[2], 'b'),\n      a: sanitizeAlpha(rawA),\n    };\n  }\n\n  if (typeof input === 'string') {\n    const match = RGB_RE.exec(input);\n    if (!match) throw new Error(`Invalid rgb(a) string: ${input}`);\n    return {\n      r: sanitizeChannel(Number(match[1]), 'r'),\n      g: sanitizeChannel(Number(match[2]), 'g'),\n      b: sanitizeChannel(Number(match[3]), 'b'),\n      a: sanitizeAlpha(match[4] !== undefined ? Number(match[4]) : 1),\n    };\n  }\n\n  // Object form — TypeScript's Array.isArray narrowing doesn't exclude\n  // readonly tuple types from the union, so cast after the guards.\n  const obj = input as RgbObject | Rgba;\n  return {\n    r: sanitizeChannel(obj.r, 'r'),\n    g: sanitizeChannel(obj.g, 'g'),\n    b: sanitizeChannel(obj.b, 'b'),\n    a: sanitizeAlpha('a' in obj ? obj.a : 1),\n  };\n}\n\n/**\n * Emit an `rgb(r, g, b)` string. Alpha is dropped; values are\n * already-clamped by rgbToRgba, but we re-clamp defensively for direct\n * Rgba-object callers who bypass the input normalizer.\n */\nexport function rgbaToRgb(rgba: Rgba): RgbString {\n  const r = clamp(Math.round(rgba.r), 0, 255);\n  const g = clamp(Math.round(rgba.g), 0, 255);\n  const b = clamp(Math.round(rgba.b), 0, 255);\n  return `rgb(${r}, ${g}, ${b})` as RgbString;\n}\n"]}

package/dist/conversions/rgb.js

@@ -1,5 +1,8 @@
 import { clamp, requireFinite } from '../math/clamp.js';
-const RGB_RE = /^rgba?\s*\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*(?:,\s*(\d*\.?\d+)\s*)?\)$/i;
+// Alpha group split into two unambiguous alternatives to avoid polynomial
+// backtracking (CodeQL js/polynomial-redos) on malformed inputs like
+// `rgb(9,9,9,99...9`.
+const RGB_RE = /^rgba?\s*\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*(?:,\s*(\d+(?:\.\d+)?|\.\d+)\s*)?\)$/i;
 function sanitizeChannel(n, label) {
     return clamp(requireFinite(n, label), 0, 255);
 }
@@ -10,7 +13,13 @@ function sanitizeAlpha(n) {
  * Normalize any RGB/RGBA input shape (string, tuple, or object) into
  * the canonical Rgba representation. Alpha defaults to 1 when absent.
  * Rejects non-finite numeric inputs; clamps r/g/b to [0,255] and a to [0,1].
- * Throws on malformed strings.
+ * Throws on malformed strings. String parsing is linear-time; no polynomial
+ * backtracking on pathological input. Leading-dot alpha (e.g. `.5`) is
+ * accepted per the CSS Color spec.
+ *
+ * @example
+ * rgbToRgba('rgba(255, 0, 0, .5)');
+ * // => { r: 255, g: 0, b: 0, a: 0.5 }
  */
 export function rgbToRgba(input) {
     if (Array.isArray(input)) {

package/dist/conversions/rgb.js.map

@@ -1 +1 @@
-{"version":3,"file":"rgb.js","sourceRoot":"","sources":["../../src/conversions/rgb.ts"],"names":[],"mappings":"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","sourcesContent":["import { clamp, requireFinite } from '../math/clamp.js';\nimport type { Rgba, RgbaInput, RgbInput, RgbObject, RgbString } from '../types.js';\n\nconst RGB_RE =\n  /^rgba?\\s*\\(\\s*(-?\\d+(?:\\.\\d+)?)\\s*,\\s*(-?\\d+(?:\\.\\d+)?)\\s*,\\s*(-?\\d+(?:\\.\\d+)?)\\s*(?:,\\s*(\\d*\\.?\\d+)\\s*)?\\)$/i;\n\nfunction sanitizeChannel(n: unknown, label: string): number {\n  return clamp(requireFinite(n, label), 0, 255);\n}\n\nfunction sanitizeAlpha(n: unknown): number {\n  return clamp(requireFinite(n, 'alpha'), 0, 1);\n}\n\n/**\n * Normalize any RGB/RGBA input shape (string, tuple, or object) into\n * the canonical Rgba representation. Alpha defaults to 1 when absent.\n * Rejects non-finite numeric inputs; clamps r/g/b to [0,255] and a to [0,1].\n * Throws on malformed strings.\n */\nexport function rgbToRgba(input: RgbInput | RgbaInput): Rgba {\n  if (Array.isArray(input)) {\n    const rawA = input.length === 4 ? input[3] : 1;\n    return {\n      r: sanitizeChannel(input[0], 'r'),\n      g: sanitizeChannel(input[1], 'g'),\n      b: sanitizeChannel(input[2], 'b'),\n      a: sanitizeAlpha(rawA),\n    };\n  }\n\n  if (typeof input === 'string') {\n    const match = RGB_RE.exec(input);\n    if (!match) throw new Error(`Invalid rgb(a) string: ${input}`);\n    return {\n      r: sanitizeChannel(Number(match[1]), 'r'),\n      g: sanitizeChannel(Number(match[2]), 'g'),\n      b: sanitizeChannel(Number(match[3]), 'b'),\n      a: sanitizeAlpha(match[4] !== undefined ? Number(match[4]) : 1),\n    };\n  }\n\n  // Object form — TypeScript's Array.isArray narrowing doesn't exclude\n  // readonly tuple types from the union, so cast after the guards.\n  const obj = input as RgbObject | Rgba;\n  return {\n    r: sanitizeChannel(obj.r, 'r'),\n    g: sanitizeChannel(obj.g, 'g'),\n    b: sanitizeChannel(obj.b, 'b'),\n    a: sanitizeAlpha('a' in obj ? obj.a : 1),\n  };\n}\n\n/**\n * Emit an `rgb(r, g, b)` string. Alpha is dropped; values are\n * already-clamped by rgbToRgba, but we re-clamp defensively for direct\n * Rgba-object callers who bypass the input normalizer.\n */\nexport function rgbaToRgb(rgba: Rgba): RgbString {\n  const r = clamp(Math.round(rgba.r), 0, 255);\n  const g = clamp(Math.round(rgba.g), 0, 255);\n  const b = clamp(Math.round(rgba.b), 0, 255);\n  return `rgb(${r}, ${g}, ${b})` as RgbString;\n}\n"]}
+{"version":3,"file":"rgb.js","sourceRoot":"","sources":["../../src/conversions/rgb.ts"],"names":[],"mappings":"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","sourcesContent":["import { clamp, requireFinite } from '../math/clamp.js';\nimport type { Rgba, RgbaInput, RgbInput, RgbObject, RgbString } from '../types.js';\n\n// Alpha group split into two unambiguous alternatives to avoid polynomial\n// backtracking (CodeQL js/polynomial-redos) on malformed inputs like\n// `rgb(9,9,9,99...9`.\nconst RGB_RE =\n  /^rgba?\\s*\\(\\s*(-?\\d+(?:\\.\\d+)?)\\s*,\\s*(-?\\d+(?:\\.\\d+)?)\\s*,\\s*(-?\\d+(?:\\.\\d+)?)\\s*(?:,\\s*(\\d+(?:\\.\\d+)?|\\.\\d+)\\s*)?\\)$/i;\n\nfunction sanitizeChannel(n: unknown, label: string): number {\n  return clamp(requireFinite(n, label), 0, 255);\n}\n\nfunction sanitizeAlpha(n: unknown): number {\n  return clamp(requireFinite(n, 'alpha'), 0, 1);\n}\n\n/**\n * Normalize any RGB/RGBA input shape (string, tuple, or object) into\n * the canonical Rgba representation. Alpha defaults to 1 when absent.\n * Rejects non-finite numeric inputs; clamps r/g/b to [0,255] and a to [0,1].\n * Throws on malformed strings. String parsing is linear-time; no polynomial\n * backtracking on pathological input. Leading-dot alpha (e.g. `.5`) is\n * accepted per the CSS Color spec.\n *\n * @example\n * rgbToRgba('rgba(255, 0, 0, .5)');\n * // => { r: 255, g: 0, b: 0, a: 0.5 }\n */\nexport function rgbToRgba(input: RgbInput | RgbaInput): Rgba {\n  if (Array.isArray(input)) {\n    const rawA = input.length === 4 ? input[3] : 1;\n    return {\n      r: sanitizeChannel(input[0], 'r'),\n      g: sanitizeChannel(input[1], 'g'),\n      b: sanitizeChannel(input[2], 'b'),\n      a: sanitizeAlpha(rawA),\n    };\n  }\n\n  if (typeof input === 'string') {\n    const match = RGB_RE.exec(input);\n    if (!match) throw new Error(`Invalid rgb(a) string: ${input}`);\n    return {\n      r: sanitizeChannel(Number(match[1]), 'r'),\n      g: sanitizeChannel(Number(match[2]), 'g'),\n      b: sanitizeChannel(Number(match[3]), 'b'),\n      a: sanitizeAlpha(match[4] !== undefined ? Number(match[4]) : 1),\n    };\n  }\n\n  // Object form — TypeScript's Array.isArray narrowing doesn't exclude\n  // readonly tuple types from the union, so cast after the guards.\n  const obj = input as RgbObject | Rgba;\n  return {\n    r: sanitizeChannel(obj.r, 'r'),\n    g: sanitizeChannel(obj.g, 'g'),\n    b: sanitizeChannel(obj.b, 'b'),\n    a: sanitizeAlpha('a' in obj ? obj.a : 1),\n  };\n}\n\n/**\n * Emit an `rgb(r, g, b)` string. Alpha is dropped; values are\n * already-clamped by rgbToRgba, but we re-clamp defensively for direct\n * Rgba-object callers who bypass the input normalizer.\n */\nexport function rgbaToRgb(rgba: Rgba): RgbString {\n  const r = clamp(Math.round(rgba.r), 0, 255);\n  const g = clamp(Math.round(rgba.g), 0, 255);\n  const b = clamp(Math.round(rgba.b), 0, 255);\n  return `rgb(${r}, ${g}, ${b})` as RgbString;\n}\n"]}

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