Add soft colorKey, feather, and dark-pixel protect

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-08-28
+
+### Added
+
+- `colorKey` options `soft` (distance-based alpha), `feather` (alpha blur, pixels), and `protectDarkerThan` (restore partial-alpha pixels darker than that luminance so labels stay crisp).
+
 ## [2.3.0] - 2026-08-26
 
 ### Added
@@ -177,7 +183,8 @@ Rename `publicBasePath` to `mapAssetBasePath` in Mapbox style configs. The old k
 
 - Initial release of the PHP tile proxy with operation pipeline, caching, and tests.
 
-[Unreleased]: https://github.com/open-mapsight/tile-proxy/compare/v2.3.0...HEAD
+[Unreleased]: https://github.com/open-mapsight/tile-proxy/compare/v2.4.0...HEAD
+[2.4.0]: https://github.com/open-mapsight/tile-proxy/compare/v2.3.0...v2.4.0
 [2.3.0]: https://github.com/open-mapsight/tile-proxy/compare/v2.2.0...v2.3.0
 [2.2.0]: https://github.com/open-mapsight/tile-proxy/compare/v2.1.2...v2.2.0
 [2.1.2]: https://github.com/open-mapsight/tile-proxy/compare/v2.1.1...v2.1.2

README.md

@@ -244,7 +244,7 @@ Operations are chained sequentially as defined in the `ops` array. The first ope
 
 * `src`: Fetches the tile from the defined `urls`, or from a `wms` GetMap source. URL templates support `{z}`, `{x}`, `{y}`, `{prefix}`, `{bbox}` / `{bbox3857}` (Web Mercator meters), and `{bbox4326}` (lon,lat,lon,lat).
 * `colorFilter`: Applies color filters. Supported filters: `reducedSaturation`, `muted`, `culture`.
-* `colorKey`: Makes nodata fill colors transparent (`colors` as `#RRGGBB`, optional `fuzz`, optional `fromEdges`). Defaults to a flood from the tile edge and already-transparent pixels so isolated interior matches stay put. Always encodes PNG.
+* `colorKey`: Makes nodata fill colors transparent (`colors` as `#RRGGBB`, optional `fuzz`, optional `fromEdges`). Defaults to a flood from the tile edge and already-transparent pixels so isolated interior matches stay put. Always encodes PNG. Optional `soft` fades alpha by distance to the key color instead of a hard cut. Optional `feather` (integer pixel passes) blurs alpha afterward. Optional `protectDarkerThan` (0–255 luminance) restores partial-alpha pixels darker than that value so labels stay opaque after a street-fill punch.
 * `encode`: Re-encodes the current tile to another image type (`mimeType`, optional `quality` for JPEG/WebP).
 * `imgOpt`: Optimizes the image using image optimizers.
 * `merge`: Merges the current tile with another set of operations.
@@ -324,6 +324,21 @@ To punch a solid nodata fill out of an aerial before overlaying it, add `colorKe
 
 Set `fromEdges` to `false` only when every matching pixel should become transparent, including interior matches.
 
+To punch cartographic fills (street interiors) and keep labels, turn off the edge flood, fade the cut, then protect dark ink:
+
+```jsonc
+{
+    "op": "colorKey",
+    "colors": ["#ffffff", "#fff8bd", "#d0d0d0"],
+    "fuzz": 8,
+    "fromEdges": false,
+    "soft": true,
+    "feather": 2,
+    "protectDarkerThan": 80,
+    "cacheServerName": "stadtplan-ink"
+}
+```
+
 Leaflet, OpenLayers, and MapLibre can consume the proxied XYZ URL like any other raster tileset.
 
 If the WMS requires Basic auth, set `upstreamHttp.headers.Authorization` in the PHP bootstrap (not in committed JSONC). Some municipal WMS licenses also forbid local storage — disable or shorten `cacheServerTtl` when that applies.