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/tests/equivalence.rs

@@ -104,12 +104,13 @@ fn neighbor_diff(img: &[u8], i: usize, j: usize) -> u8 {
     (0..4).map(|c| img[i + c].abs_diff(img[j + c])).max().unwrap_or(0)
 }
 
-fn assert_equivalent(mode: FitMode) {
+fn assert_equivalent_with(mode: FitMode, clustering: vtracer::Clustering) {
     let (w, h) = (96usize, 96usize);
     let img = blobs(w, h);
 
     let stacked = Config {
         mode,
+        clustering,
         hierarchical: Hierarchical::Stacked,
         ..Config::default()
     }
@@ -120,6 +121,7 @@ fn assert_equivalent(mode: FitMode) {
 
     let cutout = Config {
         mode,
+        clustering,
         hierarchical: Hierarchical::Cutout,
         ..Config::default()
     }
@@ -151,6 +153,10 @@ fn assert_equivalent(mode: FitMode) {
     );
 }
 
+fn assert_equivalent(mode: FitMode) {
+    assert_equivalent_with(mode, vtracer::Clustering::ColorCluster);
+}
+
 #[test]
 fn stacked_and_cutout_agree_in_interiors_spline() {
     assert_equivalent(FitMode::Spline);
@@ -166,6 +172,13 @@ fn stacked_and_cutout_agree_in_interiors_pixel() {
     assert_equivalent(FitMode::Pixel);
 }
 
+#[test]
+fn watershed_stacked_and_cutout_agree_in_interiors() {
+    for mode in [FitMode::Pixel, FitMode::Spline] {
+        assert_equivalent_with(mode, vtracer::Clustering::Watershed);
+    }
+}
+
 // --- seam / show-through test -------------------------------------------------
 
 fn rasterize_on(svg: &str, w: u32, h: u32, bg: [u8; 4]) -> Vec<u8> {
@@ -180,12 +193,12 @@ fn rasterize_on(svg: &str, w: u32, h: u32, bg: [u8; 4]) -> Vec<u8> {
 /// solid layers overdraw with no gaps, so nothing shows through. Show-through
 /// (backdrop-dependent pixels away from the canvas edge) means seams — which is
 /// exactly the hole-punching bug this guards against.
-#[test]
-fn stacked_has_no_seams() {
+fn assert_no_seams(clustering: vtracer::Clustering) {
     let (w, h) = (96usize, 96usize);
     let img = blobs(w, h); // background fills the whole canvas
     let svg = Config {
         mode: FitMode::Spline,
+        clustering,
         hierarchical: Hierarchical::Stacked,
         ..Config::default()
     }
@@ -210,6 +223,18 @@ fn stacked_has_no_seams() {
     }
     assert_eq!(
         show_through, 0,
-        "stacked mode leaked {show_through} backdrop pixels — seams/holes in solid overdraw"
+        "{clustering:?} stacked leaked {show_through} backdrop pixels — seams/holes in overdraw"
     );
 }
+
+#[test]
+fn stacked_has_no_seams() {
+    assert_no_seams(vtracer::Clustering::ColorCluster);
+}
+
+/// The watershed frontend emits disjoint region masks; its full-canvas solid
+/// background layer is what restores overdraw. This guards that construction.
+#[test]
+fn watershed_stacked_has_no_seams() {
+    assert_no_seams(vtracer::Clustering::Watershed);
+}