How labels are placed
With place: auto, shotlist chooses which side of a region a label goes on, and whether it sits over the screenshot or in a margin beside it. This page explains what it is weighing, so you can tell when to let it decide and when to override it.
The choice is not symmetrical
A label outside the capture needs space, and shotlist makes that space by extending the canvas. Which side it extends matters:
- a label to the left or right grows the canvas by the label's width
- a label above or below grows it by the label's height
On a wide screenshot with short labels those two costs differ by hundreds of pixels. Placing every label on the right, which is the obvious default, produces images that are mostly empty margin.
So auto weighs the canvas cost against how far the arrow would have to travel, and against whether the arrow's path would cross another mark or a masked region.
Why it reads the image
A label placed over the screenshot costs no canvas at all and needs only a stub of an arrow. That is the best outcome available — when there is somewhere to put it.
Whether there is somewhere to put it is not a question geometry can answer, because it depends on what the page rendered. So shotlist reads the pixels the label would cover and counts how many are far from that region's own average color.
Measuring distance from a local average, rather than from a fixed brightness, is what makes this work on real interfaces. A flat panel scores as empty however dark it is, and so does a gradient. Text or a chart over either does not. A test based on brightness alone would refuse to place a label on a dark sidebar, which is often the emptiest space in the image.
When the pixels cannot be read, the decision falls back to geometry.
What it cannot judge
shotlist can tell that a region has detail in it. It cannot tell what that detail is for.
An arrow drawn across a paragraph of body text is a legible arrow over a region with detail, which is a case the placement logic already avoids. An arrow drawn across a diagram the reader is meant to be studying is exactly the same measurement, and the same decision, but a worse outcome. The difference is editorial, and it lives with you.
That is why an explicit place is obeyed exactly, and so is an explicit inside. Automatic placement is a default for the many callouts where the answer does not matter, not a recommendation to be argued with on the few where it does.
Overlap between labels
Callouts are placed one after another, and a label that would overlap one already drawn is moved. This means the order of your callouts list affects the result: the first callout gets the position it wants, and later ones accommodate it.
If a screenshot's annotations look unbalanced, reordering the list is often a smaller change than naming a side for each one.
Discs are different
A numbered disc carries no text, so it has no width worth reasoning about and nowhere it needs to escape to. It defaults to sitting inside the box, anchored to a corner you choose with badge. There is no auto for discs, because the tradeoff that makes auto useful for labels does not exist for them.