page-agent 0.0.6 → 0.0.9

package/README.md

@@ -67,16 +67,17 @@ await agent.execute('Click the login button')
 
 ## 🏗️ Structure
 
-PageAgent follows a clean, modular architecture:
+PageAgent adopts a simplified monorepo structure:
 
 ```
-src/
-├── PageAgent.ts          # Agent main loop
-├── dom/                  # DOM processing
-├── tools/                # Agent tools
-├── ui/                   # UI components & panels
-├── llms/                 # LLM integration layer
-└── utils/                # Event bus & utilities
+packages/
+├── page-agent/          # AI agent (npm: page-agent)
+│   ├── PageAgent        # Agent main loop
+│   ├── tools/           # LLM tool definitions
+│   ├── ui/              # UI components & panels
+│   └── llms/            # LLM integration layer
+├── page-controller/     # DOM operations (npm: @page-agent/page-controller)
+└── website/             # Demo & Documentation site
 ```
 
 ## 🤝 Contributing

package/dist/lib/PageAgent.d.ts

@@ -1,4 +1,8 @@
-import { Motion } from 'ai-motion';
+import { PageController } from '@page-agent/page-controller';
+import { PageControllerConfig } from '@page-agent/page-controller';
+import { Panel } from '@page-agent/ui';
+import { SimulatorMask } from '@page-agent/ui';
+import { SupportedLanguage } from '@page-agent/ui';
 import { z } from 'zod';
 
 export declare interface AgentBrain {
@@ -85,149 +89,12 @@ export declare interface AgentHistory {
     };
 }
 
-declare type DeepStringify<T> = {
-    [K in keyof T]: T[K] extends string ? string : T[K] extends object ? DeepStringify<T[K]> : T[K];
-};
-
-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 const enUS: {
-    readonly ui: {
-        readonly panel: {
-            readonly ready: "Ready";
-            readonly thinking: "Thinking...";
-            readonly paused: "Paused";
-            readonly taskInput: "Enter new task, describe steps in detail, press Enter to submit";
-            readonly userAnswerPrompt: "Please answer the question above, press Enter to submit";
-            readonly taskTerminated: "Task terminated";
-            readonly taskCompleted: "Task completed";
-            readonly continueExecution: "Continue execution";
-            readonly userAnswer: "User answer: {{input}}";
-            readonly question: "Question: {{question}}";
-            readonly waitingPlaceholder: "Waiting for task to start...";
-            readonly pause: "Pause";
-            readonly continue: "Continue";
-            readonly stop: "Stop";
-            readonly expand: "Expand history";
-            readonly collapse: "Collapse history";
-            readonly step: "Step {{number}} · {{time}}{{duration}}";
-        };
-        readonly tools: {
-            readonly clicking: "Clicking element [{{index}}]...";
-            readonly inputting: "Inputting text to element [{{index}}]...";
-            readonly selecting: "Selecting option \"{{text}}\"...";
-            readonly scrolling: "Scrolling page...";
-            readonly waiting: "Waiting {{seconds}} seconds...";
-            readonly done: "Task done";
-            readonly clicked: "🖱️ Clicked element [{{index}}]";
-            readonly inputted: "⌨️ Inputted text \"{{text}}\"";
-            readonly selected: "☑️ Selected option \"{{text}}\"";
-            readonly scrolled: "🛞 Page scrolled";
-            readonly waited: "⌛️ Wait completed";
-            readonly executing: "Executing {{toolName}}...";
-            readonly resultSuccess: "success";
-            readonly resultFailure: "failed";
-            readonly resultError: "error";
-        };
-        readonly errors: {
-            readonly elementNotFound: "No interactive element found at index {{index}}";
-            readonly taskRequired: "Task description is required";
-            readonly executionFailed: "Task execution failed";
-            readonly notInputElement: "Element is not an input or textarea";
-            readonly notSelectElement: "Element is not a select element";
-            readonly optionNotFound: "Option \"{{text}}\" not found";
-        };
-    };
-};
-
-/**
- * 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>): void;
-    /**
-     * Listen to built-in events (one-time)
-     */
-    once<T extends keyof PageAgentEventMap>(event: T, handler: EventHandler<T>): 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;
@@ -237,105 +104,6 @@ declare interface LLMConfig {
     maxRetries?: number;
 }
 
-declare const locales: {
-    readonly 'en-US': {
-        readonly ui: {
-            readonly panel: {
-                readonly ready: "Ready";
-                readonly thinking: "Thinking...";
-                readonly paused: "Paused";
-                readonly taskInput: "Enter new task, describe steps in detail, press Enter to submit";
-                readonly userAnswerPrompt: "Please answer the question above, press Enter to submit";
-                readonly taskTerminated: "Task terminated";
-                readonly taskCompleted: "Task completed";
-                readonly continueExecution: "Continue execution";
-                readonly userAnswer: "User answer: {{input}}";
-                readonly question: "Question: {{question}}";
-                readonly waitingPlaceholder: "Waiting for task to start...";
-                readonly pause: "Pause";
-                readonly continue: "Continue";
-                readonly stop: "Stop";
-                readonly expand: "Expand history";
-                readonly collapse: "Collapse history";
-                readonly step: "Step {{number}} · {{time}}{{duration}}";
-            };
-            readonly tools: {
-                readonly clicking: "Clicking element [{{index}}]...";
-                readonly inputting: "Inputting text to element [{{index}}]...";
-                readonly selecting: "Selecting option \"{{text}}\"...";
-                readonly scrolling: "Scrolling page...";
-                readonly waiting: "Waiting {{seconds}} seconds...";
-                readonly done: "Task done";
-                readonly clicked: "🖱️ Clicked element [{{index}}]";
-                readonly inputted: "⌨️ Inputted text \"{{text}}\"";
-                readonly selected: "☑️ Selected option \"{{text}}\"";
-                readonly scrolled: "🛞 Page scrolled";
-                readonly waited: "⌛️ Wait completed";
-                readonly executing: "Executing {{toolName}}...";
-                readonly resultSuccess: "success";
-                readonly resultFailure: "failed";
-                readonly resultError: "error";
-            };
-            readonly errors: {
-                readonly elementNotFound: "No interactive element found at index {{index}}";
-                readonly taskRequired: "Task description is required";
-                readonly executionFailed: "Task execution failed";
-                readonly notInputElement: "Element is not an input or textarea";
-                readonly notSelectElement: "Element is not a select element";
-                readonly optionNotFound: "Option \"{{text}}\" not found";
-            };
-        };
-    };
-    readonly 'zh-CN': {
-        readonly ui: {
-            readonly panel: {
-                readonly ready: "准备就绪";
-                readonly thinking: "正在思考...";
-                readonly paused: "暂停中，稍后";
-                readonly taskInput: "输入新任务，详细描述步骤，回车提交";
-                readonly userAnswerPrompt: "请回答上面问题，回车提交";
-                readonly taskTerminated: "任务已终止";
-                readonly taskCompleted: "任务结束";
-                readonly continueExecution: "继续执行";
-                readonly userAnswer: "用户回答: {{input}}";
-                readonly question: "询问: {{question}}";
-                readonly waitingPlaceholder: "等待任务开始...";
-                readonly pause: "暂停";
-                readonly continue: "继续";
-                readonly stop: "终止";
-                readonly expand: "展开历史";
-                readonly collapse: "收起历史";
-                readonly step: "步骤 {{number}} · {{time}}{{duration}}";
-            };
-            readonly tools: {
-                readonly clicking: "正在点击元素 [{{index}}]...";
-                readonly inputting: "正在输入文本到元素 [{{index}}]...";
-                readonly selecting: "正在选择选项 \"{{text}}\"...";
-                readonly scrolling: "正在滚动页面...";
-                readonly waiting: "等待 {{seconds}} 秒...";
-                readonly done: "结束任务";
-                readonly clicked: "🖱️ 已点击元素 [{{index}}]";
-                readonly inputted: "⌨️ 已输入文本 \"{{text}}\"";
-                readonly selected: "☑️ 已选择选项 \"{{text}}\"";
-                readonly scrolled: "🛞 页面滚动完成";
-                readonly waited: "⌛️ 等待完成";
-                readonly executing: "正在执行 {{toolName}}...";
-                readonly resultSuccess: "成功";
-                readonly resultFailure: "失败";
-                readonly resultError: "错误";
-            };
-            readonly errors: {
-                readonly elementNotFound: "未找到索引为 {{index}} 的交互元素";
-                readonly taskRequired: "任务描述不能为空";
-                readonly executionFailed: "任务执行失败";
-                readonly notInputElement: "元素不是输入框或文本域";
-                readonly notSelectElement: "元素不是选择框";
-                readonly optionNotFound: "未找到选项 \"{{text}}\"";
-            };
-        };
-    };
-};
-
 /**
  * MacroTool input structure
  */
@@ -354,35 +122,18 @@ export declare interface MacroToolResult {
     output: string;
 }
 
-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;
     panel: Panel;
     tools: typeof tools;
     paused: boolean;
     disposed: boolean;
     task: string;
     taskId: 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;
+    /** PageController for DOM operations */
+    pageController: PageController;
     /** Fullscreen mask */
     mask: SimulatorMask;
     /** History records */
@@ -395,32 +146,7 @@ export declare class PageAgent extends EventTarget {
     dispose(reason?: string): void;
 }
 
-export declare type PageAgentConfig = LLMConfig & AgentConfig & DomConfig;
-
-/**
- * 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;
-    };
-}
+export declare type PageAgentConfig = LLMConfig & AgentConfig & PageControllerConfig;
 
 /**
  * Internal tool definition that has access to PageAgent `this` context
@@ -431,59 +157,6 @@ export declare interface PageAgentTool<TParams = any> {
     execute: (this: PageAgent, args: TParams) => Promise<string>;
 }
 
-/**
- * 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;
-}
-
 export declare function tool<TParams>(options: PageAgentTool<TParams>): PageAgentTool<TParams>;
 
 /**
@@ -492,10 +165,4 @@ export declare function tool<TParams>(options: PageAgentTool<TParams>): PageAgen
  */
 declare const tools: Map<string, PageAgentTool<any>>;
 
-declare type TranslationKey = NestedKeyOf<TranslationSchema>;
-
-declare type TranslationParams = Record<string, string | number>;
-
-declare type TranslationSchema = DeepStringify<typeof enUS>;
-
 export { }