@versatiles/style 5.5.1 → 5.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatiles/style",
-  "version": "5.5.1",
+  "version": "5.6.0",
   "description": "Generate StyleJSON for MapLibre",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -41,27 +41,27 @@
   "devDependencies": {
     "@maplibre/maplibre-gl-native": "^6.0.0",
     "@maplibre/maplibre-gl-style-spec": "^23.1.0",
-    "@rollup/plugin-commonjs": "^28.0.2",
-    "@rollup/plugin-node-resolve": "^16.0.0",
+    "@rollup/plugin-commonjs": "^28.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.2",
     "@types/bin-pack": "^1.0.3",
     "@types/brace-expansion": "^1.1.2",
     "@types/inquirer": "^9.0.7",
     "@types/jest": "^29.5.14",
-    "@types/node": "^22.13.5",
+    "@types/node": "^22.13.10",
     "@types/tar-stream": "^3.1.3",
-    "@typescript-eslint/eslint-plugin": "^8.25.0",
-    "@typescript-eslint/parser": "^8.25.0",
-    "@versatiles/release-tool": "^2.2.4",
+    "@typescript-eslint/eslint-plugin": "^8.26.1",
+    "@typescript-eslint/parser": "^8.26.1",
+    "@versatiles/release-tool": "^2.4.1",
     "bin-pack": "^1.0.2",
-    "esbuild": "^0.25.0",
-    "eslint": "^9.21.0",
-    "inquirer": "^12.4.2",
+    "esbuild": "^0.25.1",
+    "eslint": "^9.22.0",
+    "inquirer": "^12.4.3",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "jest-ts-webcompat-resolver": "^1.0.0",
-    "rollup": "^4.34.8",
+    "rollup": "^4.35.0",
     "rollup-plugin-dts": "^6.1.1",
     "rollup-plugin-sourcemaps2": "^0.5.0",
     "sharp": "^0.33.5",
@@ -69,7 +69,7 @@
     "ts-jest": "^29.2.6",
     "ts-node": "^10.9.2",
     "tsx": "^4.19.3",
-    "typescript": "^5.7.3",
-    "typescript-eslint": "^8.25.0"
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.26.1"
   }
 }

package/src/color/abstract.ts

@@ -75,6 +75,10 @@ export abstract class Color {
 		return this.toRGB().tint(value, tintColor);
 	}
 
+	blend(value: number, blendColor: Color): RGB {
+		return this.toRGB().blend(value, blendColor);
+	}
+
 	setHue(value: number): HSV {
 		return this.toHSV().setHue(value);
 	}

package/src/color/rgb.test.ts

@@ -134,94 +134,62 @@ describe('RGB Class', () => {
 			return cb(new RGB(50, 150, 200, 0.8)).round().asArray();
 		}
 
-		describe('gamma', () => {
-			test('adjusts gamma correctly', () => {
-				expect(pc(c => c.gamma(2.2))).toStrictEqual([7, 79, 149, 0.8]);
-			});
-
-			test('clamps extreme gamma values', () => {
-				expect(pc(c => c.gamma(0.001))).toStrictEqual([255, 255, 255, 0.8]);
-				expect(pc(c => c.gamma(1000))).toStrictEqual([0, 0, 0, 0.8]);
-			});
+		test('adjusts gamma correctly', () => {
+			expect(pc(c => c.gamma(2.2))).toStrictEqual([7, 79, 149, 0.8]);
+			expect(pc(c => c.gamma(0.001))).toStrictEqual([255, 255, 255, 0.8]);
+			expect(pc(c => c.gamma(1000))).toStrictEqual([0, 0, 0, 0.8]);
 		});
 
-		describe('invert', () => {
-			test('inverts RGB values correctly', () => {
-				expect(pc(c => c.invert())).toStrictEqual([205, 105, 55, 0.8]);
-			});
+		test('inverts RGB values correctly', () => {
+			expect(pc(c => c.invert())).toStrictEqual([205, 105, 55, 0.8]);
 		});
 
-		describe('contrast', () => {
-			test('adjusts contrast correctly', () => {
-				expect(pc(c => c.contrast(1.5))).toStrictEqual([11, 161, 236, 0.8]);
-			});
-
-			test('clamps extreme contrast values', () => {
-				expect(pc(c => c.contrast(1e6))).toStrictEqual([0, 255, 255, 0.8]);
-				expect(pc(c => c.contrast(0))).toStrictEqual([128, 128, 128, 0.8]);
-			});
+		test('adjusts contrast correctly', () => {
+			expect(pc(c => c.contrast(1.5))).toStrictEqual([11, 161, 236, 0.8]);
+			expect(pc(c => c.contrast(1e6))).toStrictEqual([0, 255, 255, 0.8]);
+			expect(pc(c => c.contrast(0))).toStrictEqual([128, 128, 128, 0.8]);
 		});
 
-		describe('brightness', () => {
-			test('increases brightness correctly', () => {
-				expect(pc(c => c.brightness(0.5))).toStrictEqual([153, 203, 228, 0.8]);
-			});
-
-			test('decreases brightness correctly', () => {
-				expect(pc(c => c.brightness(-0.5))).toStrictEqual([25, 75, 100, 0.8]);
-			});
-
-			test('clamps brightness values', () => {
-				expect(pc(c => c.brightness(2))).toStrictEqual([255, 255, 255, 0.8]);
-				expect(pc(c => c.brightness(-2))).toStrictEqual([0, 0, 0, 0.8]);
-			});
+		test('increases brightness correctly', () => {
+			expect(pc(c => c.brightness(0.5))).toStrictEqual([153, 203, 228, 0.8]);
+			expect(pc(c => c.brightness(-0.5))).toStrictEqual([25, 75, 100, 0.8]);
+			expect(pc(c => c.brightness(2))).toStrictEqual([255, 255, 255, 0.8]);
+			expect(pc(c => c.brightness(-2))).toStrictEqual([0, 0, 0, 0.8]);
 		});
 
-		describe('tint', () => {
-			test('tints color correctly', () => {
-				const tintColor = new RGB(255, 0, 0);
-				expect(pc(c => c.tint(0.5, tintColor))).toStrictEqual([125, 100, 125, 0.8]);
-			});
-
-			test('handles extreme tint values', () => {
-				const tintColor = new RGB(255, 0, 0);
-				expect(pc(c => c.tint(1, tintColor))).toStrictEqual([200, 50, 50, 0.8]);
-				expect(pc(c => c.tint(0, tintColor))).toStrictEqual([50, 150, 200, 0.8]);
-			});
+		test('tints color correctly', () => {
+			const tintColor = new RGB(255, 0, 0);
+			expect(pc(c => c.tint(0.5, tintColor))).toStrictEqual([125, 100, 125, 0.8]);
+			expect(pc(c => c.tint(1, tintColor))).toStrictEqual([200, 50, 50, 0.8]);
+			expect(pc(c => c.tint(0, tintColor))).toStrictEqual([50, 150, 200, 0.8]);
 		});
 
-		describe('lighten', () => {
-			test('lightens the color correctly', () => {
-				expect(pc(c => c.lighten(0.5))).toStrictEqual([153, 203, 228, 0.8]);
-			});
-
-			test('clamps lighten ratio', () => {
-				expect(pc(c => c.lighten(2))).toStrictEqual([255, 255, 255, 0.8]);
-			});
+		test('blends color correctly', () => {
+			const blendColor = new RGB(255, 0, 0);
+			expect(pc(c => c.blend(0.2, blendColor))).toStrictEqual([91, 120, 160, 0.8]);
+			expect(pc(c => c.blend(0.5, blendColor))).toStrictEqual([153, 75, 100, 0.8]);
+			expect(pc(c => c.blend(0.8, blendColor))).toStrictEqual([214, 30, 40, 0.8]);
+			expect(pc(c => c.blend(1, blendColor))).toStrictEqual([255, 0, 0, 0.8]);
+			expect(pc(c => c.blend(0, blendColor))).toStrictEqual([50, 150, 200, 0.8]);
 		});
 
-		describe('darken', () => {
-			test('darkens the color correctly', () => {
-				expect(pc(c => c.darken(0.5))).toStrictEqual([25, 75, 100, 0.8]);
-			});
-
-			test('clamps darken ratio', () => {
-				expect(pc(c => c.darken(1))).toStrictEqual([0, 0, 0, 0.8]);
-				expect(pc(c => c.darken(2))).toStrictEqual([0, 0, 0, 0.8]);
-			});
+		test('lightens the color correctly', () => {
+			expect(pc(c => c.lighten(0.5))).toStrictEqual([153, 203, 228, 0.8]);
+			expect(pc(c => c.lighten(2))).toStrictEqual([255, 255, 255, 0.8]);
 		});
 
-		describe('fade', () => {
-			test('reduces alpha correctly', () => {
-				expect(pc(c => c.fade(0.5))).toStrictEqual([50, 150, 200, 0.4]);
-			});
+		test('darkens the color correctly', () => {
+			expect(pc(c => c.darken(0.5))).toStrictEqual([25, 75, 100, 0.8]);
+			expect(pc(c => c.darken(1))).toStrictEqual([0, 0, 0, 0.8]);
+			expect(pc(c => c.darken(2))).toStrictEqual([0, 0, 0, 0.8]);
+		});
 
-			test('handles extreme fade values', () => {
-				expect(pc(c => c.fade(1))).toStrictEqual([50, 150, 200, 0]);
+		test('fades color correctly', () => {
+			expect(pc(c => c.fade(0.5))).toStrictEqual([50, 150, 200, 0.4]);
+			expect(pc(c => c.fade(1))).toStrictEqual([50, 150, 200, 0]);
 
-				const fullyOpaque = new RGB(50, 150, 200, 1);
-				expect(fullyOpaque.fade(0).asArray()).toStrictEqual([50, 150, 200, 1]);
-			});
+			const fullyOpaque = new RGB(50, 150, 200, 1);
+			expect(fullyOpaque.fade(0).asArray()).toStrictEqual([50, 150, 200, 1]);
 		});
 	});
 });

package/src/color/rgb.ts

@@ -224,6 +224,17 @@ export class RGB extends Color {
 		)
 	}
 
+	blend(value: number, blendColor: Color): RGB {
+		value = clamp(value ?? 0, 0, 1);
+		const rgbNew = blendColor.toRGB();
+		return new RGB(
+			this.r * (1 - value) + value * rgbNew.r,
+			this.g * (1 - value) + value * rgbNew.g,
+			this.b * (1 - value) + value * rgbNew.b,
+			this.a
+		);
+	}
+
 	lighten(ratio: number): RGB {
 		return new RGB(
 			clamp(255 - (255 - this.r) * (1 - ratio), 0, 255),

package/src/color/utils.ts

@@ -1,11 +1,17 @@
 
 
-export function clamp(num: number, min: number, max: number): number {
-	return Math.min(Math.max(min, num), max);
+export function clamp(value: number, min: number, max: number): number {
+	if (value == null || isNaN(value)) return min;
+	if (value < min) return min;
+	if (value > max) return max;
+	return value;
 }
 
-export function mod(num: number, max: number): number {
-	return ((num % max) + max) % max;
+export function mod(value: number, max: number): number {
+	value = value % max;
+	if (value < 0) value += max;
+	if (value == 0) return 0;
+	return value;
 }
 
 export function formatFloat(num: number, precision: number): string {

package/src/guess_style/guess_style.test.ts

@@ -61,7 +61,7 @@ describe('guessStyle', () => {
 	it('should build shortbread vector styles', () => {
 		const style = guessStyle({ tiles, vector_layers: vectorLayersShortbread }, { baseUrl: 'http://example.com' });
 
-		expect(style.layers.length).toBe(297);
+		expect(style.layers.length).toBe(309);
 		style.layers = [];
 
 		expect(style).toStrictEqual({

package/src/shortbread/layers.ts

@@ -193,7 +193,6 @@ export function getShortbreadLayers(option: { readonly language: Language }): Ma
 				});
 
 				// no links
-				const noDrivewayExpression: LegacyFilterSpecification = ['!=', 'service', 'driveway'];
 				['track', 'pedestrian', 'service', 'living_street', 'residential', 'unclassified'].forEach(t => {
 					results.push({
 						id: prefix + 'street-' + t.replace(/_/g, '') + suffix,
@@ -202,7 +201,6 @@ export function getShortbreadLayers(option: { readonly language: Language }): Ma
 						filter: ['all',
 							['==', 'kind', t],
 							...filter,
-							...(t === 'service') ? [noDrivewayExpression] : [], // ignore driveways
 						],
 					});
 				});
@@ -217,7 +215,6 @@ export function getShortbreadLayers(option: { readonly language: Language }): Ma
 							['==', 'kind', t],
 							['==', 'bicycle', 'designated'],
 							...filter,
-							...(t === 'service') ? [noDrivewayExpression] : [], // ignore driveways
 						],
 					});
 				});
@@ -254,8 +251,11 @@ export function getShortbreadLayers(option: { readonly language: Language }): Ma
 
 			// separate outline for trains
 			[':outline', ''].forEach(suffix => {
-				// transport
-				['rail', 'light_rail', 'subway', 'narrow_gauge', 'tram', 'funicular', 'monorail', 'bus_guideway', 'busway'].reverse().forEach((t) => {
+
+				// with service distinction
+				['rail', 'light_rail', 'subway', 'narrow_gauge', 'tram'].reverse().forEach((t) => {
+
+					// main rail
 					results.push({
 						id: prefix + 'transport-' + t.replace(/_/g, '') + suffix,
 						type: 'line',
@@ -266,6 +266,31 @@ export function getShortbreadLayers(option: { readonly language: Language }): Ma
 							...filter,
 						],
 					});
+
+					// service rail (crossover, siding, spur, yard)
+					results.push({
+						id: prefix + 'transport-' + t.replace(/_/g, '') + '-service' + suffix,
+						type: 'line',
+						'source-layer': 'streets',
+						filter: ['all',
+							['in', 'kind', t],
+							['has', 'service'],
+							...filter,
+						],
+					});
+				});
+
+				// other transport
+				['funicular', 'monorail', 'bus_guideway', 'busway'].reverse().forEach((t) => {
+					results.push({
+						id: prefix + 'transport-' + t.replace(/_/g, '') + suffix,
+						type: 'line',
+						'source-layer': 'streets',
+						filter: ['all',
+							['in', 'kind', t],
+							...filter,
+						],
+					});
 				});
 
 				if (c === 'street') {

package/src/style_builder/recolor.test.ts

@@ -15,6 +15,8 @@ describe('recolor', () => {
 				brightness: 0,
 				tint: 0,
 				tintColor: '#FF0000',
+				blend: 0,
+				blendColor: '#000000',
 			});
 		});
 	});
@@ -188,6 +190,50 @@ describe('recolor', () => {
 			expect(colors2string(colors)).toBe('7766DD00,0033EE55,1100FFAA,221188,665C99');
 		});
 	});
+
+	describe('blend', () => {
+		it('should not blend at all', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0, blendColor: '#F00' });
+			expect(colors2string(colors)).toBe('FFAA5500,00FFAA55,5500FFAA,AA5500,AA7755');
+		});
+
+		it('should blend a little bit red', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0.5, blendColor: '#F00' });
+			expect(colors2string(colors)).toBe('FF552B00,80805555,AA0080AA,D52B00,D53C2B');
+		});
+
+		it('should blend a little bit yellow', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0.2, blendColor: '#FF0' });
+			expect(colors2string(colors)).toBe('FFBB4400,33FF8855,7733CCAA,BB7700,BB9244');
+		});
+
+		it('should blend a little bit green', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0.2, blendColor: '#0F0' });
+			expect(colors2string(colors)).toBe('CCBB4400,00FF8855,4433CCAA,887700,889244');
+		});
+
+		it('should blend a little bit blue', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0.2, blendColor: '#00F' });
+			expect(colors2string(colors)).toBe('CC887700,00CCBB55,4400FFAA,884433,885F77');
+		});
+
+		it('should blend strongly orange', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0.8, blendColor: '#F80' });
+			expect(colors2string(colors)).toBe('FF8F1100,CCA02255,DD6D33AA,EE7E00,EE8511');
+		});
+
+		it('should blend a strongly blue', () => {
+			const colors = getTestColors();
+			recolorArray(colors, { blend: 0.8, blendColor: '#00F' });
+			expect(colors2string(colors)).toBe('3322DD00,0033EE55,1100FFAA,2211CC,2218DD');
+		});
+	});
 });
 
 describe('recolorObject', () => {

package/src/style_builder/recolor.ts

@@ -1,31 +1,124 @@
+/**
+ * Module for applying various color transformations such as hue rotation, saturation, contrast, brightness,
+ * tinting, and blending. These transformations are defined through the `RecolorOptions` interface.
+ */
+
 import { Color } from '../color/index.js';
 
+/**
+ * Configuration options for recoloring all map colors.
+ * 
+ * The transformations (if specified) are done in the following order:
+ * 1. [Invert brightness](#invertbrightness)
+ * 2. [Rotate hue](#rotate)
+ * 3. [Saturate](#saturate)
+ * 4. [Gamma correction](#gamma)
+ * 5. [Contrast adjustment](#contrast)
+ * 6. [Brightness adjustment](#brightness)
+ * 7. [Tinting](#tint)
+ * 8. [Blending](#blend)
+ *
+ * Usage Examples
+ *
+ * ```typescript
+ * const style = VersaTilesStyle.colorful({
+ *    recolor: {
+ *       rotate: 180,
+ *       saturate: 0.5,
+ *       brightness: 0.2,
+ *    }
+ * };
+ * ```
+ * 
+ * If you want do make you map simply brighter or darker, you can use the `blend` option:
+ * ```typescript
+ * const style = VersaTilesStyle.colorful({
+ *    recolor: {
+ *       blend: 0.5,
+ *       blendColor: '#000000', // to blend all colors with black
+ *       // or blendColor: '#FFFFFF', // to blend all colors with white
+ *    }
+ * };
+ * ```
+ * 
+ */
+
 export interface RecolorOptions {
-	// If true, inverts all colors.
+	/** 
+	 * If true, inverts all colors' brightness.
+	 * See also {@link HSL.invertLuminosity}
+	*/
 	invertBrightness?: boolean;
 
-	// Rotate the hue of all colors (in degrees).
+	/** 
+	 * Rotate the hue of all colors in degrees (0-360).
+	 * See also {@link HSL.rotateHue}
+	 */
 	rotate?: number;
 
-	// Adjusts the saturation level of all colors. Positive values increase saturation, negative values decrease it.
+	/** 
+	 * Adjust the saturation level. Positive values increase, negative values decrease saturation.
+	 * |value|effect           |
+	 * |----:|-----------------|
+	 * |   -1|grayscale        |
+	 * |    0|no effect        |
+	 * |    1|double saturation|
+	 * 
+	 * See also {@link HSL.saturate}
+	 */
 	saturate?: number;
 
-	// Adjusts the gamma of all colors. Affects the brightness in a non-linear manner.
+	/**
+	 * Adjust the gamma (non-linear brightness adjustment).  
+	 * Defaults to 1.   
+	 * See also {@link RGB.gamma}
+	 */
 	gamma?: number;
 
-	// Adjusts the contrast of all colors. Higher values produce more contrast.
+	/**
+	 * Adjust the contrast level.  
+	 * Values > 1 increase contrast, values < 1 decrease it.  
+	 * Defaults to 1.  
+	 * See also {@link RGB.contrast}
+	 */
 	contrast?: number;
 
-	// Adjusts the brightness of all colors. Positive values make it brighter, negative values make it darker.
+	/**
+	 * Adjust the brightness level.  
+	 * Positive values make it brighter, negative values make it darker.  
+	 * Defaults to 0.  
+	 *	See also {@link RGB.brightness}
+	 */
 	brightness?: number;
 
-	// Specifies the intensity of the tinting effect. Ranges from 0 (no effect) to 1 (full effect).
+	/**
+	 * Intensity of the tinting effect (0 = none, 1 = full effect). 
+	 * See also {@link RGB.tint}
+	 */
 	tint?: number;
 
-	// Specifies the color used for tinting, in a string format (e.g., '#FF0000').
+	/**
+	 * The tinting color in hex format (default: '#FF0000'). 
+	 * See also {@link RGB.tint}
+	 */
 	tintColor?: string;
+
+	/**
+	 * Intensity of the blending effect (0 = none, 1 = full effect). 
+	 * See also {@link RGB.blend}
+	 */
+	blend?: number;
+
+	/**
+	 * The blending color in hex format (default: '#000000'). 
+	 *	See also {@link RGB.blend}
+	 */
+	blendColor?: string;
 }
 
+/**
+ * Returns the default recolor settings.
+ */
 export function getDefaultRecolorFlags(): RecolorOptions {
 	return {
 		invertBrightness: false,
@@ -36,30 +129,49 @@ export function getDefaultRecolorFlags(): RecolorOptions {
 		brightness: 0,
 		tint: 0,
 		tintColor: '#FF0000',
+		blend: 0,
+		blendColor: '#000000',
 	};
 }
 
+/**
+ * Checks if the given options object contains any active recolor transformations.
+ * @param opt The recolor options to validate.
+ */
 function isValidRecolorOptions(opt?: RecolorOptions): opt is RecolorOptions {
 	if (!opt) return false;
-	if ((opt.invertBrightness != null) && opt.invertBrightness) return true;
-	if ((opt.rotate != null) && (opt.rotate !== 0)) return true;
-	if ((opt.saturate != null) && (opt.saturate !== 0)) return true;
-	if ((opt.gamma != null) && (opt.gamma !== 1)) return true;
-	if ((opt.contrast != null) && (opt.contrast !== 1)) return true;
-	if ((opt.brightness != null) && (opt.brightness !== 0)) return true;
-	if ((opt.tint != null) && (opt.tint !== 0)) return true;
-	if ((opt.tintColor != null) && (opt.tintColor !== '#FF0000')) return true;
-	return false;
+	return (
+		opt.invertBrightness ||
+		(opt.rotate != null && opt.rotate !== 0) ||
+		(opt.saturate != null && opt.saturate !== 0) ||
+		(opt.gamma != null && opt.gamma !== 1) ||
+		(opt.contrast != null && opt.contrast !== 1) ||
+		(opt.brightness != null && opt.brightness !== 0) ||
+		(opt.tint != null && opt.tint !== 0) ||
+		(opt.tintColor != null && opt.tintColor !== '#FF0000') ||
+		(opt.blend != null && opt.blend !== 0) ||
+		(opt.blendColor != null && opt.blendColor !== '#000000')
+	);
 }
 
+/**
+ * Applies recoloring transformations to a record of colors.
+ * @param colors A record of color names to `Color` instances.
+ * @param opt Optional recolor options.
+ */
 export function recolorObject(colors: Record<string, Color>, opt?: RecolorOptions): void {
 	if (!isValidRecolorOptions(opt)) return;
 
-	for (const [k, c] of Object.entries(colors)) {
-		colors[k] = recolor(c, opt);
+	for (const [key, color] of Object.entries(colors)) {
+		colors[key] = recolor(color, opt);
 	}
 }
 
+/**
+ * Applies recoloring transformations to an array of colors.
+ * @param colors An array of `Color` instances.
+ * @param opt Optional recolor options.
+ */
 export function recolorArray(colors: Color[], opt?: RecolorOptions): void {
 	if (!isValidRecolorOptions(opt)) return;
 
@@ -68,43 +180,58 @@ export function recolorArray(colors: Color[], opt?: RecolorOptions): void {
 	}
 }
 
+/**
+ * Caches recolored colors to optimize performance.
+ */
 export class CachedRecolor {
 	private readonly skip: boolean;
-
 	private readonly opt?: RecolorOptions;
-
 	private readonly cache: Map<string, Color>;
 
+	/**
+	 * Creates a cached recolor instance.
+	 * @param opt Optional recolor options.
+	 */
 	public constructor(opt?: RecolorOptions) {
 		this.skip = !isValidRecolorOptions(opt);
 		this.cache = new Map();
 		this.opt = opt;
 	}
 
+	/**
+	 * Applies cached recoloring to a given color.
+	 * @param color The color to recolor.
+	 * @returns The recolored color, either from cache or newly computed.
+	 */
 	public do(color: Color): Color {
 		if (this.skip) return color;
 
 		const key = color.asHex();
+		if (this.cache.has(key)) return this.cache.get(key)!;
 
-		const result = this.cache.get(key);
-		if (result) return result;
-
-		color = recolor(color, this.opt);
-		this.cache.set(key, color);
-		return color;
+		const recolored = recolor(color, this.opt);
+		this.cache.set(key, recolored);
+		return recolored;
 	}
 }
 
+/**
+ * Applies the specified recoloring transformations to a single color.
+ * @param color The original color.
+ * @param opt Optional recolor options.
+ * @returns A new `Color` instance with applied transformations.
+ */
 export function recolor(color: Color, opt?: RecolorOptions): Color {
 	if (!isValidRecolorOptions(opt)) return color;
 
-	if (opt.invertBrightness ?? false) color = color.invertLuminosity();
-	if ((opt.rotate !== undefined) && (opt.rotate !== 0)) color = color.rotateHue(opt.rotate);
-	if ((opt.saturate !== undefined) && (opt.saturate !== 0)) color = color.saturate(opt.saturate);
-	if ((opt.gamma !== undefined) && (opt.gamma !== 1)) color = color.gamma(opt.gamma);
-	if ((opt.contrast !== undefined) && (opt.contrast !== 1)) color = color.contrast(opt.contrast);
-	if ((opt.brightness !== undefined) && (opt.brightness !== 0)) color = color.brightness(opt.brightness);
-	if ((opt.tint !== undefined) && (opt.tintColor !== undefined) && (opt.tint !== 0)) color = color.tint(opt.tint, Color.parse(opt.tintColor));
+	if (opt.invertBrightness) color = color.invertLuminosity();
+	if (opt.rotate) color = color.rotateHue(opt.rotate);
+	if (opt.saturate) color = color.saturate(opt.saturate);
+	if (opt.gamma != null && opt.gamma != 1) color = color.gamma(opt.gamma);
+	if (opt.contrast != null && opt.contrast != 1) color = color.contrast(opt.contrast);
+	if (opt.brightness) color = color.brightness(opt.brightness);
+	if (opt.tint && opt.tintColor != null) color = color.tint(opt.tint, Color.parse(opt.tintColor));
+	if (opt.blend && opt.blendColor != null) color = color.blend(opt.blend, Color.parse(opt.blendColor));
 
 	return color;
 }

package/src/style_builder/style_builder.test.ts

@@ -80,6 +80,8 @@ describe('StyleBuilder', () => {
 				saturate: 0,
 				tint: 0,
 				tintColor: '#FF0000',
+				blend: 0,
+				blendColor: '#000000',
 			},
 			sprite: '',
 			tiles: [],