@planet-matrix/mobius-model 0.5.0 → 0.9.0

package/tests/unit/basic/stream.spec.ts

@@ -1,17 +1,18 @@
 import { expect, test } from "vitest"
 
 import {
-  streamConsumeInAsyncMacroTask,
-  streamConsumeInSyncMacroTask,
-  streamFromArray,
-  streamTransformInAsyncMacroTask,
+  streamConsumeInMacroTask,
+  streamConsumeInMicroTask,
+  streamFromArrayEager,
+  streamFromArrayLazy,
+  streamTransformInMacroTask,
 } from "#Source/basic/index.ts"
 
-test("streamFromArray creates a readable stream from array values", async () => {
+test("streamFromArrayEager creates a readable stream from array values", async () => {
   const source = [1, 2, 3]
   const values: number[] = []
 
-  const stream = streamFromArray(source)
+  const stream = streamFromArrayEager(source)
   for await (const value of stream) {
     values.push(value)
   }
@@ -19,18 +20,38 @@ test("streamFromArray creates a readable stream from array values", async () =>
   expect(values).toEqual(source)
 })
 
-test("streamConsumeInSyncMacroTask consumes stream and handles callback errors", async () => {
+test("streamFromArrayLazy creates a lazily consumed readable stream", async () => {
+  const source = [1, 2, 3]
+  const stream = streamFromArrayLazy(source)
+  const reader = stream.getReader()
+
+  const firstChunk = await reader.read()
+  const secondChunk = await reader.read()
+  const thirdChunk = await reader.read()
+  const doneChunk = await reader.read()
+
+  expect(firstChunk).toEqual({ done: false, value: 1 })
+  expect(secondChunk).toEqual({ done: false, value: 2 })
+  expect(thirdChunk).toEqual({ done: false, value: 3 })
+  expect(doneChunk).toEqual({ done: true, value: undefined })
+})
+
+test("streamConsumeInMicroTask consumes stream and handles callback errors", async () => {
   const consumed: number[] = []
   let doneCalled = false
 
-  await streamConsumeInSyncMacroTask<number>({
-    readableStream: streamFromArray([1, 2, 3]),
-    onValue: (chunk) => {
-      consumed.push(chunk)
-    },
-    onDone: () => {
-      doneCalled = true
-    },
+  await new Promise<void>((resolve, reject) => {
+    streamConsumeInMicroTask<number>({
+      readableStream: streamFromArrayEager([1, 2, 3]),
+      onValue: (chunk) => {
+        consumed.push(chunk)
+      },
+      onDone: () => {
+        doneCalled = true
+        resolve()
+      },
+      onError: reject,
+    })
   })
 
   expect(consumed).toEqual([1, 2, 3])
@@ -38,30 +59,33 @@ test("streamConsumeInSyncMacroTask consumes stream and handles callback errors",
 
   let errorMessage = ""
   let doneCalledInErrorCase = false
-  await streamConsumeInSyncMacroTask<number>({
-    readableStream: streamFromArray([1, 2]),
-    onValue: (chunk) => {
-      if (chunk === 2) {
-        throw new Error("boom")
-      }
-    },
-    onDone: () => {
-      doneCalledInErrorCase = true
-    },
-    onError: (error) => {
-      errorMessage = error.message
-    },
+  await new Promise<void>((resolve) => {
+    streamConsumeInMicroTask<number>({
+      readableStream: streamFromArrayEager([1, 2]),
+      onValue: (chunk) => {
+        if (chunk === 2) {
+          throw new Error("boom")
+        }
+      },
+      onDone: () => {
+        doneCalledInErrorCase = true
+      },
+      onError: (error) => {
+        errorMessage = error.message
+        resolve()
+      },
+    })
   })
 
   expect(errorMessage).toContain("boom")
   expect(doneCalledInErrorCase).toBe(false)
 })
 
-test("streamConsumeInAsyncMacroTask consumes stream and forwards callback failures", async () => {
+test("streamConsumeInMacroTask consumes stream and forwards callback failures", async () => {
   const consumed: number[] = []
   await new Promise<void>((resolve, reject) => {
-    streamConsumeInAsyncMacroTask<number>({
-      readableStream: streamFromArray([1, 2, 3]),
+    streamConsumeInMacroTask<number>({
+      readableStream: streamFromArrayEager([1, 2, 3]),
       onValue: (chunk) => {
         consumed.push(chunk)
       },
@@ -78,8 +102,8 @@ test("streamConsumeInAsyncMacroTask consumes stream and forwards callback failur
 
   let errorMessage = ""
   await new Promise<void>((resolve, reject) => {
-    streamConsumeInAsyncMacroTask<number>({
-      readableStream: streamFromArray([1]),
+    streamConsumeInMacroTask<number>({
+      readableStream: streamFromArrayEager([1]),
       onValue: () => {
         throw new Error("async-boom")
       },
@@ -96,13 +120,13 @@ test("streamConsumeInAsyncMacroTask consumes stream and forwards callback failur
   expect(errorMessage).toContain("async-boom")
 })
 
-test("streamTransformInAsyncMacroTask transforms values and handles invalid inputs/errors", async () => {
+test("streamTransformInMacroTask transforms values and handles invalid inputs/errors", async () => {
   expect(() => {
-    streamTransformInAsyncMacroTask<number, number>({})
-  }).toThrowError("Either readableStream or reader must be provided")
+    streamTransformInMacroTask<number, number>({})
+  }).toThrow("Either readableStream or reader must be provided")
 
-  const transformed = streamTransformInAsyncMacroTask<number, number>({
-    readableStream: streamFromArray([1, 2, 3]),
+  const transformed = streamTransformInMacroTask<number, number>({
+    readableStream: streamFromArrayEager([1, 2, 3]),
     onChunk: (chunk, controller) => {
       if (chunk.done === true) {
         controller.close()
@@ -117,4 +141,33 @@ test("streamTransformInAsyncMacroTask transforms values and handles invalid inpu
     values.push(value)
   }
   expect(values).toEqual([10, 20, 30])
+
+  const reader = streamFromArrayEager([4]).getReader()
+  const transformedFromReader = streamTransformInMacroTask<number, number>({
+    reader,
+    onChunk: (chunk, controller) => {
+      if (chunk.done === true) {
+        controller.close()
+        return
+      }
+      controller.enqueue(chunk.value + 1)
+    },
+  })
+
+  expect(await Array.fromAsync(transformedFromReader)).toEqual([5])
+
+  let refinedError: Error | undefined
+  const errored = streamTransformInMacroTask<number, number>({
+    readableStream: streamFromArrayEager([1]),
+    onChunk: () => {
+      throw new Error("transform-boom")
+    },
+    onError: (error) => {
+      refinedError = new Error(`wrapped:${error.message}`)
+      return refinedError
+    },
+  })
+
+  await expect(Array.fromAsync(errored)).rejects.toThrow("wrapped:Error: transform-boom")
+  expect(refinedError?.message).toBe("wrapped:Error: transform-boom")
 })

package/tests/unit/basic/string.spec.ts

@@ -5,7 +5,6 @@ import {
   stringCamelCaseToKebabCase,
   stringHelloWord,
   stringKebabCaseToCamelCase,
-  stringRandom,
   stringSliceByUnits,
   stringSmartSplit,
   stringSplit,
@@ -13,14 +12,6 @@ import {
   stringTruncateByUnits,
 } from "#Source/basic/index.ts"
 
-test("stringRandom returns expected output", () => {
-  const value = stringRandom(12)
-  expect(value).toHaveLength(12)
-
-  const constrained = stringRandom(10, "ab")
-  expect(constrained.split("").every(char => char === "a" || char === "b")).toBe(true)
-})
-
 test("stringCamelCaseToKebabCase converts correctly", () => {
   expect(stringCamelCaseToKebabCase("helloWorld")).toBe("hello-world")
   expect(stringCamelCaseToKebabCase("ab2Cd")).toBe("ab2-cd")

package/tests/unit/color/rgb/analyze.spec.ts

@@ -0,0 +1,110 @@
+import { expect, test } from "vitest"
+
+import {
+  doSrgbColorValuesMeetContrastRatio,
+  isLightSrgbColorValue,
+  linearRgbColorValueToRelativeLuminance,
+  linearRgbColorValueToTristimulusSum,
+  linearRgbColorValueToXyChromaticityValue,
+  pickReadableSrgbTextColorValue,
+  srgbColorValueToRelativeLuminance,
+  srgbColorValueToTristimulusSum,
+  srgbColorValueToXyChromaticityValue,
+  srgbColorValuesToContrastRatio,
+} from "#Source/color/index.ts"
+
+test("linearRgbColorValueToRelativeLuminance follows the explicit RGB branch pipeline", () => {
+  expect(linearRgbColorValueToRelativeLuminance({ red: 1, green: 0, blue: 0, alpha: 1 })).toBe(0.212_673)
+  expect(linearRgbColorValueToRelativeLuminance({ red: 1, green: 1, blue: 1, alpha: 1 })).toBe(1)
+})
+
+test("srgbColorValueToRelativeLuminance follows the explicit RGB branch pipeline", () => {
+  expect(srgbColorValueToRelativeLuminance({ red: 51, green: 102, blue: 153, alpha: 1 })).toBe(0.125_053)
+  expect(srgbColorValueToRelativeLuminance({ red: 255, green: 255, blue: 255, alpha: 1 })).toBe(1)
+})
+
+test("srgbColorValuesToContrastRatio supports accessibility-oriented comparisons", () => {
+  expect(srgbColorValuesToContrastRatio(
+    { red: 0, green: 0, blue: 0, alpha: 1 },
+    { red: 255, green: 255, blue: 255, alpha: 1 },
+  )).toBe(21)
+
+  expect(srgbColorValuesToContrastRatio(
+    { red: 51, green: 102, blue: 153, alpha: 1 },
+    { red: 51, green: 102, blue: 153, alpha: 1 },
+  )).toBe(1)
+})
+
+test("doSrgbColorValuesMeetContrastRatio validates thresholds and comparisons", () => {
+  expect(() => doSrgbColorValuesMeetContrastRatio(
+    { red: 0, green: 0, blue: 0, alpha: 1 },
+    { red: 255, green: 255, blue: 255, alpha: 1 },
+    0.99,
+  )).toThrow(RangeError)
+
+  expect(doSrgbColorValuesMeetContrastRatio(
+    { red: 0, green: 0, blue: 0, alpha: 1 },
+    { red: 255, green: 255, blue: 255, alpha: 1 },
+    7,
+  )).toBe(true)
+
+  expect(doSrgbColorValuesMeetContrastRatio(
+    { red: 120, green: 120, blue: 120, alpha: 1 },
+    { red: 255, green: 255, blue: 255, alpha: 1 },
+    4.5,
+  )).toBe(false)
+})
+
+test("pickReadableSrgbTextColorValue chooses the more readable candidate", () => {
+  expect(pickReadableSrgbTextColorValue({ red: 0, green: 102, blue: 204, alpha: 1 })).toEqual({
+    red: 255,
+    green: 255,
+    blue: 255,
+    alpha: 1,
+  })
+
+  expect(pickReadableSrgbTextColorValue(
+    { red: 250, green: 240, blue: 210, alpha: 1 },
+    {
+      darkColor: { red: 32, green: 32, blue: 32, alpha: 1 },
+      lightColor: { red: 255, green: 255, blue: 255, alpha: 1 },
+    },
+  )).toEqual({
+    red: 32,
+    green: 32,
+    blue: 32,
+    alpha: 1,
+  })
+})
+
+test("linearRgbColorValueToTristimulusSum follows the explicit RGB branch pipeline", () => {
+  expect(linearRgbColorValueToTristimulusSum({ red: 1, green: 0, blue: 0, alpha: 1 })).toBe(0.644_463)
+  expect(linearRgbColorValueToTristimulusSum({ red: 1, green: 1, blue: 1, alpha: 1 })).toBe(3.039_3)
+})
+
+test("srgbColorValueToTristimulusSum follows the explicit RGB branch pipeline", () => {
+  expect(srgbColorValueToTristimulusSum({ red: 51, green: 102, blue: 153, alpha: 1 })).toBe(0.562_889)
+  expect(srgbColorValueToTristimulusSum({ red: 255, green: 255, blue: 255, alpha: 1 })).toBe(3.039_3)
+})
+
+test("linearRgbColorValueToXyChromaticityValue follows the explicit RGB branch pipeline", () => {
+  expect(linearRgbColorValueToXyChromaticityValue({ red: 1, green: 0, blue: 0, alpha: 1 })).toEqual({
+    x: 0.64,
+    y: 0.33,
+  })
+})
+
+test("srgbColorValueToXyChromaticityValue follows the explicit RGB branch pipeline", () => {
+  expect(srgbColorValueToXyChromaticityValue({ red: 51, green: 102, blue: 153, alpha: 1 })).toEqual({
+    x: 0.210_775,
+    y: 0.222_163,
+  })
+})
+
+test("isLightSrgbColorValue uses relative luminance threshold", () => {
+  expect(isLightSrgbColorValue({ red: 255, green: 255, blue: 255, alpha: 1 })).toBe(true)
+  expect(isLightSrgbColorValue({ red: 0, green: 0, blue: 0, alpha: 1 })).toBe(false)
+  expect(isLightSrgbColorValue({ red: 128, green: 128, blue: 128, alpha: 1 }, 0.2)).toBe(true)
+
+  expect(() => isLightSrgbColorValue({ red: 128, green: 128, blue: 128, alpha: 1 }, 1.1)).toThrow(RangeError)
+})

package/tests/unit/color/rgb/construct.spec.ts

@@ -0,0 +1,56 @@
+import { expect, test } from "vitest"
+
+import {
+  createHslColorValue,
+  createHslColorValueByString,
+  createHsvColorValue,
+  createHsvColorValueByString,
+  createLinearRgbColorValue,
+  createSrgbColorValue,
+  createSrgbColorValueByString,
+} from "#Source/color/index.ts"
+
+test("createLinearRgbColorValue accepts finite linear channels", () => {
+  expect(createLinearRgbColorValue({ red: -0.25, green: 0.4, blue: 1.2, alpha: 1 }))
+    .toEqual({ red: -0.25, green: 0.4, blue: 1.2, alpha: 1 })
+
+  expect(createLinearRgbColorValue({ red: 0, green: 0, blue: 0, alpha: 0.5 }))
+    .toEqual({ red: 0, green: 0, blue: 0, alpha: 0.5 })
+
+  expect(() => createLinearRgbColorValue({ red: Number.NaN, green: 0.4, blue: 1.2, alpha: 1 })).toThrow(RangeError)
+})
+
+test("createSrgbColorValue validates byte channels", () => {
+  expect(createSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 0.5 }))
+    .toEqual({ red: 51, green: 102, blue: 153, alpha: 0.5 })
+
+  expect(() => createSrgbColorValue({ red: -1, green: 0, blue: 0, alpha: 1 })).toThrow(RangeError)
+  expect(() => createSrgbColorValue({ red: 0, green: 0, blue: 256, alpha: 1 })).toThrow(RangeError)
+})
+
+test("createHslColorValue normalizes hue and validates units", () => {
+  expect(createHslColorValue({ hue: -30, saturation: 0.5, lightness: 0.4, alpha: 1 }))
+    .toEqual({ hue: 330, saturation: 0.5, lightness: 0.4, alpha: 1 })
+  expect(() => createHslColorValue({ hue: 0, saturation: 1.5, lightness: 0.4, alpha: 1 })).toThrow(RangeError)
+})
+
+test("createHsvColorValue normalizes hue and validates units", () => {
+  expect(createHsvColorValue({ hue: 390, saturation: 0.5, value: 0.6, alpha: 1 }))
+    .toEqual({ hue: 30, saturation: 0.5, value: 0.6, alpha: 1 })
+  expect(() => createHsvColorValue({ hue: 0, saturation: 0.5, value: 1.5, alpha: 1 })).toThrow(RangeError)
+})
+
+test("createSrgbColorValueByString stays deterministic", () => {
+  expect(createSrgbColorValueByString("mobius")).toEqual(createSrgbColorValueByString("mobius"))
+  expect(createSrgbColorValueByString("mobius")).not.toEqual(createSrgbColorValueByString("planet"))
+})
+
+test("createHslColorValueByString stays deterministic", () => {
+  expect(createHslColorValueByString("mobius")).toEqual(createHslColorValueByString("mobius"))
+  expect(createHslColorValueByString("mobius")).not.toEqual(createHslColorValueByString("planet"))
+})
+
+test("createHsvColorValueByString stays deterministic", () => {
+  expect(createHsvColorValueByString("mobius")).toEqual(createHsvColorValueByString("mobius"))
+  expect(createHsvColorValueByString("mobius")).not.toEqual(createHsvColorValueByString("planet"))
+})

package/tests/unit/color/rgb/convert.spec.ts

@@ -0,0 +1,60 @@
+import { expect, test } from "vitest"
+
+import {
+  hslColorValueToSrgbColorValue,
+  hsvColorValueToSrgbColorValue,
+  linearRgbColorValueToSrgbColorValue,
+  srgbColorValueToHslColorValue,
+  srgbColorValueToHsvColorValue,
+  srgbColorValueToLinearRgbColorValue,
+} from "#Source/color/index.ts"
+
+test("linearRgbColorValueToSrgbColorValue converts in-gamut linear values to sRGB", () => {
+  expect(linearRgbColorValueToSrgbColorValue({ red: 1, green: 0, blue: 0, alpha: 0.5 }))
+    .toEqual({ red: 255, green: 0, blue: 0, alpha: 0.5 })
+
+  expect(linearRgbColorValueToSrgbColorValue({ red: 0.5, green: 0.5, blue: 0.5, alpha: 0.5 }))
+    .toEqual({ red: 188, green: 188, blue: 188, alpha: 0.5 })
+
+  expect(() => linearRgbColorValueToSrgbColorValue({ red: 1.2, green: 0, blue: 0, alpha: 1 })).toThrow(RangeError)
+})
+
+test("srgbColorValueToLinearRgbColorValue converts sRGB values to linear values", () => {
+  expect(srgbColorValueToLinearRgbColorValue({ red: 255, green: 0, blue: 0, alpha: 0.5 }))
+    .toEqual({ red: 1, green: 0, blue: 0, alpha: 0.5 })
+
+  expect(srgbColorValueToLinearRgbColorValue({ red: 128, green: 128, blue: 128, alpha: 0.5 }))
+    .toEqual({ red: 0.215_861, green: 0.215_861, blue: 0.215_861, alpha: 0.5 })
+})
+
+test("srgbColorValueToHslColorValue converts sRGB values to HSL", () => {
+  expect(srgbColorValueToHslColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }))
+    .toEqual({ hue: 210, saturation: 0.5, lightness: 0.4, alpha: 1 })
+
+  expect(srgbColorValueToHslColorValue({ red: 128, green: 128, blue: 128, alpha: 1 }))
+    .toEqual({ hue: 0, saturation: 0, lightness: 0.501_961, alpha: 1 })
+})
+
+test("hslColorValueToSrgbColorValue converts HSL values to sRGB", () => {
+  expect(hslColorValueToSrgbColorValue({ hue: 210, saturation: 0.5, lightness: 0.4, alpha: 1 }))
+    .toEqual({ red: 51, green: 102, blue: 153, alpha: 1 })
+
+  expect(hslColorValueToSrgbColorValue({ hue: 0, saturation: 0, lightness: 0.501_961, alpha: 1 }))
+    .toEqual({ red: 128, green: 128, blue: 128, alpha: 1 })
+})
+
+test("srgbColorValueToHsvColorValue converts sRGB values to HSV", () => {
+  expect(srgbColorValueToHsvColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }))
+    .toEqual({ hue: 210, saturation: 0.666_667, value: 0.6, alpha: 1 })
+
+  expect(srgbColorValueToHsvColorValue({ red: 128, green: 128, blue: 128, alpha: 1 }))
+    .toEqual({ hue: 0, saturation: 0, value: 0.501_961, alpha: 1 })
+})
+
+test("hsvColorValueToSrgbColorValue converts HSV values to sRGB", () => {
+  expect(hsvColorValueToSrgbColorValue({ hue: 210, saturation: 0.666_667, value: 0.6, alpha: 1 }))
+    .toEqual({ red: 51, green: 102, blue: 153, alpha: 1 })
+
+  expect(hsvColorValueToSrgbColorValue({ hue: 0, saturation: 0, value: 0.501_961, alpha: 1 }))
+    .toEqual({ red: 128, green: 128, blue: 128, alpha: 1 })
+})

package/tests/unit/color/rgb/derive.spec.ts

@@ -0,0 +1,103 @@
+import { expect, test } from "vitest"
+
+import {
+  compositeLinearRgbColorValueOverBackground,
+  compositeSrgbColorValueOverBackground,
+  darkenSrgbColorValue,
+  fadeSrgbColorValue,
+  lightenSrgbColorValue,
+  mixLinearRgbColorValues,
+  mixSrgbColorValues,
+  shadeSrgbColorValue,
+  tintSrgbColorValue,
+  toneSrgbColorValue,
+} from "#Source/color/index.ts"
+
+test("mixLinearRgbColorValues mixes directly on the linear layer", () => {
+  expect(mixLinearRgbColorValues(
+    { red: 1, green: 0, blue: 0, alpha: 1 },
+    { red: 0, green: 0, blue: 1, alpha: 1 },
+    0.5,
+  )).toEqual({ red: 0.5, green: 0, blue: 0.5, alpha: 1 })
+
+  expect(() => mixLinearRgbColorValues(
+    { red: 1, green: 0, blue: 0, alpha: 1 },
+    { red: 0, green: 0, blue: 1, alpha: 1 },
+    -0.1,
+  )).toThrow(RangeError)
+})
+
+test("mixSrgbColorValues mixes through the explicit sRGB to linear pipeline", () => {
+  expect(mixSrgbColorValues(
+    { red: 255, green: 0, blue: 0, alpha: 1 },
+    { red: 0, green: 0, blue: 255, alpha: 1 },
+    0.5,
+  )).toEqual({ red: 188, green: 0, blue: 188, alpha: 1 })
+
+  expect(mixSrgbColorValues(
+    { red: 255, green: 0, blue: 0, alpha: 1 },
+    { red: 255, green: 255, blue: 255, alpha: 1 },
+    0.5,
+  )).toEqual({ red: 255, green: 188, blue: 188, alpha: 1 })
+})
+
+test("compositeLinearRgbColorValueOverBackground composites directly on the linear layer", () => {
+  expect(compositeLinearRgbColorValueOverBackground(
+    { red: 1, green: 1, blue: 1, alpha: 0.5 },
+    { red: 0, green: 0, blue: 1, alpha: 1 },
+  )).toEqual({ red: 0.5, green: 0.5, blue: 1, alpha: 1 })
+
+  expect(compositeLinearRgbColorValueOverBackground(
+    { red: 1, green: 0, blue: 0, alpha: 1 },
+    { red: 0, green: 0, blue: 1, alpha: 1 },
+  )).toEqual({ red: 1, green: 0, blue: 0, alpha: 1 })
+})
+
+test("compositeSrgbColorValueOverBackground composites through the explicit sRGB to linear pipeline", () => {
+  expect(compositeSrgbColorValueOverBackground(
+    { red: 255, green: 255, blue: 255, alpha: 0.5 },
+    { red: 0, green: 0, blue: 255, alpha: 1 },
+  )).toEqual({ red: 188, green: 188, blue: 255, alpha: 1 })
+
+  expect(compositeSrgbColorValueOverBackground(
+    { red: 255, green: 0, blue: 0, alpha: 1 },
+    { red: 0, green: 0, blue: 255, alpha: 1 },
+  )).toEqual({ red: 255, green: 0, blue: 0, alpha: 1 })
+})
+
+test("fadeSrgbColorValue updates alpha while keeping channels stable", () => {
+  expect(fadeSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0.4)).toEqual({
+    red: 51,
+    green: 102,
+    blue: 153,
+    alpha: 0.4,
+  })
+
+  expect(() => fadeSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, -0.1)).toThrow(RangeError)
+})
+
+test("tintSrgbColorValue stays on the legal RGB branch pipeline", () => {
+  expect(tintSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0.5)).toEqual({ red: 190, green: 198, blue: 212, alpha: 1 })
+  expect(tintSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0)).toEqual({ red: 51, green: 102, blue: 153, alpha: 1 })
+  expect(() => tintSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 1.1)).toThrow(RangeError)
+})
+
+test("shadeSrgbColorValue stays on the legal RGB branch pipeline", () => {
+  expect(shadeSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0.5)).toEqual({ red: 35, green: 73, blue: 111, alpha: 1 })
+  expect(shadeSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0)).toEqual({ red: 51, green: 102, blue: 153, alpha: 1 })
+})
+
+test("toneSrgbColorValue stays on the legal RGB branch pipeline", () => {
+  expect(toneSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0.5)).toEqual({ red: 141, green: 153, blue: 171, alpha: 1 })
+  expect(toneSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0)).toEqual({ red: 51, green: 102, blue: 153, alpha: 1 })
+})
+
+test("lightenSrgbColorValue stays on the legal RGB branch pipeline", () => {
+  expect(lightenSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0.25)).toEqual({ red: 143, green: 160, blue: 186, alpha: 1 })
+  expect(lightenSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0)).toEqual({ red: 51, green: 102, blue: 153, alpha: 1 })
+})
+
+test("darkenSrgbColorValue stays on the legal RGB branch pipeline", () => {
+  expect(darkenSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0.25)).toEqual({ red: 44, green: 89, blue: 134, alpha: 1 })
+  expect(darkenSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0)).toEqual({ red: 51, green: 102, blue: 153, alpha: 1 })
+})

package/tests/unit/color/rgb/parse.spec.ts

@@ -0,0 +1,66 @@
+import { expect, test } from "vitest"
+
+import {
+  colorStringToSrgbColorValue,
+  hexColorStringToSrgbColorValue,
+  hslColorStringToHslColorValue,
+  hslaColorStringToHslColorValue,
+  hsvColorStringToHsvColorValue,
+  hsvaColorStringToHsvColorValue,
+  isHexColorString,
+  rgbColorStringToSrgbColorValue,
+  rgbaColorStringToSrgbColorValue,
+} from "#Source/color/index.ts"
+
+test("isHexColorString validates supported hex formats", () => {
+  expect(isHexColorString("#F0A")).toBe(true)
+  expect(isHexColorString("11223344")).toBe(true)
+  expect(isHexColorString("#12")).toBe(false)
+})
+
+test("hexColorStringToSrgbColorValue supports short and long hex formats", () => {
+  expect(hexColorStringToSrgbColorValue("#F0A")).toEqual({ red: 255, green: 0, blue: 170, alpha: 1 })
+  expect(hexColorStringToSrgbColorValue("#112233")).toEqual({ red: 17, green: 34, blue: 51, alpha: 1 })
+  expect(hexColorStringToSrgbColorValue("#11223344")).toEqual({ red: 17, green: 34, blue: 51, alpha: 0.266_7 })
+  expect(() => hexColorStringToSrgbColorValue("#12")).toThrow(TypeError)
+})
+
+test("rgbColorStringToSrgbColorValue returns sRGB values", () => {
+  expect(rgbColorStringToSrgbColorValue("rgb(51, 102, 153)")).toEqual({ red: 51, green: 102, blue: 153, alpha: 1 })
+  expect(rgbColorStringToSrgbColorValue("rgb(0, 0, 0)")).toEqual({ red: 0, green: 0, blue: 0, alpha: 1 })
+})
+
+test("rgbaColorStringToSrgbColorValue returns sRGB values", () => {
+  expect(rgbaColorStringToSrgbColorValue("rgba(51, 102, 153, 0.5)")).toEqual({ red: 51, green: 102, blue: 153, alpha: 0.5 })
+  expect(() => rgbaColorStringToSrgbColorValue("rgba(51, 102, 153, 1.5)")).toThrow(RangeError)
+})
+
+test("hslColorStringToHslColorValue returns HSL values", () => {
+  expect(hslColorStringToHslColorValue("hsl(210, 50%, 40%)")).toEqual({ hue: 210, saturation: 0.5, lightness: 0.4, alpha: 1 })
+  expect(hslColorStringToHslColorValue("hsl(-30, 50%, 40%)")).toEqual({ hue: 330, saturation: 0.5, lightness: 0.4, alpha: 1 })
+  expect(() => hslColorStringToHslColorValue("hsl(210, 120%, 40%)")).toThrow(RangeError)
+})
+
+test("hslaColorStringToHslColorValue returns HSL values", () => {
+  expect(hslaColorStringToHslColorValue("hsla(210, 50%, 40%, 0.5)")).toEqual({ hue: 210, saturation: 0.5, lightness: 0.4, alpha: 0.5 })
+  expect(hslaColorStringToHslColorValue("hsla(0, 0%, 100%, 1)")).toEqual({ hue: 0, saturation: 0, lightness: 1, alpha: 1 })
+})
+
+test("hsvColorStringToHsvColorValue returns HSV values", () => {
+  expect(hsvColorStringToHsvColorValue("hsv(210, 66.67%, 60%)")).toEqual({ hue: 210, saturation: 0.666_7, value: 0.6, alpha: 1 })
+  expect(hsvColorStringToHsvColorValue("hsv(390, 50%, 60%)")).toEqual({ hue: 30, saturation: 0.5, value: 0.6, alpha: 1 })
+})
+
+test("hsvaColorStringToHsvColorValue returns HSV values", () => {
+  expect(hsvaColorStringToHsvColorValue("hsva(210, 66.67%, 60%, 0.5)")).toEqual({ hue: 210, saturation: 0.666_7, value: 0.6, alpha: 0.5 })
+  expect(hsvaColorStringToHsvColorValue("hsva(0, 0%, 100%, 1)")).toEqual({ hue: 0, saturation: 0, value: 1, alpha: 1 })
+  expect(() => hsvaColorStringToHsvColorValue("hsva(210, 66.67%, 60%, -0.1)")).toThrow(RangeError)
+})
+
+test("colorStringToSrgbColorValue folds supported string inputs into sRGB", () => {
+  expect(colorStringToSrgbColorValue("#336699")).toEqual({ red: 51, green: 102, blue: 153, alpha: 1 })
+  expect(colorStringToSrgbColorValue("hsl(210, 50%, 40%)")).toEqual({ red: 51, green: 102, blue: 153, alpha: 1 })
+  expect(colorStringToSrgbColorValue("hsv(210, 66.67%, 60%)")).toEqual({ red: 51, green: 102, blue: 153, alpha: 1 })
+  expect(colorStringToSrgbColorValue("rgb(51, 102, 153)")).toEqual({ red: 51, green: 102, blue: 153, alpha: 1 })
+  expect(() => colorStringToSrgbColorValue("foo(0, 0%, 0%)")).toThrow(TypeError)
+})

package/tests/unit/color/rgb/serialize.spec.ts

@@ -0,0 +1,46 @@
+import { expect, test } from "vitest"
+
+import {
+  hslColorValueToHslColorString,
+  hslColorValueToHslaColorString,
+  hsvColorValueToHsvColorString,
+  hsvColorValueToHsvaColorString,
+  srgbColorValueToHexColorString,
+  srgbColorValueToRgbColorString,
+  srgbColorValueToRgbaColorString,
+} from "#Source/color/index.ts"
+
+test("srgbColorValueToHexColorString serializes hex output", () => {
+  expect(srgbColorValueToHexColorString({ red: 51, green: 102, blue: 153, alpha: 0.5 })).toBe("#336699")
+  expect(srgbColorValueToHexColorString({ red: 51, green: 102, blue: 153, alpha: 0.5 }, { includeAlpha: true })).toBe("#33669980")
+})
+
+test("srgbColorValueToRgbColorString serializes rgb output", () => {
+  expect(srgbColorValueToRgbColorString({ red: 51, green: 102, blue: 153, alpha: 0.5 })).toBe("rgb(51, 102, 153)")
+  expect(srgbColorValueToRgbColorString({ red: 0, green: 0, blue: 0, alpha: 1 })).toBe("rgb(0, 0, 0)")
+})
+
+test("srgbColorValueToRgbaColorString serializes rgba output", () => {
+  expect(srgbColorValueToRgbaColorString({ red: 51, green: 102, blue: 153, alpha: 0.5 })).toBe("rgba(51, 102, 153, 0.5)")
+  expect(srgbColorValueToRgbaColorString({ red: 255, green: 255, blue: 255, alpha: 1 })).toBe("rgba(255, 255, 255, 1)")
+})
+
+test("hslColorValueToHslColorString serializes hsl output", () => {
+  expect(hslColorValueToHslColorString({ hue: 210, saturation: 0.5, lightness: 0.4, alpha: 0.5 })).toBe("hsl(210, 50%, 40%)")
+  expect(hslColorValueToHslColorString({ hue: 0, saturation: 0, lightness: 1, alpha: 1 })).toBe("hsl(0, 0%, 100%)")
+})
+
+test("hslColorValueToHslaColorString serializes hsla output", () => {
+  expect(hslColorValueToHslaColorString({ hue: 210, saturation: 0.5, lightness: 0.4, alpha: 0.5 })).toBe("hsla(210, 50%, 40%, 0.5)")
+  expect(hslColorValueToHslaColorString({ hue: 0, saturation: 0, lightness: 1, alpha: 1 })).toBe("hsla(0, 0%, 100%, 1)")
+})
+
+test("hsvColorValueToHsvColorString serializes hsv output", () => {
+  expect(hsvColorValueToHsvColorString({ hue: 210, saturation: 0.666_7, value: 0.6, alpha: 0.5 })).toBe("hsv(210, 66.67%, 60%)")
+  expect(hsvColorValueToHsvColorString({ hue: 0, saturation: 0, value: 1, alpha: 1 })).toBe("hsv(0, 0%, 100%)")
+})
+
+test("hsvColorValueToHsvaColorString serializes hsva output", () => {
+  expect(hsvColorValueToHsvaColorString({ hue: 210, saturation: 0.666_7, value: 0.6, alpha: 0.5 })).toBe("hsva(210, 66.67%, 60%, 0.5)")
+  expect(hsvColorValueToHsvaColorString({ hue: 0, saturation: 0, value: 1, alpha: 1 })).toBe("hsva(0, 0%, 100%, 1)")
+})