> Emacs uses the face from the overlay only for text to which this
> overlay is applied. The display string is therefore using its own
> face definitions, which completely override those from the hl-line
> overlay.
I just figured that the overlay applies to a range of text, and the replacement text is within that range ... so it seems like it should be affected. I guess not, though. So what you're saying is, since the replacement text is not technically part of the buffer text, it doesn't count as being within the range of the overlay, and it isn't affected by the overlay at all? But that's not the case either, because as you also stated, face attributes from the overlay are applied to the display string, as long as the display string doesn't already specify those attributes. So, it seems that the overlay is applied to the display string, but it just takes a lower priority than the display string's text properties. If that was the design, that's fine, but it does conflict with the documentation stating that overlays always take priority over text properties.
I haven't looked at the code for this, so I might be wrong, but what appears to be happening is this:
1. The overlay is applied to the buffer text, and the overlay face takes priority over the buffer text's faces
2. If the overlay had a display property, that would take priority over the buffer text's display property, but since the overlay has no such property, this doesn't happen
3. After the overlay is applied, the display property is applied, and its faces take priority over the existing faces, including those supplied by the overlay
So the priority goes: display property faces > overlay faces > buffer faces. Am I on the right track?