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.

crates/vtracer-cli/src/main.rs

@@ -9,7 +9,7 @@ use std::process::ExitCode;
 
 use clap::Parser;
 use visioncortex::{Color, ColorImage};
-use vtracer::{ColorMode, Config, FitMode, Hierarchical, Preset};
+use vtracer::{Clustering, Config, FitMode, Hierarchical, Preset};
 
 /// Convert an image into vector graphics.
 #[derive(Parser, Debug)]
@@ -35,9 +35,9 @@ struct Args {
     #[arg(long)]
     preset: Option<Preset>,
 
-    /// Color image (`color`) or binary image (`bw`).
-    #[arg(long = "colormode")]
-    colormode: Option<ColorMode>,
+    /// Region forming: `color-cluster` (default), `bw`, or `watershed`.
+    #[arg(long)]
+    clustering: Option<Clustering>,
 
     /// Hierarchical clustering: `stacked` (default) or `cutout` (mosaic).
     #[arg(long)]
@@ -106,6 +106,10 @@ struct Args {
     /// Adaptive sensitivity: percent below the local mean (default 15). Implies --adaptive.
     #[arg(long)]
     adaptive_t: Option<f64>,
+
+    /// Watershed clustering: hierarchy cut level (0..=255, higher = more regions).
+    #[arg(long, value_parser = clap::value_parser!(u8))]
+    watershed_detail: Option<u8>,
 }
 
 fn parse_segment_length(s: &str) -> Result<f64, String> {
@@ -148,8 +152,8 @@ fn build_config(args: &Args) -> Result<Config, String> {
         None => Config::default(),
     };
 
-    if let Some(v) = args.colormode {
-        config.color_mode = v;
+    if let Some(v) = args.clustering {
+        config.clustering = v;
     }
     if let Some(v) = args.hierarchical {
         config.hierarchical = v;
@@ -199,6 +203,9 @@ fn build_config(args: &Args) -> Result<Config, String> {
     if let Some(v) = args.adaptive_t {
         config.binary_adaptive_t = v;
     }
+    if let Some(v) = args.watershed_detail {
+        config.watershed_detail = v;
+    }
 
     // Palette: inline flag wins over file; both parse to a color list.
     if let Some(text) = &args.palette {