@page-agent/page-controller 0.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alibaba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/lib/PageController.d.ts

@@ -0,0 +1,255 @@
+declare interface ActionResult {
+    success: boolean;
+    message: string;
+}
+
+declare function cleanUpHighlights(): void;
+
+declare namespace dom {
+    export {
+        getFlatTree,
+        flatTreeToString,
+        getSelectorMap,
+        getElementTextMap,
+        cleanUpHighlights,
+        DomConfig,
+        getAllTextTillNextClickableElement
+    }
+}
+
+declare interface DomConfig {
+    interactiveBlacklist?: (Element | (() => Element))[];
+    interactiveWhitelist?: (Element | (() => Element))[];
+    include_attributes?: string[];
+    highlightOpacity?: number;
+    highlightLabelOpacity?: number;
+}
+
+declare type DomNode = TextDomNode | ElementDomNode | InteractiveElementDomNode;
+
+declare interface ElementDomNode {
+    tagName: string;
+    attributes?: Record<string, string>;
+    xpath?: string;
+    children?: string[];
+    isVisible?: boolean;
+    isTopElement?: boolean;
+    isInViewport?: boolean;
+    isNew?: boolean;
+    isInteractive?: false;
+    highlightIndex?: number;
+    extra?: Record<string, any>;
+    [key: string]: unknown;
+}
+
+declare interface FlatDomTree {
+    rootId: string;
+    map: Record<string, DomNode>;
+}
+
+/**
+ * 对应 python 中的 views::clickable_elements_to_string,
+ * 将 dom 信息处理成适合 llm 阅读的文本格式
+ * @形如
+ * ``` text
+ * [0]<a aria-label=page-agent.js 首页 />
+ * [1]<div >P />
+ * [2]<div >page-agent.js
+ * UI Agent in your webpage />
+ * [3]<a >文档 />
+ * [4]<a aria-label=查看源码（在新窗口打开）>源码 />
+ * UI Agent in your webpage
+ * 用户输入需求，AI 理解页面并自动操作。
+ * [5]<a role=button>快速开始 />
+ * [6]<a role=button>查看文档 />
+ * 无需后端
+ * ```
+ * 其中可交互元素用序号标出，提示llm可以用序号操作。
+ * 缩进代表父子关系。
+ * 普通文本则直接列出来。
+ *
+ * @todo 数据脱敏过滤器
+ */
+declare function flatTreeToString(flatTree: FlatDomTree, include_attributes?: string[]): string;
+
+declare const getAllTextTillNextClickableElement: (node: TreeNode, maxDepth?: number) => string;
+
+declare function getElementTextMap(simplifiedHTML: string): Map<number, string>;
+
+declare function getFlatTree(config: DomConfig): FlatDomTree;
+
+declare function getSelectorMap(flatTree: FlatDomTree): Map<number, InteractiveElementDomNode>;
+
+declare interface InteractiveElementDomNode {
+    tagName: string;
+    attributes?: Record<string, string>;
+    xpath?: string;
+    children?: string[];
+    isVisible?: boolean;
+    isTopElement?: boolean;
+    isInViewport?: boolean;
+    isInteractive: true;
+    highlightIndex: number;
+    /**
+     * 可交互元素的 dom 引用
+     */
+    ref: HTMLElement;
+    [key: string]: unknown;
+}
+
+/**
+ * PageController manages DOM state and element interactions.
+ * It provides async methods for all DOM operations, keeping state isolated.
+ *
+ * @lifecycle
+ * - beforeUpdate: Emitted before the DOM tree is updated.
+ * - afterUpdate: Emitted after the DOM tree is updated.
+ */
+export declare class PageController extends EventTarget {
+    private config;
+    /** Corresponds to eval_page in browser-use */
+    private flatTree;
+    /**
+     * All highlighted index-mapped interactive elements
+     * Corresponds to DOMState.selector_map in browser-use
+     */
+    private selectorMap;
+    /** Index -> element text description mapping */
+    private elementTextMap;
+    /**
+     * Simplified HTML for LLM consumption.
+     * Corresponds to clickable_elements_to_string in browser-use
+     */
+    private simplifiedHTML;
+    /** last time the tree was updated */
+    private lastTimeUpdate;
+    constructor(config?: PageControllerConfig);
+    /**
+     * Get current page URL
+     */
+    getCurrentUrl(): Promise<string>;
+    /**
+     * Get current page title
+     */
+    getPageTitle(): Promise<string>;
+    /**
+     * Get page scroll and size info
+     */
+    getPageInfo(): Promise<{
+        viewport_width: number;
+        viewport_height: number;
+        page_width: number;
+        page_height: number;
+        scroll_x: number;
+        scroll_y: number;
+        pixels_above: number;
+        pixels_below: number;
+        pages_above: number;
+        pages_below: number;
+        total_pages: number;
+        current_page_position: number;
+        pixels_left: number;
+        pixels_right: number;
+    }>;
+    /**
+     * Get the simplified HTML representation of the page.
+     * This is used by LLM to understand the page structure.
+     */
+    getSimplifiedHTML(): Promise<string>;
+    /**
+     * Get text description for an element by index
+     */
+    getElementText(index: number): Promise<string | undefined>;
+    /**
+     * Get total number of indexed interactive elements
+     */
+    getElementCount(): Promise<number>;
+    /**
+     * Get last tree update timestamp
+     */
+    getLastUpdateTime(): Promise<number>;
+    /**
+     * Get the viewport expansion setting
+     */
+    getViewportExpansion(): Promise<number>;
+    /**
+     * Update DOM tree, returns simplified HTML for LLM.
+     * This is the main method to refresh the page state.
+     */
+    updateTree(): Promise<string>;
+    /**
+     * Clean up all element highlights
+     */
+    cleanUpHighlights(): Promise<void>;
+    /**
+     * Click element by index
+     */
+    clickElement(index: number): Promise<ActionResult>;
+    /**
+     * Input text into element by index
+     */
+    inputText(index: number, text: string): Promise<ActionResult>;
+    /**
+     * Select dropdown option by index and option text
+     */
+    selectOption(index: number, optionText: string): Promise<ActionResult>;
+    /**
+     * Scroll vertically
+     */
+    scroll(options: {
+        down: boolean;
+        numPages: number;
+        pixels?: number;
+        index?: number;
+    }): Promise<ActionResult>;
+    /**
+     * Scroll horizontally
+     */
+    scrollHorizontally(options: {
+        right: boolean;
+        pixels: number;
+        index?: number;
+    }): Promise<ActionResult>;
+    /**
+     * Execute arbitrary JavaScript on the page
+     */
+    executeJavascript(script: string): Promise<ActionResult>;
+    /**
+     * Dispose and clean up resources
+     */
+    dispose(): void;
+}
+
+/**
+ * Configuration for PageController
+ */
+export declare interface PageControllerConfig extends dom.DomConfig {
+    viewportExpansion?: number;
+}
+
+declare interface TextDomNode {
+    type: 'TEXT_NODE';
+    text: string;
+    isVisible: boolean;
+    [key: string]: unknown;
+}
+
+/**
+ * elementsToString 内部使用的类型
+ */
+declare interface TreeNode {
+    type: 'text' | 'element';
+    parent: TreeNode | null;
+    children: TreeNode[];
+    isVisible: boolean;
+    text?: string;
+    tagName?: string;
+    attributes?: Record<string, string>;
+    isInteractive?: boolean;
+    isTopElement?: boolean;
+    isNew?: boolean;
+    highlightIndex?: number;
+    extra?: Record<string, any>;
+}
+
+export { }