feat: multi-tab, popup, and backend-switching surfaces (carry-over of openadapt-flow#533)

packages/flow/README.md

@@ -289,9 +289,12 @@ Install the extras for the surface that records and replays the workflow:
 each surface, and [docs/PRODUCT_STATUS.md](docs/PRODUCT_STATUS.md) lists the
 evidence for each one. A bundle is bound to the surface it was recorded on.
 
-One bundle drives one surface: one browser tab, one desktop app, or one
-remote desktop session. For a task that crosses surfaces, record one bundle
-per surface and chain them with `openadapt-flow compose`. Each child starts
+A bundle drives one surface by default: one browser tab, one desktop app, or
+one remote desktop session. A bundle can also declare more than one surface:
+popups and new tabs it opens, or another backend it switches to with an
+explicit, identity-checked step. See [docs/MULTI_SURFACE.md](docs/MULTI_SURFACE.md)
+for this and its limits. Otherwise, record one bundle per surface and chain
+them with `openadapt-flow compose`. Each child starts
 only after the one before it ends with a checked save, unless you allow a
 specific stop with `--allow-halt`.
 

packages/flow/docs/BROWSER_RECORDING.md

@@ -76,6 +76,12 @@ Flow selects the sole open HTTP or HTTPS tab on the `--url` origin. It does not
 navigate the tab. It also does not close the tab or browser when recording
 finishes.
 
+Attach mode follows a popup or tab that the selected tab (or a page it already
+follows) opened, on the declared origin. These pages are recorded as surfaces,
+as they are in a browser Flow launched (`record --url`); see
+[MULTI_SURFACE.md](MULTI_SURFACE.md). A tab the person opens by hand is
+refused.
+
 If two or more open tabs have that origin, Flow refuses to guess. Supply the
 exact current URL:
 
@@ -133,8 +139,10 @@ silently acting in a new, signed-out one.
 - The selected tab must stay on that origin for the full recording. A
   cross-origin navigation stops the recording and does not produce complete
   metadata.
-- Do not open a popup or a new tab in the selected tab's browser context while
-  recording. Flow currently binds one page. It installs a new-page latch on
+- Do not open a new tab by hand in the selected tab's browser context while
+  recording. A popup or tab that a followed page opens is followed, judged by
+  `window.opener` or the browser target's opener id. Any other new page is
+  refused. Flow installs a new-page latch on
   every candidate context before it reads the accepted page baseline or selects
   the recording tab. Listener registration does not replay pre-existing tabs,
   so those tabs remain allowed. The selected-context latch records every later
@@ -371,7 +379,7 @@ Attach mode supports local Chromium-family browsers that expose a CDP
 endpoint. It requires a browser process started with remote debugging and a
 separate user-data directory. It does not claim Firefox, WebKit, arbitrary
 Chrome extensions, an ordinary browser process that was not started for local
-debugging, cross-origin tab selection, multi-page/popup recording, or direct
+debugging, cross-origin tab selection, cross-origin popups, or direct
 extension replay.
 
 Same-origin iframes are recorded: every emitted coordinate is composed into
@@ -395,8 +403,11 @@ Refused loudly, never recorded silently wrong:
   dropdown UI that produces no recordable action events, so the choice would
   be silently absent from the compiled workflow. The recording stops with an
   explicit error at the moment of selection.
-- A new tab or popup. The recording is bound to one tab and stops when
-  another page appears.
+- In attach mode, a new tab that no followed page opened, or a popup on
+  another origin. Popups and tabs that a followed page opens are recorded as
+  surfaces ([MULTI_SURFACE.md](MULTI_SURFACE.md)). A popup that closes itself
+  is followed by an explicit switch back. A popup whose first action closes
+  it, before any frame of it was captured, stops the recording.
 - An action in a frame whose page-space position cannot be proven (see
   above).
 

packages/flow/docs/LIMITS.md

@@ -463,7 +463,7 @@ and exposes independently verifiable outcomes.
 | --- | --- |
 | Zoom, DPI, font, layout, viewport, or monitor changes | Browser attach recording accepts a stable viewport or device-scale change between actions, starts a new exact geometry epoch, and refuses an action that overlaps the transition. Native offline conversion can normalize a stable source-window move, resize, monitor change, or scale change into one fixed output viewport when every timeline row carries valid mapping metadata. It refuses a malformed timeline or a changed output viewport. RDP and Citrix live backends can rebaseline geometry between actions and refuse a change during the exact-frame lease. Other rescale or reflow behavior remains workflow-specific. |
 | Native select menus, file choosers, permission prompts, and secure desktops | OS or browser chrome may not appear in the captured surface and may be unrecordable or undrivable. Prefer an application-level or keyboard/API path. |
-| New tabs and windows | Opening a tab can be observed structurally where the backend supports it; interaction inside additional windows and multi-window coordination are not a general supported path. |
+| New tabs and windows | A bundle recorded with `Recorder` can declare the popups and tabs a step opens, act in them after an explicit surface switch, and halt on any page it did not declare ([MULTI_SURFACE.md](MULTI_SURFACE.md)). Such bundles run governed, qualified, and durable. Resume re-binds surfaces by identity, and managed Cloud dispatch needs only the `surfaces:` map. A program (graph) resume is refused. `record --url` and attach mode (`--cdp`, only pages a followed page opened) capture popups and tabs, and `--surface NAME=KIND[:TARGET]` binds backend surfaces at replay. Native windows and JavaScript dialogs are screen states, not surfaces. A dialog is answered by the step that raises it (browser backend, scripted recorder), and a hidden native window is reached by an explicit focus step. |
 | Drag and drop or gesture-heavy controls | Not a general supported primitive. Use a structured/API alternative or validate a purpose-built workflow. |
 | Dates, locale-sensitive fields, and auto-formatting | The same keystrokes can produce different values across platforms or locales. Require an explicit read-back or system effect and test the deployment locale. |
 | Slow or asynchronous applications | A state that outlasts configured waits can halt. Increasing a timeout does not establish correctness. |