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.

nodejs/src/lib.rs

@@ -15,7 +15,8 @@ use wasm_bindgen::prelude::*;
 #[derive(Default, Deserialize)]
 #[serde(default, rename_all = "camelCase")]
 struct Options {
-    color_mode: Option<String>,
+    /// Region forming: "color-cluster" | "bw" | "watershed".
+    clustering: Option<String>,
     hierarchical: Option<String>,
     mode: Option<String>,
     filter_speckle: Option<usize>,
@@ -37,6 +38,8 @@ struct Options {
     adaptive_window: Option<u32>,
     /// Adaptive sensitivity: percent below the local mean (default 15).
     adaptive_t: Option<f64>,
+    /// Watershed clustering: hierarchy cut level (0..=255).
+    watershed_detail: Option<u8>,
     /// One of "bw" | "poster" | "photo"; applied before the other fields.
     preset: Option<String>,
 }
@@ -71,8 +74,8 @@ fn config_from(options: JsValue) -> Result<Config, JsValue> {
         None => Config::default(),
     };
 
-    if let Some(v) = opts.color_mode {
-        config.color_mode = v.parse().map_err(err)?;
+    if let Some(v) = opts.clustering {
+        config.clustering = v.parse().map_err(err)?;
     }
     if let Some(v) = opts.hierarchical {
         config.hierarchical = v.parse().map_err(err)?;
@@ -126,6 +129,9 @@ fn config_from(options: JsValue) -> Result<Config, JsValue> {
     if let Some(v) = opts.adaptive_t {
         config.binary_adaptive_t = v;
     }
+    if let Some(v) = opts.watershed_detail {
+        config.watershed_detail = v;
+    }
     Ok(config)
 }