screen method

Future<void> screen(
  1. String name, {
  2. List<String> tags = const [],
  3. Settle? settle,
  4. bool force = false,
})

Names the screen as it stands, without performing an action.

Where nothing has moved since the last verb captured — the ordinary tap then screen pair — this names that capture rather than photographing the same frame a second time:

await s.tap(Keys.search);
await s.screen('Cases');   // one step, named 'Cases', verb `tap`

So a name costs nothing, and an author never has to weigh writing one against the picture it would duplicate. "Nothing has moved" is answered twice: the frame count answers first and free — nothing drawn is the same picture — and where frames were drawn (extra settling between the verb and its name, a periodic timer repainting an identical screen) the render this call was about to pay anyway is compared against the held one — words, bytes and all — and a proven-identical screen adopts just the same. Only where the screen actually differs — a pump, a completer, a rebuild from outside the tree — is there something new to photograph, and this captures it, which is the whole reason the verb exists:

await s.tap(Keys.takePicture);
await s.screen('Capturing');        // names the tap's frame
await s.wait(const Duration(seconds: 5));
await s.screen('Captured');         // a new frame: its own step

It settles first, like every other verb — a capture wants a screen that has finished moving, and which verb waits and which does not is exactly the knowledge Settle exists to remove. To photograph a screen mid-flight, say so here, on the name rather than only on the verb before it:

await s.tap(Keys.takePicture, settle: Settle.none);
await s.screen('Capturing', settle: Settle.none);

Both halves, because the wait is per step and the second one would otherwise undo the first. On a screen holding an indefinite animation that is not pedantry: a bounded policy never sees a quiet frame there, so it spends its whole budget, and a spent budget under fake time is a clock that moved — every timer due inside the window fires, and the thing the scenario meant to photograph may have finished. True of any verb that follows, not only of this one.

A name never overwrites a name: two screen calls on one frame stay two steps. force declines the adoption outright, for a deliberate second picture of a frame that already has a name on it.

Implementation

Future<void> screen(
  String name, {
  List<String> tags = const [],
  Settle? settle,
  bool force = false,
}) => _step(
  Shot(name, tags: tags),
  settle,
  () async {},
  verb: 'screen',
  adopt: !force,
);