Close the boundary audit: digest every shape argument and guard it in CI

Completes the three findings of devguide/python_js_boundary_audit_2026_07.md.

The twenty remaining arguments, all in shapes, now have digesters. Contracts
follow their call sites: optional flags stay None so the shape applies its own
default and reject truthy non-booleans; colours go through normalize_color;
opacities are numbers in [0, 1]; atom quads and triplets must hold exactly four
and three non-negative indices, so a malformed mesh cannot reach the frontend;
normals and directions are 3D vectors with finite components; segments needs at
least three to close a ring; length_scale must be positive, since zero or
negative would collapse or invert every vector; and color_component is an axis
index. NumPy arrays are accepted throughout, because that is how this data
arrives.

dynamic_region_evaluation_warning now has a handler: a canvas toast naming the
region and the timing that blew the budget. The first attempt was to stop
emitting it, since the freeze already reaches the user through the message
catalog, but the suite rejected that — a test asserts the message is sent. The
emission was deliberate and tested; the missing half was the receiver.

Both sweeps now run as tests/test_python_js_boundary.py, so the pattern cannot
come back unnoticed: one fails if a @digest() argument has no digester, the other
if Python emits an op no handler reads. Both are mutation-verified.

Also fixes three pre-existing type errors in trajectory-plot-overlay.ts, where
narrowing did not carry across an alias.

Author: dprada

devguide/python_js_boundary_audit_2026_07.md

@@ -76,18 +76,25 @@ hit; it is worth re-running when a new enum-like argument is added.
 them: dead code in the opposite direction. A reverse sweep (digesters with no
 consumer) would find more.
 
-## Status
-
-The six non-shape digesters are **done** (`region`, `fade`, `meta`, `layer`,
-`target`, `transaction_id`), each mutation-verified. Re-running sweep 1 now
-reports 20 missing arguments instead of 26, all of them in `shapes`.
-
-## Recommendation
-
-1. Fill the remaining 20 digesters, all in `shapes`. The group is homogeneous and
-   can be done in one pass.
-2. Decide on `dynamic_region_evaluation_warning`: surface it in the frontend, or
-   stop emitting it. A performance warning that reaches nobody is worse than no
-   warning, because the region silently degrades.
-3. Re-run sweeps 1 and 2 in CI. Both are cheap and deterministic, and would have
-   caught every instance of this pattern found during dogfooding.
+## Status: closed
+
+All three findings are resolved.
+
+- **26 missing digesters → 0.** The six non-shape ones came first (`region`,
+  `fade`, `meta`, `layer`, `target`, `transaction_id`), then the twenty in
+  `shapes`. Contracts follow their call sites, and booleans are rejected wherever
+  they would masquerade as a number or an index.
+- **The orphan op now has a handler.** `dynamic_region_evaluation_warning` is
+  surfaced as a canvas toast naming the region and the timing that blew the
+  budget. The first attempt was to stop emitting it, on the grounds that the
+  freeze already reaches the user through the message catalog — but the suite
+  rejected that: `test_over_budget_dynamic_region_freezes_to_static_and_reports_runtime`
+  asserts the message is sent. The emission was deliberate and tested; what was
+  missing was the other half. Worth remembering when this sweep flags an orphan:
+  check for a test asserting the emission before assuming it is dead weight.
+- **Sweeps 1 and 2 now run in CI** as `tests/test_python_js_boundary.py`. Both
+  are mutation-verified: removing a digester or adding an unread op fails them.
+
+Sweep 3 (values Python accepts that the frontend does not know) is **not**
+automated: its signal-to-noise ratio is poor and every hit needs manual reading.
+Re-run it by hand when adding an enum-like argument that crosses the boundary.

molsysviewer/_private/arg_digestion/_group_indices.py

@@ -0,0 +1,41 @@
+"""Shared validation for fixed-size groups of atom indices."""
+
+import numpy as np
+
+from ..exceptions import ArgumentError
+
+
+def digest_fixed_size_index_groups(value, size, argument, caller=None):
+    """Return a list of ``size``-long lists of non-negative atom indices.
+
+    Accepts any iterable of iterables, including NumPy arrays, and rejects
+    groups of the wrong length or with non-integer entries, which would
+    otherwise reach the frontend as a malformed mesh.
+    """
+    if isinstance(value, np.ndarray):
+        if value.ndim != 2 or value.shape[1] != size:
+            raise ArgumentError(argument, value=value, caller=caller, message=None)
+        rows = value.tolist()
+    elif isinstance(value, (list, tuple)):
+        rows = list(value)
+    else:
+        raise ArgumentError(argument, value=value, caller=caller, message=None)
+
+    out = []
+    for row in rows:
+        if isinstance(row, np.ndarray):
+            row = row.tolist()
+        if not isinstance(row, (list, tuple)) or len(row) != size:
+            raise ArgumentError(argument, value=value, caller=caller, message=None)
+        group = []
+        for index in row:
+            if isinstance(index, bool) or not isinstance(index, (int, np.integer)):
+                raise ArgumentError(argument, value=value, caller=caller, message=None)
+            if int(index) < 0:
+                raise ArgumentError(argument, value=value, caller=caller, message=None)
+            group.append(int(index))
+        out.append(group)
+
+    if not out:
+        raise ArgumentError(argument, value=value, caller=caller, message=None)
+    return out

molsysviewer/_private/arg_digestion/argument/alpha_alpha_spheres.py

@@ -0,0 +1,23 @@
+from ...exceptions import ArgumentError
+
+
+def digest_alpha_alpha_spheres(alpha_alpha_spheres, caller=None):
+    """Digest the ``alpha_alpha_spheres`` opacity, a number in ``[0, 1]``.
+
+    Booleans are rejected: ``True``/``False`` are ints in Python but not
+    meaningful opacities.
+    """
+    if alpha_alpha_spheres is None:
+        return None
+
+    if not isinstance(alpha_alpha_spheres, bool) and isinstance(alpha_alpha_spheres, (int, float)):
+        value = float(alpha_alpha_spheres)
+        if 0.0 <= value <= 1.0:
+            return value
+
+    raise ArgumentError(
+        "alpha_alpha_spheres",
+        value=alpha_alpha_spheres,
+        caller=caller,
+        message=" Opacity must be a number between 0 and 1.",
+    )

molsysviewer/_private/arg_digestion/argument/alpha_atoms.py

@@ -0,0 +1,23 @@
+from ...exceptions import ArgumentError
+
+
+def digest_alpha_atoms(alpha_atoms, caller=None):
+    """Digest the ``alpha_atoms`` opacity, a number in ``[0, 1]``.
+
+    Booleans are rejected: ``True``/``False`` are ints in Python but not
+    meaningful opacities.
+    """
+    if alpha_atoms is None:
+        return None
+
+    if not isinstance(alpha_atoms, bool) and isinstance(alpha_atoms, (int, float)):
+        value = float(alpha_atoms)
+        if 0.0 <= value <= 1.0:
+            return value
+
+    raise ArgumentError(
+        "alpha_atoms",
+        value=alpha_atoms,
+        caller=caller,
+        message=" Opacity must be a number between 0 and 1.",
+    )

molsysviewer/_private/arg_digestion/argument/atom_quads.py

@@ -0,0 +1,13 @@
+from ...exceptions import ArgumentError
+from .._group_indices import digest_fixed_size_index_groups
+
+
+def digest_atom_quads(atom_quads, caller=None):
+    """Digest the atom quadruplets defining tetrahedra.
+
+    Each entry must hold exactly four atom indices (non-negative integers).
+    ``None`` means the shape is defined by explicit coordinates instead.
+    """
+    if atom_quads is None:
+        return None
+    return digest_fixed_size_index_groups(atom_quads, 4, "atom_quads", caller=caller)

molsysviewer/_private/arg_digestion/argument/atom_triplets.py

@@ -0,0 +1,13 @@
+from ...exceptions import ArgumentError
+from .._group_indices import digest_fixed_size_index_groups
+
+
+def digest_atom_triplets(atom_triplets, caller=None):
+    """Digest the atom triplets defining triangle faces.
+
+    Each entry must hold exactly three atom indices (non-negative integers).
+    ``None`` means the shape is defined by explicit vertices instead.
+    """
+    if atom_triplets is None:
+        return None
+    return digest_fixed_size_index_groups(atom_triplets, 3, "atom_triplets", caller=caller)

molsysviewer/_private/arg_digestion/argument/color_alpha_spheres.py

@@ -0,0 +1,18 @@
+from molsysviewer.colors import normalize_color
+
+from ...exceptions import ArgumentError
+
+
+def digest_color_alpha_spheres(color_alpha_spheres, caller=None):
+    """Digest the ``color_alpha_spheres`` colour, normalized to a packed integer.
+
+    Accepts any colour form the viewer understands (packed int, ``"#rrggbb"``,
+    a name, an RGB(A) triplet). ``None`` keeps the shape's own default.
+    """
+    if color_alpha_spheres is None:
+        return None
+
+    try:
+        return normalize_color(color_alpha_spheres)
+    except Exception as exc:
+        raise ArgumentError("color_alpha_spheres", value=color_alpha_spheres, caller=caller, message=None) from exc

molsysviewer/_private/arg_digestion/argument/color_atoms.py

@@ -0,0 +1,18 @@
+from molsysviewer.colors import normalize_color
+
+from ...exceptions import ArgumentError
+
+
+def digest_color_atoms(color_atoms, caller=None):
+    """Digest the ``color_atoms`` colour, normalized to a packed integer.
+
+    Accepts any colour form the viewer understands (packed int, ``"#rrggbb"``,
+    a name, an RGB(A) triplet). ``None`` keeps the shape's own default.
+    """
+    if color_atoms is None:
+        return None
+
+    try:
+        return normalize_color(color_atoms)
+    except Exception as exc:
+        raise ArgumentError("color_atoms", value=color_atoms, caller=caller, message=None) from exc

molsysviewer/_private/arg_digestion/argument/color_component.py

@@ -0,0 +1,17 @@
+from ...exceptions import ArgumentError
+
+
+def digest_color_component(color_component, caller=None):
+    """Digest the vector component driving "component" colouring: 0, 1 or 2 (x, y, z)."""
+    if isinstance(color_component, bool):
+        raise ArgumentError("color_component", value=color_component, caller=caller, message=None)
+
+    if isinstance(color_component, int) and color_component in (0, 1, 2):
+        return color_component
+
+    raise ArgumentError(
+        "color_component",
+        value=color_component,
+        caller=caller,
+        message=" The component must be 0, 1 or 2 (x, y or z).",
+    )

molsysviewer/_private/arg_digestion/argument/directions.py

@@ -0,0 +1,40 @@
+import numpy as np
+
+from ...exceptions import ArgumentError
+
+
+def digest_directions(directions, caller=None):
+    """Digest a sequence of 3D vectors, one per element.
+
+    Returns a list of ``[x, y, z]`` floats. ``None`` means the shape does not
+    use them. Non-finite components are rejected: they would produce degenerate
+    geometry in the frontend.
+    """
+    if directions is None:
+        return None
+
+    value = directions
+    if isinstance(value, np.ndarray):
+        if value.ndim != 2 or value.shape[1] != 3:
+            raise ArgumentError("directions", value=directions, caller=caller, message=None)
+        value = value.tolist()
+
+    if not isinstance(value, (list, tuple)) or len(value) == 0:
+        raise ArgumentError("directions", value=directions, caller=caller, message=None)
+
+    out = []
+    for vector in value:
+        if isinstance(vector, np.ndarray):
+            vector = vector.tolist()
+        if not isinstance(vector, (list, tuple)) or len(vector) != 3:
+            raise ArgumentError("directions", value=directions, caller=caller, message=None)
+        components = []
+        for component in vector:
+            if isinstance(component, bool) or not isinstance(component, (int, float, np.number)):
+                raise ArgumentError("directions", value=directions, caller=caller, message=None)
+            fc = float(component)
+            if not np.isfinite(fc):
+                raise ArgumentError("directions", value=directions, caller=caller, message=None)
+            components.append(fc)
+        out.append(components)
+    return out