fix(web-integration): add browser agent page following

Author: quanru

apps/site/docs/en/automate-with-scripts-in-yaml.mdx

@@ -192,6 +192,10 @@ web:
   # Whether to restrict page navigation to the current tab, optional, defaults to true.
   forceSameTabNavigation: <boolean>
 
+  # Whether to use BrowserAgent and automatically continue in newly opened pages, optional, defaults to false.
+  # Cannot be used together with forceSameTabNavigation: true.
+  autoFollowNewPage: <boolean>
+
   # CDP endpoint, optional. Connects to an existing browser instance via CDP instead of launching a new one.
   # Mutually exclusive with bridgeMode.
   cdpEndpoint: ws://localhost:9222/devtools/browser

apps/site/docs/en/integrate-with-playwright.mdx

@@ -267,14 +267,18 @@ After the command executes successfully, it will output: `Midscene - report file
 
 Each Agent instance is bound to a single page. To make debugging easier, Midscene intercepts new tabs by default (for example, links with `target="_blank"`) and opens them in the current page.
 
-If you want to restore opening in a new tab, set `forceSameTabNavigation` to `false`—but you’ll need to create a new Agent instance for each new tab.
+If you want to restore opening in a new tab while keeping the Agent on the original page, set `forceSameTabNavigation` to `false` and create a new Agent instance for each new tab yourself.
+
+If subsequent actions should automatically continue in the newly opened tab, use `PlaywrightBrowserAgent` and enable `autoFollowNewPage`.
 
 ```typescript
-const mid = new PlaywrightAgent(page, {
-  forceSameTabNavigation: false,
+const mid = new PlaywrightBrowserAgent(context, page, {
+  autoFollowNewPage: true,
 });
 ```
 
+Use `PlaywrightBrowserAgent.create(context, options)` only when you do not already have a page. The factory uses `initialPage` when provided, otherwise it reuses the first existing context page or creates a new page.
+
 ### Connect Midscene Agent to a Remote Playwright Browser
 
 :::info Example Project

apps/site/docs/en/integrate-with-puppeteer.mdx

@@ -106,14 +106,18 @@ After the above command executes successfully, the console will output: `Midscen
 
 Each Agent instance is bound to a single page. For easier debugging, Midscene intercepts new tabs by default (for example, links with `target="_blank"`) and opens them in the current page.
 
-If you want to allow new tabs again, set `forceSameTabNavigation` to `false`—but you must create a new Agent instance for each new tab.
+If you want to allow new tabs again while keeping the Agent on the original page, set `forceSameTabNavigation` to `false` and create a new Agent instance for each new tab yourself.
+
+If subsequent actions should automatically continue in the newly opened tab, use `PuppeteerBrowserAgent` and enable `autoFollowNewPage`.
 
 ```typescript
-const mid = new PuppeteerAgent(page, {
-  forceSameTabNavigation: false,
+const mid = new PuppeteerBrowserAgent(browser, page, {
+  autoFollowNewPage: true,
 });
 ```
 
+Use `PuppeteerBrowserAgent.create(browser, options)` only when you do not already have a page. The factory uses `initialPage` when provided, otherwise it reuses the first existing browser page or creates a new page.
+
 ### Connect Midscene Agent to a Remote Puppeteer Browser
 
 :::info Example Project

apps/site/docs/en/web-api-reference.mdx

@@ -56,11 +56,29 @@ In addition to the base agent options, Puppeteer exposes:
 
 :::info
 
-- One agent per page: by default (`forceSameTabNavigation: true`), Midscene opens new links in the current tab for easier debugging. Set it to `false` if you want new tabs, and create a new agent per tab.
+- One agent per page: by default (`forceSameTabNavigation: true`), Midscene opens new links in the current tab for easier debugging. Set it to `false` if you want normal new-tab behavior and create a new `PuppeteerAgent` for each page yourself. Use `PuppeteerBrowserAgent` when the same Agent should manage browser-level page switching.
 - For the full list of interaction methods, see [API reference (Common)](./api#interaction-methods).
 
 :::
 
+### Browser agent
+
+Use `PuppeteerBrowserAgent` when one Midscene Agent should manage page switching inside a Puppeteer browser.
+
+```ts
+const agent = new PuppeteerBrowserAgent(browser, page, {
+  autoFollowNewPage: true,
+});
+```
+
+- Constructor: `new PuppeteerBrowserAgent(browser, page, options?)` — Use this when you already have the initial page.
+- Factory: `PuppeteerBrowserAgent.create(browser, options?)` — Use this when you do not already have a page. It uses `initialPage` if provided, otherwise the first existing browser page, or creates a new page.
+- `initialPage: Page` — Initial Puppeteer page for the factory.
+- `autoFollowNewPage: boolean` — Automatically switch the active page when the browser opens a new page. Default `false`.
+- `newPageTimeout: number` — Timeout for `waitForNewPage`. Default `5000`.
+- `setActivePage(page: Page)` — Explicitly set which Puppeteer page the Browser Agent controls next.
+- `waitForNewPage(action?, options?)` — Wait for a newly opened page without implicitly switching the active page.
+
 ### Examples
 
 #### Quick start
@@ -143,11 +161,29 @@ const agent = new PlaywrightAgent(page, {
 
 :::info
 
-- One agent per page: with `forceSameTabNavigation` (default `true`), Midscene intercepts new tabs for stability. Set it to `false` to allow new tabs and create a separate agent for each.
+- One agent per page: with `forceSameTabNavigation` (default `true`), Midscene intercepts new tabs for stability. Set it to `false` to allow normal new tabs and create a new `PlaywrightAgent` for each page yourself. Use `PlaywrightBrowserAgent` when the same Agent should manage browser-context-level page switching.
 - For the full list of interaction methods, see [API reference (Common)](./api#interaction-methods).
 
 :::
 
+### Browser agent
+
+Use `PlaywrightBrowserAgent` when one Midscene Agent should manage page switching inside a Playwright browser context.
+
+```ts
+const agent = new PlaywrightBrowserAgent(context, page, {
+  autoFollowNewPage: true,
+});
+```
+
+- Constructor: `new PlaywrightBrowserAgent(context, page, options?)` — Use this when you already have the initial page.
+- Factory: `PlaywrightBrowserAgent.create(context, options?)` — Use this when you do not already have a page. It uses `initialPage` if provided, otherwise the first existing context page, or creates a new page.
+- `initialPage: Page` — Initial Playwright page for the factory.
+- `autoFollowNewPage: boolean` — Automatically switch the active page when the context opens a new page. Default `false`.
+- `newPageTimeout: number` — Timeout for `waitForNewPage`. Default `5000`.
+- `setActivePage(page: Page)` — Explicitly set which Playwright page the Browser Agent controls next.
+- `waitForNewPage(action?, options?)` — Wait for a newly opened page without implicitly switching the active page.
+
 ### Examples
 
 #### Quick start

apps/site/docs/zh/automate-with-scripts-in-yaml.mdx

@@ -191,6 +191,10 @@ web:
   # 是否限制页面在当前 tab 打开，可选，默认 true
   forceSameTabNavigation: <boolean>
 
+  # 是否使用 BrowserAgent 并自动继续在新打开的页面中执行，可选，默认 false
+  # 不能与 forceSameTabNavigation: true 同时使用
+  autoFollowNewPage: <boolean>
+
   # CDP 连接端点，可选。设置后通过 CDP 连接到已有浏览器实例，而非启动新浏览器。
   # 与 bridgeMode 互斥，不可同时使用。
   cdpEndpoint: ws://localhost:9222/devtools/browser

apps/site/docs/zh/integrate-with-playwright.mdx

@@ -266,14 +266,18 @@ npx playwright test ./e2e/ebay-search.spec.ts
 
 每个 Agent 实例都与对应的页面唯一绑定，为了方便开发者调试，Midscene 默认拦截了新 tab 的页面（如点击一个带有 `target="_blank"` 属性的链接），将其改为在当前页面打开。
 
-如果你想恢复在新标签页打开的行为，你可以设置 `forceSameTabNavigation` 选项为 `false`，但相应的，你需要为新标签页创建一个 Agent 实例。
+如果你想恢复在新标签页打开的行为，同时让当前 Agent 仍留在原页面，可以设置 `forceSameTabNavigation` 为 `false`，并自行为每个新标签页创建新的 Agent 实例。
+
+如果后续操作要自动继续在新打开的标签页中执行，请使用 `PlaywrightBrowserAgent` 并开启 `autoFollowNewPage`。
 
 ```typescript
-const mid = new PlaywrightAgent(page, {
-  forceSameTabNavigation: false,
+const mid = new PlaywrightBrowserAgent(context, page, {
+  autoFollowNewPage: true,
 });
 ```
 
+仅当你手上还没有现成的 page 时，才需要使用 `PlaywrightBrowserAgent.create(context, options)`。这个工厂会优先使用 `initialPage`，否则复用 context 里的第一个页面，或者创建一个新页面。
+
 ### 连接远程 Playwright 浏览器并接入 Midscene Agent
 
 :::info 示例项目

apps/site/docs/zh/integrate-with-puppeteer.mdx

@@ -106,14 +106,18 @@ npx tsx demo.ts
 
 每个 Agent 实例都与对应的页面唯一绑定，为了方便开发者调试，Midscene 默认拦截了新 tab 的页面（如点击一个带有 `target="_blank"` 属性的链接），将其改为在当前页面打开。
 
-如果你想恢复在新标签页打开的行为，你可以设置 `forceSameTabNavigation` 选项为 `false`，但相应的，你需要为新标签页创建一个 Agent 实例。
+如果你想恢复在新标签页打开的行为，同时让当前 Agent 仍留在原页面，可以设置 `forceSameTabNavigation` 为 `false`，并自行为每个新标签页创建新的 Agent 实例。
+
+如果后续操作要自动继续在新打开的标签页中执行，请使用 `PuppeteerBrowserAgent` 并开启 `autoFollowNewPage`。
 
 ```typescript
-const mid = new PuppeteerAgent(page, {
-  forceSameTabNavigation: false,
+const mid = new PuppeteerBrowserAgent(browser, page, {
+  autoFollowNewPage: true,
 });
 ```
 
+仅当你手上还没有现成的 page 时，才需要使用 `PuppeteerBrowserAgent.create(browser, options)`。这个工厂会优先使用 `initialPage`，否则复用浏览器里的第一个页面，或者创建一个新页面。
+
 ### 连接远程 Puppeteer 浏览器并接入 Midscene Agent
 
 :::info 示例项目

apps/site/docs/zh/web-api-reference.mdx

@@ -56,11 +56,29 @@ const agent = new PuppeteerAgent(page, {
 
 :::info
 
-- 每个页面一个 Agent：默认情况下（`forceSameTabNavigation: true`）Midscene 会拦截新标签并在当前页打开，便于调试；若想保留新标签行为可设为 `false`，并为每个标签创建新的 Agent。
+- 每个页面一个 Agent：默认情况下（`forceSameTabNavigation: true`）Midscene 会拦截新标签并在当前页打开，便于调试；若想保留浏览器原生的新标签行为可设为 `false`，并自行给每个页面创建新的 `PuppeteerAgent`。如果需要同一个 Agent 管理浏览器级别的页面切换，请使用 `PuppeteerBrowserAgent`。
 - 更多交互方法请参考 [API 参考（通用）](./api#interaction-methods)。
 
 :::
 
+### Browser Agent
+
+当一个 Midscene Agent 需要管理 Puppeteer 浏览器内的页面切换时，使用 `PuppeteerBrowserAgent`。
+
+```ts
+const agent = new PuppeteerBrowserAgent(browser, page, {
+  autoFollowNewPage: true,
+});
+```
+
+- 构造函数：`new PuppeteerBrowserAgent(browser, page, options?)` —— 已经有初始页面时使用。
+- 工厂方法：`PuppeteerBrowserAgent.create(browser, options?)` —— 手上还没有 page 时使用。它会优先使用 `initialPage`，否则复用浏览器里的第一个页面，或者创建一个新页面。
+- `initialPage: Page` —— 工厂方法使用的初始 Puppeteer 页面。
+- `autoFollowNewPage: boolean` —— 浏览器打开新页面时是否自动切换 active page，默认 `false`。
+- `newPageTimeout: number` —— `waitForNewPage` 的超时时间，默认 `5000`。
+- `setActivePage(page: Page)` —— 显式指定 Browser Agent 接下来控制哪个 Puppeteer 页面。
+- `waitForNewPage(action?, options?)` —— 等待新打开的页面，但不会隐式切换 active page。
+
 ### 示例
 
 #### 快速上手
@@ -143,11 +161,29 @@ const agent = new PlaywrightAgent(page, {
 
 :::info
 
-- 每个页面一个 Agent：默认 `forceSameTabNavigation` 为 `true`，Midscene 会拦截新标签确保稳定性；如需新标签请设为 `false` 并为每个标签创建新的 Agent。
+- 每个页面一个 Agent：默认 `forceSameTabNavigation` 为 `true`，Midscene 会拦截新标签确保稳定性；如需浏览器原生新标签行为请设为 `false`，并自行给每个页面创建新的 `PlaywrightAgent`。如果需要同一个 Agent 管理 browser context 级别的页面切换，请使用 `PlaywrightBrowserAgent`。
 - 更多交互方法请参考 [API 参考（通用）](./api#interaction-methods)。
 
 :::
 
+### Browser Agent
+
+当一个 Midscene Agent 需要管理 Playwright browser context 内的页面切换时，使用 `PlaywrightBrowserAgent`。
+
+```ts
+const agent = new PlaywrightBrowserAgent(context, page, {
+  autoFollowNewPage: true,
+});
+```
+
+- 构造函数：`new PlaywrightBrowserAgent(context, page, options?)` —— 已经有初始页面时使用。
+- 工厂方法：`PlaywrightBrowserAgent.create(context, options?)` —— 手上还没有 page 时使用。它会优先使用 `initialPage`，否则复用 context 里的第一个页面，或者创建一个新页面。
+- `initialPage: Page` —— 工厂方法使用的初始 Playwright 页面。
+- `autoFollowNewPage: boolean` —— context 打开新页面时是否自动切换 active page，默认 `false`。
+- `newPageTimeout: number` —— `waitForNewPage` 的超时时间，默认 `5000`。
+- `setActivePage(page: Page)` —— 显式指定 Browser Agent 接下来控制哪个 Playwright 页面。
+- `waitForNewPage(action?, options?)` —— 等待新打开的页面，但不会隐式切换 active page。
+
 ### 示例
 
 #### 快速上手

packages/core/src/yaml.ts

@@ -162,7 +162,8 @@ export interface MidsceneYamlScriptWebEnv
    */
   extraHTTPHeaders?: Record<string, string>;
 
-  forceSameTabNavigation?: boolean; // if track the newly opened tab, true for default in yaml script
+  forceSameTabNavigation?: boolean; // if limit the new tab to the current page, true for default in yaml script
+  autoFollowNewPage?: boolean; // if use BrowserAgent to follow newly opened pages, false for default
 
   /**
    * Custom Chrome launch arguments (Puppeteer only, not supported in bridge mode).

packages/web-integration/src/common/web-agent.ts

@@ -0,0 +1,72 @@
+import { getWebpackRequire } from '@/utils';
+import type { Page as PlaywrightPage } from 'playwright';
+import type { Page as PuppeteerPage } from 'puppeteer';
+import semver from 'semver';
+import {
+  BROWSER_NAVIGATION_ERROR_PATTERN,
+  forceChromeSelectRendering,
+} from '../puppeteer/base-page';
+
+type BrowserRuntime = 'puppeteer' | 'playwright';
+
+const browserRuntimeConfig: Record<
+  BrowserRuntime,
+  {
+    displayName: string;
+    packageName: string;
+    minimumVersion: string;
+    requirementLabel: string;
+  }
+> = {
+  puppeteer: {
+    displayName: 'Puppeteer',
+    packageName: 'puppeteer',
+    minimumVersion: '24.6.0',
+    requirementLabel: '> 24.6.0',
+  },
+  playwright: {
+    displayName: 'Playwright',
+    packageName: 'playwright',
+    minimumVersion: '1.52.0',
+    requirementLabel: '>= 1.52.0',
+  },
+};
+
+function getPackageVersion(packageName: string): string | null {
+  try {
+    const pkg = getWebpackRequire()(`${packageName}/package.json`);
+    return pkg.version || null;
+  } catch (error) {
+    console.error(
+      `[midscene:error] Failed to get ${packageName} version`,
+      error,
+    );
+    return null;
+  }
+}
+
+export function isRetryableBrowserNavigationError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    BROWSER_NAVIGATION_ERROR_PATTERN.test(error.message)
+  );
+}
+
+export function applyForceChromeSelectRendering(
+  page: PuppeteerPage | PlaywrightPage,
+  runtime: BrowserRuntime,
+  enabled?: boolean,
+): void {
+  if (!enabled) {
+    return;
+  }
+
+  const config = browserRuntimeConfig[runtime];
+  const version = getPackageVersion(config.packageName);
+  if (version && !semver.gte(version, config.minimumVersion)) {
+    console.warn(
+      `[midscene:error] forceChromeSelectRendering requires ${config.displayName} ${config.requirementLabel}, but current version is ${version}. This feature may not work correctly.`,
+    );
+  }
+  forceChromeSelectRendering(page);
+}