color-bits 1.1.0 → 1.2.0

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git worktree *)",
+      "Bash(npx tsx *)",
+      "mcp__zym__set_worktree"
+    ]
+  }
+}

package/README.md

@@ -6,7 +6,7 @@
   <b>High-performance color library</b>
 </p>
 
-This library represents RGBA colors as a single `int32` number and avoids allocating memory as much as possible while parsing, handling, and formatting colors, to provide the best possible memory and CPU efficiency.
+This library represents RGBA colors as a single `int32` number and avoids allocating memory as much as possible while parsing, handling, and formatting colors, to provide the best possible memory and CPU efficiency. For a full technical overview, [read the blog post](https://romgrk.com/posts/color-bits/).
 
 <p align="center">
   <a href="#-benchmarks">Benchmarks</a> •
@@ -24,11 +24,13 @@ This library represents RGBA colors as a single `int32` number and avoids alloca
 
 | Library        | Operations/sec | Relative speed |
 | ---            | --:            | ---            |
-| **color-bits** | **22 966 299** | fastest        |
-| colord         | 4 308 547      | 81.24% slower  |
-| tinycolor2     | 1 475 762      | 93.57% slower  |
-| chroma-js      | 846 924        | 96.31% slower  |
-| color          | 799 262        | 96.52% slower  |
+| **color-bits** | **84 428 994** | fastest        |
+| @texel/color   | 7 160 587      | 91.52% slower  |
+| colord         | 6 604 745      | 92.18% slower  |
+| culori         | 5 223 367      | 93.81% slower  |
+| tinycolor2     | 2 479 660      | 97.06% slower  |
+| color          | 1 440 968      | 98.29% slower  |
+| chroma-js      | 1 348 236      | 98.40% slower  |
 
 ### 🛠️ Install
 
@@ -36,19 +38,29 @@ This library represents RGBA colors as a single `int32` number and avoids alloca
 pnpm install color-bits
 ```
 
-### 📑 Technical details
+### 📑 Usage
 
-Due to the compact representation, `color-bits` preserves **at most 8 bits of precision for each channel**, so an operation like `alpha(color, 0.000001)` would simply return the same color with no modification.
+The fast `Color.parse` supports the full **CSS Color Module Level 4** color spaces in **absolute** representations (`#hex`, `rgb()`, `hsl()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, `color()`).
 
-`color-bits` supports the full **CSS Color Module Level 4** color spaces **in absolute representations only**, so:
- - Yes: `oklab(59.69% 0.1007 0.1191)`
- - No: `oklab(from green l a b / 0.5)`
+Named colors, **relative** colors and `color-mix()` are supported through `parseCSS()` from the separate `color-bits/css` entry, which is slower and bigger. If you don't need those features, go for `parse()`.
 
-When parsing and converting non-sRGB color spaces, `color-bits` behaves the same as browsers do, which differs from the formal CSS spec! In technical terms: non-sRGB color spaces with a wider gamut are converted using clipping rather than gamut-mapping.
+```tsx
+import { parseCSS } from 'color-bits/css'
+
+parseCSS('rebeccapurple')                       // named colors
+parseCSS('oklab(from green l a b / 0.5)')       // relative colors
+parseCSS('hsl(from red calc(h + 120) s l)')     // relative colors with calc()
+parseCSS('color-mix(in oklch, red 40%, blue)')  // color-mix()
+
+// currentColor / system colors need context, passed via `resolve`:
+parseCSS('currentColor', { resolve: () => getComputedStyle(el).color })
+```
 
-For performance reasons, the representation is `int32`, not `uint32`. It is expected if you see negative numbers when you print the color value.
+**WARNING**: Due to the compact representation, `color-bits` preserves **at most 8 bits of precision for each channel**, so an operation like `lighten(color, 0.000001)` would simply return the same color with no modification. For performance reasons, the color representation is `int32`, not `uint32`. **It is expected if you see negative numbers when you print the raw color value**. Use the formatting functions to transform the color representation back into a usable format.
 
-Every function is tree-shakeable, so the bundle size cost should be from 1.5kb to 3kb, depending on which functions you use.
+The named-color table lives in its own `color-bits/named` entry (`resolveNamed`, `namedColors`), and `color-mix` is also exposed programmatically over parsed colors from `color-bits/css`.
+
+Every function is tree-shakeable, so the bundle size cost should be from 1.5kb to 3kb, depending on which functions you use. `parseCSS` and the named-color table are only pulled into your bundle if you import them.
 
 ### 📚 Documentation
 
@@ -73,6 +85,10 @@ import * as Color from 'color-bits/string'
 const output = Color.alpha('#232323', 0.5) // #RRGGBBAA string
 ```
 
+### Color conversion & gamut-mapping
+
+When parsing and converting non-sRGB color spaces, `color-bits` behaves the same as browsers (Chrome in particular) do, which differs from the formal CSS spec! In technical terms: non-sRGB color spaces with a wider gamut are converted using clipping rather than gamut-mapping.
+
 ### 📜 License
 
 I release any of the code I wrote here to the public domain. Feel free to copy/paste in part or in full without attribution.

package/benchmarks/compare-oklab.ts

@@ -0,0 +1,44 @@
+import b from 'benny'
+import { alpha as colorBitsAlpha } from '../src/string'
+import chroma from 'chroma-js'
+import { parse as culoriParse, formatHex8 as culoriFormatHex8 } from 'culori'
+
+const input = 'oklab(40.1% 0.1143 0.045)'
+
+async function main() {
+  // @texel/color is ESM-only; load it dynamically so this file still runs under tsx's CJS.
+  const { parse: texelParse, sRGB, RGBToHex } = (await import('@texel/color')) as any
+
+  b.suite(
+    'Parse an OKLab color, set to 0.5 opacity, and convert back to hexadecimal',
+
+    b.add('color-bits', () => {
+      colorBitsAlpha(input, 0.5)
+    }),
+
+    b.add('chroma-js', () => {
+      chroma(input).alpha(0.5).hex()
+    }),
+
+    b.add('culori', () => {
+      const parsed = culoriParse(input)!
+      parsed.alpha = 0.5
+      culoriFormatHex8(parsed)
+    }),
+
+    b.add('@texel/color', () => {
+      const rgb = texelParse(input, sRGB)
+      rgb[3] = 0.5
+      RGBToHex(rgb)
+    }),
+
+    b.cycle(),
+    b.complete((summary: any) => {
+      for (const r of summary.results) {
+        console.log(`RESULT ${r.name.padEnd(14)} ${Math.round(r.ops).toString().padStart(12)} ops/s`)
+      }
+    }),
+  )
+}
+
+main()

package/benchmarks/compare-srgb.ts

@@ -0,0 +1,59 @@
+import b from 'benny'
+import { alpha as colorBitsAlpha } from '../src/string'
+import { colord } from 'colord'
+import tinycolor2 from 'tinycolor2'
+import color from 'color'
+import chroma from 'chroma-js'
+import { parse as culoriParse, formatHex8 as culoriFormatHex8 } from 'culori'
+
+const input = '#808080'
+
+async function main() {
+  // @texel/color is ESM-only; load it dynamically so this file still runs under tsx's CJS.
+  const { hexToRGB, RGBToHex } = (await import('@texel/color')) as any
+
+  b.suite(
+    `Parse color, set to 0.5 opacity, and convert back to hexadecimal`,
+
+    b.add('color-bits', () => {
+      colorBitsAlpha(input, 0.5)
+    }),
+
+    b.add('colord', () => {
+      colord(input).alpha(0.5).toHex()
+    }),
+
+    b.add('color', () => {
+      color(input).alpha(0.5).hex()
+    }),
+
+    b.add('tinycolor2', () => {
+      tinycolor2(input).setAlpha(0.5).toHexString()
+    }),
+
+    b.add('chroma-js', () => {
+      chroma(input).alpha(0.5).hex()
+    }),
+
+    b.add('culori', () => {
+      const parsed = culoriParse(input)!
+      parsed.alpha = 0.5
+      culoriFormatHex8(parsed)
+    }),
+
+    b.add('@texel/color', () => {
+      const rgb = hexToRGB(input)
+      rgb[3] = 0.5
+      RGBToHex(rgb)
+    }),
+
+    b.cycle(),
+    b.complete((summary: any) => {
+      for (const r of summary.results) {
+        console.log(`RESULT ${r.name.padEnd(14)} ${Math.round(r.ops).toString().padStart(12)} ops/s`)
+      }
+    }),
+  )
+}
+
+main()

package/benchmarks/compare.ts

@@ -0,0 +1,46 @@
+import { parse } from '../src/index'
+
+// Deterministic best-of-N micro-benchmark for one case, run in an isolated
+// process to avoid cross-case JIT pollution. Usage:
+//   tsx benchmarks/compare.ts <case-name>
+// Compare before/after a refactor by running it, then `git stash` + run again.
+
+const cases: Record<string, string> = {
+  'hex-short':  '#59f',
+  'hex':        '#5599ff',
+  'hex-alpha':  '#5599ff88',
+  'rgb':        'rgb(255 153 85)',
+  'rgb-legacy': 'rgb(255, 153, 85)',
+  'rgb-alpha':  'rgb(255 153 85 / 50%)',
+  'hsl':        'hsl(50deg 80% 40%)',
+  'hwb':        'hwb(50deg 30% 40%)',
+  'lab':        'lab(50% 40 59.5)',
+  'lch':        'lch(52.2% 72.2 50)',
+  'oklab':      'oklab(40.1% 0.1143 0.045)',
+  'oklch':      'oklch(40.1% 0.123 21.57)',
+  'color-srgb': 'color(srgb 1 0.5 0)',
+  'color-p3':   'color(display-p3 1 0.5 0)',
+}
+
+const name = process.argv[2]
+const input = cases[name]
+if (!input) { console.error(`unknown case: ${name}`); process.exit(1) }
+
+const ITERATIONS = 1_000_000
+const TRIALS = 15
+let sink = 0
+
+// warmup
+for (let i = 0; i < 200_000; i++) sink ^= parse(input)
+
+let best = Infinity
+for (let t = 0; t < TRIALS; t++) {
+  const start = process.hrtime.bigint()
+  for (let i = 0; i < ITERATIONS; i++) sink ^= parse(input)
+  const ns = Number(process.hrtime.bigint() - start)
+  if (ns < best) best = ns
+}
+const opsPerSec = Math.round((ITERATIONS / best) * 1e9)
+console.log(`RESULT ${name.padEnd(12)} ${opsPerSec.toString().padStart(12)} ops/s`)
+
+if (sink === 42) console.log('') // prevent dead-code elimination

package/benchmarks/parse.ts

@@ -0,0 +1,41 @@
+import b from 'benny'
+import { parse } from '../src/index'
+
+// Benchmarks the `parse` fast path across every absolute representation.
+// Used as the regression gate for the channels.ts refactor: the hex hot path
+// must stay flat, and the function parsers must not regress.
+
+const cases: Record<string, string> = {
+  'hex-short':  '#59f',
+  'hex':        '#5599ff',
+  'hex-alpha':  '#5599ff88',
+  'rgb':        'rgb(255 153 85)',
+  'rgb-legacy': 'rgb(255, 153, 85)',
+  'rgb-alpha':  'rgb(255 153 85 / 50%)',
+  'hsl':        'hsl(50deg 80% 40%)',
+  'hwb':        'hwb(50deg 30% 40%)',
+  'lab':        'lab(50% 40 59.5)',
+  'lch':        'lch(52.2% 72.2 50)',
+  'oklab':      'oklab(40.1% 0.1143 0.045)',
+  'oklch':      'oklch(40.1% 0.123 21.57)',
+  'color-srgb': 'color(srgb 1 0.5 0)',
+  'color-p3':   'color(display-p3 1 0.5 0)',
+}
+
+// XOR results into a sink so the (pure, number-returning) parse call cannot be
+// dead-code-eliminated, which would inflate ops/s and hide regressions.
+let sink = 0
+
+b.suite(
+  'Color.parse() — absolute representations',
+  ...Object.entries(cases).map(([name, input]) =>
+    b.add(name, () => { sink ^= parse(input) })
+  ),
+  b.cycle(),
+  b.complete((summary) => {
+    for (const r of summary.results) {
+      console.log(`RESULT ${r.name.padEnd(12)} ${Math.round(r.ops).toString().padStart(12)} ops/s`)
+    }
+    if (sink === 42) console.log('')
+  }),
+)

package/build/conversion/channels.d.ts

@@ -0,0 +1,61 @@
+import { ColorBits } from '../core/bits';
+/** Build ColorBits from sRGB components in [0, 1] and an alpha byte (0..255). */
+export declare function srgbToColor(r: number, g: number, b: number, a: number): ColorBits;
+/**
+ * @param h degrees, any value (wrapped by 360°)
+ * @param s nominally 0..100 (clamped)
+ * @param l nominally 0..100 (clamped)
+ * @param a alpha byte
+ */
+export declare function hslToColor(h: number, s: number, l: number, a: number): ColorBits;
+/** @param sRGB in [0, 1] @returns out as [h degrees, s 0..100, l 0..100] */
+export declare function srgbToHsl(r: number, g: number, b: number, out: Float64Array): Float64Array;
+/**
+ * @param h degrees, any value (wrapped by 360°)
+ * @param w nominally 0..100 (clamped)
+ * @param b nominally 0..100 (clamped)
+ * @param a alpha byte
+ */
+export declare function hwbToColor(h: number, w: number, b: number, a: number): ColorBits;
+/** @param sRGB in [0, 1] @returns out as [h degrees, w 0..100, b 0..100] */
+export declare function srgbToHwb(r: number, g: number, b: number, out: Float64Array): Float64Array;
+/** @param l 0..100 @param a raw @param b raw @param alpha alpha byte */
+export declare function labToColor(l: number, a: number, b: number, alpha: number): ColorBits;
+/** @param sRGB in [0, 1] @returns out as [l 0..100, a raw, b raw] */
+export declare function srgbToLab(r: number, g: number, b: number, out: Float64Array): Float64Array;
+/** @param l 0..100 @param c raw @param h degrees @param alpha alpha byte */
+export declare function lchToColor(l: number, c: number, h: number, alpha: number): ColorBits;
+/** @param sRGB in [0, 1] @returns out as [l 0..100, c raw, h degrees] */
+export declare function srgbToLch(r: number, g: number, b: number, out: Float64Array): Float64Array;
+/** @param l 0..1 @param a raw @param b raw @param alpha alpha byte */
+export declare function oklabToColor(l: number, a: number, b: number, alpha: number): ColorBits;
+/** @param sRGB in [0, 1] @returns out as [l 0..1, a raw, b raw] */
+export declare function srgbToOklab(r: number, g: number, b: number, out: Float64Array): Float64Array;
+/** @param l 0..1 @param c raw @param h degrees @param alpha alpha byte */
+export declare function oklchToColor(l: number, c: number, h: number, alpha: number): ColorBits;
+/** @param sRGB in [0, 1] @returns out as [l 0..1, c raw, h degrees] */
+export declare function srgbToOklch(r: number, g: number, b: number, out: Float64Array): Float64Array;
+/** Channel keywords exposed by color(from <origin> <space> …) per color space. */
+export declare function colorSpaceChannels(space: string): string[] | null;
+/** @param channels in 0..1 @returns out as sRGB in [0, 1], or null for an unknown space */
+export declare function colorSpaceToSrgb(space: string, c1: number, c2: number, c3: number, out: Float64Array): Float64Array | null;
+/** @param channels in 0..1 @returns ColorBits, or null for an unknown space */
+export declare function colorSpaceToColor(space: string, c1: number, c2: number, c3: number, alpha: number): ColorBits | null;
+/** @param sRGB in [0, 1] @returns out as the space's channels in 0..1, or null for an unknown space */
+export declare function srgbToColorSpace(space: string, r: number, g: number, b: number, out: Float64Array): Float64Array | null;
+export interface ColorModel {
+    keys: [string, string, string];
+    /** percentage reference per channel (e.g. 100 for lab L, 360 for hues) */
+    ranges: [number, number, number];
+    /** whether each channel is a hue angle */
+    hues: [boolean, boolean, boolean];
+    /** sRGB in [0, 1] -> the model's keyword-unit channels, written into `out` and returned */
+    fromSrgb: (r: number, g: number, b: number, out: Float64Array) => Float64Array;
+    /** keyword-unit channels + alpha byte -> ColorBits */
+    toColor: (c1: number, c2: number, c3: number, alpha: number) => ColorBits;
+}
+/** Model for a color-model name (hsl, oklch, …), or null. Own-key lookup so
+ * that Object.prototype names ('constructor', '__proto__') are not models. */
+export declare function colorModel(name: string): ColorModel | null;
+/** Model for a color() predefined space (channels in 0..1), or null. */
+export declare function colorSpaceModel(space: string): ColorModel | null;