Return flow sample locations with an active flag and a fixed colour ramp

The selector returned only the arrows it would draw, so a view could not draw
anything at a quiet sample and the below-threshold branch was unreachable. It
now returns every candidate location plus an `active` flag, both callers filter
on it, and the magnitude colour ramp is fixed so one magnitude is one colour
across frames. Verified by pixel parity against HEAD for the 2D canvas and the
3D overlay, and by the shared and studio suites.

shared/tests/test_visual_policy.py

@@ -44,6 +44,13 @@ def test_select_flow_samples_uses_shared_grid_and_mask() -> None:
 
 
 def test_select_flow_samples_hysteresis_keeps_weaker_motion() -> None:
+    """The band between ``flow_off_px`` and ``flow_on_px`` decides through ``active``.
+
+    The location is a candidate either way — the band is a statement about activity, not
+    about where the policy samples — so what changes with ``previously_on`` is the flag.
+    This is the single place the two views' thresholds are applied: a caller that draws
+    ``active_only()`` draws what it drew when the selector filtered for it.
+    """
     h, w = 30, 30
     flow = np.zeros((h, w, 2), dtype=np.float64)
     # |2*flow| = 0.7: below on (0.8) but above off (0.5)
@@ -58,8 +65,36 @@ def test_select_flow_samples_hysteresis_keeps_weaker_motion() -> None:
     previously[15, 15] = True
     off = select_flow_samples(flow, None, policy, previously_on=None)
     on = select_flow_samples(flow, None, policy, previously_on=previously)
-    assert off.rows.size == 0
-    assert on.rows.size == 1
+    # Same candidate locations: the grid does not depend on the verdict.
+    assert off.rows.tolist() == on.rows.tolist()
+    assert off.cols.tolist() == on.cols.tolist()
+    assert (15, 15) in set(zip(on.rows.tolist(), on.cols.tolist()))
+    # Only the verdict does.
+    assert on.active_count == 1
+    assert off.active_count == 0
+    assert on.active_only().rows.tolist() == [15]
+    assert on.active_only().cols.tolist() == [15]
+    assert off.active_only().rows.size == 0
+
+
+def test_the_location_cap_is_a_location_budget() -> None:
+    """``max_arrows`` limits candidate locations, not arrows.
+
+    The cap has to be spent before the activity verdict, otherwise the set of locations
+    would depend on the threshold and a caller drawing inactive candidates too would draw
+    a different set from the one a caller drawing arrows does. The strongest candidates
+    are kept, and every inactive candidate is one no arrow was ever drawn for.
+    """
+    h, w = 40, 40
+    flow = np.zeros((h, w, 2), dtype=np.float64)
+    flow[15, 15] = (5.0, 0.0)  # far above the threshold
+    policy = VisualPolicy(flow_on_px=0.4, flow_grid_spacing=1, flow_edge_margin=0, max_arrows=4)
+    samples = select_flow_samples(flow, np.ones((h, w), dtype=bool), policy)
+    assert samples.rows.size == 4
+    assert samples.active_count == 1
+    assert (15, 15) in set(zip(samples.rows.tolist(), samples.cols.tolist())), (
+        "the cap dropped the only moving sample"
+    )
 
 
 def test_paint_domain_background_colours() -> None: