Add watershed clustering: hierarchical watershed frontend

An alternative region-forming frontend selected by --clustering watershed
(the color_mode field is replaced by clustering: color-cluster | bw |
watershed across CLI, Rust, Python, and Node — it selects the algorithm,
not a color space).

The algorithm is the watershed hierarchy by volume on the 4-adjacency
pixel graph, implemented from the papers:

  Cousty, Bertrand, Najman, Couprie, "Watershed Cuts: Minimum Spanning
  Forests and the Drop of Water Principle", IEEE TPAMI 31(8), 2009.
  Najman, Cousty, Perret, "Playing with Kruskal", ISMM 2013.

Edge weights are the max per-channel color difference between adjacent
pixels (no gradient image); a counting-sorted Kruskal pass builds the
binary partition tree as a flat parents array; a leaves-to-root pass
computes subtree area and volume; each merge's persistence (the volume of
the smaller side, plateau-corrected) becomes its MST edge's saliency; and
cutting the hierarchy is single-linkage over MST edges below the cut
level. Watershed cuts label every pixel — no watershed-line pixel class —
so the output is a strict, gapless partition that drops straight into
both stacked and cutout modes. Integer arithmetic and flat u32 arrays
throughout; deterministic across platforms; ~66 ms on a 1400x775 photo.

The one dial, --watershed-detail (0..=255), maps exponentially to a
target region count (each +25.5 doubles it) since the persistence
distribution is far too skewed for a linear threshold. filter_speckle
absorbs undersized basins into their most color-similar neighbour rather
than dropping them, preserving the partition. The largest region is
emitted first as a solid full-canvas background layer so stacked mode
keeps its seam-free overdraw; the mosaic flatten is unaffected.

Tests: partition invariant (disjoint masks tiling the canvas), detail
monotonicity, min-area absorption, determinism, watershed cases in the
pipeline/golden suites, stacked-vs-cutout interior equivalence, a
watershed seam test, and SegmentKey coverage for the new params.

README.md

@@ -80,7 +80,7 @@ Options:
   -i, --input <INPUT>                        Path to the input raster image
   -o, --output <OUTPUT>                      Path to the output SVG
       --preset <PRESET>                      Start from a preset: bw, poster, photo
-      --colormode <COLORMODE>                Color image `color` (default) or binary image `bw`
+      --clustering <CLUSTERING>              Region forming: `color-cluster` (default), `bw`, `watershed`
       --hierarchical <HIERARCHICAL>          Clustering: `stacked` (default) or `cutout` (seam-free mosaic)
   -m, --mode <MODE>                          Curve-fitting mode: `pixel`, `polygon`, `spline`
   -f, --filter-speckle <FILTER_SPECKLE>      Discard patches smaller than X px in size (0..=128)
@@ -98,6 +98,7 @@ Options:
       --adaptive                             Binary mode: Bradley–Roth adaptive threshold (uneven lighting)
       --adaptive-window <ADAPTIVE_WINDOW>    Adaptive window size in px (0 = auto); implies --adaptive
       --adaptive-t <ADAPTIVE_T>              Adaptive sensitivity: % below local mean (default 15)
+      --watershed-detail <WATERSHED_DETAIL>  Watershed: hierarchy cut level 0..=255 (higher = more regions)
   -h, --help                                 Print help
   -V, --version                              Print version
 ```
@@ -112,6 +113,10 @@ Options:
 - **Binary thresholding** — a tunable fixed cutoff (`--threshold`) or
   **Bradley–Roth adaptive** thresholding (`--adaptive`, with `--adaptive-window`
   / `--adaptive-t`) for scans with uneven lighting.
+- **`--clustering watershed`** — an alternative region-forming algorithm: a
+  hierarchical watershed on the pixel graph (Cousty et al., TPAMI 2009; Najman,
+  Cousty & Perret, ISMM 2013), cut at `--watershed-detail`. Content-adaptive
+  regions that follow object shape — pairs beautifully with `cutout`.
 
 ## Downloads
 
@@ -135,11 +140,14 @@ cargo install vtracer-cli
 ./vtracer input.jpg output.svg --preset bw
 
 # scanned/photographed line art with uneven lighting
-./vtracer scan.jpg output.svg --colormode bw --adaptive
+./vtracer scan.jpg output.svg --clustering bw --adaptive
 
 # seam-free mosaic (gapless tessellation)
 ./vtracer input.jpg output.svg --hierarchical cutout
 
+# watershed region forming, cut to taste
+./vtracer photo.jpg output.svg --clustering watershed --watershed-detail 192
+
 # constrain to a fixed palette
 ./vtracer input.jpg output.svg --palette '#1b1b1b,#e0c088,#5a7d3c,#8fb0d0'
 ```
@@ -202,8 +210,12 @@ cfg.palette = ["#1b1b1b", "#e0c088", "#5a7d3c"]
 svg = cfg.convert_bytes(data)
 vtracer.Config.poster().convert_file("photo.jpg", "poster.svg")
 
+# watershed region forming
+ws = vtracer.Config(clustering="watershed", watershed_detail=192)
+svg = ws.convert_file("photo.jpg", "photo.svg")
+
 # binary with adaptive (Bradley–Roth) thresholding
-bw = vtracer.Config(color_mode="bw", adaptive=True)
+bw = vtracer.Config(clustering="bw", adaptive=True)
 svg = bw.convert_file("scan.jpg", "scan.svg")
 ```
 
@@ -222,10 +234,10 @@ const vtracer = require('@visioncortex/vtracer');
 
 await vtracer.convertFile('in.png', 'out.svg', { mode: 'polygon' });
 const svg = vtracer.convertBuffer(buffer, { preset: 'poster' });
-const svg2 = vtracer.convertPixels(rgba, width, height, { colorMode: 'bw' });
+const svg2 = vtracer.convertPixels(rgba, width, height, { clustering: 'bw' });
 
 // binary with adaptive thresholding
-const bw = vtracer.convertBuffer(buffer, { colorMode: 'bw', adaptive: true });
+const bw = vtracer.convertBuffer(buffer, { clustering: 'bw', adaptive: true });
 ```
 
 ## Citations