@versatiles/style 5.8.4 → 5.9.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@versatiles/style",
-  "version": "5.8.4",
+  "version": "5.9.0",
   "description": "Generate StyleJSON for MapLibre",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "devEngines": {
     "runtime": {
       "name": "node",
-      "version": ">=20.0.0 <24.0.0"
+      "version": ">= 20.0.0"
     }
   },
   "scripts": {
@@ -48,8 +48,8 @@
     "src/*"
   ],
   "devDependencies": {
-    "@maplibre/maplibre-gl-native": "^6.2.0",
-    "@maplibre/maplibre-gl-style-spec": "^24.3.1",
+    "@maplibre/maplibre-gl-native": "^6.3.0",
+    "@maplibre/maplibre-gl-style-spec": "^24.4.1",
     "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^0.4.4",
@@ -57,26 +57,26 @@
     "@types/bin-pack": "^1.0.3",
     "@types/brace-expansion": "^1.1.2",
     "@types/inquirer": "^9.0.9",
-    "@types/node": "^24.10.2",
+    "@types/node": "^25.2.1",
     "@types/tar-stream": "^3.1.4",
-    "@typescript-eslint/eslint-plugin": "^8.49.0",
-    "@typescript-eslint/parser": "^8.49.0",
-    "@versatiles/release-tool": "^2.5.0",
-    "@vitest/coverage-v8": "^4.0.15",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "@versatiles/release-tool": "^2.7.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "bin-pack": "^1.0.2",
-    "esbuild": "^0.27.1",
-    "eslint": "^9.39.1",
+    "esbuild": "^0.27.3",
+    "eslint": "^9.39.2",
     "husky": "^9.1.7",
-    "inquirer": "^13.0.2",
-    "prettier": "^3.7.4",
-    "rollup": "^4.53.3",
+    "inquirer": "^13.2.2",
+    "prettier": "^3.8.1",
+    "rollup": "^4.57.1",
     "rollup-plugin-dts": "^6.3.0",
     "rollup-plugin-sourcemaps2": "^0.5.4",
     "sharp": "^0.34.5",
     "tar-stream": "^3.1.7",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.49.0",
-    "vitest": "^4.0.15"
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^4.0.18"
   }
 }

package/src/color/hsl.test.ts

@@ -38,10 +38,9 @@ describe('HSL Class', () => {
 			expect(color2.asString()).toBe('hsla(120,50%,50%,0.5)');
 		});
 
-		it('asHSL and toHSL should return the same instance', () => {
+		it('asHSL should return a clone', () => {
 			const color = new HSL(120, 50, 50);
 			expect(color.asHSL()).toStrictEqual(color);
-			expect(color.toHSL()).toStrictEqual(color);
 		});
 
 		it('asHSV should correctly convert HSL to HSV', () => {

package/src/color/hsl.ts

@@ -87,14 +87,6 @@ export class HSL extends Color {
 		return this.clone();
 	}
 
-	/**
-	 * Returns the current HSL color.
-	 * @returns The current HSL color.
-	 */
-	toHSL(): HSL {
-		return this;
-	}
-
 	/**
 	 * Converts the HSL color to an HSV color.
 	 * @returns A new HSV color representing the same color.

package/src/color/hsv.ts

@@ -85,7 +85,7 @@ export class HSV extends Color {
 		const v = this.v / 100;
 		const k = (2 - s) * v;
 		const q = k < 1 ? k : 2 - k;
-		return new HSL(this.h, q == 0 ? 0 : (100 * s * v) / q, (100 * k) / 2, this.a);
+		return new HSL(this.h, q === 0 ? 0 : (100 * s * v) / q, (100 * k) / 2, this.a);
 	}
 
 	/**

package/src/color/index.test.ts

@@ -73,7 +73,9 @@ describe('Color.parse', () => {
 	});
 
 	it('throws an error for unsupported formats', () => {
-		expect(() => Color.parse('invalid color string')).toThrow('Unknown color format: invalid color string');
+		expect(() => Color.parse('invalid color string')).toThrow(
+			'Color.parse: Unknown color format "invalid color string"'
+		);
 	});
 });
 
@@ -97,3 +99,89 @@ describe('Exported Module', () => {
 		expect(module.Color).toBe(Color);
 	});
 });
+
+describe('Color Transformation Methods', () => {
+	it('gamma() applies gamma correction', () => {
+		const color = Color.parse('#808080');
+		expect(color.gamma(2.2).asString()).toBe('rgb(56,56,56)');
+	});
+
+	it('gamma() works from HSL', () => {
+		const hsl = new HSL(120, 50, 50, 1);
+		expect(hsl.gamma(2.2).asString()).toBe('rgb(12,135,12)');
+	});
+
+	it('contrast() adjusts contrast', () => {
+		const color = Color.parse('#FF8040');
+		expect(color.contrast(1.5).asString()).toBe('rgb(255,128,32)');
+	});
+
+	it('contrast() works from HSV', () => {
+		const hsv = new HSV(180, 50, 50, 1);
+		expect(hsv.contrast(1.5).asString()).toBe('rgb(32,128,128)');
+	});
+
+	it('brightness() works from HSL', () => {
+		const hsl = new HSL(240, 100, 50, 1);
+		expect(hsl.brightness(0.3).asString()).toBe('rgb(77,77,255)');
+	});
+
+	it('lighten() works from HSL', () => {
+		const hsl = new HSL(0, 100, 30, 1);
+		expect(hsl.lighten(0.2).asString()).toBe('rgb(173,51,51)');
+	});
+
+	it('darken() works from HSV', () => {
+		const hsv = new HSV(60, 100, 80, 1);
+		expect(hsv.darken(0.3).asString()).toBe('rgb(143,143,0)');
+	});
+
+	it('tint() blends with a tint color', () => {
+		const color = Color.parse('#FF0000');
+		const tintColor = Color.parse('#0000FF');
+		expect(color.tint(0.5, tintColor).asString()).toBe('rgb(128,0,128)');
+	});
+
+	it('tint() works from HSL', () => {
+		const hsl = new HSL(0, 100, 50, 1);
+		const tintColor = new HSL(120, 100, 50, 1);
+		expect(hsl.tint(0.5, tintColor).asString()).toBe('rgb(128,128,0)');
+	});
+
+	it('blend() blends with another color', () => {
+		const color1 = Color.parse('#FF0000');
+		const color2 = Color.parse('#0000FF');
+		expect(color1.blend(0.5, color2).asString()).toBe('rgb(128,0,128)');
+	});
+
+	it('blend() works from HSV', () => {
+		const hsv1 = new HSV(0, 100, 100, 1);
+		const hsv2 = new HSV(240, 100, 100, 1);
+		expect(hsv1.blend(0.3, hsv2).asString()).toBe('rgb(179,0,77)');
+	});
+
+	it('setHue() changes the hue', () => {
+		const color = Color.parse('#FF0000');
+		expect(color.setHue(180).asString()).toBe('hsl(180,100%,50%)');
+	});
+
+	it('invertLuminosity() inverts from HSV', () => {
+		const hsv = new HSV(200, 50, 60, 1);
+		expect(hsv.invertLuminosity().asString()).toBe('hsl(200,33%,55%)');
+	});
+
+	it('rotateHue() rotates from RGB', () => {
+		const rgb = new RGB(255, 0, 0, 1);
+		expect(rgb.rotateHue(120).asString()).toBe('hsl(120,100%,50%)');
+	});
+
+	it('saturate() increases saturation from HSV', () => {
+		const hsv = new HSV(100, 30, 70, 1);
+		expect(hsv.saturate(1.5).asString()).toBe('hsl(100,65%,60%)');
+	});
+
+	it('invert() inverts from HSL', () => {
+		const hsl = new HSL(180, 100, 50, 1);
+		expect(hsl.invert().asString()).toBe('rgb(255,0,0)');
+	});
+});

package/src/color/index.ts

@@ -20,7 +20,9 @@ Color.parse = function (input: string | Color): Color {
 		case 'hsla(':
 			return HSL.parse(input);
 		default:
-			throw Error('Unknown color format: ' + input);
+			throw new Error(
+				`Color.parse: Unknown color format "${input}". Expected formats: "#RRGGBB", "#RGB", "rgb(...)", "rgba(...)", "hsl(...)", or "hsla(...)".`
+			);
 	}
 };
 

package/src/color/random.test.ts

@@ -42,6 +42,60 @@ describe('RandomColor', () => {
 			expect(t({ seed: 'testSeed' })).toBe('hsl(185,90%,23%)');
 		});
 
+		it('generates light colors with luminosity: "light"', () => {
+			const color = randomColor({ seed: 'lightSeed', luminosity: 'light' });
+			const hsv = color.asArray();
+			// Light colors should have higher brightness values
+			expect(hsv[2]).toBeGreaterThan(50);
+			expect(color).toBeInstanceOf(HSV);
+		});
+
+		it('generates random luminosity colors with luminosity: "random"', () => {
+			const color = randomColor({ seed: 'randomSeed', luminosity: 'random' });
+			const hsv = color.asArray();
+			// Random luminosity can be anywhere from 0-100
+			expect(hsv[2]).toBeGreaterThanOrEqual(0);
+			expect(hsv[2]).toBeLessThanOrEqual(100);
+			expect(color).toBeInstanceOf(HSV);
+		});
+
+		it('generates light saturation with luminosity: "light"', () => {
+			// Test light luminosity affects saturation picking
+			const color1 = randomColor({ seed: 'lightTest1', luminosity: 'light', hue: 'blue' });
+			const color2 = randomColor({ seed: 'lightTest2', luminosity: 'light', hue: 'green' });
+			expect(color1).toBeInstanceOf(HSV);
+			expect(color2).toBeInstanceOf(HSV);
+		});
+
+		it('generates colors with various saturation options', () => {
+			const weak = randomColor({ seed: 'satTest', saturation: 'weak' });
+			const strong = randomColor({ seed: 'satTest', saturation: 'strong' });
+
+			expect(weak).toBeInstanceOf(HSV);
+			expect(strong).toBeInstanceOf(HSV);
+			// Strong saturation should have higher saturation values
+			expect(strong.s).toBeGreaterThan(80);
+		});
+
+		it('generates colors with all hue name options', () => {
+			const hues: Array<string | number> = [
+				'red',
+				'orange',
+				'yellow',
+				'green',
+				'blue',
+				'purple',
+				'pink',
+				'monochrome',
+				180,
+			];
+
+			hues.forEach((hue) => {
+				const color = randomColor({ seed: `hue-${hue}`, hue });
+				expect(color).toBeInstanceOf(HSV);
+			});
+		});
+
 		it('consistent color generation with a seed', () => {
 			const color1 = randomColor({ seed: 'consistentSeed' });
 			const color2 = randomColor({ seed: 'consistentSeed' });

package/src/color/random.ts

@@ -263,5 +263,7 @@ function getColorInfo(hue: number): ColorInfo {
 			return color;
 		}
 	}
-	throw Error('Color hue value not found');
+	throw new Error(
+		`getColorInfo: No color info found for hue value ${hue}. This indicates a gap in the color dictionary hue ranges.`
+	);
 }

package/src/color/rgb.test.ts

@@ -84,10 +84,9 @@ describe('RGB Class', () => {
 			expect(RGB.parse('#FF0080').asHSV().round().asArray()).toStrictEqual([330, 100, 100, 1]);
 		});
 
-		it('asRGB and toRGB return the same instance or clone', () => {
+		it('asRGB returns a clone', () => {
 			const color = new RGB(255, 128, 64, 0.5);
 			expect(color.asRGB()).toStrictEqual(color);
-			expect(color.toRGB()).toStrictEqual(color);
 		});
 
 		it('handles black correctly', () => {
@@ -182,6 +181,8 @@ describe('RGB Class', () => {
 			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]);
+			expect(pc((c) => c.tint(-1, tintColor))).toStrictEqual([50, 150, 200, 0.8]);
+			expect(pc((c) => c.tint(2, tintColor))).toStrictEqual([200, 50, 50, 0.8]);
 		});
 
 		it('blends color correctly', () => {
@@ -191,6 +192,8 @@ describe('RGB Class', () => {
 			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]);
+			expect(pc((c) => c.blend(-1, blendColor))).toStrictEqual([50, 150, 200, 0.8]);
+			expect(pc((c) => c.blend(2, blendColor))).toStrictEqual([255, 0, 0, 0.8]);
 		});
 
 		it('lightens the color correctly', () => {

package/src/color/rgb.ts

@@ -181,15 +181,6 @@ export class RGB extends Color {
 		return this.clone();
 	}
 
-	/**
-	 * Returns the RGB color.
-	 *
-	 * @returns The current RGB instance.
-	 */
-	toRGB(): RGB {
-		return this;
-	}
-
 	/**
 	 * Parses a string or Color instance into an RGB color.
 	 *

package/src/color/utils.ts

@@ -8,7 +8,7 @@ export function clamp(value: number, min: number, max: number): number {
 export function mod(value: number, max: number): number {
 	value = value % max;
 	if (value < 0) value += max;
-	if (value == 0) return 0;
+	if (value === 0) return 0;
 	return value;
 }
 

package/src/guess_style/guess_style.ts

@@ -58,7 +58,9 @@ export function guessStyle(tileJSON: TileJSONSpecification, options?: GuessStyle
 		tileJSON.tiles = tileJSON.tiles.map((url) => resolveUrl(baseUrl, url));
 	}
 
-	if (!isTileJSONSpecification(tileJSON)) throw Error('Invalid TileJSON specification');
+	if (!isTileJSONSpecification(tileJSON)) {
+		throw new Error('guessStyle: Invalid TileJSON specification (this error should never be reached)');
+	}
 
 	let style: StyleSpecification;
 	if (isRasterTileJSONSpecification(tileJSON)) {

package/src/index.test.ts

@@ -110,7 +110,7 @@ describe('exports', () => {
 	it('should export styles', () => {
 		type something = Record<string, unknown>;
 		expect(typeof lib.styles).toBe('object');
-		const styleNames = ['colorful', 'eclipse', 'graybeard', 'neutrino', 'shadow'];
+		const styleNames = ['colorful', 'eclipse', 'graybeard', 'neutrino', 'shadow', 'satellite'];
 		for (const name of styleNames) {
 			expect(typeof (lib as something)[name]).toBe('function');
 			expect(typeof (lib.styles as something)[name]).toBe('function');

package/src/index.ts

@@ -80,14 +80,24 @@
  * @module
  */
 
-export { colorful, eclipse, graybeard, neutrino, shadow, type StyleBuilderFunction } from './styles/index.js';
-import { colorful, eclipse, graybeard, neutrino, shadow } from './styles/index.js';
+export {
+	colorful,
+	eclipse,
+	graybeard,
+	neutrino,
+	shadow,
+	satellite,
+	type StyleBuilderFunction,
+	type SatelliteStyleOptions,
+} from './styles/index.js';
+import { colorful, eclipse, graybeard, neutrino, shadow, satellite } from './styles/index.js';
 export const styles = {
 	colorful,
 	eclipse,
 	graybeard,
 	shadow,
 	neutrino,
+	satellite,
 };
 
 export type { GuessStyleOptions } from './guess_style/index.js';

package/src/lib/utils.test.ts

@@ -85,7 +85,7 @@ describe('isBasicType', () => {
 	});
 
 	it('throws an error for unsupported types like functions', () => {
-		expect(() => isBasicType(() => true)).toThrow('unknown type: function');
+		expect(() => isBasicType(() => true)).toThrow('isBasicType: Unknown type "function"');
 	});
 });
 
@@ -123,6 +123,89 @@ describe('deepMerge', () => {
 		const source = { a: { b: 1 } };
 		expect(() => deepMerge(target, source)).toThrow('Not implemented yet: "function" case');
 	});
+
+	it('merges multiple source objects', () => {
+		const target = { a: 1, b: 2, c: 3 };
+		const source1 = { b: 10, d: 4 };
+		const source2 = { c: 20, e: 5 };
+		const result = deepMerge(target, source1, source2);
+		expect(result).toEqual({ a: 1, b: 10, c: 20, d: 4, e: 5 });
+	});
+
+	it('handles undefined values in source', () => {
+		const target = { a: 1, b: 2 };
+		const source = { a: undefined, c: 3 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual({ a: undefined, b: 2, c: 3 });
+	});
+
+	it('overwrites with null when target is a basic type', () => {
+		const target = { a: 1, b: 'string' };
+		const source = { a: null, b: null };
+		const result = deepMerge(target, source);
+		expect(result).toEqual({ a: null, b: null });
+	});
+
+	it('throws error when merging null with object', () => {
+		const target = { a: { x: 10 } } as { a: object | null };
+		const source = { a: null };
+		expect(() => deepMerge(target, source)).toThrow('deepMerge: Cannot merge incompatible types for key "a"');
+	});
+
+	it('merges with empty source object', () => {
+		const target = { a: 1, b: 2 };
+		const source = {};
+		const result = deepMerge(target, source);
+		expect(result).toEqual({ a: 1, b: 2 });
+	});
+
+	it('skips non-object sources', () => {
+		const target = { a: 1, b: 2 };
+		// @ts-expect-error Testing runtime behavior with invalid input
+		const result = deepMerge(target, null, undefined, 'string', 123, { c: 3 });
+		expect(result).toEqual({ a: 1, b: 2, c: 3 });
+	});
+
+	it('throws error when merging incompatible types (array with object)', () => {
+		const target = { a: [1, 2, 3] } as { a: object };
+		const source = { a: { b: 1 } };
+		expect(() => deepMerge(target, source)).toThrow('deepMerge: Cannot merge incompatible types for key "a"');
+	});
+
+	it('throws error when merging incompatible types (object with array)', () => {
+		const target = { a: { b: 1 } } as { a: object };
+		const source = { a: [1, 2, 3] };
+		expect(() => deepMerge(target, source)).toThrow('deepMerge: Cannot merge incompatible types for key "a"');
+	});
+
+	it('overwrites basic types with arrays', () => {
+		const target = { a: 1, b: 'string' };
+		const source = { a: [1, 2, 3], b: [4, 5] };
+		const result = deepMerge(target, source);
+		expect(result).toEqual({ a: [1, 2, 3], b: [4, 5] });
+		expect(result.a).not.toBe(source.a); // Should be a deep clone
+	});
+
+	it('throws error when merging array with array', () => {
+		const target = { a: [1, 2, 3] };
+		const source = { a: [4, 5] };
+		expect(() => deepMerge(target, source)).toThrow('deepMerge: Cannot merge incompatible types for key "a"');
+	});
+
+	it('deeply merges nested objects across multiple levels', () => {
+		const target = { a: { b: { c: 1, d: 2 }, e: 3 }, f: 4 };
+		const source = { a: { b: { c: 10 }, g: 5 }, h: 6 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual({ a: { b: { c: 10, d: 2 }, e: 3, g: 5 }, f: 4, h: 6 });
+	});
+
+	it('does not mutate the original target object', () => {
+		const target = { a: { b: 1 }, c: 2 };
+		const source = { a: { b: 10 }, d: 3 };
+		const result = deepMerge(target, source);
+		expect(target).toEqual({ a: { b: 1 }, c: 2 }); // Original unchanged
+		expect(result).toEqual({ a: { b: 10 }, c: 2, d: 3 });
+	});
 });
 
 describe('resolveUrl', () => {

package/src/lib/utils.ts

@@ -29,9 +29,7 @@ export function deepClone<T>(obj: T): T {
 
 	if (obj == null) return obj;
 
-	console.log('obj', obj);
-	console.log('obj.prototype', Object.getPrototypeOf(obj));
-	throw Error();
+	throw new Error(`deepClone: Unsupported object type "${Object.getPrototypeOf(obj)?.constructor?.name ?? 'unknown'}"`);
 }
 
 export function isSimpleObject(item: unknown): item is object {
@@ -54,7 +52,7 @@ export function isBasicType(item: unknown): item is boolean | number | string |
 		case 'object':
 			return false;
 		default:
-			throw Error('unknown type: ' + typeof item);
+			throw new Error(`isBasicType: Unknown type "${typeof item}"`);
 	}
 }
 
@@ -68,9 +66,7 @@ export function deepMerge<T extends object>(source0: T, ...sources: Partial<T>[]
 
 			const sourceValue = source[key] as T[typeof key];
 
-			// *********
-			// overwrite
-			// *********
+			// Handle basic types (number, string, boolean) - always overwrite
 			switch (typeof sourceValue) {
 				case 'number':
 				case 'string':
@@ -80,33 +76,28 @@ export function deepMerge<T extends object>(source0: T, ...sources: Partial<T>[]
 				default:
 			}
 
+			// If target is a basic type, overwrite with deep clone of source
 			if (isBasicType(target[key])) {
 				target[key] = deepClone(sourceValue);
 				continue;
 			}
 
+			// Handle Color instances - clone the source color
 			if (sourceValue instanceof Color) {
 				target[key] = sourceValue.clone() as T[typeof key];
 				continue;
 			}
 
+			// If both are simple objects, merge them recursively
 			if (isSimpleObject(target[key]) && isSimpleObject(sourceValue)) {
 				target[key] = deepMerge(target[key], sourceValue);
 				continue;
 			}
 
-			// *********
-			// merge
-			// *********
-
-			if (isSimpleObject(target[key]) && isSimpleObject(sourceValue)) {
-				target[key] = deepMerge(target[key], sourceValue);
-				continue;
-			}
-
-			console.log('target[key]:', target[key]);
-			console.log('source[key]:', source[key]);
-			throw Error('unpredicted case');
+			// Incompatible types - throw error
+			throw new Error(
+				`deepMerge: Cannot merge incompatible types for key "${String(key)}" (target: ${typeof target[key]}, source: ${typeof sourceValue})`
+			);
 		}
 	}
 	return target;

package/src/style_builder/decorator.ts

@@ -22,7 +22,9 @@ export function decorate(layers: MaplibreLayer[], rules: StyleRules, recolor: Ca
 			if (!id.includes('*')) return id;
 			const regExpString = id.replace(/[^a-z_:-]/g, (c) => {
 				if (c === '*') return '[a-z_-]*';
-				throw new Error('unknown char to process. Do not know how to make a RegExp from: ' + JSON.stringify(c));
+				throw new Error(
+					`decorator: Invalid character ${JSON.stringify(c)} in layer ID pattern "${id}". Only alphanumeric, underscore, colon, hyphen, and asterisk are allowed.`
+				);
 			});
 			const regExp = new RegExp(`^${regExpString}$`, 'i');
 			return layerIds.filter((layerId) => regExp.test(layerId));
@@ -78,26 +80,27 @@ export function decorate(layers: MaplibreLayer[], rules: StyleRules, recolor: Ca
 						value = processExpression(value);
 						break;
 					default:
-						throw new Error(`unknown propertyDef.valueType "${propertyDef.valueType}" for key "${key}"`);
+						throw new Error(
+							`decorator: Unknown property value type "${propertyDef.valueType}" for key "${key}" on layer type "${layer.type}". This may indicate a MapLibre property definition mismatch.`
+						);
 				}
 
 				switch (propertyDef.parent) {
 					case 'layer':
-						// @ts-expect-error: too complex to handle
-						layer[key] = value;
+						(layer as Record<string, unknown>)[key] = value;
 						break;
 					case 'layout':
 						if (!layer.layout) layer.layout = {};
-						// @ts-expect-error: too complex to handle
-						layer.layout[key] = value;
+						(layer.layout as Record<string, unknown>)[key] = value;
 						break;
 					case 'paint':
 						if (!layer.paint) layer.paint = {};
-						// @ts-expect-error: too complex to handle
-						layer.paint[key] = value;
+						(layer.paint as Record<string, unknown>)[key] = value;
 						break;
 					default:
-						throw new Error(`unknown parent "${propertyDef.parent}" for key "${key}"`);
+						throw new Error(
+							`decorator: Unknown property parent "${propertyDef.parent}" for key "${key}" on layer type "${layer.type}". Expected "layer", "layout", or "paint".`
+						);
 				}
 			});
 		}
@@ -108,12 +111,16 @@ export function decorate(layers: MaplibreLayer[], rules: StyleRules, recolor: Ca
 				const color = recolor.do(value as Color);
 				return color.asString();
 			}
-			throw new Error(`unknown color type "${typeof value}"`);
+			throw new Error(
+				`decorator.processColor: Expected a color string or Color instance, but got ${typeof value}. Value: ${JSON.stringify(value)}`
+			);
 		}
 
 		function processFont(value: StyleRuleValue): string[] {
 			if (typeof value === 'string') return [value];
-			throw new Error(`unknown font type "${typeof value}"`);
+			throw new Error(
+				`decorator.processFont: Expected a font name string, but got ${typeof value}. Value: ${JSON.stringify(value)}`
+			);
 		}
 
 		function processExpression(