• Is the intention of these new functions to bypass that (because it's not needed for these use cases). Or is it required that the caller apply those invalidation manually when calling these functions

The intention isn't to bypass it, but delay it until the next layout. In the meantime, the device can be used for media queries which do not require the stylesheets to be dirtied.

• If invalidation is required, should we make these function apply it automatically? and/or document correct usage of the function?

I'm not sure these function can apply it automatically, because the invalidation actually happens in the Stylist and not the the Device. In general the relationship between changing the Device (or replacing it) hasn't changed in the Stylo API. We are just doing it in a different place in Servo, so the semantics of this API don't really change. This is the invalidation in question: https://github.com/servo/servo/pull/40432/files#diff-49c9dea0cc9af0161b4681a4c4b1ed81f38f8190bd6854fd2ba6b3d74502b047R998

The intention isn't to bypass it, but delay it until the next layout. In the meantime, the device can be used for media queries which do not require the stylesheets to be dirtied.

I see. This makes sense.

I'm not sure these function can apply it automatically, because the invalidation actually happens in the Stylist and not the the Device.

I think we could do this in device_mut if we want to (we might need to return a "guard" that deref_mut's to the Device) and calls the invalidation functions on Drop. That wouldn't work with the delaying the invalidation though (and I agree it makes sense to delay it).

My suggestion would be to store the device_has_changed bit inside the Device itself. Then I think recalc_style could automatically apply the invalidations. That could be done as a follow-up though (if you agree it makes sense).

let sheet_origins_affected_by_device_change = stylist
      .media_features_change_changed_style(&guards, self.device());
stylist
    .force_stylesheet_origins_dirty(sheet_origins_affected_by_device_change);

on the device_mut method.

Since device_mut is shared code, I've just put this documentation on the new setters. Hopefully that's okay.