page-agent 0.0.0

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/NOTICE

@@ -0,0 +1,23 @@
+Page-Agent
+Copyright (c) 2025 Alibaba Group Holding Limited
+Author: Simon<gaomeng1900>
+
+This project incorporates work covered by the following copyright and permission notices:
+
+================================================================================
+
+Browser Use
+Copyright (c) 2024 Gregor Zunic
+Licensed under the MIT License
+
+Original browser-use project: https://github.com/browser-use/browser-use
+License: MIT License
+
+We gratefully acknowledge the browser-use project and its contributors for their
+excellent work on web automation and DOM interaction patterns that helped make
+this project possible.
+
+================================================================================
+
+Third-party dependencies and their licenses can be found in the package.json
+file and in the node_modules directory after installation.

package/README.md

@@ -0,0 +1,102 @@
+# PageAgent 🤖
+
+[![npm version](https://badge.fury.io/js/page-agent.svg)](https://badge.fury.io/js/page-agent) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) [![Downloads](https://img.shields.io/npm/dt/page-agent.svg)](https://www.npmjs.com/package/page-agent) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/page-agent)](https://bundlephobia.com/package/page-agent) [![GitHub stars](https://img.shields.io/github/stars/gaomeng1900/page-agent.svg)](https://github.com/gaomeng1900/page-agent)
+
+**Transform any webpage into an AI-powered application with a single script tag.**
+
+PageAgent is an intelligent UI agent for web automation and DOM interaction. Built on browser-use architecture, it enables natural language control of web interfaces through LLM integration.
+
+🌐 **English** | [中文](./README-zh.md)
+
+👉 [📖 **Documentation**](#) | [🚀 **Try Demo**](#)
+
+---
+
+## ✨ Features
+
+- **🎯 Easy Integration** - Add to any webpage via CDN or npm
+- **🔐 Client-Side Processing** - No data leaves the browser
+- **🧠 DOM Extraction**
+- **💬 Natural Language Interface**
+- **🎨 UI with Human in the loop**
+
+## 🗺️ Roadmap
+
+👉 [**Roadmap**](./ROADMAP.md)
+
+## 🚀 Quick Start
+
+### CDN Integration
+
+> **TODO**: CDN endpoint to be determined.
+
+```html
+<!-- CDN script tag - URL to be updated -->
+<script src="TODO-CDN-URL"></script>
+```
+
+### NPM Installation
+
+```bash
+npm install page-agent
+```
+
+```javascript
+import { PageAgent } from 'page-agent'
+
+const agent = new PageAgent({
+  modelName: 'gpt-4.1-mini'
+  baseURL: 'xxxx',
+  apiKey: 'xxxx'
+})
+
+await agent.execute("Click the login button")
+```
+
+## 🏗️ Structure
+
+PageAgent follows a clean, modular architecture:
+
+```
+src/
+├── PageAgent.ts          # Agent main loop
+├── dom/                  # DOM processing
+├── tools/                # Agent tools
+├── ui/                   # UI components & panels
+├── llms/                 # LLM integration layer
+└── utils/                # Event bus & utilities
+```
+
+## 🤝 Contributing
+
+We welcome contributions from the community! Here's how to get started:
+
+### Setup
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/alibaba/page-agent.git && cd page-agent`
+3. Install dependencies: `npm install`
+4. Start development: `npm start`
+
+### Contributing Guidelines
+
+Please read our [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing Guide](CONTRIBUTING.md) before contributing.
+
+## 👏 Acknowledgments
+
+This project builds upon the excellent work of:
+
+- **[browser-use](https://github.com/browser-use/browser-use)**
+- **[ai-sdk](https://ai-sdk.dev/)**
+
+PageAgent is designed for **client-side web enhancement**, not server-side automation.
+
+## 📄 License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+DOM processing components and prompt are derived from [browser-use](https://github.com/browser-use/browser-use) (MIT License). See [NOTICE](NOTICE) for full attribution.
+
+---
+
+**⭐ Star this repo if you find PageAgent helpful!**

package/dist/lib/PageAgent.d.ts

@@ -0,0 +1,297 @@
+import { LanguageModelUsage } from 'ai';
+import { Motion } from 'ai-motion';
+import { Tool } from 'ai';
+
+export declare interface AgentBrain {
+    evaluation_previous_goal: string;
+    memory: string;
+    next_goal: string;
+}
+
+export declare interface AgentHistory {
+    brain: AgentBrain;
+    action: {
+        name: string;
+        input: any;
+        output: any;
+    };
+    usage: LanguageModelUsage;
+}
+
+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;
+}
+
+/**
+ * Type-safe event bus
+ * @note Mainly used to decouple logic and UI
+ * @note All modules of a PageAgent instance share the same EventBus instance for communication
+ * @note Use with caution if delivery guarantee is needed for logic communication
+ * @note `on` `once` `emit` methods handle built-in events with type protection, use `addEventListener` for other events
+ */
+declare class EventBus extends EventTarget {
+    /**
+     * Listen to built-in events
+     */
+    on<T extends keyof PageAgentEventMap>(event: T, handler: EventHandler<T & keyof PageAgentEventMap>): void;
+    /**
+     * Listen to built-in events (one-time)
+     */
+    once<T extends keyof PageAgentEventMap>(event: T, handler: EventHandler<T & keyof PageAgentEventMap>): void;
+    /**
+     * Emit built-in events
+     */
+    emit<T extends keyof PageAgentEventMap>(event: T, ...args: PageAgentEventMap[T]['params'] extends undefined ? [] : [PageAgentEventMap[T]['params']]): void;
+}
+
+/**
+ * Event handler type definitions
+ */
+declare type EventHandler<T extends keyof PageAgentEventMap> = PageAgentEventMap[T]['params'] extends undefined ? () => void : (params: PageAgentEventMap[T]['params']) => void;
+
+export declare interface ExecutionResult {
+    success: boolean;
+    data: string;
+    history: AgentHistory[];
+}
+
+declare interface FlatDomTree {
+    rootId: string;
+    map: Record<string, DomNode>;
+}
+
+declare class I18n {
+    private language;
+    private translations;
+    constructor(language?: SupportedLanguage);
+    t(key: TranslationKey, params?: TranslationParams): string;
+    private getNestedValue;
+    private interpolate;
+    getLanguage(): SupportedLanguage;
+}
+
+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;
+}
+
+declare interface LLMConfig {
+    baseURL?: string;
+    apiKey?: string;
+    modelName?: string;
+    maxRetries?: number;
+}
+
+declare const locales: {
+    readonly 'zh-CN': TranslationSchema;
+    readonly 'en-US': TranslationSchema;
+};
+
+declare type NestedKeyOf<ObjectType extends object> = {
+    [Key in keyof ObjectType & (string | number)]: ObjectType[Key] extends object ? `${Key}` | `${Key}.${NestedKeyOf<ObjectType[Key]>}` : `${Key}`;
+}[keyof ObjectType & (string | number)];
+
+export declare class PageAgent extends EventTarget {
+    #private;
+    config: PageAgentConfig;
+    id: string;
+    bus: EventBus;
+    i18n: I18n;
+    paused: boolean;
+    disposed: boolean;
+    task: string;
+    /** Corresponds to eval_page in browser-use */
+    flatTree: FlatDomTree | null;
+    /**
+     * All highlighted index-mapped interactive elements
+     * Corresponds to DOMState.selector_map in browser-use
+     */
+    selectorMap: Map<number, InteractiveElementDomNode>;
+    /** highlight index -> element text */
+    elementTextMap: Map<number, string>;
+    /** Corresponds to clickable_elements_to_string in browser-use */
+    simplifiedHTML: string;
+    /** last time the tree was updated */
+    lastTimeUpdate: number;
+    /** Corresponds to actions in browser-use */
+    tools: Map<string, Tool>;
+    /** Fullscreen mask */
+    mask: SimulatorMask;
+    /** Interactive panel */
+    panel: Panel;
+    /** History records */
+    history: AgentHistory[];
+    constructor(config?: PageAgentConfig);
+    /**
+     * @todo maybe return something?
+     */
+    execute(task: string): Promise<ExecutionResult>;
+    dispose(): void;
+}
+
+export declare type PageAgentConfig = LLMConfig & DomConfig & UIConfig;
+
+/**
+ * Event mapping definitions
+ * @note Event bus callbacks must be repeatable without errors
+ */
+declare interface PageAgentEventMap {
+    'panel:show': {
+        params: undefined;
+    };
+    'panel:hide': {
+        params: undefined;
+    };
+    'panel:reset': {
+        params: undefined;
+    };
+    'panel:update': {
+        params: Omit<Step, 'id' | 'stepNumber' | 'timestamp'>;
+    };
+    'panel:expand': {
+        params: undefined;
+    };
+    'panel:collapse': {
+        params: undefined;
+    };
+}
+
+/**
+ * Agent control panel
+ */
+declare class Panel {
+    #private;
+    get wrapper(): HTMLElement;
+    constructor(pageAgent: PageAgent);
+    /**
+     * Ask for user input
+     */
+    askUser(question: string): Promise<string>;
+    /**
+     * Dispose panel
+     */
+    dispose(): void;
+}
+
+declare class SimulatorMask {
+    #private;
+    wrapper: HTMLDivElement;
+    motion: Motion;
+    constructor();
+    setCursorPosition(x: number, y: number): void;
+    triggerClickAnimation(): void;
+    show(): void;
+    hide(): void;
+    dispose(): void;
+}
+
+/**
+ * Agent execution state management
+ */
+declare interface Step {
+    id: string;
+    stepNumber: number;
+    timestamp: Date;
+    type: 'thinking' | 'tool_executing' | 'completed' | 'error' | 'output' | 'input' | 'retry';
+    toolName?: string;
+    toolArgs?: any;
+    toolResult?: any;
+    displayText: string;
+    duration?: number;
+}
+
+declare type SupportedLanguage = keyof typeof locales;
+
+declare interface TextDomNode {
+    type: 'TEXT_NODE';
+    text: string;
+    isVisible: boolean;
+    [key: string]: unknown;
+}
+
+declare type TranslationKey = NestedKeyOf<TranslationSchema>;
+
+declare type TranslationParams = Record<string, string | number>;
+
+declare interface TranslationSchema {
+    ui: {
+        panel: {
+            ready: string;
+            thinking: string;
+            paused: string;
+            taskInput: string;
+            userAnswerPrompt: string;
+            taskTerminated: string;
+            taskCompleted: string;
+            continueExecution: string;
+            userAnswer: string;
+            pause: string;
+            continue: string;
+            stop: string;
+            expand: string;
+            collapse: string;
+            step: string;
+        };
+        tools: {
+            clicking: string;
+            inputting: string;
+            selecting: string;
+            scrolling: string;
+            waiting: string;
+            done: string;
+            clicked: string;
+            inputted: string;
+            selected: string;
+            scrolled: string;
+            waited: string;
+            executing: string;
+        };
+        errors: {
+            elementNotFound: string;
+            taskRequired: string;
+            executionFailed: string;
+            notInputElement: string;
+            notSelectElement: string;
+            optionNotFound: string;
+        };
+    };
+}
+
+declare interface UIConfig {
+    language?: SupportedLanguage;
+}
+
+export { }