# Frames, overlays, dialogs, and the human

## Cross-origin frames and shadow DOM

A cross-origin iframe is a separate target with its own snapshot. `snapshotWithFrames(page)`
reconciles the child trees into the parent so one tree describes the whole page, and reports
`missingFrames` for any it could not enter; address child elements through the page-level ref
(`f1e3`) — never by fetching a frame handle first. Shadow roots are traversed by the snapshot
engine; they are not a special case for you.

## Overlays that swallow clicks

Two identical misses on an element that is clearly visible usually means something invisible sits
on top: a consent banner, a modal backdrop, a sticky header, a full-viewport tracking layer.
`describeLayers(page)` names the topmost fixed or sticky element covering the viewport, and
`snapshotWithLayers(page)` prefixes a snapshot with `@layers blocking=<role> "<name>"` when one
exists. Either the overlay is named — dismiss it and continue — or `@layers none`, which means the
miss has another cause and you climb the ladder instead.

## Dialogs never block

`alert`, `confirm`, `prompt`, and `beforeunload` are answered at the protocol layer, before the
page sees them: by a `dialog` listener that answers, otherwise by the `dialogPolicy` passed to
`connectPipe` (or `browser.setDialogPolicy`). Default to accepting (`{ accept: true }`; a policy
function receives a plain `{ type, message, defaultPrompt, url }` and returns `{ accept, promptText }`).

`page.on("dialog", (dialog) => ...)` hands each listener a Playwright-style `Dialog` object, not a
plain object: read it through methods (`dialog.type()`, `dialog.message()`, `dialog.defaultValue()`,
and the `dialog.url` getter). A listener can answer it itself, which replaces the policy for that
dialog; a listener that only observes leaves it to the policy:

```js
page.on("dialog", (dialog) => dialog.type() === "prompt" ? dialog.accept("42") : dialog.dismiss())
```

A dialog is answered once; a second `accept()` / `dismiss()` throws. A run that hangs on
an unhandled dialog looks exactly like a hang with no cause, which is the most expensive kind to
diagnose.

## Device emulation

`emulate(page, "iphone-14")` applies viewport, device scale factor, user agent and touch together;
changing only the viewport produces a desktop page at a phone size, which is not what you are
testing. `emulate(page, null)` restores. Re-read the viewport after emulating, and re-pin
coordinates.

## Handing the page to a human

When every rung fails on a login, a one-time code, or a challenge you cannot clear, the human is
the fallback, not the failure:

```js
const { outcome } = await omowright.requestHuman(page, {
  prompt: "Please finish the sign-in in this window.",
  until: { url: /\/dashboard/ },          // or { selector } or async (page) => boolean
  timeoutMs: 300_000,
})
```

It brings the window to the front, shows a banner with a Done button, and waits on a
**condition** with a bounded timeout rather than a fixed delay. Respect the answer: `timed_out`
or `cancelled` is a stop, and the correct response is to report which rung failed with what
evidence. Working around the user's refusal is never correct.
