nit: I'd drop the "can" and just start with "sizes". The word "can" instills doubt. I'm guessing you added it because there's no guarantee that this overlay is the top-most one and so it will not necessarily be used to determine the size of the view. However, that's just a precedence rule or a tie-breaker. It's still OK to say that it sizes the view.

The word "can" instills doubt.

That's exactly the doubt I want to install because in the vast majority of cases (the Overlay is getting non-infinite constraints) it does not size the overlay. The cases where it does size it are very, very, very rare. I want people to see this property, pause, and read the documentation to learn when it will size the overlay.

nit: it's pretty clear what "Overlay" and "OverlayEntries" are referring to, so I'd just use the plain English phrases "overlay" and "overlay entries" to refer to them. Otherwise, without the [...] they are kind of in limbo state, neither proper symbol links, nor proper nouns.

good point, updated.

Has it been asserted elsewhere that child.parentData vends StackParentData? If not, consider asserting with a descriptive error message prior to unboxing.

It's guaranteed to be StackParentData here and using it this way is the established pattern in the framework.

Or adding a overlay entry with canSizeOverlay set to true?

Added.

Should we memoize the sizeDeterminingChild from the computeDryLayout invocation? I can imagine two issues with the code as is:

1. Due to a bug _findSizeDeterminingChild() returns different children and the code will keep on trucking, sizing itself incorrectly.
2. It looks up the same child twice, while a single look-up would suffice. Of course, in debug mode we could assert that the child hasn't changed since the last look-up.

If we go with memoization, we'd probably want to null out the memoized child after the layout is done for this frame, because it should be legal to change the child in the next frame.

The "dry" part in computeDryLayout means that the layout should be computed without changing any internal state. There is no guarantee that performLayout is called after computeDryLayout or that it is called with the same constraints or that the RenderObject is still in the same state when it is called and the memoized child is still valid. Of course, we could add caching logic that is invalidated when necessary, but let's defer adding more complexity to this until we see an actual performance problem with this (given that there are only every very few children in a overlay I doubt that there is much performance gain to be had here).

nit: I'd move this above the testWidgets and reduce the number of empty lines in the body of the test.

Consider being more specific than "works". For example, "sizes to its child".

ditto re "works"

nit: "and has no"

The last part of the sentence was confusing to me. "child that has OverlayEntry.canSizeOverlay set to true" sounds wrong because the positioned child is not an OverlayEntry so it can't have OverlayEntry.canSizeOverlay set to true. How about "but the overlay did not contain an overlay entry with a non-positioned child"?

Rephrased this a bit to hopefully remove that confusion. Just having a non-positioned child is not enough, though, it has to belong to an OverlayEntry that also sets canSizeOverlay. Hope that's clearer now.

Unless the OverlayEntry is positioned?

Right, updated this to make that clearer.

question: determining whether an OverlayEntry can handle unconstrained BoxConstraints sounds a bit challenging in general? Right now it seems it's always set to true for opaque routes,
so I guess the idea is to trust developers to not put widgets that want to take the full width/height, into a dynamically sized view, without applying extra constraints? If they did then RenderBox.setter should be able to provide actionable feedback?

Yes, all of this is true, assuming you mean the RenderBox.size setter.

nit: not necessarily completely unconstrained I think? Maybe it's just infinite maxWidth or infinite maxHeight or infinite both? I feel unconstrained [BoxConstraints] sounded like we are going to throw the incoming constraints away.

(Can a dynamically sized view give you constrained width but unconstrained height?)

I feel unconstrained [BoxConstraints] sounded like we are going to throw the incoming constraints away.

Oh, good catch. I'll update the docs to make it clear that we just pass on the incoming constraints in that case.

(Can a dynamically sized view give you constrained width but unconstrained height?)

Yes, this is allowed.

Should non-positioned be mentioned here too?

I added it for clarity.

Should this be constraints.isTight? Otherwise, will this allow the user to give the view the flexibility to size itself, but also set a limit to make sure the size doesn't blow up? If I'm reading it correctly, if the constraints are limited in any way then we'll force it to take up all the available space, even if biggest is overkill for the content that's shown.

If I'm reading it correctly, if the constraints are limited in any way then we'll force it to take up all the available space, even if biggest is overkill for the content that's shown.

Yes, that's existing behavior and a lot of things would likely break if we change that :)