Merge branch 'worktree-agent-a22a049c461818dbe' into integration

# Conflicts:
#	core/dr-pipeline/tests/mask_sidecar.rs

core/dr-pipeline/src/mask.rs

@@ -533,25 +533,44 @@ pub enum MaskSource {
 
     /// A linear gradient — the graduated-filter mask.
     ///
-    /// Geometry is in **normalised output coordinates**, so it survives a crop
-    /// or an export at another size. Storing pixels would make a mask that
-    /// silently moves when the frame changes.
+    /// Geometry is in **normalised source coordinates**, so it survives a crop,
+    /// a zoom or an export at another size: the mask is rasterised in source
+    /// space and sampled through the framing map, exactly as a subject mask is.
+    /// Storing pixels would make a mask that silently moves when the frame
+    /// changes.
+    ///
+    /// # Two spaces, and why both are here
+    ///
+    /// The **centre** is a point, so it is a plain `0.0..=1.0` fraction of each
+    /// axis — the same coordinates a click carries.
+    ///
+    /// The **angle and the width are measurements**, and a fraction of the
+    /// width is not the same length as a fraction of the height on any frame
+    /// that is not square. So they are in the frame's *isotropic* units: y
+    /// spans `0..1` and x spans `0..aspect`, which is what makes 45° actually
+    /// 45° and a circle actually round. `frame_delta` in `mask.wgsl` is the
+    /// one place that conversion happens, and it must stay the only one.
     Linear {
         /// Midpoint of the ramp, `0.0..=1.0` in each axis.
         centre: (f32, f32),
-        /// Radians, measured from the +x axis.
+        /// Radians, measured clockwise from the +x axis in frame units.
+        /// Coverage increases in this direction.
         angle: f32,
-        /// Distance from full effect to none, in normalised units. Zero is a
-        /// hard edge.
+        /// Distance from full effect to none, in frame units. Zero is a hard
+        /// edge.
         width: f32,
     },
 
     /// A radial gradient — the classic vignette-shaped local adjustment.
+    ///
+    /// The same two spaces as [`Self::Linear`]: a `0..1` centre, and semi-axes
+    /// measured in the frame's isotropic units so equal radii draw a circle.
     Radial {
         centre: (f32, f32),
-        /// Semi-axes, normalised. Two of them, because a face is an ellipse
-        /// and forcing a circle makes the user compensate with a crop.
+        /// Semi-axes, in frame units. Two of them, because a face is an
+        /// ellipse and forcing a circle makes the user compensate with a crop.
         radii: (f32, f32),
+        /// Rotation of the ellipse, radians.
         angle: f32,
         /// Fraction of the radius over which the edge falls off.
         feather: f32,