@letsscrapedata/controller 0.0.38 → 0.0.40

package/dist/index.cjs

@@ -76,7 +76,6 @@ var PlaywrightElement = class _PlaywrightElement {
     return names;
   }
   /*
-    // 如果不存在指定的子iframe，则返回null
     async #getChildFrame(parentFrame: Frame, iframeOption: IframeOption): Promise<Frame | null> {
       if (!parentFrame) {
         throw new Error("Invalid parent frame");
@@ -268,6 +267,13 @@ var PlaywrightElement = class _PlaywrightElement {
     await this.#locator.press(key, options);
     return true;
   }
+  async screenshot(options) {
+    return await this.#locator.screenshot(options);
+  }
+  async scrollIntoView() {
+    await this.#locator.scrollIntoViewIfNeeded();
+    return true;
+  }
   async select(options) {
     const { type, values = [], labels = [], indexes = [] } = options;
     switch (type) {
@@ -307,13 +313,15 @@ var PlaywrightElement = class _PlaywrightElement {
     }
     return true;
   }
-  async screenshot(options) {
-    return await this.#locator.screenshot(options);
-  }
-  async scrollIntoView() {
-    await this.#locator.scrollIntoViewIfNeeded();
+  async setAttribute(attributeName, newValue) {
+    await this.#locator.evaluate((node) => {
+      node.setAttribute(attributeName, newValue);
+    });
     return true;
   }
+  _origElement() {
+    return this.#locator;
+  }
 };
 
 // src/playwright/page.ts
@@ -420,7 +428,6 @@ var PlaywrightPage = class extends import_node_events.default {
     return true;
   }
   /*
-    // 如果不存在指定的子iframe，则返回null
     async #getChildFrame(parentFrame: Frame, iframeOption: IframeOption): Promise<Frame | null> {
       if (!parentFrame) {
         throw new Error("Invalid parent frame");
@@ -1354,6 +1361,13 @@ var PlaywrightBrowserContext = class extends import_node_events2.default {
       return false;
     }
   }
+  doesMeetBrowserContextRequirements(browserContextRequirements) {
+    if (!this.#lsdBrowser.doesMeetBrowserContextRequirements(browserContextRequirements)) {
+      return false;
+    }
+    const { incognitos } = browserContextRequirements;
+    return incognitos.length === 0 || incognitos.includes(this.#incognito);
+  }
   async getPage(always = false) {
     if (!this.#browserContext) {
       throw new Error("Invalid browserContext");
@@ -1491,7 +1505,7 @@ var PlaywrightBrowser = class extends import_node_events3.default {
   #maxPageFreeSeconds() {
     return this.#options.maxPageFreeSeconds ? this.#options.maxPageFreeSeconds : 900;
   }
-  // 构造函数：缺省只能由LsdBrowserController.launch/connect调用创建实例!!!
+  // constructor: called only by LsdBrowserController.launch/connect
   constructor(browser, browerType, browserCreateMethod, options, browserIdx = 0, pid = 0) {
     if (!browser || typeof browser.contexts !== "function") {
       throw new Error(`Invalid playwright browser parameter`);
@@ -1557,7 +1571,6 @@ var PlaywrightBrowser = class extends import_node_events3.default {
       await lsdBrowserContext.closeFreePages();
     }
   }
-  // 常用方法（按常见调用顺序排序）
   async newBrowserContext(options) {
     if (this.#lsdBrowserContexts.length >= this.#maxBrowserContextsPerBrowser()) {
       (0, import_utils4.logwarn)(`##browser ${this.id()} can not create more new browserContext`);
@@ -1592,7 +1605,6 @@ var PlaywrightBrowser = class extends import_node_events3.default {
     await this.#browser.close();
     return true;
   }
-  // 其它方法（按字母顺序排序）
   browserContexts() {
     return this.#lsdBrowserContexts;
   }
@@ -1605,6 +1617,10 @@ var PlaywrightBrowser = class extends import_node_events3.default {
   browserType() {
     return this.#browserType;
   }
+  doesMeetBrowserContextRequirements(browserContextRequirements) {
+    const { browserControllerTypes, browserTypes, headlesses } = browserContextRequirements;
+    return (browserControllerTypes.length === 0 || browserControllerTypes.includes(this.#browserControllerType)) && (browserTypes.length === 0 && browserTypes.includes(this.#browserType)) && (headlesses.length === 0 && headlesses.includes(this.#headless));
+  }
   executablePath() {
     return this.#executablePath;
   }
@@ -1669,7 +1685,6 @@ var PuppeteerElement = class _PuppeteerElement {
     const names = await this.#frame.evaluate((ele) => ele.getAttributeNames(), this.#$ele);
     return names;
   }
-  // 如果不存在指定的子iframe，则返回null
   async #getChildFrame(parentFrame, iframeOption) {
     if (!parentFrame) {
       throw new Error("Invalid parent frame");
@@ -1847,6 +1862,15 @@ var PuppeteerElement = class _PuppeteerElement {
     await this.#$ele.press(key, options);
     return true;
   }
+  async screenshot(options) {
+    return await this.#$ele.screenshot(options);
+  }
+  async scrollIntoView() {
+    await this.#frame.evaluate((ele) => {
+      ele.scrollIntoView();
+    }, this.#$ele);
+    return true;
+  }
   async select(options) {
     const { type, values = [], labels = [], indexes = [] } = options;
     switch (type) {
@@ -1901,15 +1925,15 @@ var PuppeteerElement = class _PuppeteerElement {
     }
     return true;
   }
-  async screenshot(options) {
-    return await this.#$ele.screenshot(options);
-  }
-  async scrollIntoView() {
-    await this.#frame.evaluate((ele) => {
-      ele.scrollIntoView();
-    }, this.#$ele);
+  async setAttribute(attributeName, newValue) {
+    await this.#frame.evaluate((ele, name, value) => {
+      ele.setAttribute(name, value);
+    }, this.#$ele, attributeName, newValue);
     return true;
   }
+  _origElement() {
+    return this.#$ele;
+  }
 };
 
 // src/puppeteer/page.ts
@@ -1993,7 +2017,6 @@ var PuppeteerPage = class extends import_node_events4.default {
     });
     return true;
   }
-  // 如果不存在指定的子iframe，则返回null
   async #getChildFrame(parentFrame, iframeOption) {
     if (!parentFrame) {
       throw new Error("Invalid parent frame");
@@ -2875,6 +2898,13 @@ var PuppeteerBrowserContext = class extends import_node_events5.default {
       return false;
     }
   }
+  doesMeetBrowserContextRequirements(browserContextRequirements) {
+    if (!this.#lsdBrowser.doesMeetBrowserContextRequirements(browserContextRequirements)) {
+      return false;
+    }
+    const { incognitos } = browserContextRequirements;
+    return incognitos.length === 0 || incognitos.includes(this.#incognito);
+  }
   async getPage(always = false) {
     if (!this.#browserContext) {
       throw new Error("Invalid browserContext");
@@ -3017,7 +3047,7 @@ var PuppeteerBrowser = class extends import_node_events6.default {
   #userAgent() {
     return this.#options.userAgent ? this.#options.userAgent : "";
   }
-  // 构造函数：缺省只能由LsdBrowserController.launch/connect调用创建实例!!!
+  // constructor: called only by LsdBrowserController.launch/connect
   constructor(browser, browerType, browserCreateMethod, options, browserIdx = 0, pid = 0) {
     if (!browser || typeof browser.browserContexts !== "function") {
       throw new Error(`Invalid puppeteer browser parameter`);
@@ -3080,7 +3110,6 @@ var PuppeteerBrowser = class extends import_node_events6.default {
       await lsdBrowserContext.closeFreePages();
     }
   }
-  // 常用方法（按常见调用顺序排序）
   async newBrowserContext(options) {
     if (this.#lsdBrowserContexts.length >= this.#maxBrowserContextsPerBrowser()) {
       (0, import_utils8.logwarn)(`##browser ${this.id()} can not create more new browserContext`);
@@ -3111,7 +3140,6 @@ var PuppeteerBrowser = class extends import_node_events6.default {
     await this.#browser.close();
     return true;
   }
-  // 其它方法（按字母顺序排序）
   browserContexts() {
     return this.#lsdBrowserContexts;
   }
@@ -3124,6 +3152,10 @@ var PuppeteerBrowser = class extends import_node_events6.default {
   browserType() {
     return this.#browserType;
   }
+  doesMeetBrowserContextRequirements(browserContextRequirements) {
+    const { browserControllerTypes, browserTypes, headlesses } = browserContextRequirements;
+    return (browserControllerTypes.length === 0 || browserControllerTypes.includes(this.#browserControllerType)) && (browserTypes.length === 0 && browserTypes.includes(this.#browserType)) && (headlesses.length === 0 && headlesses.includes(this.#headless));
+  }
   executablePath() {
     return this.#executablePath;
   }
@@ -3265,13 +3297,19 @@ var CheerioElement = class _CheerioElement {
   async press() {
     throw new Error("Not supported in CheerioElement.");
   }
+  async screenshot() {
+    throw new Error("Not supported in CheerioElement.");
+  }
+  async scrollIntoView() {
+    throw new Error("Not supported in CheerioElement.");
+  }
   async select() {
     throw new Error("Not supported in CheerioElement.");
   }
-  async screenshot() {
+  async setAttribute() {
     throw new Error("Not supported in CheerioElement.");
   }
-  async scrollIntoView() {
+  _origElement() {
     throw new Error("Not supported in CheerioElement.");
   }
 };

package/dist/index.d.cts

@@ -1,23 +1,24 @@
 import EventEmitter from 'node:events';
-import { Browser as Browser$1, BrowserContext as BrowserContext$1, Frame as Frame$1, Page as Page$1, HTTPResponse, PuppeteerNode, ElementHandle } from 'puppeteer';
-import { Browser, BrowserContext, Frame, Page, Response, APIRequestContext, BrowserType, Locator, FrameLocator } from 'playwright';
-
-/**
- * 命名规则：为了与playwright/puppeteer中的同名区别
- * 1. name of type：AllXxxYyy，如AllBrowserContext
- * 2. 接口的实现类class的名称: LsdXxxYyy，如LsdBrowserContext
- */
+import { Browser as Browser$1, BrowserContext as BrowserContext$1, Frame as Frame$1, Page as Page$1, ElementHandle, HTTPResponse, PuppeteerNode } from 'puppeteer';
+import { Browser, BrowserContext, Frame, Page, Locator, Response, APIRequestContext, BrowserType, FrameLocator } from 'playwright';
 
 type AllBrowser = Browser | Browser$1;
 type AllBrowserContext = BrowserContext | BrowserContext$1;
 type AllFrame = Frame | Frame$1;
 type AllPage = Page | Page$1;
+type AllElement = Locator | ElementHandle;
 type AllResponse = Response | HTTPResponse;
 type AllApiRequestContext = APIRequestContext;
 type CheerioNode = cheerio.Cheerio;
 type BrowserControllerType = "puppeteer" | "playwright";
 type BrowserCreationMethod = "launch" | "connect";
 type LsdBrowserType = "chromium" | "firefox" | "webkit";
+interface BrowserContextRequirements {
+    browserControllerTypes: BrowserControllerType[];
+    browserTypes: LsdBrowserType[];
+    headlesses: boolean[];
+    incognitos: boolean[];
+}
 interface ProxyInController {
     proxyUrl: string;
     username?: string;
@@ -208,7 +209,7 @@ type LsdBrowserContextOptions = {
 type PageStatus = "free" | "busy" | "closed";
 /**
  * newpage: open by browserContext.newPage()
- * popup: open by clicking etc, 主要关注此类
+ * popup: open by clicking etc, important
  * manual: open by manual operation
  * launch: open by puppeteer.launch
  * connect: opened pages before connecting to browser
@@ -245,17 +246,16 @@ interface PageInfo {
      */
     openType: PageOpenType;
     /**
-     * page添加时间：针对非connect场景，也是page打开时间
      * @default current unix time
      */
     openTime: number;
     /**
-     * 上次status变化时间：如果status为free，表示空闲开始时间；如果status为busy，表示TE开始数据
+     * page's status: free or busy
      * @default current unix time
      */
     lastStatusUpdateTime: number;
     /**
-     * 正在执行的task的ID，参见enumSpecialTaskId
+     * taskId that are using this page
      * @default 0
      */
     taskId: number;
@@ -270,12 +270,12 @@ interface PageInfo {
 }
 interface UpdatablePageInfo {
     /**
-     * 上次status变化时间：如果status为free，表示空闲开始时间；如果status为busy，表示TE开始数据
+     * page's status: free or busy
      * @default current unix time
      */
     lastStatusUpdateTime?: number;
     /**
-     * 正在执行的task的ID，参见enumSpecialTaskId
+     * taskId that are using this page
      * @default 0
      */
     taskId?: number;
@@ -455,9 +455,11 @@ interface LsdElement {
      */
     input(value: string, options?: InputOptions): Promise<boolean>;
     press(key: KeyInput, options: KeyPressOptions): Promise<boolean>;
-    select(options: SelectOptions): Promise<boolean>;
     screenshot(options?: ScreenshotOptions): Promise<Buffer>;
     scrollIntoView(): Promise<boolean>;
+    select(options: SelectOptions): Promise<boolean>;
+    setAttribute(attributeName: string, newValue: string): Promise<boolean>;
+    _origElement(): AllElement;
 }
 interface ViewportSize {
     height: number;
@@ -949,7 +951,7 @@ interface LsdPage extends EventEmitter {
     title(): Promise<string>;
     url(): string;
     /**
-     * 开始使用该page(当前状态必须为free)
+     * start to use this free page
      */
     use(): boolean;
     /**
@@ -985,6 +987,11 @@ interface LsdBrowserContext extends EventEmitter {
      * @default 0 the default maxPageFreeSeconds of the browserContext will be used
      */
     closeFreePages(maxPageFreeSeconds?: number): Promise<boolean>;
+    /**
+     * doest this browser meet browserContextRequirements (incognitos ignored in browser)?
+     * @param browserContextRequirements
+     */
+    doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
     /**
      * get a free page from current pages or by creating a new page
      */
@@ -1016,6 +1023,11 @@ interface LsdBrowser extends EventEmitter {
     browserControllerType(): BrowserControllerType;
     browserCreationMethod(): BrowserCreationMethod;
     browserType(): LsdBrowserType;
+    /**
+     * doest this browser meet browserContextRequirements (incognitos ignored in browser)?
+     * @param browserContextRequirements
+     */
+    doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
     /**
      * @returns
      * 1. launched: actual executable path
@@ -1074,33 +1086,6 @@ interface LsdBrowserController$1 {
      */
     newApiContext(options?: LsdApiContextOptions): Promise<LsdApiContext>;
 }
-/**
- * globObj.cfg.XXX:
- * 1. 最大browser数:
- * 2. 最大browserContext数/browser:
- * 3. 最大page数/browserContext:
- *
- * 影响一个browserContext是否满足执行某TE(taskCfg)要求的因素包括：
- * 1. domainCfg/taskCfg对代理的要求：proxyTypes:
- * 2. domainCfg/taskCfg对浏览器的要求：
- * * browserControllerTypes: playwright | puppeteer
- * * browserTypes: chromium | firefox | webkit
- * * browserModes: normal | incognito
- * * browserHeads: headless | headful
- * * APP支持的浏览器因素：globObj.cfg.supportedBrowserControllerTypes/supportedBrowserTypes(尝试启动新浏览器时判断)
- * 3. 能力账号：capName
- *
- * 连接已有浏览器：
- * * endpoint：
- * * browserControllerTypes: playwright | puppeteer
- * * browserType: chromium | firefox | webkit
- * * browserMode: normal
- * * browserHead: headful
- * * proxyTypes：
- */
-interface BrowserManager {
-    getPage(): any;
-}
 
 declare class PlaywrightBrowser extends EventEmitter implements LsdBrowser {
     #private;
@@ -1111,6 +1096,7 @@ declare class PlaywrightBrowser extends EventEmitter implements LsdBrowser {
     browserControllerType(): BrowserControllerType;
     browserCreationMethod(): BrowserCreationMethod;
     browserType(): LsdBrowserType;
+    doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
     executablePath(): string;
     id(): string;
     isConnected(): boolean;
@@ -1132,6 +1118,7 @@ declare class PlaywrightBrowserContext extends EventEmitter implements LsdBrowse
     browser(): LsdBrowser;
     close(): Promise<boolean>;
     closeFreePages(maxPageFreeSeconds?: number): Promise<boolean>;
+    doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
     getPage(always?: boolean): Promise<LsdPage | null>;
     hasFreePage(pageNum?: number): boolean;
     id(): string;
@@ -1214,9 +1201,11 @@ declare class PlaywrightElement implements LsdElement {
     hover(): Promise<boolean>;
     input(value: string, options?: InputOptions): Promise<boolean>;
     press(key: KeyInput, options?: KeyPressOptions): Promise<boolean>;
-    select(options: SelectOptions): Promise<boolean>;
     screenshot(options?: ScreenshotOptions): Promise<Buffer>;
     scrollIntoView(): Promise<boolean>;
+    select(options: SelectOptions): Promise<boolean>;
+    setAttribute(attributeName: string, newValue: string): Promise<boolean>;
+    _origElement(): AllElement;
 }
 
 declare class PuppeteerBrowser extends EventEmitter implements LsdBrowser {
@@ -1228,6 +1217,7 @@ declare class PuppeteerBrowser extends EventEmitter implements LsdBrowser {
     browserControllerType(): BrowserControllerType;
     browserCreationMethod(): BrowserCreationMethod;
     browserType(): LsdBrowserType;
+    doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
     executablePath(): string;
     id(): string;
     isConnected(): boolean;
@@ -1249,6 +1239,7 @@ declare class PuppeteerBrowserContext extends EventEmitter implements LsdBrowser
     browser(): LsdBrowser;
     close(): Promise<boolean>;
     closeFreePages(maxPageFreeSeconds?: number): Promise<boolean>;
+    doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
     getPage(always?: boolean): Promise<LsdPage | null>;
     hasFreePage(pageNum?: number): boolean;
     id(): string;
@@ -1331,9 +1322,11 @@ declare class PuppeteerElement implements LsdElement {
     hover(): Promise<boolean>;
     input(value: string, options?: InputOptions): Promise<boolean>;
     press(key: KeyInput, options?: KeyPressOptions): Promise<boolean>;
-    select(options: SelectOptions): Promise<boolean>;
     screenshot(options?: ScreenshotOptions): Promise<Buffer>;
     scrollIntoView(): Promise<boolean>;
+    select(options: SelectOptions): Promise<boolean>;
+    setAttribute(attributeName: string, newValue: string): Promise<boolean>;
+    _origElement(): AllElement;
 }
 
 declare class CheerioPage extends EventEmitter implements LsdPage {
@@ -1411,9 +1404,11 @@ declare class CheerioElement implements LsdElement {
     hover(): Promise<boolean>;
     input(): Promise<boolean>;
     press(): Promise<boolean>;
-    select(): Promise<boolean>;
     screenshot(): Promise<Buffer>;
     scrollIntoView(): Promise<boolean>;
+    select(): Promise<boolean>;
+    setAttribute(): Promise<boolean>;
+    _origElement(): AllElement;
 }
 
 declare class LsdBrowserController implements LsdBrowserController$1 {
@@ -1427,4 +1422,4 @@ declare class LsdBrowserController implements LsdBrowserController$1 {
 }
 declare const controller: LsdBrowserController;
 
-export { type AllApiRequestContext, type AllBrowser, type AllBrowserContext, type AllFrame, type AllPage, type AllResponse, type BrowserControllerType, type BrowserCreationMethod, type BrowserLaunchMethod, type BrowserManager, type BrowserStateData, CheerioElement, type CheerioNode, CheerioPage, type ClientCertificate, type CookieItem, type GotoOptions, type IframeOption, type InputOptions, type KeyInput, type KeyPressOptions, type LocalStorageItem, type LocalStorageOrigin, type LowerCasePaperFormat, type LsdApiContext, type LsdApiContextOptions, type LsdApiResponse, type LsdBrowser, type LsdBrowserContext, type LsdBrowserContextOptions, type LsdBrowserController$1 as LsdBrowserController, type LsdBrowserType, type LsdConnectOptions, type LsdElement, type LsdFetchOptions, type LsdLaunchOptions, type LsdPage, type MouseClickOptions, type MouseClickType, type NavigationWaitUntil, type PDFMargin, type PDFOptions, type PageEvent, type PageExtInPlaywright, type PageExtInPuppeteer, type PageInfo, type PageOpenType, type PageStatus, type PaperFormat, PlaywrightBrowser, PlaywrightBrowserContext, type PlaywrightBrowserTypes, PlaywrightElement, PlaywrightPage, type ProxyInController, PuppeteerBrowser, PuppeteerBrowserContext, PuppeteerElement, PuppeteerPage, type RequestInterceptionAction, type RequestInterceptionOption, type RequestMatch, type RequestMethod, type RequestResourceType, type ResponseHandler, type ResponseHandlerOptions, type ResponseInterceptionItem, type ResponseInterceptionOption, type ResponseMatch, type ResponsePageData, type ScreenshotOptions, type SelectOptions, type UpdatablePageInfo, type ViewportSize, type WaitElementOptions, type WaitElementState, type WaitNavigationOptions, controller };
+export { type AllApiRequestContext, type AllBrowser, type AllBrowserContext, type AllElement, type AllFrame, type AllPage, type AllResponse, type BrowserContextRequirements, type BrowserControllerType, type BrowserCreationMethod, type BrowserLaunchMethod, type BrowserStateData, CheerioElement, type CheerioNode, CheerioPage, type ClientCertificate, type CookieItem, type GotoOptions, type IframeOption, type InputOptions, type KeyInput, type KeyPressOptions, type LocalStorageItem, type LocalStorageOrigin, type LowerCasePaperFormat, type LsdApiContext, type LsdApiContextOptions, type LsdApiResponse, type LsdBrowser, type LsdBrowserContext, type LsdBrowserContextOptions, type LsdBrowserController$1 as LsdBrowserController, type LsdBrowserType, type LsdConnectOptions, type LsdElement, type LsdFetchOptions, type LsdLaunchOptions, type LsdPage, type MouseClickOptions, type MouseClickType, type NavigationWaitUntil, type PDFMargin, type PDFOptions, type PageEvent, type PageExtInPlaywright, type PageExtInPuppeteer, type PageInfo, type PageOpenType, type PageStatus, type PaperFormat, PlaywrightBrowser, PlaywrightBrowserContext, type PlaywrightBrowserTypes, PlaywrightElement, PlaywrightPage, type ProxyInController, PuppeteerBrowser, PuppeteerBrowserContext, PuppeteerElement, PuppeteerPage, type RequestInterceptionAction, type RequestInterceptionOption, type RequestMatch, type RequestMethod, type RequestResourceType, type ResponseHandler, type ResponseHandlerOptions, type ResponseInterceptionItem, type ResponseInterceptionOption, type ResponseMatch, type ResponsePageData, type ScreenshotOptions, type SelectOptions, type UpdatablePageInfo, type ViewportSize, type WaitElementOptions, type WaitElementState, type WaitNavigationOptions, controller };

package/dist/index.d.ts

@@ -1,23 +1,24 @@
 import EventEmitter from 'node:events';
-import { Browser as Browser$1, BrowserContext as BrowserContext$1, Frame as Frame$1, Page as Page$1, HTTPResponse, PuppeteerNode, ElementHandle } from 'puppeteer';
-import { Browser, BrowserContext, Frame, Page, Response, APIRequestContext, BrowserType, Locator, FrameLocator } from 'playwright';
-
-/**
- * 命名规则：为了与playwright/puppeteer中的同名区别
- * 1. name of type：AllXxxYyy，如AllBrowserContext
- * 2. 接口的实现类class的名称: LsdXxxYyy，如LsdBrowserContext
- */
+import { Browser as Browser$1, BrowserContext as BrowserContext$1, Frame as Frame$1, Page as Page$1, ElementHandle, HTTPResponse, PuppeteerNode } from 'puppeteer';
+import { Browser, BrowserContext, Frame, Page, Locator, Response, APIRequestContext, BrowserType, FrameLocator } from 'playwright';
 
 type AllBrowser = Browser | Browser$1;
 type AllBrowserContext = BrowserContext | BrowserContext$1;
 type AllFrame = Frame | Frame$1;
 type AllPage = Page | Page$1;
+type AllElement = Locator | ElementHandle;
 type AllResponse = Response | HTTPResponse;
 type AllApiRequestContext = APIRequestContext;
 type CheerioNode = cheerio.Cheerio;
 type BrowserControllerType = "puppeteer" | "playwright";
 type BrowserCreationMethod = "launch" | "connect";
 type LsdBrowserType = "chromium" | "firefox" | "webkit";
+interface BrowserContextRequirements {
+    browserControllerTypes: BrowserControllerType[];
+    browserTypes: LsdBrowserType[];
+    headlesses: boolean[];
+    incognitos: boolean[];
+}
 interface ProxyInController {
     proxyUrl: string;
     username?: string;
@@ -208,7 +209,7 @@ type LsdBrowserContextOptions = {
 type PageStatus = "free" | "busy" | "closed";
 /**
  * newpage: open by browserContext.newPage()
- * popup: open by clicking etc, 主要关注此类
+ * popup: open by clicking etc, important
  * manual: open by manual operation
  * launch: open by puppeteer.launch
  * connect: opened pages before connecting to browser
@@ -245,17 +246,16 @@ interface PageInfo {
      */
     openType: PageOpenType;
     /**
-     * page添加时间：针对非connect场景，也是page打开时间
      * @default current unix time
      */
     openTime: number;
     /**
-     * 上次status变化时间：如果status为free，表示空闲开始时间；如果status为busy，表示TE开始数据
+     * page's status: free or busy
      * @default current unix time
      */
     lastStatusUpdateTime: number;
     /**
-     * 正在执行的task的ID，参见enumSpecialTaskId
+     * taskId that are using this page
      * @default 0
      */
     taskId: number;
@@ -270,12 +270,12 @@ interface PageInfo {
 }
 interface UpdatablePageInfo {
     /**
-     * 上次status变化时间：如果status为free，表示空闲开始时间；如果status为busy，表示TE开始数据
+     * page's status: free or busy
      * @default current unix time
      */
     lastStatusUpdateTime?: number;
     /**
-     * 正在执行的task的ID，参见enumSpecialTaskId
+     * taskId that are using this page
      * @default 0
      */
     taskId?: number;
@@ -455,9 +455,11 @@ interface LsdElement {
      */
     input(value: string, options?: InputOptions): Promise<boolean>;
     press(key: KeyInput, options: KeyPressOptions): Promise<boolean>;
-    select(options: SelectOptions): Promise<boolean>;
     screenshot(options?: ScreenshotOptions): Promise<Buffer>;
     scrollIntoView(): Promise<boolean>;
+    select(options: SelectOptions): Promise<boolean>;
+    setAttribute(attributeName: string, newValue: string): Promise<boolean>;
+    _origElement(): AllElement;
 }
 interface ViewportSize {
     height: number;
@@ -949,7 +951,7 @@ interface LsdPage extends EventEmitter {
     title(): Promise<string>;
     url(): string;
     /**
-     * 开始使用该page(当前状态必须为free)
+     * start to use this free page
      */
     use(): boolean;
     /**
@@ -985,6 +987,11 @@ interface LsdBrowserContext extends EventEmitter {
      * @default 0 the default maxPageFreeSeconds of the browserContext will be used
      */
     closeFreePages(maxPageFreeSeconds?: number): Promise<boolean>;
+    /**
+     * doest this browser meet browserContextRequirements (incognitos ignored in browser)?
+     * @param browserContextRequirements
+     */
+    doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
     /**
      * get a free page from current pages or by creating a new page
      */
@@ -1016,6 +1023,11 @@ interface LsdBrowser extends EventEmitter {
     browserControllerType(): BrowserControllerType;
     browserCreationMethod(): BrowserCreationMethod;
     browserType(): LsdBrowserType;
+    /**
+     * doest this browser meet browserContextRequirements (incognitos ignored in browser)?
+     * @param browserContextRequirements
+     */
+    doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
     /**
      * @returns
      * 1. launched: actual executable path
@@ -1074,33 +1086,6 @@ interface LsdBrowserController$1 {
      */
     newApiContext(options?: LsdApiContextOptions): Promise<LsdApiContext>;
 }
-/**
- * globObj.cfg.XXX:
- * 1. 最大browser数:
- * 2. 最大browserContext数/browser:
- * 3. 最大page数/browserContext:
- *
- * 影响一个browserContext是否满足执行某TE(taskCfg)要求的因素包括：
- * 1. domainCfg/taskCfg对代理的要求：proxyTypes:
- * 2. domainCfg/taskCfg对浏览器的要求：
- * * browserControllerTypes: playwright | puppeteer
- * * browserTypes: chromium | firefox | webkit
- * * browserModes: normal | incognito
- * * browserHeads: headless | headful
- * * APP支持的浏览器因素：globObj.cfg.supportedBrowserControllerTypes/supportedBrowserTypes(尝试启动新浏览器时判断)
- * 3. 能力账号：capName
- *
- * 连接已有浏览器：
- * * endpoint：
- * * browserControllerTypes: playwright | puppeteer
- * * browserType: chromium | firefox | webkit
- * * browserMode: normal
- * * browserHead: headful
- * * proxyTypes：
- */
-interface BrowserManager {
-    getPage(): any;
-}
 
 declare class PlaywrightBrowser extends EventEmitter implements LsdBrowser {
     #private;
@@ -1111,6 +1096,7 @@ declare class PlaywrightBrowser extends EventEmitter implements LsdBrowser {
     browserControllerType(): BrowserControllerType;
     browserCreationMethod(): BrowserCreationMethod;
     browserType(): LsdBrowserType;
+    doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
     executablePath(): string;
     id(): string;
     isConnected(): boolean;
@@ -1132,6 +1118,7 @@ declare class PlaywrightBrowserContext extends EventEmitter implements LsdBrowse
     browser(): LsdBrowser;
     close(): Promise<boolean>;
     closeFreePages(maxPageFreeSeconds?: number): Promise<boolean>;
+    doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
     getPage(always?: boolean): Promise<LsdPage | null>;
     hasFreePage(pageNum?: number): boolean;
     id(): string;
@@ -1214,9 +1201,11 @@ declare class PlaywrightElement implements LsdElement {
     hover(): Promise<boolean>;
     input(value: string, options?: InputOptions): Promise<boolean>;
     press(key: KeyInput, options?: KeyPressOptions): Promise<boolean>;
-    select(options: SelectOptions): Promise<boolean>;
     screenshot(options?: ScreenshotOptions): Promise<Buffer>;
     scrollIntoView(): Promise<boolean>;
+    select(options: SelectOptions): Promise<boolean>;
+    setAttribute(attributeName: string, newValue: string): Promise<boolean>;
+    _origElement(): AllElement;
 }
 
 declare class PuppeteerBrowser extends EventEmitter implements LsdBrowser {
@@ -1228,6 +1217,7 @@ declare class PuppeteerBrowser extends EventEmitter implements LsdBrowser {
     browserControllerType(): BrowserControllerType;
     browserCreationMethod(): BrowserCreationMethod;
     browserType(): LsdBrowserType;
+    doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
     executablePath(): string;
     id(): string;
     isConnected(): boolean;
@@ -1249,6 +1239,7 @@ declare class PuppeteerBrowserContext extends EventEmitter implements LsdBrowser
     browser(): LsdBrowser;
     close(): Promise<boolean>;
     closeFreePages(maxPageFreeSeconds?: number): Promise<boolean>;
+    doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
     getPage(always?: boolean): Promise<LsdPage | null>;
     hasFreePage(pageNum?: number): boolean;
     id(): string;
@@ -1331,9 +1322,11 @@ declare class PuppeteerElement implements LsdElement {
     hover(): Promise<boolean>;
     input(value: string, options?: InputOptions): Promise<boolean>;
     press(key: KeyInput, options?: KeyPressOptions): Promise<boolean>;
-    select(options: SelectOptions): Promise<boolean>;
     screenshot(options?: ScreenshotOptions): Promise<Buffer>;
     scrollIntoView(): Promise<boolean>;
+    select(options: SelectOptions): Promise<boolean>;
+    setAttribute(attributeName: string, newValue: string): Promise<boolean>;
+    _origElement(): AllElement;
 }
 
 declare class CheerioPage extends EventEmitter implements LsdPage {
@@ -1411,9 +1404,11 @@ declare class CheerioElement implements LsdElement {
     hover(): Promise<boolean>;
     input(): Promise<boolean>;
     press(): Promise<boolean>;
-    select(): Promise<boolean>;
     screenshot(): Promise<Buffer>;
     scrollIntoView(): Promise<boolean>;
+    select(): Promise<boolean>;
+    setAttribute(): Promise<boolean>;
+    _origElement(): AllElement;
 }
 
 declare class LsdBrowserController implements LsdBrowserController$1 {
@@ -1427,4 +1422,4 @@ declare class LsdBrowserController implements LsdBrowserController$1 {
 }
 declare const controller: LsdBrowserController;
 
-export { type AllApiRequestContext, type AllBrowser, type AllBrowserContext, type AllFrame, type AllPage, type AllResponse, type BrowserControllerType, type BrowserCreationMethod, type BrowserLaunchMethod, type BrowserManager, type BrowserStateData, CheerioElement, type CheerioNode, CheerioPage, type ClientCertificate, type CookieItem, type GotoOptions, type IframeOption, type InputOptions, type KeyInput, type KeyPressOptions, type LocalStorageItem, type LocalStorageOrigin, type LowerCasePaperFormat, type LsdApiContext, type LsdApiContextOptions, type LsdApiResponse, type LsdBrowser, type LsdBrowserContext, type LsdBrowserContextOptions, type LsdBrowserController$1 as LsdBrowserController, type LsdBrowserType, type LsdConnectOptions, type LsdElement, type LsdFetchOptions, type LsdLaunchOptions, type LsdPage, type MouseClickOptions, type MouseClickType, type NavigationWaitUntil, type PDFMargin, type PDFOptions, type PageEvent, type PageExtInPlaywright, type PageExtInPuppeteer, type PageInfo, type PageOpenType, type PageStatus, type PaperFormat, PlaywrightBrowser, PlaywrightBrowserContext, type PlaywrightBrowserTypes, PlaywrightElement, PlaywrightPage, type ProxyInController, PuppeteerBrowser, PuppeteerBrowserContext, PuppeteerElement, PuppeteerPage, type RequestInterceptionAction, type RequestInterceptionOption, type RequestMatch, type RequestMethod, type RequestResourceType, type ResponseHandler, type ResponseHandlerOptions, type ResponseInterceptionItem, type ResponseInterceptionOption, type ResponseMatch, type ResponsePageData, type ScreenshotOptions, type SelectOptions, type UpdatablePageInfo, type ViewportSize, type WaitElementOptions, type WaitElementState, type WaitNavigationOptions, controller };
+export { type AllApiRequestContext, type AllBrowser, type AllBrowserContext, type AllElement, type AllFrame, type AllPage, type AllResponse, type BrowserContextRequirements, type BrowserControllerType, type BrowserCreationMethod, type BrowserLaunchMethod, type BrowserStateData, CheerioElement, type CheerioNode, CheerioPage, type ClientCertificate, type CookieItem, type GotoOptions, type IframeOption, type InputOptions, type KeyInput, type KeyPressOptions, type LocalStorageItem, type LocalStorageOrigin, type LowerCasePaperFormat, type LsdApiContext, type LsdApiContextOptions, type LsdApiResponse, type LsdBrowser, type LsdBrowserContext, type LsdBrowserContextOptions, type LsdBrowserController$1 as LsdBrowserController, type LsdBrowserType, type LsdConnectOptions, type LsdElement, type LsdFetchOptions, type LsdLaunchOptions, type LsdPage, type MouseClickOptions, type MouseClickType, type NavigationWaitUntil, type PDFMargin, type PDFOptions, type PageEvent, type PageExtInPlaywright, type PageExtInPuppeteer, type PageInfo, type PageOpenType, type PageStatus, type PaperFormat, PlaywrightBrowser, PlaywrightBrowserContext, type PlaywrightBrowserTypes, PlaywrightElement, PlaywrightPage, type ProxyInController, PuppeteerBrowser, PuppeteerBrowserContext, PuppeteerElement, PuppeteerPage, type RequestInterceptionAction, type RequestInterceptionOption, type RequestMatch, type RequestMethod, type RequestResourceType, type ResponseHandler, type ResponseHandlerOptions, type ResponseInterceptionItem, type ResponseInterceptionOption, type ResponseMatch, type ResponsePageData, type ScreenshotOptions, type SelectOptions, type UpdatablePageInfo, type ViewportSize, type WaitElementOptions, type WaitElementState, type WaitNavigationOptions, controller };

package/dist/index.js

@@ -30,7 +30,6 @@ var PlaywrightElement = class _PlaywrightElement {
     return names;
   }
   /*
-    // 如果不存在指定的子iframe，则返回null
     async #getChildFrame(parentFrame: Frame, iframeOption: IframeOption): Promise<Frame | null> {
       if (!parentFrame) {
         throw new Error("Invalid parent frame");
@@ -222,6 +221,13 @@ var PlaywrightElement = class _PlaywrightElement {
     await this.#locator.press(key, options);
     return true;
   }
+  async screenshot(options) {
+    return await this.#locator.screenshot(options);
+  }
+  async scrollIntoView() {
+    await this.#locator.scrollIntoViewIfNeeded();
+    return true;
+  }
   async select(options) {
     const { type, values = [], labels = [], indexes = [] } = options;
     switch (type) {
@@ -261,13 +267,15 @@ var PlaywrightElement = class _PlaywrightElement {
     }
     return true;
   }
-  async screenshot(options) {
-    return await this.#locator.screenshot(options);
-  }
-  async scrollIntoView() {
-    await this.#locator.scrollIntoViewIfNeeded();
+  async setAttribute(attributeName, newValue) {
+    await this.#locator.evaluate((node) => {
+      node.setAttribute(attributeName, newValue);
+    });
     return true;
   }
+  _origElement() {
+    return this.#locator;
+  }
 };
 
 // src/playwright/page.ts
@@ -374,7 +382,6 @@ var PlaywrightPage = class extends EventEmitter {
     return true;
   }
   /*
-    // 如果不存在指定的子iframe，则返回null
     async #getChildFrame(parentFrame: Frame, iframeOption: IframeOption): Promise<Frame | null> {
       if (!parentFrame) {
         throw new Error("Invalid parent frame");
@@ -1308,6 +1315,13 @@ var PlaywrightBrowserContext = class extends EventEmitter2 {
       return false;
     }
   }
+  doesMeetBrowserContextRequirements(browserContextRequirements) {
+    if (!this.#lsdBrowser.doesMeetBrowserContextRequirements(browserContextRequirements)) {
+      return false;
+    }
+    const { incognitos } = browserContextRequirements;
+    return incognitos.length === 0 || incognitos.includes(this.#incognito);
+  }
   async getPage(always = false) {
     if (!this.#browserContext) {
       throw new Error("Invalid browserContext");
@@ -1445,7 +1459,7 @@ var PlaywrightBrowser = class extends EventEmitter3 {
   #maxPageFreeSeconds() {
     return this.#options.maxPageFreeSeconds ? this.#options.maxPageFreeSeconds : 900;
   }
-  // 构造函数：缺省只能由LsdBrowserController.launch/connect调用创建实例!!!
+  // constructor: called only by LsdBrowserController.launch/connect
   constructor(browser, browerType, browserCreateMethod, options, browserIdx = 0, pid = 0) {
     if (!browser || typeof browser.contexts !== "function") {
       throw new Error(`Invalid playwright browser parameter`);
@@ -1511,7 +1525,6 @@ var PlaywrightBrowser = class extends EventEmitter3 {
       await lsdBrowserContext.closeFreePages();
     }
   }
-  // 常用方法（按常见调用顺序排序）
   async newBrowserContext(options) {
     if (this.#lsdBrowserContexts.length >= this.#maxBrowserContextsPerBrowser()) {
       logwarn3(`##browser ${this.id()} can not create more new browserContext`);
@@ -1546,7 +1559,6 @@ var PlaywrightBrowser = class extends EventEmitter3 {
     await this.#browser.close();
     return true;
   }
-  // 其它方法（按字母顺序排序）
   browserContexts() {
     return this.#lsdBrowserContexts;
   }
@@ -1559,6 +1571,10 @@ var PlaywrightBrowser = class extends EventEmitter3 {
   browserType() {
     return this.#browserType;
   }
+  doesMeetBrowserContextRequirements(browserContextRequirements) {
+    const { browserControllerTypes, browserTypes, headlesses } = browserContextRequirements;
+    return (browserControllerTypes.length === 0 || browserControllerTypes.includes(this.#browserControllerType)) && (browserTypes.length === 0 && browserTypes.includes(this.#browserType)) && (headlesses.length === 0 && headlesses.includes(this.#headless));
+  }
   executablePath() {
     return this.#executablePath;
   }
@@ -1623,7 +1639,6 @@ var PuppeteerElement = class _PuppeteerElement {
     const names = await this.#frame.evaluate((ele) => ele.getAttributeNames(), this.#$ele);
     return names;
   }
-  // 如果不存在指定的子iframe，则返回null
   async #getChildFrame(parentFrame, iframeOption) {
     if (!parentFrame) {
       throw new Error("Invalid parent frame");
@@ -1801,6 +1816,15 @@ var PuppeteerElement = class _PuppeteerElement {
     await this.#$ele.press(key, options);
     return true;
   }
+  async screenshot(options) {
+    return await this.#$ele.screenshot(options);
+  }
+  async scrollIntoView() {
+    await this.#frame.evaluate((ele) => {
+      ele.scrollIntoView();
+    }, this.#$ele);
+    return true;
+  }
   async select(options) {
     const { type, values = [], labels = [], indexes = [] } = options;
     switch (type) {
@@ -1855,15 +1879,15 @@ var PuppeteerElement = class _PuppeteerElement {
     }
     return true;
   }
-  async screenshot(options) {
-    return await this.#$ele.screenshot(options);
-  }
-  async scrollIntoView() {
-    await this.#frame.evaluate((ele) => {
-      ele.scrollIntoView();
-    }, this.#$ele);
+  async setAttribute(attributeName, newValue) {
+    await this.#frame.evaluate((ele, name, value) => {
+      ele.setAttribute(name, value);
+    }, this.#$ele, attributeName, newValue);
     return true;
   }
+  _origElement() {
+    return this.#$ele;
+  }
 };
 
 // src/puppeteer/page.ts
@@ -1947,7 +1971,6 @@ var PuppeteerPage = class extends EventEmitter4 {
     });
     return true;
   }
-  // 如果不存在指定的子iframe，则返回null
   async #getChildFrame(parentFrame, iframeOption) {
     if (!parentFrame) {
       throw new Error("Invalid parent frame");
@@ -2829,6 +2852,13 @@ var PuppeteerBrowserContext = class extends EventEmitter5 {
       return false;
     }
   }
+  doesMeetBrowserContextRequirements(browserContextRequirements) {
+    if (!this.#lsdBrowser.doesMeetBrowserContextRequirements(browserContextRequirements)) {
+      return false;
+    }
+    const { incognitos } = browserContextRequirements;
+    return incognitos.length === 0 || incognitos.includes(this.#incognito);
+  }
   async getPage(always = false) {
     if (!this.#browserContext) {
       throw new Error("Invalid browserContext");
@@ -2971,7 +3001,7 @@ var PuppeteerBrowser = class extends EventEmitter6 {
   #userAgent() {
     return this.#options.userAgent ? this.#options.userAgent : "";
   }
-  // 构造函数：缺省只能由LsdBrowserController.launch/connect调用创建实例!!!
+  // constructor: called only by LsdBrowserController.launch/connect
   constructor(browser, browerType, browserCreateMethod, options, browserIdx = 0, pid = 0) {
     if (!browser || typeof browser.browserContexts !== "function") {
       throw new Error(`Invalid puppeteer browser parameter`);
@@ -3034,7 +3064,6 @@ var PuppeteerBrowser = class extends EventEmitter6 {
       await lsdBrowserContext.closeFreePages();
     }
   }
-  // 常用方法（按常见调用顺序排序）
   async newBrowserContext(options) {
     if (this.#lsdBrowserContexts.length >= this.#maxBrowserContextsPerBrowser()) {
       logwarn5(`##browser ${this.id()} can not create more new browserContext`);
@@ -3065,7 +3094,6 @@ var PuppeteerBrowser = class extends EventEmitter6 {
     await this.#browser.close();
     return true;
   }
-  // 其它方法（按字母顺序排序）
   browserContexts() {
     return this.#lsdBrowserContexts;
   }
@@ -3078,6 +3106,10 @@ var PuppeteerBrowser = class extends EventEmitter6 {
   browserType() {
     return this.#browserType;
   }
+  doesMeetBrowserContextRequirements(browserContextRequirements) {
+    const { browserControllerTypes, browserTypes, headlesses } = browserContextRequirements;
+    return (browserControllerTypes.length === 0 || browserControllerTypes.includes(this.#browserControllerType)) && (browserTypes.length === 0 && browserTypes.includes(this.#browserType)) && (headlesses.length === 0 && headlesses.includes(this.#headless));
+  }
   executablePath() {
     return this.#executablePath;
   }
@@ -3219,13 +3251,19 @@ var CheerioElement = class _CheerioElement {
   async press() {
     throw new Error("Not supported in CheerioElement.");
   }
+  async screenshot() {
+    throw new Error("Not supported in CheerioElement.");
+  }
+  async scrollIntoView() {
+    throw new Error("Not supported in CheerioElement.");
+  }
   async select() {
     throw new Error("Not supported in CheerioElement.");
   }
-  async screenshot() {
+  async setAttribute() {
     throw new Error("Not supported in CheerioElement.");
   }
-  async scrollIntoView() {
+  _origElement() {
     throw new Error("Not supported in CheerioElement.");
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letsscrapedata/controller",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "description": "Unified browser / HTML controller interfaces that support playwright, puppeteer and cheerio",
   "type": "module",
   "main": "./dist/index.mjs",