chore(version): bump version to 0.2.5

feat: make all ui optional

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -58,4 +58,4 @@ body:
         - label: I have read the Code of Conduct. / 我已阅读行为准则。
           required: true
     validations:
-      required: true
+      required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -44,4 +44,4 @@ body:
         - label: I have read the CODE_OF_CONDUCT.md and CONTRIBUTING.md. / 我已阅读行为准则。
           required: true
     validations:
-      required: true
+      required: true

.github/workflows/ci.yml

@@ -13,10 +13,10 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20, 22]
+        node-version: [20, 24, 25]
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Setup Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v6
@@ -24,6 +24,13 @@ jobs:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'
 
+      # test on default version of npm
+      # - 9.6~10.8 on node@20
+      # - 11.3~11.6 on node@24
+
+      - name: Node and NPM version
+        run: node --version && npm --version
+
       - name: Install dependencies
         run: npm install
 

.github/workflows/deploy-demo.yml

@@ -13,19 +13,19 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 24
           cache: 'npm'
 
       - name: Install dependencies
         run: npm ci
 
       - name: Build demo
-        run: npm run build
+        run: npm run build:website
 
       - name: Setup Pages
         uses: actions/configure-pages@v5

.github/workflows/release.yml

@@ -6,30 +6,30 @@ on:
       - 'v*'
 
 permissions:
-  id-token: write  # Required for OIDC
+  id-token: write # Required for OIDC
   contents: read
 
 jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 24
           registry-url: 'https://registry.npmjs.org'
 
       # Ensure npm 11.5.1 or later is installed
       - name: Update npm
         run: npm install -g npm@latest
-        
+
       - name: Install dependencies
         run: npm ci
 
       - name: Build
-        run: npm run build:lib
+        run: npm run build:libs
 
-      - name: Publish to npm
+      - name: Publish all public packages
-        run: npm publish --workspace=page-agent
+        run: npm publish --workspaces --access public

.gitignore

@@ -23,6 +23,7 @@ dist-ssr
 *.njsproj
 *.sln
 *.sw?
+.qoder
 
 
 # 

.husky/pre-commit

@@ -1 +1 @@
-npx lint-staged
+npx lint-staged --allow-empty

.vscode/extensions.json

@@ -1,3 +1,3 @@
 {
-	"recommendations": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"]
+    "recommendations": ["dbaeumer.vscode-eslint", "prettier.prettier-vscode"]
 }

.vscode/settings.json

@@ -1,18 +1,29 @@
 {
-	"editor.fontLigatures": true,
+    "editor.fontLigatures": true,
-	"cSpell.words": ["HITL", "innerhtml", "opensource", "retryable", "wouter"],
+    "cSpell.words": [
-	"markdownlint.config": {
+        "deepseek",
-		// "comment": "Relaxed rules",
+        "HITL",
-		"default": true,
+        "innerhtml",
-		"whitespace": false,
+        "llms",
-		"line_length": false,
+        "onwarn",
-		"ul-indent": false,
+        "opensource",
-		"no-inline-html": false,
+        "qwen",
-		"no-bare-urls": false,
+        "retryable",
-		"fenced-code-language": false,
+        "shadcn",
-		"first-line-h1": false,
+        "wouter"
-		"block-spacing": false,
+    ],
-		"blanks-around-lists": false,
+    "markdownlint.config": {
-		"ol-prefix": false
+        // "comment": "Relaxed rules",
-	}
+        "default": true,
+        "whitespace": false,
+        "line_length": false,
+        "ul-indent": false,
+        "no-inline-html": false,
+        "no-bare-urls": false,
+        "fenced-code-language": false,
+        "first-line-h1": false,
+        "block-spacing": false,
+        "blanks-around-lists": false,
+        "ol-prefix": false
+    }
 }

AGENTS.md

@@ -1,182 +1,131 @@
-# Instructions for coding assistants
+# Instructions for Coding Assistants
 
 ## Project Overview
 
-This is a **monorepo** with npm workspaces containing **two main packages**:
+This is a **monorepo** with npm workspaces:
 
-1. **Core Library** (`packages/page-agent/`) - Pure JavaScript/TypeScript AI agent library for browser DOM automation, published as `page-agent` on npm
+- **Core Library** (`packages/page-agent/`) - AI agent for browser DOM automation, published as `page-agent` on npm
-2. **Website** (`packages/website/`) - React documentation and landing page. Also as demo and test page for the core lib. private package `@page-agent/website`
+- **Website** (`packages/website/`) - React docs and landing page. **When working on website, follow `packages/website/AGENTS.md`**
+
+Internal packages:
+
+- **CDN** (`packages/cdn/`) - IIFE builds for script tag usage (npm: `@page-agent/cdn`)
+- **LLMs** (`packages/llms/`) - LLM client with reflection-before-action mental model
+- **Page Controller** (`packages/page-controller/`) - DOM operations and visual feedback (SimulatorMask), independent of LLM
+- **UI** (`packages/ui/`) - Panel and i18n. Decoupled from PageAgent
 
 ## Development Commands
 
-### Core Commands
-
 ```bash
 npm start                    # Start website dev server
-npm run dev                  # Same as start
 npm run build                # Build all packages
-npm run build:lib            # Build page-agent library only
+npm run build:libs           # Build all libraries
 npm run lint                 # ESLint with TypeScript strict rules
 ```
 
-### Package-specific Commands
+## Architecture
-
-```bash
-# Core library
-npm run build --workspace=page-agent
-npm run build:watch --workspace=page-agent
-
-# Website
-npm run dev --workspace=@page-agent/website
-npm run build --workspace=@page-agent/website
-```
-
-## Architecture & Critical Patterns
 
 ### Monorepo Structure
 
+Simple monorepo solution: TypeScript references + Vite aliases. Update tsconfig and vite config when adding/removing packages.
+
 ```
 packages/
-├── page-agent/              # npm: "page-agent"
+├── page-agent/              # npm: "page-agent" ⭐ MAIN
-│   ├── src/                 # Core library source
+├── cdn/                     # npm: "@page-agent/cdn" (IIFE builds)
-│   ├── vite.config.js       # Library build (ES + UMD)
+├── website/                 # @page-agent/website (private)
-│   └── package.json
+├── llms/                    # @page-agent/llms
-└── website/                 # npm: "@page-agent/website" (private)
+├── page-controller/         # @page-agent/page-controller
-    ├── src/                 # Website source (formerly pages/)
+└── ui/                      # @page-agent/ui
-    ├── index.html
-    ├── vite.config.js       # Website build
-    └── package.json
 ```
 
-### Module Boundaries (Critical)
+`workspaces` in `package.json` must be in topological order.
 
-- **Core library** (`packages/page-agent/`): NEVER import from website - must remain pure JavaScript
+### Module Boundaries
-- **Website** (`packages/website/`): CAN import from `page-agent` for demos. Alias `@/` → `website/src/`
+
+- **Page Agent**: Core lib. Imports from `@page-agent/llms`, `@page-agent/page-controller`, `@page-agent/ui`
+- **LLMs**: LLM client with MacroToolInput contract. No dependency on page-agent
+- **UI**: Panel and i18n. No dependency on page-agent
+- **Page Controller**: DOM operations with optional visual feedback (SimulatorMask). No LLM dependency. Enable mask via `enableMask: true` config
+
+### PageController ↔ PageAgent Communication
+
+All communication is async and isolated:
+
+```typescript
+// PageAgent delegates DOM operations to PageController
+await this.pageController.updateTree()
+await this.pageController.clickElement(index)
+await this.pageController.inputText(index, text)
+await this.pageController.scroll({ down: true, numPages: 1 })
+
+// PageController exposes state via async methods
+const simplifiedHTML = await this.pageController.getSimplifiedHTML()
+const pageInfo = await this.pageController.getPageInfo()
+```
 
 ### DOM Pipeline
 
-1. **DOM Extraction**: Convert live DOM to `FlatDomTree` via `src/dom/dom_tree/`
+1. **DOM Extraction**: Live DOM → `FlatDomTree` via `page-controller/src/dom/dom_tree/`
-2. **Dehydration**: DOM tree → simplified text for LLM processing
+2. **Dehydration**: DOM tree → simplified text for LLM
-3. **LLM Processing**: AI model returns action plans
+3. **LLM Processing**: AI returns action plans (page-agent)
-4. **Indexed Operations**: Map LLM responses back to specific DOM elements
+4. **Indexed Operations**: PageAgent calls PageController by element index
 
-### Event Bus Communication
+### CDN Builds (`packages/cdn/`)
 
-Use `src/utils/bus.ts` for decoupled PageAgent ↔ UI communication:
+Two IIFE builds for script tag usage:
 
-```typescript
+| Build | File                 | Description                      |
-// Emit from PageAgent
+| ----- | -------------------- | -------------------------------- |
-getEventBus().emit('panel:show')
+| Demo  | `page-agent.demo.js` | Auto-init with built-in test API |
-getEventBus().emit('panel:update', { status: 'thinking' })
+| Full  | `page-agent.js`      | Exposes `PageAgent` class only   |
 
-// Listen in UI components
+Demo build supports query params (e.g., `?model=gpt-4&lang=en-US`).
-getEventBus().on('panel:show', () => panel.show())
-```
 
-### Hash Routing Requirement
+## Key Files Reference
 
-Uses wouter with `useHashLocation` for static hosting:
+### Page Agent (`packages/page-agent/`)
 
-```tsx
+| File               | Description                             |
-<Router hook={useHashLocation}>  // Always hash-based routes
+| ------------------ | --------------------------------------- |
-```
+| `src/PageAgent.ts` | ⭐ Main AI agent class                  |
+| `src/umd.ts`       | CDN/UMD entry with auto-init            |
+| `src/tools/`       | Tool definitions calling PageController |
 
-### CDN Auto-Injection Pattern
+### LLMs (`packages/llms/`)
 
-Library auto-initializes when injected via script tag:
+| File                         | Description                           |
+| ---------------------------- | ------------------------------------- |
+| `src/index.ts`               | ⭐ LLM class with retry logic         |
+| `src/types.ts`               | MacroToolInput, AgentBrain, LLMConfig |
+| `src/OpenAILenientClient.ts` | OpenAI-compatible client              |
 
-```html
+### Page Controller (`packages/page-controller/`)
-<script src="page-agent.js?model=gpt-4"></script>
-```
 
-Query params configure `PageAgentConfig` automatically in `src/entry.ts`.
+| File                        | Description                                                |
-
+| --------------------------- | ---------------------------------------------------------- |
-## File Organization
+| `src/PageController.ts`     | ⭐ Main controller class with optional mask support        |
-
+| `src/SimulatorMask.ts`      | Visual overlay blocking user interaction during automation |
-### Core Library (`packages/page-agent/src/`)
+| `src/actions.ts`            | Element interactions (click, input, scroll)                |
-
+| `src/dom/dom_tree/index.js` | Core DOM extraction engine                                 |
-- `entry.ts` - CDN/UMD entry point with auto-initialization
-- `PageAgent.ts` - **Main AI agent class** orchestrating DOM operations
-- `tools/` - Agent tool implementations for web actions
-- `ui/` - UI components (Panel, SimulatorMask) with CSS modules
-- `utils/bus.ts` - **Type-safe event bus** for decoupled communication
-- `patches/` - Framework-specific optimizations (React, Antd compatibility)
-- `llms/` - LLM integration and communication layer
-- `dom/` - HTML serialization and page analysis utilities
-- `config/` - Configuration constants and settings
-
-### Website (`packages/website/src/`)
-
-- `main.tsx` - Site entry with hash routing setup
-- `router.tsx` - **Manual route definitions** (requires explicit registration)
-- `components/DocsLayout.tsx` - Navigation structure (hardcoded nav items)
-- `docs/[section]/[topic]/page.tsx` - Documentation pages
-- `test-pages/` - Library integration test pages
 
 ## Adding New Features
 
-### New Documentation Page
-
-1. Create `packages/website/src/docs/<section>/<slug>/page.tsx`
-2. Add route to `packages/website/src/router.tsx` with `<Header /> + <DocsLayout>` wrapper
-3. Add navigation item to `DocsLayout.tsx`
-
 ### New Agent Tool
 
-1. Implement under `packages/page-agent/src/tools/`
+1. Implement in `packages/page-agent/src/tools/index.ts`
-2. Export via `packages/page-agent/src/tools/index.ts`
+2. If tool needs DOM ops, add method to PageController first
-3. Wire into `PageAgent.ts` if needed
+3. Tool calls `this.pageController.methodName()` for DOM interactions
 
-### New UI Component
+### New PageController Action
 
-1. Create in `packages/page-agent/src/ui/` with colocated CSS modules
+1. Add implementation in `packages/page-controller/src/actions.ts`
-2. Use event bus for PageAgent communication
+2. Expose via async method in `PageController.ts`
+3. Export from `packages/page-controller/src/index.ts`
 
 ## Code Standards
 
-### TypeScript
-
 - Explicit typing for exported/public APIs
 - ESLint relaxes some unsafe rules for rapid iteration
-
+- Every change you make should not only implement the desired functionality but also improve the quality of the codebase
-### CSS & Styling
+- All code and comments must be in English.
-
-- **Prefer Tailwind CSS over custom CSS**
-- Custom CSS variables for theme gradients in `src/index.css`
-- Dark mode support via `dark:` classes
-- CSS modules for component-specific styles
-
-### Import Organization
-
-- External libraries first
-- Internal modules (`@/`, `@pages/`)
-- Relative imports last
-- Blank lines between groups
-
-## Critical Files to Understand
-
-- `packages/page-agent/src/PageAgent.ts` - Core AI agent class with DOM manipulation
-- `packages/page-agent/src/dom/dom_tree/index.js` - DOM extraction engine
-- `packages/page-agent/src/utils/bus.ts` - Type-safe event bus system
-- `packages/page-agent/src/entry.ts` - Library entry point for CDN usage
-- `packages/page-agent/vite.config.js` - Library build configuration
-
-- `packages/website/src/router.tsx` - Central routing definition (manual registration required)
-- `packages/website/src/components/DocsLayout.tsx` - Navigation structure
-- `packages/website/vite.config.js` - Website build configuration
-
-## Debugging Common Issues
-
-### Blank Documentation Pages
-
-1. Verify route exists in `packages/website/src/router.tsx`
-2. Check component import path
-3. Verify CSS isn't hiding content (check dark mode classes)
-4. Test with minimal component first
-
-### Library Integration Issues
-
-1. Check `packages/page-agent/dist/lib/page-agent.umd.js` builds correctly
-2. Test CDN injection with query params
-3. Verify event bus communications are properly typed
-4. Use `packages/website/src/test-pages/` for isolated testing

CONTRIBUTING.md

@@ -7,18 +7,16 @@ Thank you for your interest in contributing to Page-Agent! We welcome contributi
 ### Development Setup
 
 1. **Prerequisites**
-   - Node.js 20+
+    - `node.js >= 20` with `npm >= 10`
-   - npm 10+
+    - An editor that supports `ts/eslint/prettier`
-   - typescript as required in package.json
+    - Make sure `eslint`, `prettier` and `commitlint` work well
-   - vscode or other editors that support ts/eslint/prettier
-   - make sure `eslint`, `auto-format` and `commit-lint` all work
 
 2. **Setup**
 
-   ```bash
+    ```bash
-   npm install
+    npm ci
-   npm start          # Start demo and documentation site
+    npm start          # Start demo and documentation site
-   ```
+    ```
 
 ### Project Structure
 
@@ -27,7 +25,11 @@ This is a **monorepo** with npm workspaces containing **two main packages**:
 1. **Core Library** (`packages/page-agent/`) - Pure JavaScript/TypeScript AI agent library for browser DOM automation, published as `page-agent` on npm
 2. **Website** (`packages/website/`) - React documentation and landing page. Also as demo and test page for the core lib. private package `@page-agent/website`
 
-We use a simplified monorepo solution with native npm-workspace. No fancy tooling. Hoisting is required.
+We use a simplified monorepo solution with `native npm-workspace + ts reference + vite alias`. No fancy tooling. Hoisting is required.
+
+- When developing. Use alias so that we don't have to pre-build.
+- When bundling. Use external and disable ts `paths` alias to leave deps out.
+- When bundling `IIFE` and `Website`. Bundle everything including local packages.
 
 ## 🤝 How to Contribute
 
@@ -42,40 +44,39 @@ We use a simplified monorepo solution with native npm-workspace. No fancy toolin
 
 1. **Fork and Clone**
 
-   ```bash
+    ```bash
-   git clone https://github.com/your-username/page-agent.git
+    git clone https://github.com/your-username/page-agent.git
-   cd page-agent
+    cd page-agent
-   ```
+    ```
 
 2. **Create Feature Branch**
 
-   ```bash
+    ```bash
-   git checkout -b feat/your-feature-name
+    git checkout -b feat/your-feature-name
-   ```
+    ```
 
 3. **Make Changes**
-   - Follow existing code style and patterns
+    - Follow existing code style and patterns
-   - Add tests for new functionality
+    - Add tests for new functionality
-   - Update documentation as needed
+    - Update documentation as needed
 
 4. **Test Your Changes**
-
+    - Test in our demo website
-   ```bash
+    - Test it on other websites if applicable
-   # TODO
+    - `@TODO: test suite`
-   ```
 
 5. **Commit and Push**
 
-   ```bash
+    ```bash
-   git add .
+    git add .
-   git commit -m "feat: add awesome feature"
+    git commit -m "feat: add awesome feature"
-   git push origin feat/your-feature-name
+    git push origin feat/your-feature-name
-   ```
+    ```
 
 6. **Create Pull Request**
-   - Provide clear description of changes
+    - Provide clear description of changes
-   - Link related issues
+    - Link related issues
-   - Include screenshots for UI changes
+    - Include screenshots for UI changes
 
 ## 📝 Code Style
 
@@ -92,52 +93,52 @@ We use a simplified monorepo solution with native npm-workspace. No fancy toolin
 - It's **recommended** to heavily rely on AI (aka "vibe coding") when maintaining **demo pages and tests**.
 - BUT **NOT the core lib!!!** Be very careful if AI ever touched the core lib!!!
 - Review anything AI wrote before make a commit. You are the author of anything you commit. NOT AI.
-- Update the AI instructions when structure changed.
+- Update the [AI instructions](AGENTS.md) when structure changed.
-   - Cursor and Cline: `./.cursor/rules`
-   - Github Copilot: `./.github/copilot-instructions.md`
-   - Claude Code: `./CLAUDE.md`
-
-### Core Library (`src/`)
-
-- **No React dependencies** - Pure JavaScript/TypeScript only
-- Use event bus for component communication
-- Follow browser-use patterns for DOM operations
-
-### Doc&demo Site (`pages/`)
-
-- Use React 19 + TypeScript
-- Follow hash routing patterns (`useHashLocation`)
-- Use Tailwind CSS for styling
-- Add new docs pages to both router and sidebar
 
 ## 🔧 Development Workflows
 
+### Test With Your Own LLM API
+
+- Create a `.env` file in the repo root with your LLM API config
+
+    ```env
+    LLM_MODEL_NAME=gpt-5.2
+    LLM_API_KEY=your-api-key
+    LLM_BASE_URL=https://api.your-llm-provider.com/v1
+    ```
+
+- Restart the dev server to load new env vars
+- If not provided, the demo will the free testing proxy by default
+
 ### Website Development
 
 ```bash
-npm start                # React development server
+npm start
 ```
 
-### Core Lib Development and Testing
+### Testing on Other Websites
 
-- Config your LLM API
+- Start and serve a local `iife` script
-- Start a local script
 
-   ```bash
+    ```bash
-   npm run build:lib:watch    # Auto-rebuild on changes
+    npm run dev:iife # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.js
-   ```
+    ```
 
-- Add a new bookmark enable it on other website
+- Add a new bookmark
 
-   ```
+    ```javascript
-   javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5173/dist/lib/page-agent.umd.cjs?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
+    javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.js?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
-   ```
+    ```
+
+- Click the bookmark on any page to load Page-Agent
+
+> Warning: AK in your local `.env` will be inlined in the iife script.
 
 ### Adding Documentation
 
-1. Create `pages/docs/section/page-name/page.tsx`
+Ask an AI to help you add documentation to the `website/` package. Follow the existing style.
-2. Add route to `pages/router.tsx`
+
-3. Add navigation link to `pages/components/DocsLayout.tsx`
+> Our AGENTS.md file and guardrails are designed for this purpose. But please be careful and review anything AI generated.
 
 ## 🎯 Contribution Areas
 
@@ -152,7 +153,7 @@ We especially welcome contributions in:
 
 ## 🚫 What We Don't Accept
 
-- Changes that break existing API compatibility
+- Changes that break existing API compatibility (Discuss first)
 - Heavy dependencies to core library
 - Contributions without proper testing
 - Code that doesn't follow project conventions

LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
-Copyright (c) 2025 Alibaba
+Copyright (c) 2026 Alibaba
+Copyright (c) 2026 Simon
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README-zh.md

@@ -1,16 +1,19 @@
 # PageAgent 🤖🪄
 
-![banner](https://img.alicdn.com/imgextra/i1/O1CN01RY0Wvh26ATVeDIX7v_!!6000000007621-0-tps-1672-512.jpg)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://img.alicdn.com/imgextra/i4/O1CN01qKig1P1FnhpFKNdi6_!!6000000000532-2-tps-1280-256.png">
+  <img alt="Page Agent Banner" src="https://img.alicdn.com/imgextra/i1/O1CN01NCMKXj1Gn4tkFTsxf_!!6000000000666-2-tps-1280-256.png">
+</picture>
 
-[![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/alibaba/page-agent.svg)](https://github.com/alibaba/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/alibaba/page-agent.svg)](https://github.com/alibaba/page-agent)
 
 纯 JS 实现的 GUI agent。使用自然语言操作你的 Web 应用。无须后端、客户端、浏览器插件。
 
 🌐 [English](./README.md) | **中文**
 
-👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a> 
+👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a>
 
-<video id="demo-video" src="https://github.com/user-attachments/assets/141bbb01-8022-4d1f-919d-9efc9a1dc1cf" width="640" crossorigin muted autoplay loop></video>
+<video id="demo-video" src="https://github.com/user-attachments/assets/34d8444d-cbfb-44a3-a24e-fd5c167bb0bf" controls crossorigin muted></video>
 
 ---
 
@@ -24,21 +27,28 @@
 
 ## 🗺️ Roadmap
 
-👉 [**Roadmap**](./ROADMAP.md)
+👉 [**Roadmap**](https://github.com/alibaba/page-agent/issues/96)
 
 ## 🚀 快速开始
 
-### CDN 集成
+### 快速体验 (With Testing LLM)
+
+最快的体验方式：
 
 ```html
-<!-- 临时 CDN URL. 未来会变更 -->
 <script
-	src="https://hwcxiuzfylggtcktqgij.supabase.co/storage/v1/object/public/demo-public/v0.0.4/page-agent.js"
+    src="https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js"
-	crossorigin="true"
+    crossorigin="true"
-	type="text/javascript"
 ></script>
 ```
 
+> ⚠️ **仅用于技术评估。** Demo 模型有速率限制和使用限制，生产环境请使用 NPM 方式。
+
+| Mirrors | URL                                                                                 |
+| ------- | ----------------------------------------------------------------------------------- |
+| Global  | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js                |
+| China   | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js |
+
 ### NPM 安装
 
 ```bash
@@ -48,63 +58,49 @@ npm install page-agent
 ```javascript
 import { PageAgent } from 'page-agent'
 
-// 测试接口
-// @note: 限流，限制 prompt 内容，限制来源，随时变更，请替换成你自己的
-// @note: 使用 DeepSeek-chat(3.2) 官方版本，使用协议和隐私策略见 DeepSeek 网站
-const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
 const agent = new PageAgent({
-	modelName: DEMO_MODEL,
+    model: 'deepseek-chat',
-	baseURL: DEMO_BASE_URL,
+    baseURL: 'https://api.deepseek.com',
-	apiKey: DEMO_API_KEY,
+    apiKey: 'YOUR_API_KEY',
-	language: 'zh-CN',
+    language: 'zh-CN',
 })
 
 await agent.execute('点击登录按钮')
 ```
 
+适用于无法使用 NPM 的环境，我们也提供了 IIFE 构建的 CDN 方式。[@see CDN Usage](https://alibaba.github.io/page-agent/#/docs/integration/cdn-setup)
+
 ## 🏗️ 架构设计
 
-PageAgent 采用清晰的模块化架构：
+PageAgent adopts a simplified monorepo structure:
 
 ```
-src/
+packages/
-├── PageAgent.ts          # Agent 主流程
+├── page-agent/          # AI agent (npm: page-agent)
-├── dom/                  # DOM 理解
+├── llms/                # LLM 客户端 (npm: @page-agent/llms)
-├── tools/                # 代理交互工具
+├── page-controller/     # DOM 操作 & 蒙层 & 模拟鼠标 (npm: @page-agent/page-controller)
-├── ui/                   # UI 组件和面板
+├── ui/                  # 面板 & i18n (npm: @page-agent/ui)
-├── llms/                 # LLM 集成层
+├── cdn/                 # CDN IIFE builds (npm: @page-agent/cdn)
-└── utils/                # 事件总线和工具
+└── website/             # 文档站点
 ```
 
 ## 🤝 贡献
 
 欢迎社区贡献！以下是参与方式：
 
-### 开发环境
+1. Fork 并 clone。`git clone https://github.com/alibaba/page-agent.git && cd page-agent`
+2. 安装依赖: `npm install`
+3. 启动开发: `npm start`
 
-1. Fork 项目仓库
+更多详情请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
-2. Clone or fork: `git clone https://github.com/alibaba/page-agent.git && cd page-agent`
-3. 安装依赖: `npm install`
-4. 启动开发: `npm start`
 
-### 贡献指南
+请在贡献前阅读我们的[行为准则](CODE_OF_CONDUCT.md)。
-
-请在贡献前阅读我们的[行为准则](CODE_OF_CONDUCT.md)和[贡献指南](CONTRIBUTING.md)。
 
 ## 👏 致谢
 
-本项目基于以下优秀项目构建：
+本项目基于 **[`browser-use`](https://github.com/browser-use/browser-use)** 的优秀工作构建。
 
-- **[browser-use](https://github.com/browser-use/browser-use)**
+`PageAgent` 专为**客户端网页增强**设计，不是服务端自动化工具。
-
-PageAgent 专为**客户端网页增强**设计，不是服务端自动化工具。
-
-## 📄 许可证
-
-MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。
 
 ```
 DOM processing components and prompt are derived from browser-use:
@@ -123,6 +119,10 @@ Third-party dependencies and their licenses can be found in the package.json
 file and in the node_modules directory after installation.
 ```
 
+## 📄 许可证
+
+[MIT License](LICENSE)
+
 ---
 
 **⭐ 如果觉得 PageAgent 有用或有趣，请给项目点个星！**

README.md

@@ -1,16 +1,19 @@
 # PageAgent 🤖🪄
 
-![banner](https://img.alicdn.com/imgextra/i1/O1CN01RY0Wvh26ATVeDIX7v_!!6000000007621-0-tps-1672-512.jpg)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://img.alicdn.com/imgextra/i4/O1CN01qKig1P1FnhpFKNdi6_!!6000000000532-2-tps-1280-256.png">
+  <img alt="Page Agent Banner" src="https://img.alicdn.com/imgextra/i1/O1CN01NCMKXj1Gn4tkFTsxf_!!6000000000666-2-tps-1280-256.png">
+</picture>
 
-[![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/alibaba/page-agent.svg)](https://github.com/alibaba/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/alibaba/page-agent.svg)](https://github.com/alibaba/page-agent)
 
 The GUI Agent Living in Your Webpage. Control web interfaces with natural language.
 
 🌐 **English** | [中文](./README-zh.md)
 
-👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a> 
+👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a>
 
-<video id="demo-video" src="https://github.com/user-attachments/assets/de8d1964-8bde-494f-a52f-2975469557a5" width="640" crossorigin muted autoplay loop></video>
+<video id="demo-video" src="https://github.com/user-attachments/assets/34d8444d-cbfb-44a3-a24e-fd5c167bb0bf" controls crossorigin muted></video>
 
 ---
 
@@ -24,21 +27,28 @@ The GUI Agent Living in Your Webpage. Control web interfaces with natural langua
 
 ## 🗺️ Roadmap
 
-👉 [**Roadmap**](./ROADMAP.md)
+👉 [**Roadmap**](https://github.com/alibaba/page-agent/issues/96)
 
 ## 🚀 Quick Start
 
-### CDN Integration
+### Quick Try (With Testing LLM)
+
+Fastest way to try PageAgent:
 
 ```html
-<!-- temporary CDN URL. May change in the future -->
 <script
-	src="https://hwcxiuzfylggtcktqgij.supabase.co/storage/v1/object/public/demo-public/v0.0.4/page-agent.js"
+    src="https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js"
-	crossorigin="true"
+    crossorigin="true"
-	type="text/javascript"
 ></script>
 ```
 
+> ⚠️ **For technical evaluation only.** Demo model has rate limits and usage restrictions. Use NPM for production.
+
+| Mirrors | URL                                                                                 |
+| ------- | ----------------------------------------------------------------------------------- |
+| Global  | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js                |
+| China   | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js |
+
 ### NPM Installation
 
 ```bash
@@ -48,63 +58,49 @@ npm install page-agent
 ```javascript
 import { PageAgent } from 'page-agent'
 
-// test server
-// @note: rate limit. prompt limit. Origin limit. May change anytime. Use your own llm!
-// @note Using official DeepSeek-chat(3.2). Go to DeepSeek website for privacy policy.
-const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
 const agent = new PageAgent({
-	modelName: DEMO_MODEL,
+    model: 'deepseek-chat',
-	baseURL: DEMO_BASE_URL,
+    baseURL: 'https://api.deepseek.com',
-	apiKey: DEMO_API_KEY,
+    apiKey: 'YOUR_API_KEY',
-	language: 'en-US',
+    language: 'en-US',
 })
 
 await agent.execute('Click the login button')
 ```
 
+For environments where NPM is not available. We do offer a IIFE build via CDN. [@see CDN Usage](https://alibaba.github.io/page-agent/#/docs/integration/cdn-setup)
+
 ## 🏗️ Structure
 
-PageAgent follows a clean, modular architecture:
+PageAgent adopts a simplified monorepo structure:
 
 ```
-src/
+packages/
-├── PageAgent.ts          # Agent main loop
+├── page-agent/          # AI agent (npm: page-agent)
-├── dom/                  # DOM processing
+├── llms/                # LLM client (npm: @page-agent/llms)
-├── tools/                # Agent tools
+├── page-controller/     # DOM operations & Visual Mask (npm: @page-agent/page-controller)
-├── ui/                   # UI components & panels
+├── ui/                  # Panel & i18n (npm: @page-agent/ui)
-├── llms/                 # LLM integration layer
+├── cdn/                 # CDN IIFE builds (npm: @page-agent/cdn)
-└── utils/                # Event bus & utilities
+└── website/             # Demo & Documentation site
 ```
 
 ## 🤝 Contributing
 
 We welcome contributions from the community! Here's how to get started:
 
-### Setup
+1. Fork and clone. `git clone https://github.com/alibaba/page-agent.git && cd page-agent`
+2. Install dependencies: `npm install`
+3. Start development: `npm start`
 
-1. Fork the repository
+More details in [CONTRIBUTING.md](CONTRIBUTING.md).
-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) before contributing.
-
-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:
+This project builds upon the excellent work of **[`browser-use`](https://github.com/browser-use/browser-use)**.
 
-- **[browser-use](https://github.com/browser-use/browser-use)**
+`PageAgent` is designed for **client-side web enhancement**, not server-side automation.
-
-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:
@@ -123,6 +119,10 @@ Third-party dependencies and their licenses can be found in the package.json
 file and in the node_modules directory after installation.
 ```
 
+## 📄 License
+
+[MIT License](LICENSE)
+
 ---
 
 **⭐ Star this repo if you find PageAgent helpful!**

ROADMAP.md

@@ -1,61 +0,0 @@
-# 🗺️ PageAgent Roadmap
-
-The development progress and future plans for PageAgent.
-
-## 🚀 Current Works
-
-- [x] **MVP** 
-  - Core functionality implemented.
-- [x] **SPA interaction** 
-- [x] **Reasoning and (short) memory**
-- [x] **Multi model provider integration and testing**
-- [x] **UI with HITL** 
-  - Human-in-the-loop user interface. Agent can ask user questions.
-- [x] **Landing and doc pages**
-- [x] **Remove `ai-sdk`** 
-  - Only one function of AI-ADK is being used.
-  - Our agent memory and thinking mechanism does not suite ai-sdk.
-- [x] **Robust LLM output**
-  - Auto-fix incomplete output format of DeepSeek and QWen.
-- [x] **Working homepage with live LLM API**
-- [x] **~~free~~ CDN**
-- [x] **Free evaluation plan**
-- [x] **Custom actions and HITL**
-- [ ] **Hooks and Events**
-  - [x] **lifecycle hooks**
-  - [ ] **lifecycle events**
-- [ ] **❗Pause and intervene** 
-  - Current pause does not allow user intervention.
-- [ ] **❗Hijack `page_open/page_change/page_unload` behavior**
-- [ ] **Custom knowledge base and instructions**
-- [ ] **Black/white-list safeguard**
-- [ ] **Data-masking**
-- [ ] **Improve Memory**
-  - Current phrasing can cause logic-loop for some models.
-  - Test adding `Action` to memory.
-- [ ] **Tools for more complex tasks**
-  - todo list
-  - file sys
-- [ ] **Optimize for popular UI frameworks**
-- [x] **i18n of the website**
-  - [x] Chinese version
-  - [x] English version
-- [ ] **Testing suits**
-- [ ] **Support custom llm fetch**
-- [ ] **Refactor: Separate `Agent` and `Page-Controller`** 
-  - Agent should be able to run w/o dom. 
-  - Actions should be able to be injected through iframe.
-
-♻️ Following browser-use's update and contribute back.
-
-## 📋 Pending Features
-
-- [ ] **Chrome-ext wrapper**
-- [ ] **Same-origin multi-page-app rally**
-- [ ] **Local MCP proxy**
-
-## 🤔 To Be Decided
-
-- [ ] **Cross-origin multi-page?** 
-  - Tricky
-  - Need some kind of "memory rally"

eslint.config.js

@@ -8,7 +8,7 @@ import globals from 'globals'
 import tseslint from 'typescript-eslint'
 
 export default defineConfig([
-	globalIgnores(['**/dist', '**/test-pages', '**/node_modules']),
+	globalIgnores(['**/dist', '**/node_modules', 'packages/website/src/components/ui']),
 	{
 		plugins: {
 			'react-hooks': reactHooks,
@@ -37,8 +37,10 @@ export default defineConfig([
 		],
 		languageOptions: {
 			parserOptions: {
-				project: ['./packages/*/tsconfig.json'],
+				// project: ['./tsconfig.json'],
-				tsconfigRootDir: import.meta.dirname,
+				// project: ['./packages/*/tsconfig.json'],
+				// tsconfigRootDir: import.meta.dirname,
+				projectService: true,
 			},
 			ecmaVersion: 2020,
 			globals: globals.browser,
@@ -67,6 +69,9 @@ export default defineConfig([
 			'react-dom/no-missing-button-type': 'off',
 			'react-x/no-nested-component-definitions': 'off',
 			'@typescript-eslint/prefer-optional-chain': 'off',
+
+			// 'require-await': 'off',
+			'@typescript-eslint/require-await': 'off',
 		},
 	},
 ])

package.json

@@ -1,10 +1,15 @@
 {
 	"name": "root",
 	"private": true,
-	"version": "0.0.5",
+	"version": "0.2.5",
 	"type": "module",
 	"workspaces": [
-		"packages/*"
+		"packages/page-controller",
+		"packages/ui",
+		"packages/llms",
+		"packages/page-agent",
+		"packages/cdn",
+		"packages/website"
 	],
 	"description": "AI-powered UI agent for web applications",
 	"author": "Simon<gaomeng1900>",
@@ -19,33 +24,43 @@
 		"npm": ">=10.0.0"
 	},
 	"scripts": {
-		"dev": "npm run dev --workspace=@page-agent/website",
+		"cleanup": "rm -rf packages/*/dist",
 		"start": "npm run dev --workspace=@page-agent/website",
-		"build": "npm run build --workspaces --if-present",
+		"build:website": "npm run build:website --workspace=@page-agent/website",
-		"build:lib": "npm run build --workspace=page-agent",
+		"build:libs": "npm run build --workspaces --if-present",
+		"build": "npm run build:libs && npm run build:website",
+		"dev:iife": "npm run dev:iife --workspace=page-agent",
 		"version": "node scripts/sync-version.js",
 		"lint": "eslint .",
 		"prepare": "husky"
 	},
 	"devDependencies": {
-		"@commitlint/cli": "^20.1.0",
+		"@commitlint/cli": "^20.3.1",
-		"@commitlint/config-conventional": "^20.0.0",
+		"@commitlint/config-conventional": "^20.3.1",
-		"@eslint/js": "^9.37.0",
+		"@eslint/js": "^9.39.2",
-		"@trivago/prettier-plugin-sort-imports": "^5.2.2",
+		"@microsoft/api-extractor": "^7.55.2",
+		"@trivago/prettier-plugin-sort-imports": "^6.0.2",
+		"@types/node": "^25.0.7",
+		"concurrently": "^9.2.1",
 		"dotenv": "^17.2.3",
-		"eslint": "^9.37.0",
+		"eslint": "^9.39.2",
 		"eslint-config-prettier": "^10.1.8",
-		"eslint-plugin-react-dom": "^2.3.9",
+		"eslint-plugin-react-dom": "^2.5.7",
 		"eslint-plugin-react-hooks": "^7.0.1",
-		"eslint-plugin-react-refresh": "^0.4.24",
+		"eslint-plugin-react-refresh": "^0.4.26",
-		"eslint-plugin-react-x": "^2.3.9",
+		"eslint-plugin-react-x": "^2.5.7",
-		"globals": "^16.4.0",
+		"globals": "^17.0.0",
 		"husky": "^9.1.7",
 		"lint-staged": "^16.2.4",
-		"prettier": "^3.6.2",
+		"prettier": "^3.7.4",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.46.0",
+		"typescript-eslint": "^8.53.0",
-		"vite": "^7.1.9"
+		"unplugin-dts": "^1.0.0-beta.6",
+		"vite": "^7.3.1",
+		"vite-plugin-css-injected-by-js": "^3.5.2"
+	},
+	"overrides": {
+		"typescript": "^5.9.3"
 	},
 	"lint-staged": {
 		"*.{js,ts,cjs,cts,mjs,mts}": [
@@ -87,6 +102,22 @@
 			".css$"
 		],
 		"importOrderSeparation": true,
-		"importOrderSortSpecifiers": true
+		"importOrderSortSpecifiers": true,
+		"overrides": [
+			{
+				"files": "*.md",
+				"options": {
+					"useTabs": false,
+					"tabWidth": 4
+				}
+			},
+			{
+				"files": "*.json",
+				"options": {
+					"useTabs": false,
+					"tabWidth": 4
+				}
+			}
+		]
 	}
 }

packages/cdn/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "@page-agent/cdn",
+	"private": false,
+	"version": "0.2.5",
+	"type": "module",
+	"files": [
+		"dist/"
+	],
+	"description": "CDN builds for page-agent - IIFE bundles for script tag usage",
+	"author": "Simon<gaomeng1900>",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/alibaba/page-agent.git"
+	},
+	"homepage": "https://alibaba.github.io/page-agent/",
+	"scripts": {
+		"build": "vite build && vite build --mode demo"
+	},
+	"dependencies": {
+		"page-agent": "0.2.5"
+	}
+}

packages/cdn/src/demo.js

@@ -0,0 +1,64 @@
+// @ts-nocheck
+/**
+ * Demo CDN build for page-agent
+ * Auto-initializes with built-in demo API for testing
+ *
+ * Usage:
+ *   <script src="https://unpkg.com/@page-agent/cdn/dist/page-agent.demo.js"></script>
+ */
+import { PageAgent } from 'page-agent'
+
+// Clean up existing instances to prevent multiple injections from bookmarklet
+if (window.pageAgent) {
+	window.pageAgent.dispose()
+}
+
+// Mount to global window object
+window.PageAgent = PageAgent
+
+// Export for IIFE
+export { PageAgent }
+
+console.log('🚀 page-agent.js loaded!')
+
+const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
+const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+
+// Demo warning
+console.log(
+	'%c⚠️ DEMO MODE %c\n' +
+		'This build uses a shared testing LLM with rate limits.\n' +
+		'For production, use page-agent.js with your own API key:\n' +
+		'https://alibaba.github.io/page-agent/#/docs/features/models',
+	'background: #f59e0b; color: #000; font-size: 14px; font-weight: bold; padding: 4px 8px; border-radius: 4px;',
+	'color: #f59e0b; font-size: 12px;'
+)
+
+// in case document.x is not ready yet
+setTimeout(() => {
+	const currentScript = document.currentScript
+
+	if (currentScript) {
+		console.log('🚀 page-agent.js detected current script:', currentScript.src)
+		const url = new URL(currentScript.src)
+		const model = url.searchParams.get('model') || DEMO_MODEL
+		const baseURL = url.searchParams.get('baseURL') || DEMO_BASE_URL
+		const apiKey = url.searchParams.get('apiKey') || DEMO_API_KEY
+		const language = url.searchParams.get('lang') || 'zh-CN'
+		const config = { model, baseURL, apiKey, language }
+		window.pageAgent = new PageAgent(config)
+	} else {
+		console.log('🚀 page-agent.js no current script detected, using default demo config')
+		const config = {
+			model: DEMO_MODEL,
+			baseURL: DEMO_BASE_URL,
+			apiKey: DEMO_API_KEY,
+		}
+		window.pageAgent = new PageAgent(config)
+	}
+
+	console.log('🚀 page-agent.js initialized with config:', window.pageAgent.config)
+
+	window.pageAgent.panel.show()
+})

packages/cdn/src/full.js

@@ -0,0 +1,15 @@
+// @ts-nocheck
+/**
+ * Full CDN build for page-agent
+ * Exposes PageAgent class for manual instantiation and configuration
+ *
+ * Usage:
+ *   <script src="https://unpkg.com/@page-agent/cdn/dist/page-agent.js"></script>
+ *   <script>
+ *     const agent = new PageAgent({ model: 'gpt-4o', apiKey: 'your-key' })
+ *     agent.panel.show()
+ *   </script>
+ */
+import { PageAgent } from 'page-agent'
+
+export { PageAgent }

packages/cdn/vite.config.js

@@ -0,0 +1,49 @@
+// @ts-nocheck
+import { dirname, resolve } from 'path'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * CDN IIFE builds for page-agent
+ *
+ * Build targets (via --mode):
+ * - demo: page-agent.demo.js with auto-init and built-in API
+ * - full (default): page-agent.js exposes PageAgent class only
+ */
+export default defineConfig(({ mode }) => {
+	const isDemo = mode === 'demo'
+	const entry = isDemo ? resolve(__dirname, 'src/demo.js') : resolve(__dirname, 'src/full.js')
+	const fileName = isDemo ? 'page-agent.demo' : 'page-agent'
+
+	return {
+		plugins: [cssInjectedByJsPlugin({ relativeCSSInjection: true })],
+		publicDir: false,
+		esbuild: {
+			keepNames: true,
+		},
+		build: {
+			lib: {
+				entry,
+				name: 'PageAgent',
+				fileName: () => `${fileName}.js`,
+				formats: ['iife'],
+			},
+			outDir: resolve(__dirname, 'dist'),
+			emptyOutDir: !isDemo, // only empty on first build (full)
+			minify: false,
+			cssCodeSplit: true,
+			rollupOptions: {
+				onwarn: function (message, handler) {
+					if (message.code === 'EVAL') return
+					handler(message)
+				},
+			},
+		},
+		define: {
+			'process.env.NODE_ENV': '"production"',
+		},
+	}
+})

packages/llms/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@page-agent/llms",
+	"version": "0.2.5",
+	"type": "module",
+	"main": "./dist/lib/page-agent-llms.js",
+	"module": "./dist/lib/page-agent-llms.js",
+	"types": "./dist/lib/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/lib/index.d.ts",
+			"import": "./dist/lib/page-agent-llms.js",
+			"default": "./dist/lib/page-agent-llms.js"
+		}
+	},
+	"files": [
+		"dist/"
+	],
+	"description": "LLM client with reflection-before-action mental model for page-agent",
+	"keywords": [
+		"page-agent",
+		"llm",
+		"openai",
+		"tool-calling",
+		"agent"
+	],
+	"author": "Simon<gaomeng1900>",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/alibaba/page-agent.git",
+		"directory": "packages/llms"
+	},
+	"homepage": "https://alibaba.github.io/page-agent/",
+	"scripts": {
+		"build": "vite build",
+		"prepublishOnly": "node -e \"const fs=require('fs');['LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
+		"postpublish": "node -e \"['LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
+	},
+	"dependencies": {
+		"chalk": "^5.6.2",
+		"zod": "^4.3.5"
+	}
+}

packages/llms/src/OpenAIClient.ts

@@ -0,0 +1,206 @@
+/**
+ * OpenAI Client implementation
+ */
+import { InvokeError, InvokeErrorType } from './errors'
+import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
+import { modelPatch, zodToOpenAITool } from './utils'
+
+/**
+ * Client for OpenAI compatible APIs
+ */
+export class OpenAIClient implements LLMClient {
+	config: Required<LLMConfig>
+	private fetch: typeof globalThis.fetch
+
+	constructor(config: Required<LLMConfig>) {
+		this.config = config
+		this.fetch = config.customFetch
+	}
+
+	async invoke(
+		messages: Message[],
+		tools: Record<string, Tool>,
+		abortSignal?: AbortSignal,
+		options?: InvokeOptions
+	): Promise<InvokeResult> {
+		// 1. Convert tools to OpenAI format
+		const openaiTools = Object.entries(tools).map(([name, t]) => zodToOpenAITool(name, t))
+
+		// Build request body
+		const requestBody: Record<string, unknown> = {
+			model: this.config.model,
+			temperature: this.config.temperature,
+			messages,
+			tools: openaiTools,
+			parallel_tool_calls: false,
+			// Require tool call: specific tool if provided, otherwise any tool
+			tool_choice: options?.toolChoiceName
+				? { type: 'function', function: { name: options.toolChoiceName } }
+				: 'required',
+		}
+
+		// 2. Call API
+		let response: Response
+		try {
+			response = await this.fetch(`${this.config.baseURL}/chat/completions`, {
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/json',
+					Authorization: `Bearer ${this.config.apiKey}`,
+				},
+				body: JSON.stringify(modelPatch(requestBody)),
+				signal: abortSignal,
+			})
+		} catch (error: unknown) {
+			console.error(error)
+			throw new InvokeError(InvokeErrorType.NETWORK_ERROR, 'Network request failed', error)
+		}
+
+		// 3. Handle HTTP errors
+		if (!response.ok) {
+			const errorData = await response.json().catch()
+			const errorMessage =
+				(errorData as { error?: { message?: string } }).error?.message || response.statusText
+
+			if (response.status === 401 || response.status === 403) {
+				throw new InvokeError(
+					InvokeErrorType.AUTH_ERROR,
+					`Authentication failed: ${errorMessage}`,
+					errorData
+				)
+			}
+			if (response.status === 429) {
+				throw new InvokeError(
+					InvokeErrorType.RATE_LIMIT,
+					`Rate limit exceeded: ${errorMessage}`,
+					errorData
+				)
+			}
+			if (response.status >= 500) {
+				throw new InvokeError(
+					InvokeErrorType.SERVER_ERROR,
+					`Server error: ${errorMessage}`,
+					errorData
+				)
+			}
+			throw new InvokeError(
+				InvokeErrorType.UNKNOWN,
+				`HTTP ${response.status}: ${errorMessage}`,
+				errorData
+			)
+		}
+
+		// 4. Parse and validate response
+		const data = await response.json()
+
+		const choice = data.choices?.[0]
+		if (!choice) {
+			throw new InvokeError(InvokeErrorType.UNKNOWN, 'No choices in response', data)
+		}
+
+		// Check finish_reason
+		switch (choice.finish_reason) {
+			case 'tool_calls':
+			case 'function_call': // gemini
+			case 'stop': // some models use this even with tool calls
+				break
+			case 'length':
+				throw new InvokeError(
+					InvokeErrorType.CONTEXT_LENGTH,
+					'Response truncated: max tokens reached'
+				)
+			case 'content_filter':
+				throw new InvokeError(InvokeErrorType.CONTENT_FILTER, 'Content filtered by safety system')
+			default:
+				throw new InvokeError(
+					InvokeErrorType.UNKNOWN,
+					`Unexpected finish_reason: ${choice.finish_reason}`
+				)
+		}
+
+		// Apply normalizeResponse if provided (for fixing format issues automatically)
+		const normalizedData = options?.normalizeResponse ? options.normalizeResponse(data) : data
+		const normalizedChoice = (normalizedData as any).choices?.[0]
+
+		// Get tool name from response
+		const toolCallName = normalizedChoice?.message?.tool_calls?.[0]?.function?.name
+		if (!toolCallName) {
+			throw new InvokeError(
+				InvokeErrorType.NO_TOOL_CALL,
+				'No tool call found in response',
+				normalizedData
+			)
+		}
+
+		const tool = tools[toolCallName]
+		if (!tool) {
+			throw new InvokeError(
+				InvokeErrorType.UNKNOWN,
+				`Tool "${toolCallName}" not found in tools`,
+				normalizedData
+			)
+		}
+
+		// Extract and parse tool arguments
+		const argString = normalizedChoice.message?.tool_calls?.[0]?.function?.arguments
+		if (!argString) {
+			throw new InvokeError(
+				InvokeErrorType.INVALID_TOOL_ARGS,
+				'No tool call arguments found',
+				normalizedData
+			)
+		}
+
+		let parsedArgs: unknown
+		try {
+			parsedArgs = JSON.parse(argString)
+		} catch (error) {
+			throw new InvokeError(
+				InvokeErrorType.INVALID_TOOL_ARGS,
+				'Failed to parse tool arguments as JSON',
+				error
+			)
+		}
+
+		// Validate with schema
+		const validation = tool.inputSchema.safeParse(parsedArgs)
+		if (!validation.success) {
+			console.error(validation.error)
+			throw new InvokeError(
+				InvokeErrorType.INVALID_TOOL_ARGS,
+				'Tool arguments validation failed',
+				validation.error
+			)
+		}
+		const toolInput = validation.data
+
+		// 5. Execute tool
+		let toolResult: unknown
+		try {
+			toolResult = await tool.execute(toolInput)
+		} catch (e) {
+			throw new InvokeError(
+				InvokeErrorType.TOOL_EXECUTION_ERROR,
+				`Tool execution failed: ${(e as Error).message}`,
+				e
+			)
+		}
+
+		// Return result
+		return {
+			toolCall: {
+				name: toolCallName,
+				args: toolInput,
+			},
+			toolResult,
+			usage: {
+				promptTokens: data.usage?.prompt_tokens ?? 0,
+				completionTokens: data.usage?.completion_tokens ?? 0,
+				totalTokens: data.usage?.total_tokens ?? 0,
+				cachedTokens: data.usage?.prompt_tokens_details?.cached_tokens,
+				reasoningTokens: data.usage?.completion_tokens_details?.reasoning_tokens,
+			},
+			rawResponse: data,
+		}
+	}
+}

packages/llms/src/constants.ts

@@ -0,0 +1,3 @@
+// Internal constants
+export const LLM_MAX_RETRIES = 2
+export const DEFAULT_TEMPERATURE = 0.7 // higher randomness helps auto-recovery

packages/llms/src/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

packages/llms/src/index.ts

@@ -0,0 +1,108 @@
+import { OpenAIClient } from './OpenAIClient'
+import { DEFAULT_TEMPERATURE, LLM_MAX_RETRIES } from './constants'
+import { InvokeError } from './errors'
+import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
+
+export type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool }
+
+export function parseLLMConfig(config: LLMConfig): Required<LLMConfig> {
+	// Runtime validation as defensive programming (types already guarantee these)
+	if (!config.baseURL || !config.apiKey || !config.model) {
+		throw new Error(
+			'[PageAgent] LLM configuration required. Please provide: baseURL, apiKey, model. ' +
+				'See: https://alibaba.github.io/page-agent/#/docs/features/models'
+		)
+	}
+
+	return {
+		baseURL: config.baseURL,
+		apiKey: config.apiKey,
+		model: config.model,
+		temperature: config.temperature ?? DEFAULT_TEMPERATURE,
+		maxRetries: config.maxRetries ?? LLM_MAX_RETRIES,
+		customFetch: (config.customFetch ?? fetch).bind(globalThis), // fetch will be illegal unless bound
+	}
+}
+
+export class LLM extends EventTarget {
+	config: Required<LLMConfig>
+	client: LLMClient
+
+	constructor(config: LLMConfig) {
+		super()
+		this.config = parseLLMConfig(config)
+
+		// Default to OpenAI client
+		this.client = new OpenAIClient(this.config)
+	}
+
+	/**
+	 * - call llm api *once*
+	 * - invoke tool call *once*
+	 * - return the result of the tool
+	 */
+	async invoke(
+		messages: Message[],
+		tools: Record<string, Tool>,
+		abortSignal: AbortSignal,
+		options?: InvokeOptions
+	): Promise<InvokeResult> {
+		return await withRetry(
+			async () => {
+				const result = await this.client.invoke(messages, tools, abortSignal, options)
+
+				return result
+			},
+			// retry settings
+			{
+				maxRetries: this.config.maxRetries,
+				onRetry: (current: number) => {
+					this.dispatchEvent(
+						new CustomEvent('retry', { detail: { current, max: this.config.maxRetries } })
+					)
+				},
+				onError: (error: Error) => {
+					this.dispatchEvent(new CustomEvent('error', { detail: { error } }))
+				},
+			}
+		)
+	}
+}
+
+async function withRetry<T>(
+	fn: () => Promise<T>,
+	settings: {
+		maxRetries: number
+		onRetry: (retries: number) => void
+		onError: (error: Error) => void
+	}
+): Promise<T> {
+	let retries = 0
+	let lastError: Error | null = null
+	while (retries <= settings.maxRetries) {
+		if (retries > 0) {
+			settings.onRetry(retries)
+			await new Promise((resolve) => setTimeout(resolve, 100))
+		}
+
+		try {
+			return await fn()
+		} catch (error: unknown) {
+			console.error(error)
+			settings.onError(error as Error)
+
+			// do not retry if aborted by user
+			if ((error as { name?: string })?.name === 'AbortError') throw error
+
+			// do not retry if error is not retryable (InvokeError)
+			if (error instanceof InvokeError && !error.retryable) throw error
+
+			lastError = error as Error
+			retries++
+
+			await new Promise((resolve) => setTimeout(resolve, 100))
+		}
+	}
+
+	throw lastError!
+}

packages/llms/src/types.ts

@@ -32,6 +32,24 @@ export interface Tool<TParams = any, TResult = any> {
 	execute: (args: TParams) => Promise<TResult>
 }
 
+/**
+ * Invoke options for LLM call
+ */
+export interface InvokeOptions {
+	/**
+	 * Force LLM to call a specific tool by name.
+	 * If provided: tool_choice = { type: 'function', function: { name: toolChoiceName } }
+	 * If not provided: tool_choice = 'required' (must call some tool, but model chooses which)
+	 */
+	toolChoiceName?: string
+	/**
+	 * Response normalization function.
+	 * Called before parsing the response.
+	 * Used to fix various response format errors from the model.
+	 */
+	normalizeResponse?: (response: any) => any
+}
+
 /**
  * LLM Client interface
  * Note: Does not use generics because each tool in the tools array has different types
@@ -40,7 +58,8 @@ export interface LLMClient {
 	invoke(
 		messages: Message[],
 		tools: Record<string, Tool>,
-		abortSignal?: AbortSignal
+		abortSignal?: AbortSignal,
+		options?: InvokeOptions
 	): Promise<InvokeResult>
 }
 
@@ -65,13 +84,20 @@ export interface InvokeResult<TResult = unknown> {
 }
 
 /**
- * OpenAI Client config
+ * LLM configuration
  */
-export interface OpenAIClientConfig {
+export interface LLMConfig {
-	model: string
-	apiKey: string
 	baseURL: string
+	apiKey: string
+	model: string
+
 	temperature?: number
-	maxTokens?: number
 	maxRetries?: number
+
+	/**
+	 * Custom fetch function for LLM API requests.
+	 * Use this to customize headers, credentials, proxy, etc.
+	 * The response should follow OpenAI API format.
+	 */
+	customFetch?: typeof globalThis.fetch
 }

packages/llms/src/utils.ts

@@ -0,0 +1,120 @@
+/**
+ * Utility functions for LLM integration
+ */
+import chalk from 'chalk'
+import { z } from 'zod'
+
+import type { Tool } from './types'
+
+function debug(message: string) {
+	console.debug(chalk.gray('[LLM]'), message)
+}
+
+/**
+ * Convert Zod schema to OpenAI tool format
+ * Uses Zod 4 native z.toJSONSchema()
+ */
+export function zodToOpenAITool(name: string, tool: Tool) {
+	return {
+		type: 'function' as const,
+		function: {
+			name,
+			description: tool.description,
+			parameters: z.toJSONSchema(tool.inputSchema, { target: 'openapi-3.0' }),
+		},
+	}
+}
+
+/**
+ * Patch model specific parameters
+ */
+export function modelPatch(body: Record<string, any>) {
+	const model: string = body.model || ''
+	if (!model) return body
+
+	const modelName = normalizeModelName(model)
+
+	if (modelName.startsWith('qwen')) {
+		debug('Applying Qwen patch: use higher temperature for auto fixing')
+		body.temperature = Math.max(body.temperature || 0, 1.0)
+	}
+
+	if (modelName.startsWith('claude')) {
+		debug('Applying Claude patch: disable thinking')
+		body.thinking = { type: 'disabled' }
+
+		// Convert tool_choice to Claude format
+		if (body.tool_choice === 'required') {
+			// 'required' -> { type: 'any' } (must call some tool)
+			debug('Applying Claude patch: convert tool_choice "required" to { type: "any" }')
+			body.tool_choice = { type: 'any' }
+		} else if (body.tool_choice?.function?.name) {
+			// { type: 'function', function: { name: '...' } } -> { type: 'tool', name: '...' }
+			debug('Applying Claude patch: convert tool_choice format')
+			body.tool_choice = { type: 'tool', name: body.tool_choice.function.name }
+		}
+	}
+
+	if (modelName.startsWith('grok')) {
+		debug('Applying Grok patch: removing tool_choice')
+		delete body.tool_choice
+		debug('Applying Grok patch: disable reasoning and thinking')
+		body.thinking = { type: 'disabled', effort: 'minimal' }
+		body.reasoning = { enabled: false, effort: 'low' }
+	}
+
+	if (modelName.startsWith('gpt')) {
+		debug('Applying GPT patch: set verbosity to low')
+		body.verbosity = 'low'
+
+		if (modelName.startsWith('gpt-52')) {
+			debug('Applying GPT-52 patch: disable reasoning')
+			body.reasoning_effort = 'none'
+		} else if (modelName.startsWith('gpt-51')) {
+			debug('Applying GPT-51 patch: disable reasoning')
+			body.reasoning_effort = 'none'
+		} else if (modelName.startsWith('gpt-5')) {
+			debug('Applying GPT-5 patch: set reasoning effort to low')
+			body.reasoning_effort = 'low'
+		}
+	}
+
+	if (modelName.startsWith('gemini')) {
+		debug('Applying Gemini patch: set reasoning effort to minimal')
+		body.reasoning_effort = 'minimal'
+	}
+
+	return body
+}
+
+/**
+ * check if a given model ID fits a specific model name
+ *
+ * @note
+ * Different model providers may use different model IDs for the same model.
+ * For example, openai's `gpt-5.2` may called:
+ *
+ * - `gpt-5.2-version`
+ * - `gpt-5_2-date`
+ * - `GPT-52-version-date`
+ * - `openai/gpt-5.2-chat`
+ *
+ * They should be treated as the same model.
+ * Normalize them to `gpt-52`
+ */
+function normalizeModelName(modelName: string): string {
+	let normalizedName = modelName.toLowerCase()
+
+	// remove prefix before '/'
+	if (normalizedName.includes('/')) {
+		normalizedName = normalizedName.split('/')[1]
+	}
+
+	// remove '_'
+	normalizedName = normalizedName.replace(/_/g, '')
+
+	// remove '.'
+	normalizedName = normalizedName.replace(/\./g, '')
+
+	return normalizedName
+}

packages/llms/tsconfig.dts.json

@@ -0,0 +1,9 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        // @workaround DTS bug
+        // dts do not work with monorepo path mapping
+        // disable path mapping for it
+        "paths": {}
+    }
+}

packages/llms/tsconfig.json

@@ -0,0 +1,12 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
+        "noEmit": false,
+        "allowImportingTsExtensions": false,
+        "baseUrl": ".",
+        "outDir": "dist"
+    },
+    "include": ["**/*.ts"],
+    "exclude": ["dist", "node_modules"]
+}

packages/llms/vite.config.js

@@ -0,0 +1,36 @@
+// @ts-check
+import chalk from 'chalk'
+import { dirname, resolve } from 'path'
+import dts from 'unplugin-dts/vite'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+console.log(chalk.cyan(`📦 Building @page-agent/llms`))
+
+export default defineConfig({
+	clearScreen: false,
+	plugins: [dts({ tsconfigPath: './tsconfig.dts.json', bundleTypes: true })],
+	publicDir: false,
+	esbuild: {
+		keepNames: true,
+	},
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/index.ts'),
+			name: 'PageAgentLLMs',
+			fileName: 'page-agent-llms',
+			formats: ['es'],
+		},
+		outDir: resolve(__dirname, 'dist', 'lib'),
+		rollupOptions: {
+			external: ['chalk', 'zod'],
+		},
+		minify: false,
+		sourcemap: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})

packages/page-agent/package.json

@@ -1,59 +1,52 @@
 {
 	"name": "page-agent",
 	"private": false,
-	"version": "0.0.5",
+	"version": "0.2.5",
 	"type": "module",
-	"main": "./dist/lib/page-agent.js",
+	"main": "./dist/esm/page-agent.js",
-	"module": "./dist/lib/page-agent.js",
+	"module": "./dist/esm/page-agent.js",
-	"types": "./dist/lib/PageAgent.d.ts",
+	"types": "./dist/esm/PageAgent.d.ts",
 	"exports": {
 		".": {
-			"types": "./dist/lib/PageAgent.d.ts",
+			"types": "./dist/esm/PageAgent.d.ts",
-			"import": "./dist/lib/page-agent.js",
+			"import": "./dist/esm/page-agent.js",
-			"default": "./dist/lib/page-agent.js"
+			"default": "./dist/esm/page-agent.js"
 		}
 	},
 	"files": [
-		"dist/",
+		"dist/"
-		"README.md",
-		"README-zh.md",
-		"LICENSE"
 	],
-	"description": "AI-powered UI agent for web applications - add intelligent automation to any webpage with a single script tag",
+	"description": "GUI agent for web applications - add intelligent automation to any webpage with a single script",
 	"keywords": [
 		"ai",
 		"automation",
 		"ui-agent",
+		"GUI-agent",
 		"browser-automation",
 		"web-agent",
 		"llm",
 		"dom-interaction",
-		"intelligent-ui"
+		"web-automation",
+		"GUI-simulation"
 	],
 	"author": "Simon<gaomeng1900>",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/alibaba/page-agent.git",
+		"url": "https://github.com/alibaba/page-agent.git"
-		"directory": "packages/page-agent"
 	},
 	"homepage": "https://alibaba.github.io/page-agent/",
 	"scripts": {
-		"build": "MODE=lib vite build && MODE=umd vite build",
+		"build": "vite build",
-		"build:lib": "MODE=lib vite build",
+		"dev:iife": "concurrently \"vite build --config vite.iife.config.js --watch\" \"npx serve dist/iife -p 5174\"",
-		"build:umd": "MODE=umd vite build",
+		"prepublishOnly": "node -e \"const fs=require('fs');['README.md','LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
-		"build:watch": "MODE=lib vite build --watch",
+		"postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
-		"prepublishOnly": "node -e \"const fs=require('fs');['README.md','README-zh.md','LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
-		"postpublish": "node -e \"['README.md','README-zh.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
 	},
 	"dependencies": {
-		"ai-motion": "^0.4.7",
 		"chalk": "^5.6.2",
-		"zod": "^4.1.12"
+		"zod": "^4.3.5",
-	},
+		"@page-agent/llms": "0.2.5",
-	"devDependencies": {
+		"@page-agent/page-controller": "0.2.5",
-		"@microsoft/api-extractor": "^7.55.1",
+		"@page-agent/ui": "0.2.5"
-		"unplugin-dts": "^1.0.0-beta.6",
-		"vite-plugin-css-injected-by-js": "^3.5.2"
 	}
 }

packages/page-agent/src/PageAgent.ts

@@ -2,30 +2,28 @@
  * Copyright (C) 2025 Alibaba Group Holding Limited
  * All rights reserved.
  */
+import { LLM, type Tool } from '@page-agent/llms'
+import { PageController } from '@page-agent/page-controller'
+import { Panel } from '@page-agent/ui'
 import chalk from 'chalk'
 import zod from 'zod'
 
 import type { PageAgentConfig } from './config'
-import { MAX_STEPS, VIEWPORT_EXPANSION } from './config/constants'
+import { MAX_STEPS } from './config/constants'
-import * as dom from './dom'
-import { FlatDomTree, InteractiveElementDomNode } from './dom/dom_tree/type'
-import { getPageInfo } from './dom/getPageInfo'
-import { I18n } from './i18n'
-import { LLM, type Tool } from './llms'
-import { patchReact } from './patches/react'
 import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
 import { tools } from './tools'
-import { Panel, getToolCompletedText, getToolExecutingText } from './ui/Panel'
+import { normalizeResponse, trimLines, uid } from './utils'
-import { SimulatorMask } from './ui/SimulatorMask'
-import { trimLines, uid, waitUntil } from './utils'
 import { assert } from './utils/assert'
-import { getEventBus } from './utils/bus'
 
-export type { PageAgentConfig }
+/**
-export { tool, type PageAgentTool } from './tools'
+ * Agent reflection state - the reflection-before-action model
-
+ *
-export interface AgentBrain {
+ * Every tool call must first reflect on:
-	// thinking?: string
+ * - evaluation_previous_goal: How well did the previous action achieve its goal?
+ * - memory: Key information to remember for future steps
+ * - next_goal: What should be accomplished in the next action?
+ */
+export interface AgentReflection {
 	evaluation_previous_goal: string
 	memory: string
 	next_goal: string
@@ -33,11 +31,11 @@ export interface AgentBrain {
 
 /**
  * MacroTool input structure
+ *
+ * This is the core abstraction that enforces the "reflection-before-action" mental model.
+ * Before executing any action, the LLM must output its reasoning state.
  */
-export interface MacroToolInput {
+export interface MacroToolInput extends Partial<AgentReflection> {
-	evaluation_previous_goal?: string
-	memory?: string
-	next_goal?: string
 	action: Record<string, any>
 }
 
@@ -49,8 +47,15 @@ export interface MacroToolResult {
 	output: string
 }
 
-export interface AgentHistory {
+export type { PageAgentConfig }
-	brain: AgentBrain
+export { tool, type PageAgentTool } from './tools'
+
+/**
+ * A single agent step with reflection and action
+ */
+export interface AgentStep {
+	type: 'step'
+	reflection: Partial<AgentReflection>
 	action: {
 		name: string
 		input: any
@@ -65,56 +70,97 @@ export interface AgentHistory {
 	}
 }
 
+/**
+ * Persistent observation event (stays in memory)
+ */
+export interface ObservationEvent {
+	type: 'observation'
+	content: string
+}
+
+/**
+ * User takeover event
+ */
+export interface UserTakeoverEvent {
+	type: 'user_takeover'
+}
+
+/**
+ * Union type for all history events
+ */
+export type HistoryEvent = AgentStep | ObservationEvent | UserTakeoverEvent
+
 export interface ExecutionResult {
 	success: boolean
 	data: string
-	history: AgentHistory[]
+	history: HistoryEvent[]
 }
 
 export class PageAgent extends EventTarget {
 	config: PageAgentConfig
 	id = uid()
-	bus = getEventBus(this.id)
+	panel: Panel | null = null
-	i18n: I18n
-	panel: Panel
 	tools: typeof tools
-	paused = false
 	disposed = false
 	task = ''
 	taskId = ''
 
 	#llm: LLM
-	#totalWaitTime = 0
 	#abortController = new AbortController()
+	#llmRetryListener: ((e: Event) => void) | null = null
+	#llmErrorListener: ((e: Event) => void) | null = null
+	#beforeUnloadListener: ((e: Event) => void) | null = null
 
-	/** Corresponds to eval_page in browser-use */
+	/** PageController for DOM operations */
-	flatTree: FlatDomTree | null = null
+	pageController: PageController
-	/**
-	 * All highlighted index-mapped interactive elements
-	 * Corresponds to DOMState.selector_map in browser-use
-	 */
-	selectorMap = new Map<number, InteractiveElementDomNode>()
-	/** highlight index -> element text */
-	elementTextMap = new Map<number, string>()
-	/** Corresponds to clickable_elements_to_string in browser-use */
-	simplifiedHTML = '<EMPTY>'
-	/** last time the tree was updated */
-	lastTimeUpdate = 0
 
-	/** Fullscreen mask */
+	/** Runtime states for tracking across steps */
-	mask = new SimulatorMask()
+	states = {
-	/** History records */
+		/** Accumulated wait time in seconds, used by wait tool */
-	history: AgentHistory[] = []
+		totalWaitTime: 0,
+		/** Last known URL for detecting navigation */
+		lastURL: '',
+	}
 
-	constructor(config: PageAgentConfig = {}) {
+	/** History events */
+	history: HistoryEvent[] = []
+
+	constructor(config: PageAgentConfig) {
 		super()
 
 		this.config = config
-		this.#llm = new LLM(this.config, this.id)
+		this.#llm = new LLM(this.config)
-		this.i18n = new I18n(this.config.language)
+
-		this.panel = new Panel(this)
+		// Conditionally initialize Panel
+		if (this.config.enablePanel !== false) {
+			this.panel = new Panel({
+				language: this.config.language,
+				onExecuteTask: (task) => this.execute(task),
+				onStop: () => this.dispose(),
+				promptForNextTask: this.config.promptForNextTask,
+			})
+		}
+
 		this.tools = new Map(tools)
 
+		// Initialize PageController with config (mask enabled by default)
+		this.pageController = new PageController({
+			...this.config,
+			enableMask: this.config.enableMask ?? true,
+		})
+
+		// Listen to LLM events
+		this.#llmRetryListener = (e) => {
+			const { current, max } = (e as CustomEvent).detail
+			this.panel?.update({ type: 'retry', current, max })
+		}
+		this.#llmErrorListener = (e) => {
+			const { error } = (e as CustomEvent).detail
+			this.panel?.update({ type: 'error', message: `step failed: ${error.message}` })
+		}
+		this.#llm.addEventListener('retry', this.#llmRetryListener)
+		this.#llm.addEventListener('error', this.#llmErrorListener)
+
 		if (this.config.customTools) {
 			for (const [name, tool] of Object.entries(this.config.customTools)) {
 				if (tool === null) {
@@ -129,16 +175,26 @@ export class PageAgent extends EventTarget {
 			this.tools.delete('execute_javascript')
 		}
 
-		patchReact(this)
+		// Disable ask_user tool if enableAskUser is false or if panel is disabled
+		if (this.config.enableAskUser === false || this.config.enablePanel === false) {
+			this.tools.delete('ask_user')
+		}
 
-		window.addEventListener('beforeunload', (e) => {
+		this.#beforeUnloadListener = (e) => {
 			if (!this.disposed) this.dispose('PAGE_UNLOADING')
-		})
+		}
+		window.addEventListener('beforeunload', this.#beforeUnloadListener)
 	}
 
 	/**
-	 * @todo maybe return something?
+	 * Push a persistent observation to the history event stream.
+	 * This will be visible in <agent_history> and remain in memory across steps.
 	 */
+	pushObservation(content: string): void {
+		this.history.push({ type: 'observation', content })
+		this.panel?.update({ type: 'observation', content })
+	}
+
 	async execute(task: string): Promise<ExecutionResult> {
 		if (!task) throw new Error('Task is required')
 		this.task = task
@@ -152,15 +208,12 @@ export class PageAgent extends EventTarget {
 		await onBeforeTask.call(this)
 
 		// Show mask and panel
-		this.mask.show()
+		this.pageController.showMask()
 
-		this.bus.emit('panel:show')
+		this.panel?.show()
-		this.bus.emit('panel:reset')
+		this.panel?.reset()
 
-		this.bus.emit('panel:update', {
+		this.panel?.update({ type: 'input', task: this.task })
-			type: 'input',
-			displayText: this.task,
-		})
 
 		if (this.#abortController) {
 			this.#abortController.abort()
@@ -169,25 +222,28 @@ export class PageAgent extends EventTarget {
 
 		this.history = []
 
+		// Reset states
+		this.states = {
+			totalWaitTime: 0,
+			lastURL: '',
+		}
+
 		try {
 			let step = 0
 
 			while (true) {
+				await this.#generateObservations(step)
+
 				await onBeforeStep.call(this, step)
 
-				console.group(`step: ${step + 1}`)
+				console.group(`step: ${step}`)
 
 				// abort
 				if (this.#abortController.signal.aborted) throw new Error('AbortError')
-				// pause
-				await waitUntil(() => !this.paused)
 
 				// Update status to thinking
 				console.log(chalk.blue('Thinking...'))
-				this.bus.emit('panel:update', {
+				this.panel?.update({ type: 'thinking' })
-					type: 'thinking',
-					displayText: this.i18n.t('ui.panel.thinking'),
-				})
 
 				const result = await this.#llm.invoke(
 					[
@@ -197,33 +253,38 @@ export class PageAgent extends EventTarget {
 						},
 						{
 							role: 'user',
-							content: this.#assembleUserPrompt(),
+							content: await this.#assembleUserPrompt(),
 						},
 					],
 					{ AgentOutput: this.#packMacroTool() },
-					this.#abortController.signal
+					this.#abortController.signal,
+					{
+						toolChoiceName: 'AgentOutput',
+						normalizeResponse,
+					}
 				)
 
 				const macroResult = result.toolResult as MacroToolResult
 				const input = macroResult.input
 				const output = macroResult.output
-				const brain = {
+				const reflection: Partial<AgentReflection> = {
-					evaluation_previous_goal: input.evaluation_previous_goal || '',
+					evaluation_previous_goal: input.evaluation_previous_goal,
-					memory: input.memory || '',
+					memory: input.memory,
-					next_goal: input.next_goal || '',
+					next_goal: input.next_goal,
 				}
 				const actionName = Object.keys(input.action)[0]
-				const action = {
+				const action: AgentStep['action'] = {
 					name: actionName,
 					input: input.action[actionName],
 					output: output,
 				}
 
 				this.history.push({
-					brain,
+					type: 'step',
+					reflection,
 					action,
 					usage: result.usage,
-				})
+				} as AgentStep)
 
 				console.log(chalk.green('Step finished:'), actionName)
 				console.groupEnd()
@@ -281,9 +342,7 @@ export class PageAgent extends EventTarget {
 		const tools = this.tools
 
 		const actionSchemas = Array.from(tools.entries()).map(([toolName, tool]) => {
-			return zod.object({
+			return zod.object({ [toolName]: tool.inputSchema }).describe(tool.description)
-				[toolName]: tool.inputSchema,
-			})
 		})
 
 		const actionSchema = zod.union(
@@ -299,71 +358,60 @@ export class PageAgent extends EventTarget {
 		})
 
 		return {
+			description: 'You MUST call this tool every step. Outputs your reflections and next action.',
 			inputSchema: macroToolSchema as zod.ZodType<MacroToolInput>,
 			execute: async (input: MacroToolInput): Promise<MacroToolResult> => {
 				// abort
 				if (this.#abortController.signal.aborted) throw new Error('AbortError')
-				// pause
-				await waitUntil(() => !this.paused)
 
 				console.log(chalk.blue.bold('MacroTool execute'), input)
 				const action = input.action
 
 				const toolName = Object.keys(action)[0]
 				const toolInput = action[toolName]
-				const brain = trimLines(`✅: ${input.evaluation_previous_goal}
-						💾: ${input.memory}
-						🎯: ${input.next_goal}
-					`)
 
-				console.log(brain)
+				// Build reflection text, only include non-empty fields
-				this.bus.emit('panel:update', {
+				const reflectionLines: string[] = []
-					type: 'thinking',
+				if (input.evaluation_previous_goal)
-					displayText: brain,
+					reflectionLines.push(`✅: ${input.evaluation_previous_goal}`)
-				})
+				if (input.memory) reflectionLines.push(`💾: ${input.memory}`)
+				if (input.next_goal) reflectionLines.push(`🎯: ${input.next_goal}`)
+
+				const reflectionText = reflectionLines.length > 0 ? reflectionLines.join('\n') : ''
+
+				if (reflectionText) {
+					console.log(reflectionText)
+					this.panel?.update({ type: 'thinking', text: reflectionText })
+				}
 
 				// Find the corresponding tool
 				const tool = tools.get(toolName)
 				assert(tool, `Tool ${toolName} not found. (@note should have been caught before this!!!)`)
 
 				console.log(chalk.blue.bold(`Executing tool: ${toolName}`), toolInput)
-				this.bus.emit('panel:update', {
+				this.panel?.update({ type: 'toolExecuting', toolName, args: toolInput })
-					type: 'tool_executing',
-					toolName,
-					toolArgs: toolInput,
-					displayText: getToolExecutingText(toolName, toolInput, this.i18n),
-				})
 
 				const startTime = Date.now()
 
 				// Execute tool, bind `this` to PageAgent
-				let result = await tool.execute.bind(this)(toolInput)
+				const result = await tool.execute.bind(this)(toolInput)
 
 				const duration = Date.now() - startTime
 				console.log(chalk.green.bold(`Tool (${toolName}) executed for ${duration}ms`), result)
 
-				if (toolName === 'wait') {
+				// Reset wait time for non-wait tools
-					this.#totalWaitTime += Math.round(toolInput.seconds + duration / 1000)
+				if (toolName !== 'wait') {
-					result += `\n<sys> You have waited ${this.#totalWaitTime} seconds accumulatively.`
+					this.states.totalWaitTime = 0
-					if (this.#totalWaitTime >= 3)
-						result += '\nDo NOT wait any longer unless you have a good reason.\n'
-					result += '</sys>'
-				} else {
-					// For other tools, reset wait time
-					this.#totalWaitTime = 0
 				}
 
 				// Briefly display execution result
-				const displayResult = getToolCompletedText(toolName, toolInput, this.i18n)
+				this.panel?.update({
-				if (displayResult)
+					type: 'toolCompleted',
-					this.bus.emit('panel:update', {
+					toolName,
-						type: 'tool_executing',
+					args: toolInput,
-						toolName,
+					result,
-						toolArgs: toolInput,
+					duration,
-						toolResult: result,
+				})
-						displayText: displayResult,
-						duration,
-					})
 
 				// Wait a moment to let user see the result
 				await new Promise((resolve) => setTimeout(resolve, 100))
@@ -392,146 +440,190 @@ export class PageAgent extends EventTarget {
 		return systemPrompt
 	}
 
-	#assembleUserPrompt(): string {
+	/**
+	 * Get instructions from config and format as XML block
+	 */
+	async #getInstructions(): Promise<string> {
+		const { instructions } = this.config
+		if (!instructions) return ''
+
+		const systemInstructions = instructions.system?.trim()
+		const url = await this.pageController.getCurrentUrl()
+		let pageInstructions: string | undefined
+
+		if (instructions.getPageInstructions) {
+			try {
+				pageInstructions = instructions.getPageInstructions(url)?.trim()
+			} catch (error) {
+				console.error(
+					chalk.red('[PageAgent] Failed to execute getPageInstructions callback:'),
+					error
+				)
+			}
+		}
+		if (!systemInstructions && !pageInstructions) return ''
+
+		let result = '<instructions>\n'
+
+		if (systemInstructions) {
+			result += `<system_instructions>\n${systemInstructions}\n</system_instructions>\n`
+		}
+
+		if (pageInstructions) {
+			result += `<page_instructions>\n${pageInstructions}\n</page_instructions>\n`
+		}
+
+		result += '</instructions>\n\n'
+
+		return result
+	}
+
+	/**
+	 * Generate observations before each step
+	 * - URL change detection
+	 * - Too many steps warning
+	 * @todo loop detection
+	 * @todo console error
+	 */
+	async #generateObservations(stepCount: number): Promise<void> {
+		// Detect URL change
+		const currentURL = await this.pageController.getCurrentUrl()
+		if (currentURL !== this.states.lastURL) {
+			this.pushObservation(`Page navigated to → ${currentURL}`)
+			this.states.lastURL = currentURL
+		}
+
+		// Warn about remaining steps
+		const remaining = MAX_STEPS - stepCount
+		if (remaining === 5) {
+			this.pushObservation(
+				`⚠️ Only ${remaining} steps remaining. Consider wrapping up or calling done with partial results.`
+			)
+		} else if (remaining === 2) {
+			this.pushObservation(
+				`⚠️ Critical: Only ${remaining} steps left! You must finish the task or call done immediately.`
+			)
+		}
+	}
+
+	async #assembleUserPrompt(): Promise<string> {
 		let prompt = ''
 
-		// <agent_history>
+		// <instructions> (optional)
-		//  - <step_>
+		prompt += await this.#getInstructions()
-
-		prompt += '<agent_history>\n'
-
-		this.history.forEach((history, index) => {
-			prompt += `<step_${index + 1}>
-				Evaluation of Previous Step: ${history.brain.evaluation_previous_goal}
-				Memory: ${history.brain.memory}
-				Next Goal: ${history.brain.next_goal}
-				Action Results: ${history.action.output}
-				</step_${index + 1}>
-			`
-		})
-
-		prompt += '</agent_history>\n\n'
 
 		// <agent_state>
 		//  - <user_request>
 		//  - <step_info>
 		// <agent_state>
 
+		const stepCount = this.history.filter((e) => e.type === 'step').length
+
 		prompt += `<agent_state>
 			<user_request>
 			${this.task}
 			</user_request>
 			<step_info>
-			Step ${this.history.length + 1} of ${MAX_STEPS} max possible steps
+			Step ${stepCount + 1} of ${MAX_STEPS} max possible steps
 			Current date and time: ${new Date().toISOString()}
 			</step_info>
 			</agent_state>
 		`
 
+		// <agent_history>
+		//  - <step_N> for steps
+		//  - <sys> for observations and system messages
+
+		prompt += '\n<agent_history>\n'
+
+		let stepIndex = 0
+		for (const event of this.history) {
+			if (event.type === 'step') {
+				stepIndex++
+				prompt += `<step_${stepIndex}>
+				Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}
+				Memory: ${event.reflection.memory}
+				Next Goal: ${event.reflection.next_goal}
+				Action Results: ${event.action.output}
+				</step_${stepIndex}>
+			`
+			} else if (event.type === 'observation') {
+				prompt += `<sys>${event.content}</sys>\n`
+			} else if (event.type === 'user_takeover') {
+				prompt += `<sys>User took over control and made changes to the page.</sys>\n`
+			}
+		}
+
+		prompt += '</agent_history>\n\n'
+
 		// <browser_state>
 
-		prompt += this.#getBrowserState()
+		prompt += await this.#getBrowserState()
 
 		return trimLines(prompt)
 	}
 
 	#onDone(text: string, success = true) {
-		dom.cleanUpHighlights()
+		this.pageController.cleanUpHighlights()
 
 		// Update panel status
-		this.bus.emit('panel:update', {
+		if (success) {
-			type: success ? 'output' : 'error',
+			this.panel?.update({ type: 'output', text })
-			displayText: text,
+		} else {
-		})
+			this.panel?.update({ type: 'error', message: text })
+		}
 
 		// Task completed
-		this.bus.emit('panel:update', {
+		this.panel?.update({ type: 'completed' })
-			type: 'completed',
-			displayText: this.i18n.t('ui.panel.taskCompleted'),
-		})
 
-		this.mask.hide()
+		this.pageController.hideMask()
 
 		this.#abortController.abort()
 	}
 
-	#getBrowserState(): string {
+	async #getBrowserState(): Promise<string> {
-		const pageUrl = window.location.href
+		const state = await this.pageController.getBrowserState()
-		const pageTitle = document.title
-		const pi = getPageInfo()
 
-		this.#updateTree()
+		let content = state.content
+		if (this.config.transformPageContent) {
+			content = await this.config.transformPageContent(content)
+		}
 
-		let prompt = trimLines(`<browser_state>
+		return trimLines(`<browser_state>
-			Current Page: [${pageTitle}](${pageUrl})
+			Current Page: [${state.title}](${state.url})
 
-			Page info: ${pi.viewport_width}x${pi.viewport_height}px viewport, ${pi.page_width}x${pi.page_height}px total page size, ${pi.pages_above.toFixed(1)} pages above, ${pi.pages_below.toFixed(1)} pages below, ${pi.total_pages.toFixed(1)} total pages, at ${(pi.current_page_position * 100).toFixed(0)}% of page
+			${state.header}
-
+			${content}
-			${VIEWPORT_EXPANSION === -1 ? 'Interactive elements from top layer of the current page (full page):' : 'Interactive elements from top layer of the current page inside the viewport:'}
+			${state.footer}
 
+			</browser_state>
 		`)
-
-		// Page header info
-		const has_content_above = pi.pixels_above > 4
-		if (has_content_above && VIEWPORT_EXPANSION !== -1) {
-			prompt += `... ${pi.pixels_above} pixels above (${pi.pages_above.toFixed(1)} pages) - scroll to see more ...\n`
-		} else {
-			prompt += `[Start of page]\n`
-		}
-
-		// Current viewport info
-		prompt += this.simplifiedHTML
-		prompt += `\n`
-
-		// Page footer info
-		const has_content_below = pi.pixels_below > 4
-		if (has_content_below && VIEWPORT_EXPANSION !== -1) {
-			prompt += `... ${pi.pixels_below} pixels below (${pi.pages_below.toFixed(1)} pages) - scroll to see more ...\n`
-		} else {
-			prompt += `[End of page]\n`
-		}
-
-		prompt += `</browser_state>\n`
-
-		return prompt
-	}
-
-	/**
-	 * Update document tree
-	 */
-	#updateTree() {
-		this.dispatchEvent(new Event('beforeUpdate'))
-		this.lastTimeUpdate = Date.now()
-		dom.cleanUpHighlights()
-		this.mask.wrapper.style.pointerEvents = 'none'
-		this.flatTree = dom.getFlatTree({
-			...this.config,
-			interactiveBlacklist: [
-				...(this.config.interactiveBlacklist || []),
-				...document.querySelectorAll('[data-page-agent-not-interactive]').values(),
-			],
-		})
-		this.mask.wrapper.style.pointerEvents = 'auto'
-		this.simplifiedHTML = dom.flatTreeToString(this.flatTree, this.config.include_attributes)
-		this.selectorMap.clear()
-		this.selectorMap = dom.getSelectorMap(this.flatTree)
-		this.elementTextMap.clear()
-		this.elementTextMap = dom.getElementTextMap(this.simplifiedHTML)
-		this.dispatchEvent(new Event('afterUpdate'))
 	}
 
 	dispose(reason?: string) {
 		console.log('Disposing PageAgent...')
 		this.disposed = true
-		dom.cleanUpHighlights()
+		this.pageController.dispose()
-		this.flatTree = null
+		this.panel?.dispose()
-		this.selectorMap.clear()
-		this.elementTextMap.clear()
-		this.panel.dispose()
-		this.mask.dispose()
 		this.history = []
 		this.#abortController.abort(reason ?? 'PageAgent disposed')
 
+		// Clean up LLM event listeners
+		if (this.#llmRetryListener) {
+			this.#llm.removeEventListener('retry', this.#llmRetryListener)
+			this.#llmRetryListener = null
+		}
+		if (this.#llmErrorListener) {
+			this.#llm.removeEventListener('error', this.#llmErrorListener)
+			this.#llmErrorListener = null
+		}
+
+		// Clean up window event listeners
+		if (this.#beforeUnloadListener) {
+			window.removeEventListener('beforeunload', this.#beforeUnloadListener)
+			this.#beforeUnloadListener = null
+		}
+
 		this.config.onDispose?.call(this, reason)
 	}
 }

packages/page-agent/src/config/constants.ts

@@ -1,29 +1,2 @@
-/**
+// Agent-specific constants (LLM constants moved to @page-agent/llms)
- * @note Since isTopElement depends on elementFromPoint,
- * it returns null when out of viewport, this feature has no practical use, only differ between -1 and 0
- */
-// export const VIEWPORT_EXPANSION = 100
-export const VIEWPORT_EXPANSION = -1
-
-// Dev environment: use .env config if available, otherwise fallback to testing api
-export const DEFAULT_MODEL_NAME: string =
-	import.meta.env.DEV && import.meta.env.LLM_MODEL_NAME
-		? import.meta.env.LLM_MODEL_NAME
-		: 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
-export const DEFAULT_API_KEY: string =
-	import.meta.env.DEV && import.meta.env.LLM_API_KEY
-		? import.meta.env.LLM_API_KEY
-		: 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
-export const DEFAULT_BASE_URL: string =
-	import.meta.env.DEV && import.meta.env.LLM_BASE_URL
-		? import.meta.env.LLM_BASE_URL
-		: 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-
-// internal
-
-export const LLM_MAX_RETRIES = 2
 export const MAX_STEPS = 20
-export const DEFAULT_TEMPERATURE = 0.7 // higher randomness helps auto-recovery
-export const DEFAULT_MAX_TOKENS = 4096

packages/page-agent/src/config/index.ts

@@ -1,29 +1,37 @@
-import type { AgentHistory, ExecutionResult, PageAgent } from '../PageAgent'
+import type { LLMConfig } from '@page-agent/llms'
-import type { DomConfig } from '../dom'
+import type { PageControllerConfig } from '@page-agent/page-controller'
-import type { SupportedLanguage } from '../i18n'
+import type { SupportedLanguage } from '@page-agent/ui'
-import type { PageAgentTool } from '../tools'
-import {
-	DEFAULT_API_KEY,
-	DEFAULT_BASE_URL,
-	DEFAULT_MAX_TOKENS,
-	DEFAULT_MODEL_NAME,
-	DEFAULT_TEMPERATURE,
-	LLM_MAX_RETRIES,
-} from './constants'
 
-export interface LLMConfig {
+import type { ExecutionResult, HistoryEvent, PageAgent } from '../PageAgent'
-	baseURL?: string
+import type { PageAgentTool } from '../tools'
-	apiKey?: string
+
-	model?: string
+export type { LLMConfig }
-	temperature?: number
-	maxTokens?: number
-	maxRetries?: number
-}
 
 export interface AgentConfig {
 	// theme?: 'light' | 'dark'
 	language?: SupportedLanguage
 
+	/**
+	 * Whether to prompt for next task after task completion
+	 * @default true
+	 */
+	promptForNextTask?: boolean
+
+	/**
+	 * Enable the UI panel for visual feedback and user interaction
+	 * When disabled, the panel will not be created and all UI operations will be skipped.
+	 * Useful for automated testing or when integrating PageAgent as a library.
+	 * @default true
+	 */
+	enablePanel?: boolean
+
+	/**
+	 * Enable the ask_user tool for agent to ask questions
+	 * When disabled, the agent cannot ask user questions during execution.
+	 * @default true
+	 */
+	enableAskUser?: boolean
+
 	/**
 	 * Custom tools to extend PageAgent capabilities
 	 * @experimental
@@ -55,17 +63,37 @@ export interface AgentConfig {
 	 */
 	customTools?: Record<string, PageAgentTool | null>
 
+	/**
+	 * Instructions to guide the agent's behavior
+	 */
+	instructions?: {
+		/**
+		 * Global system-level instructions, applied to all tasks
+		 */
+		system?: string
+
+		/**
+		 * Dynamic page-level instructions callback
+		 * Called before each step to get instructions for the current page
+		 * @param url - Current page URL (window.location.href)
+		 * @returns Instructions string, or undefined/null to skip
+		 */
+		getPageInstructions?: (url: string) => string | undefined | null
+	}
+
 	// lifecycle hooks
 	// @todo: use event instead of hooks
+	// @todo: remove `this` binding, pass agent as explicit parameter instead
 
 	onBeforeStep?: (this: PageAgent, stepCnt: number) => Promise<void> | void
-	onAfterStep?: (this: PageAgent, stepCnt: number, history: AgentHistory[]) => Promise<void> | void
+	onAfterStep?: (this: PageAgent, stepCnt: number, history: HistoryEvent[]) => Promise<void> | void
 	onBeforeTask?: (this: PageAgent) => Promise<void> | void
 	onAfterTask?: (this: PageAgent, result: ExecutionResult) => Promise<void> | void
 
 	/**
 	 * @note this hook can block the disposal process
 	 * @note when dispose caused by page unload, reason will be 'PAGE_UNLOADING'. this method CANNOT block unloading. async operations may be cut.
+	 * @todo remove `this` binding, pass agent as explicit parameter instead
 	 */
 	onDispose?: (this: PageAgent, reason?: string) => void
 
@@ -79,30 +107,36 @@ export interface AgentConfig {
 	 */
 	experimentalScriptExecutionTool?: boolean
 
+	/**
+	 * Transform page content before sending to LLM.
+	 * Called after DOM extraction and simplification, before LLM invocation.
+	 * Use cases: inspect extraction results, modify page info, mask sensitive data.
+	 *
+	 * @param content - Simplified page content that will be sent to LLM
+	 * @returns Transformed content
+	 *
+	 * @example
+	 * // Mask phone numbers
+	 * transformPageContent: async (content) => {
+	 *   return content.replace(/1[3-9]\d{9}/g, '***********')
+	 * }
+	 */
+	transformPageContent?: (content: string) => Promise<string> | string
+
 	/**
 	 * TODO: @unimplemented
 	 * hook when action causes a new page to be opened
 	 * @note PageAgent will try to detect new pages and decide if it's caused by an action. But not very reliable.
+	 * @todo remove `this` binding, pass agent as explicit parameter instead
 	 */
-	onNewPageOpen?: (this: PageAgent, url: string) => Promise<void> | void
+	// onNewPageOpen?: (this: PageAgent, url: string) => Promise<void> | void
 
 	/**
 	 * TODO: @unimplemented
 	 * try to navigate to a new page instead of opening a new tab/window.
 	 * @note will unload the current page when a action tries to open a new page. so that things keep in the same tab/window.
 	 */
-	experimentalPreventNewPage?: boolean
+	// experimentalPreventNewPage?: boolean
 }
 
-export type PageAgentConfig = LLMConfig & AgentConfig & DomConfig
+export type PageAgentConfig = LLMConfig & AgentConfig & PageControllerConfig
-
-export function parseLLMConfig(config: LLMConfig): Required<LLMConfig> {
-	return {
-		baseURL: config.baseURL ?? DEFAULT_BASE_URL,
-		apiKey: config.apiKey ?? DEFAULT_API_KEY,
-		model: config.model ?? DEFAULT_MODEL_NAME,
-		temperature: config.temperature ?? DEFAULT_TEMPERATURE,
-		maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS,
-		maxRetries: config.maxRetries ?? LLM_MAX_RETRIES,
-	}
-}

packages/page-agent/src/entry.ts

@@ -1,40 +0,0 @@
-/**
- * Auto-run entry for page-agent.js. Insert this script into your page to get page-agent functionality.
- */
-import { PageAgent, type PageAgentConfig } from './PageAgent'
-
-// Clean up existing instances to prevent multiple injections from bookmarklet
-if (window.pageAgent) {
-	window.pageAgent.dispose()
-}
-
-// Mount to global window object
-window.PageAgent = PageAgent
-
-// Export for ES module usage
-// export { PageAgent }
-
-console.log('🚀 page-agent.js loaded!')
-
-const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
-const currentScript = document.currentScript as HTMLScriptElement | null
-if (currentScript) {
-	console.log('🚀 page-agent.js detected current script:', currentScript.src)
-	const url = new URL(currentScript.src)
-	const model = url.searchParams.get('model') || DEMO_MODEL
-	const baseURL = url.searchParams.get('baseURL') || DEMO_BASE_URL
-	const apiKey = url.searchParams.get('apiKey') || DEMO_API_KEY
-	const language = (url.searchParams.get('lang') as 'zh-CN' | 'en-US') || 'zh-CN'
-	const config: PageAgentConfig = { model, baseURL, apiKey, language }
-	window.pageAgent = new PageAgent(config)
-} else {
-	console.log('🚀 page-agent.js no current script detected, using default demo config')
-	window.pageAgent = new PageAgent()
-}
-
-console.log('🚀 page-agent.js initialized with config:', window.pageAgent.config)
-
-window.pageAgent.bus.emit('panel:show') // Show panel

packages/page-agent/src/env.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="vite/client" />
-import type { PageAgent } from './src/PageAgent'
+import type { PageAgent } from './PageAgent'
 
 declare module '*.module.css' {
 	const classes: Record<string, string>

packages/page-agent/src/iife.ts

@@ -0,0 +1,53 @@
+/**
+ * Auto-run entry for page-agent.js. Insert this script into your page to get page-agent functionality.
+ */
+import { PageAgent, type PageAgentConfig } from './PageAgent'
+
+// Clean up existing instances to prevent multiple injections from bookmarklet
+if (window.pageAgent) {
+	window.pageAgent.dispose()
+}
+
+// Mount to global window object
+window.PageAgent = PageAgent
+
+// Export for ES module usage
+// export { PageAgent }
+
+console.log('🚀 page-agent.js loaded!')
+
+const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
+const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+
+// in case document.x is not ready yet
+// @todo give a switch to disable auto-init
+setTimeout(() => {
+	const currentScript = document.currentScript as HTMLScriptElement | null
+	if (currentScript) {
+		console.log('🚀 page-agent.js detected current script:', currentScript.src)
+		const url = new URL(currentScript.src)
+		const model = url.searchParams.get('model') || DEMO_MODEL
+		const baseURL = url.searchParams.get('baseURL') || DEMO_BASE_URL
+		const apiKey = url.searchParams.get('apiKey') || DEMO_API_KEY
+		const language = (url.searchParams.get('lang') as 'zh-CN' | 'en-US') || 'zh-CN'
+		const config: PageAgentConfig = { model, baseURL, apiKey, language }
+		window.pageAgent = new PageAgent(config)
+	} else {
+		console.log('🚀 page-agent.js no current script detected, using default demo config')
+		const config: PageAgentConfig = {
+			// model: DEMO_MODEL,
+			// baseURL: DEMO_BASE_URL,
+			// apiKey: DEMO_API_KEY,
+
+			model: import.meta.env.LLM_MODEL_NAME ? import.meta.env.LLM_MODEL_NAME : DEMO_MODEL,
+			baseURL: import.meta.env.LLM_BASE_URL ? import.meta.env.LLM_BASE_URL : DEMO_BASE_URL,
+			apiKey: import.meta.env.LLM_API_KEY ? import.meta.env.LLM_API_KEY : DEMO_API_KEY,
+		}
+		window.pageAgent = new PageAgent(config)
+	}
+
+	console.log('🚀 page-agent.js initialized with config:', window.pageAgent.config)
+
+	window.pageAgent.panel.show() // Show panel
+})

packages/page-agent/src/llms/OpenAIClient.ts

@@ -1,188 +0,0 @@
-/**
- * OpenAI Client implementation
- */
-import { InvokeError, InvokeErrorType } from './errors'
-import type { InvokeResult, LLMClient, Message, OpenAIClientConfig, Tool } from './types'
-import { modelPatch, zodToOpenAITool } from './utils'
-
-export class OpenAIClient implements LLMClient {
-	config: OpenAIClientConfig
-
-	constructor(config: OpenAIClientConfig) {
-		this.config = config
-	}
-
-	async invoke(
-		messages: Message[],
-		tools: Record<string, Tool>,
-		abortSignal?: AbortSignal
-	): Promise<InvokeResult> {
-		// 1. Convert tools to OpenAI format
-		const openaiTools = Object.entries(tools).map(([name, tool]) => zodToOpenAITool(name, tool))
-
-		// 2. Call API
-		let response: Response
-		try {
-			response = await fetch(`${this.config.baseURL}/chat/completions`, {
-				method: 'POST',
-				headers: {
-					'Content-Type': 'application/json',
-					Authorization: `Bearer ${this.config.apiKey}`,
-				},
-				body: JSON.stringify(
-					modelPatch({
-						model: this.config.model,
-						temperature: this.config.temperature,
-						max_tokens: this.config.maxTokens,
-						messages,
-
-						tools: openaiTools,
-						// tool_choice: 'required',
-						tool_choice: { type: 'function', function: { name: 'AgentOutput' } },
-
-						// model specific params
-
-						// reasoning_effort: 'minimal',
-						// verbosity: 'low',
-						parallel_tool_calls: false,
-					})
-				),
-				signal: abortSignal,
-			})
-		} catch (error: unknown) {
-			// Network error
-			throw new InvokeError(InvokeErrorType.NETWORK_ERROR, 'Network request failed', error)
-		}
-
-		// 3. Handle HTTP errors
-		if (!response.ok) {
-			const errorData = await response.json().catch()
-			const errorMessage =
-				(errorData as { error?: { message?: string } }).error?.message || response.statusText
-
-			if (response.status === 401 || response.status === 403) {
-				throw new InvokeError(
-					InvokeErrorType.AUTH_ERROR,
-					`Authentication failed: ${errorMessage}`,
-					errorData
-				)
-			}
-			if (response.status === 429) {
-				throw new InvokeError(
-					InvokeErrorType.RATE_LIMIT,
-					`Rate limit exceeded: ${errorMessage}`,
-					errorData
-				)
-			}
-			if (response.status >= 500) {
-				throw new InvokeError(
-					InvokeErrorType.SERVER_ERROR,
-					`Server error: ${errorMessage}`,
-					errorData
-				)
-			}
-			throw new InvokeError(
-				InvokeErrorType.UNKNOWN,
-				`HTTP ${response.status}: ${errorMessage}`,
-				errorData
-			)
-		}
-
-		const data = await response.json()
-
-		// 4. Check finish_reason
-		const choice = data.choices?.[0]
-		if (!choice) {
-			throw new InvokeError(InvokeErrorType.UNKNOWN, 'No choices in response', data)
-		}
-
-		switch (choice.finish_reason) {
-			case 'tool_calls':
-				// ✅ Normal
-				break
-			case 'length':
-				// ⚠️ Token limit reached
-				throw new InvokeError(
-					InvokeErrorType.CONTEXT_LENGTH,
-					'Response truncated: max tokens reached',
-					data
-				)
-			case 'content_filter':
-				// ❌ Content filtered
-				throw new InvokeError(
-					InvokeErrorType.CONTENT_FILTER,
-					'Content filtered by safety system',
-					data
-				)
-			case 'stop':
-				// ❌ Did not call tool (we require tool call)
-				throw new InvokeError(InvokeErrorType.NO_TOOL_CALL, 'Model did not call any tool', data)
-			default:
-				throw new InvokeError(
-					InvokeErrorType.UNKNOWN,
-					`Unexpected finish_reason: ${choice.finish_reason}`,
-					data
-				)
-		}
-
-		// 5. Parse tool call
-		const toolCall = choice.message?.tool_calls?.[0]
-		if (!toolCall) {
-			throw new InvokeError(InvokeErrorType.NO_TOOL_CALL, 'No tool call found in response', data)
-		}
-
-		const toolName = toolCall.function.name
-		const tool = tools[toolName]
-		if (!tool) {
-			throw new InvokeError(InvokeErrorType.UNKNOWN, `Tool ${toolName} not found`, data)
-		}
-
-		// 6. Parse and validate arguments
-		let toolArgs: unknown
-		try {
-			toolArgs = JSON.parse(toolCall.function.arguments)
-		} catch (e) {
-			throw new InvokeError(InvokeErrorType.INVALID_TOOL_ARGS, 'Invalid JSON in tool arguments', e)
-		}
-
-		// Validate against zod schema
-		const validation = tool.inputSchema.safeParse(toolArgs)
-		if (!validation.success) {
-			throw new InvokeError(
-				InvokeErrorType.INVALID_TOOL_ARGS,
-				`Tool arguments validation failed: ${validation.error.message}`,
-				validation.error
-			)
-		}
-
-		// 7. Execute tool
-		let toolResult: unknown
-		try {
-			toolResult = await tool.execute(validation.data)
-		} catch (e) {
-			throw new InvokeError(
-				InvokeErrorType.TOOL_EXECUTION_ERROR,
-				`Tool execution failed: ${(e as Error).message}`,
-				e
-			)
-		}
-
-		// 8. Return result (including cache tokens)
-		return {
-			toolCall: {
-				// id: toolCall.id,
-				name: toolName,
-				args: validation.data as Record<string, unknown>,
-			},
-			toolResult,
-			usage: {
-				promptTokens: data.usage?.prompt_tokens ?? 0,
-				completionTokens: data.usage?.completion_tokens ?? 0,
-				totalTokens: data.usage?.total_tokens ?? 0,
-				cachedTokens: data.usage?.prompt_tokens_details?.cached_tokens,
-				reasoningTokens: data.usage?.completion_tokens_details?.reasoning_tokens,
-			},
-			rawResponse: data,
-		}
-	}
-}

packages/page-agent/src/llms/OpenAILenientClient.ts

@@ -1,128 +0,0 @@
-/**
- * OpenAI Client implementation
- */
-import type { MacroToolInput } from '../PageAgent'
-import { InvokeError, InvokeErrorType } from './errors'
-import type { InvokeResult, LLMClient, Message, OpenAIClientConfig, Tool } from './types'
-import { lenientParseMacroToolCall, modelPatch, zodToOpenAITool } from './utils'
-
-export class OpenAIClient implements LLMClient {
-	config: OpenAIClientConfig
-
-	constructor(config: OpenAIClientConfig) {
-		this.config = config
-	}
-
-	async invoke(
-		messages: Message[],
-		tools: { AgentOutput: Tool<MacroToolInput> },
-		abortSignal?: AbortSignal
-	): Promise<InvokeResult> {
-		// 1. Convert tools to OpenAI format
-		const openaiTools = Object.entries(tools).map(([name, tool]) => zodToOpenAITool(name, tool))
-
-		// 2. Call API
-		let response: Response
-		try {
-			response = await fetch(`${this.config.baseURL}/chat/completions`, {
-				method: 'POST',
-				headers: {
-					'Content-Type': 'application/json',
-					Authorization: `Bearer ${this.config.apiKey}`,
-				},
-				body: JSON.stringify(
-					modelPatch({
-						model: this.config.model,
-						temperature: this.config.temperature,
-						max_tokens: this.config.maxTokens,
-						messages,
-
-						tools: openaiTools,
-						// tool_choice: 'required',
-						tool_choice: { type: 'function', function: { name: 'AgentOutput' } },
-
-						// model specific params
-
-						// reasoning_effort: 'minimal',
-						// verbosity: 'low',
-						parallel_tool_calls: false,
-					})
-				),
-				signal: abortSignal,
-			})
-		} catch (error: unknown) {
-			// Network error
-			throw new InvokeError(InvokeErrorType.NETWORK_ERROR, 'Network request failed', error)
-		}
-
-		// 3. Handle HTTP errors
-		if (!response.ok) {
-			const errorData = await response.json().catch()
-			const errorMessage =
-				(errorData as { error?: { message?: string } }).error?.message || response.statusText
-
-			if (response.status === 401 || response.status === 403) {
-				throw new InvokeError(
-					InvokeErrorType.AUTH_ERROR,
-					`Authentication failed: ${errorMessage}`,
-					errorData
-				)
-			}
-			if (response.status === 429) {
-				throw new InvokeError(
-					InvokeErrorType.RATE_LIMIT,
-					`Rate limit exceeded: ${errorMessage}`,
-					errorData
-				)
-			}
-			if (response.status >= 500) {
-				throw new InvokeError(
-					InvokeErrorType.SERVER_ERROR,
-					`Server error: ${errorMessage}`,
-					errorData
-				)
-			}
-			throw new InvokeError(
-				InvokeErrorType.UNKNOWN,
-				`HTTP ${response.status}: ${errorMessage}`,
-				errorData
-			)
-		}
-
-		// parse response
-
-		const data = await response.json()
-		const tool = tools.AgentOutput
-		const macroToolInput = lenientParseMacroToolCall(data, tool.inputSchema as any)
-
-		// Execute tool
-		let toolResult: unknown
-		try {
-			toolResult = await tool.execute(macroToolInput)
-		} catch (e) {
-			throw new InvokeError(
-				InvokeErrorType.TOOL_EXECUTION_ERROR,
-				`Tool execution failed: ${(e as Error).message}`,
-				e
-			)
-		}
-
-		// Return result (including cache tokens)
-		return {
-			toolCall: {
-				// id: toolCall.id,
-				name: 'AgentOutput',
-				args: macroToolInput,
-			},
-			toolResult,
-			usage: {
-				promptTokens: data.usage?.prompt_tokens ?? 0,
-				completionTokens: data.usage?.completion_tokens ?? 0,
-				totalTokens: data.usage?.total_tokens ?? 0,
-				cachedTokens: data.usage?.prompt_tokens_details?.cached_tokens,
-				reasoningTokens: data.usage?.completion_tokens_details?.reasoning_tokens,
-			},
-			rawResponse: data,
-		}
-	}
-}

packages/page-agent/src/llms/index.ts

@@ -1,137 +0,0 @@
-/**
- * @topic LLM 与主流程的隔离
- * @reasoning
- * 将 llm 的调用和主流程分开是复杂的，
- * 因为 agent 的 tool call 通常集成在 llm 模块中，而而先得到 llm 返回，然后处理工具调用
- * tools 和 llm 调用的逻辑不可避免地耦合在一起，tool 的执行又和主流程耦合在一起
- * 而 history 的维护和更新逻辑，又必须嵌入多轮 tool call 中
- * @reasoning
- * - 放弃框架提供的自动的多轮调用，每轮调用都由主流程发起
- * - 理想情况下，llm 调用应该获得 structured output，然后由额外的模块触发 tool call，目前模型和框架都无法实现
- * - 当前只能将 llm api 和 本地 tool call 耦合在一起，不关心其中的衔接方式
- * @conclusion
- * - @llm responsibility boundary:
- *   - call llm api with given messages and tools
- *   - invoke tool call and get the result of the tool
- *   - return the result to main loop
- * - @main_loop responsibility boundary:
- *   - maintain all behaviors of an **agent**
- * @conclusion
- * - 这里的 llm 模块不是 agent，只负责一轮 llm 调用和工具调用，无状态
- */
-/**
- * @topic 结构化输出
- * @facts
- * - 几乎所有模型都支持 tool call schema
- * - 几乎所有模型都支持返回 json
- *   - 只有 openAI/grok/gemini 支持 schema 并保证格式
- * - 主流模型都支持 tool_choice: required
- *   - 除了 qwen 必须指定一个函数名 (9月上新后支持)
- * @conclusion
- * - 永远使用 tool call 来返回结构化数据，禁止模型直接返回（视为出错）
- * - 不能假设 tool 参数合法，必须有修复机制，而且修复也应该使用 tool call 返回
- */
-import type { LLMConfig } from '../config'
-import { parseLLMConfig } from '../config'
-import { EventBus, getEventBus } from '../utils/bus'
-import { OpenAIClient } from './OpenAILenientClient'
-import { InvokeError } from './errors'
-import type { InvokeResult, LLMClient, Message, Tool } from './types'
-
-export type { Message, Tool, InvokeResult, LLMClient }
-
-export class LLM {
-	config: Required<LLMConfig>
-	id: string
-	client: LLMClient
-	#bus: EventBus
-
-	constructor(config: LLMConfig, id: string) {
-		this.config = parseLLMConfig(config)
-		this.id = id
-
-		this.#bus = getEventBus(id)
-
-		// Default to OpenAI client
-		this.client = new OpenAIClient({
-			model: this.config.model,
-			apiKey: this.config.apiKey,
-			baseURL: this.config.baseURL,
-			temperature: this.config.temperature,
-			maxTokens: this.config.maxTokens,
-		})
-	}
-
-	/**
-	 * - call llm api *once*
-	 * - invoke tool call *once*
-	 * - return the result of the tool
-	 */
-	async invoke(
-		messages: Message[],
-		tools: Record<string, Tool>,
-		abortSignal: AbortSignal
-	): Promise<InvokeResult> {
-		return await withRetry(
-			async () => {
-				const result = await this.client.invoke(messages, tools, abortSignal)
-
-				return result
-			},
-			// retry settings
-			{
-				maxRetries: this.config.maxRetries,
-				onRetry: (retries: number) => {
-					this.#bus.emit('panel:update', {
-						type: 'retry',
-						displayText: `retry-ing (${retries} / ${this.config.maxRetries})`,
-					})
-				},
-				onError: (error: Error, withRetry: boolean) => {
-					this.#bus.emit('panel:update', {
-						type: 'error',
-						displayText: `step failed: ${(error as Error).message}`,
-					})
-				},
-			}
-		)
-	}
-}
-
-async function withRetry<T>(
-	fn: () => Promise<T>,
-	settings: {
-		maxRetries: number
-		onRetry: (retries: number) => void
-		onError: (error: Error, withRetry: boolean) => void
-	}
-): Promise<T> {
-	let retries = 0
-	let lastError: Error | null = null
-	while (retries <= settings.maxRetries) {
-		if (retries > 0) {
-			settings.onRetry(retries)
-			await new Promise((resolve) => setTimeout(resolve, 100))
-		}
-
-		try {
-			return await fn()
-		} catch (error: unknown) {
-			console.error(error)
-			settings.onError(error as Error, retries < settings.maxRetries)
-
-			// do not retry if aborted by user
-			if ((error as { name?: string })?.name === 'AbortError') throw error
-
-			// do not retry if error is not retryable (InvokeError)
-			if (error instanceof InvokeError && !error.retryable) throw error
-
-			lastError = error as Error
-			retries++
-
-			await new Promise((resolve) => setTimeout(resolve, 100))
-		}
-	}
-
-	throw lastError!
-}

packages/page-agent/src/llms/utils.ts

@@ -1,214 +0,0 @@
-/**
- * Utility functions for LLM integration
- */
-import chalk from 'chalk'
-import { z } from 'zod'
-
-import type { MacroToolInput } from '../PageAgent'
-import { InvokeError, InvokeErrorType } from './errors'
-import type { Tool } from './types'
-
-/**
- * Convert Zod schema to OpenAI tool format
- * Uses Zod 4 native z.toJSONSchema()
- */
-export function zodToOpenAITool(name: string, tool: Tool) {
-	return {
-		type: 'function' as const,
-		function: {
-			name,
-			description: tool.description,
-			parameters: z.toJSONSchema(tool.inputSchema, { target: 'openapi-3.0' }),
-		},
-	}
-}
-
-/**
- * Although some models cannot guarantee correct response. Common issues are fixable:
- * - Instead of returning a proper tool call. Return the tool call parameters in the message content.
- * - Returned tool calls or messages don't follow the nested MacroToolInput format.
- */
-export function lenientParseMacroToolCall(
-	responseData: any,
-	inputSchema: z.ZodObject<MacroToolInput & Record<string, any>>
-): MacroToolInput {
-	// check
-	const choice = responseData.choices?.[0]
-	if (!choice) {
-		throw new InvokeError(InvokeErrorType.UNKNOWN, 'No choices in response', responseData)
-	}
-
-	// check
-	switch (choice.finish_reason) {
-		case 'tool_calls':
-		case 'function_call': // gemini
-		case 'stop': // will try a robust parse
-			// ✅ Normal
-			break
-		case 'length':
-			// ⚠️ Token limit reached
-			throw new InvokeError(
-				InvokeErrorType.CONTEXT_LENGTH,
-				'Response truncated: max tokens reached'
-			)
-		case 'content_filter':
-			// ❌ Content filtered
-			throw new InvokeError(InvokeErrorType.CONTENT_FILTER, 'Content filtered by safety system')
-		default:
-			throw new InvokeError(
-				InvokeErrorType.UNKNOWN,
-				`Unexpected finish_reason: ${choice.finish_reason}`
-			)
-	}
-
-	// Extract action schema from MacroToolInput schema
-	const actionSchema = inputSchema.shape.action
-	if (!actionSchema) {
-		throw new Error('inputSchema must have an "action" field')
-	}
-
-	// patch stopReason mis-format
-
-	let arg: string | null = null
-
-	// try to use tool call
-	const toolCall = choice.message?.tool_calls?.[0]?.function
-	arg = toolCall?.arguments ?? null
-
-	if (arg && toolCall.name !== 'AgentOutput') {
-		// TODO: check if toolCall.name is a valid action name
-		// case: instead of AgentOutput, the model returned a action name as tool call
-		console.log(chalk.yellow('lenientParseMacroToolCall: #1 fixing incorrect tool call'))
-		let tmpArg
-		try {
-			tmpArg = JSON.parse(arg)
-		} catch (error) {
-			throw new InvokeError(
-				InvokeErrorType.INVALID_TOOL_ARGS,
-				'Failed to parse tool arguments as JSON',
-				error
-			)
-		}
-		arg = JSON.stringify({ action: { [toolCall.name]: tmpArg } })
-	}
-
-	if (!arg) {
-		// try to use message content as JSON
-		arg = choice.message?.content.trim() || null
-	}
-
-	if (!arg) {
-		throw new InvokeError(
-			InvokeErrorType.NO_TOOL_CALL,
-			'No tool call or content found in response',
-			responseData
-		)
-	}
-
-	// make sure is valid JSON
-
-	let parsedArgs: any
-	try {
-		parsedArgs = JSON.parse(arg)
-	} catch (error) {
-		throw new InvokeError(
-			InvokeErrorType.INVALID_TOOL_ARGS,
-			'Failed to parse tool arguments as JSON',
-			error
-		)
-	}
-
-	// patch incomplete formats
-
-	if (parsedArgs.action || parsedArgs.evaluation_previous_goal || parsedArgs.next_goal) {
-		// case: nested MacroToolInput format (correct format)
-
-		// some models may give a empty action (they may think reasoning and action should be separate)
-		if (!parsedArgs.action) {
-			console.log(chalk.yellow('lenientParseMacroToolCall: #2 fixing incorrect tool call'))
-			parsedArgs.action = {
-				wait: { seconds: 1 },
-			}
-		}
-	} else if (parsedArgs.type && parsedArgs.function) {
-		// case: upper level function call format provided. only keep its arguments
-		// TODO: check if function name is a valid action name
-		if (parsedArgs.function.name !== 'AgentOutput')
-			throw new InvokeError(
-				InvokeErrorType.INVALID_TOOL_ARGS,
-				`Expected function name "AgentOutput", got "${parsedArgs.function.name}"`,
-				null
-			)
-
-		console.log(chalk.yellow('lenientParseMacroToolCall: #3 fixing incorrect tool call'))
-		parsedArgs = parsedArgs.function.arguments
-	} else if (parsedArgs.name && parsedArgs.arguments) {
-		// case: upper level function call format provided. only keep its arguments
-		// TODO: check if function name is a valid action name
-		if (parsedArgs.name !== 'AgentOutput')
-			throw new InvokeError(
-				InvokeErrorType.INVALID_TOOL_ARGS,
-				`Expected function name "AgentOutput", got "${parsedArgs.name}"`,
-				null
-			)
-
-		console.log(chalk.yellow('lenientParseMacroToolCall: #4 fixing incorrect tool call'))
-		parsedArgs = parsedArgs.arguments
-	} else {
-		// case: only action parameters provided, wrap into MacroToolInput
-		// TODO: check if action name is valid
-		console.log(chalk.yellow('lenientParseMacroToolCall: #5 fixing incorrect tool call'))
-		parsedArgs = { action: parsedArgs } as MacroToolInput
-	}
-
-	// make sure it's not wrapped as string
-	if (typeof parsedArgs === 'string') {
-		console.log(chalk.yellow('lenientParseMacroToolCall: #6 fixing incorrect tool call'))
-		try {
-			parsedArgs = JSON.parse(parsedArgs)
-		} catch (error) {
-			throw new InvokeError(
-				InvokeErrorType.INVALID_TOOL_ARGS,
-				'Failed to parse nested tool arguments as JSON',
-				error
-			)
-		}
-	}
-
-	const validation = inputSchema.safeParse(parsedArgs)
-	if (validation.success) {
-		return validation.data as unknown as MacroToolInput
-	} else {
-		const action = parsedArgs.action ?? {}
-		const actionName = Object.keys(action)[0] || 'unknown'
-		const actionArgs = JSON.stringify(action[actionName] || 'unknown')
-
-		// TODO: check if action name is valid. give a readable error message
-
-		throw new InvokeError(
-			InvokeErrorType.INVALID_TOOL_ARGS,
-			`Tool arguments validation failed: action "${actionName}" with args ${actionArgs}`,
-			validation.error
-		)
-	}
-}
-
-export function modelPatch(body: Record<string, any>) {
-	const model: string = body.model || ''
-
-	if (model.toLowerCase().startsWith('claude')) {
-		body.tool_choice = { type: 'tool', name: 'AgentOutput' }
-		body.thinking = { type: 'disabled' }
-		// body.reasoning = { enabled: 'disabled' }
-	}
-
-	if (model.toLowerCase().includes('grok')) {
-		console.log('Applying Grok patch: removing tool_choice')
-		delete body.tool_choice
-		console.log('Applying Grok patch: disable reasoning and thinking')
-		body.thinking = { type: 'disabled', effort: 'minimal' }
-		body.reasoning = { enabled: false, effort: 'low' }
-	}
-
-	return body
-}

packages/page-agent/src/prompts/.prettierignore

@@ -0,0 +1 @@
+system_prompt.md

packages/page-agent/src/prompts/system_prompt.md

@@ -92,7 +92,6 @@ Strictly follow these rules while using the browser and navigating the web:
 	- User can be wrong. If the request of user is not achievable, inappropriate or you do not have enough information or tools to achieve it. Tell user to make a better request.
 	- Webpage can be broken. All webpages or apps have bugs. Some bug will make it hard for your job. It's encouraged to tell user the problem of current page. Your feedbacks (including failing) are valuable for user.
 	- Trying to hard can be harmful. Repeating some action back and forth or pushing for a complex procedure with little knowledge can cause unwanted result and harmful side-effects. User would rather you to complete the task with a fail.
-- If you are not clear about the request or steps. `ask_user` to clarify it.
 - If you do not have knowledge for the current webpage or task. You must require user to give specific instructions and detailed steps.
 </capability>
 
@@ -120,7 +119,7 @@ Exhibit the following reasoning patterns to successfully achieve the <user_reque
 - Analyze all relevant items in <agent_history> and <browser_state> to understand your state.
 - Explicitly judge success/failure/uncertainty of the last action. Never assume an action succeeded just because it appears to be executed in your last step in <agent_history>. If the expected change is missing, mark the last action as failed (or uncertain) and plan a recovery.
 - Analyze whether you are stuck, e.g. when you repeat the same actions multiple times without any progress. Then consider alternative approaches e.g. scrolling for more context or ask user for help.
-- `ask_user` for help if you have any difficulty. Users want to be kept in the loop.
+- Ask user for help if you have any difficulty. Keep user in the loop.
 - If you see information relevant to <user_request>, plan saving the information to memory.
 - Always reason about the <user_request>. Make sure to carefully analyze the specific steps and information required. E.g. specific filters, specific form fields, specific information to search. Make sure to always compare the current trajectory with the user request and think carefully if thats how the user requested it.
 </reasoning_rules>

packages/page-agent/src/tools/index.ts

@@ -5,21 +5,7 @@
 import zod, { type z } from 'zod'
 
 import type { PageAgent } from '../PageAgent'
-import {
+import { waitFor } from '../utils'
-	clickElement,
-	getElementByIndex,
-	getSystemInfo,
-	inputTextElement,
-	scrollHorizontally,
-	scrollVertically,
-	selectOptionElement,
-	waitFor,
-} from './actions'
-// debug
-import * as utils from './actions'
-
-// @ts-expect-error debug only
-window.utils = utils
 
 /**
  * Internal tool definition that has access to PageAgent `this` context
@@ -41,18 +27,6 @@ export function tool<TParams>(options: PageAgentTool<TParams>): PageAgentTool<TP
  */
 export const tools = new Map<string, PageAgentTool>()
 
-// tools.set(
-// 	'get_current_html',
-// 	tool({
-// 		description: 'Get the current (updated) simplified HTML of the page',
-// 		inputSchema: zod.object({}),
-// 		execute: function (this: PageAgent) {
-// 			this.updateTree()
-// 			return this.simplifiedHTML
-// 		},
-// 	})
-// )
-
 tools.set(
 	'done',
 	tool({
@@ -79,11 +53,20 @@ tools.set(
 			seconds: zod.number().min(1).max(10).default(1),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const lastTimeUpdate = this.lastTimeUpdate
+			const lastTimeUpdate = await this.pageController.getLastUpdateTime()
 			const actualWaitTime = Math.max(0, input.seconds - (Date.now() - lastTimeUpdate) / 1000)
 			console.log(`actualWaitTime: ${actualWaitTime} seconds`)
 			await waitFor(actualWaitTime)
-			return `✅ Waited for ${input.seconds} seconds.` + (await getSystemInfo())
+
+			this.states.totalWaitTime += input.seconds
+
+			if (this.states.totalWaitTime >= 3) {
+				this.pushObservation(
+					`You have waited ${this.states.totalWaitTime} seconds accumulatively. Do NOT wait any longer unless you have a good reason.`
+				)
+			}
+
+			return `✅ Waited for ${input.seconds} seconds.`
 		},
 	})
 )
@@ -97,8 +80,11 @@ tools.set(
 			question: zod.string(),
 		}),
 		execute: async function (this: PageAgent, input) {
+			if (!this.panel) {
+				throw new Error('ask_user tool requires panel to be enabled')
+			}
 			const answer = await this.panel.askUser(input.question)
-			return `✅ Received user answer: ${answer}` + (await getSystemInfo())
+			return `✅ Received user answer: ${answer}`
 		},
 	})
 )
@@ -111,16 +97,8 @@ tools.set(
 			index: zod.int().min(0),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const element = getElementByIndex(this, input.index)
+			const result = await this.pageController.clickElement(input.index)
-			const elemText = this.elementTextMap.get(input.index)
+			return result.message
-			await clickElement(element)
-
-			// @workaround: Handle links that open in new tabs
-			if (element instanceof HTMLAnchorElement && element.target === '_blank') {
-				return `⚠️ Clicked link that opens in a new tab (${elemText ? elemText : input.index}). You are not capable of reading new tabs.`
-			}
-
-			return `✅ Clicked element (${elemText ? elemText : input.index}).` + (await getSystemInfo())
 		},
 	})
 )
@@ -134,13 +112,8 @@ tools.set(
 			text: zod.string(),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const element = getElementByIndex(this, input.index)
+			const result = await this.pageController.inputText(input.index, input.text)
-			const elemText = this.elementTextMap.get(input.index)
+			return result.message
-			await inputTextElement(element, input.text)
-			return (
-				`✅ Input text (${input.text}) into element (${elemText ? elemText : input.index}).` +
-				(await getSystemInfo())
-			)
 		},
 	})
 )
@@ -155,13 +128,8 @@ tools.set(
 			text: zod.string(),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const element = getElementByIndex(this, input.index)
+			const result = await this.pageController.selectOption(input.index, input.text)
-			const elemText = this.elementTextMap.get(input.index)
+			return result.message
-			await selectOptionElement(element as HTMLSelectElement, input.text)
-			return (
-				`✅ Selected option (${input.text}) in element (${elemText ? elemText : input.index}).` +
-				(await getSystemInfo())
-			)
 		},
 	})
 )
@@ -181,13 +149,11 @@ tools.set(
 			index: zod.number().int().min(0).optional(),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const { down, num_pages, index, pixels } = input
+			const result = await this.pageController.scroll({
-
+				...input,
-			const scroll_amount = pixels ? pixels : num_pages * (down ? 1 : -1) * window.innerHeight
+				numPages: input.num_pages,
-
+			})
-			const element = index !== undefined ? getElementByIndex(this, index) : null
+			return result.message
-
-			return (await scrollVertically(down, scroll_amount, element)) + (await getSystemInfo())
 		},
 	})
 )
@@ -203,13 +169,8 @@ tools.set(
 			index: zod.number().int().min(0).optional(),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const { right, pixels, index } = input
+			const result = await this.pageController.scrollHorizontally(input)
-
+			return result.message
-			const scroll_amount = pixels * (right ? 1 : -1)
-
-			const element = index !== undefined ? getElementByIndex(this, index) : null
-
-			return (await scrollHorizontally(right, scroll_amount, element)) + (await getSystemInfo())
 		},
 	})
 )
@@ -223,14 +184,8 @@ tools.set(
 			script: zod.string(),
 		}),
 		execute: async function (this: PageAgent, input) {
-			try {
+			const result = await this.pageController.executeJavascript(input.script)
-				// Wrap script in async function to support await
+			return result.message
-				const asyncFunction = eval(`(async () => { ${input.script} })`)
-				const result = await asyncFunction()
-				return `✅ Executed JavaScript. Result: ${result}` + (await getSystemInfo())
-			} catch (error) {
-				return `❌ Error executing JavaScript: ${error}` + (await getSystemInfo())
-			}
 		},
 	})
 )

packages/page-agent/src/utils/autoFixer.ts

@@ -0,0 +1,157 @@
+import chalk from 'chalk'
+
+/**
+ * Normalize LLM response and fix common format issues.
+ *
+ * Handles:
+ * - No tool_calls but JSON in message.content (fallback)
+ * - Model returns action name as tool call instead of AgentOutput
+ * - Arguments wrapped as double JSON string
+ * - Nested function call format
+ * - Missing action field (fallback to wait)
+ * - etc.
+ */
+export function normalizeResponse(response: any): any {
+	let resolvedArguments = null as any
+
+	const choice = (response as { choices?: Choice[] }).choices?.[0]
+	if (!choice) throw new Error('No choices in response')
+
+	const message = choice.message
+	if (!message) throw new Error('No message in choice')
+
+	const toolCall = message.tool_calls?.[0]
+
+	// fix level and location of arguments
+
+	if (toolCall?.function?.arguments) {
+		resolvedArguments = safeJsonParse(toolCall.function.arguments)
+
+		// case: sometimes the model only returns the action level
+		if (toolCall.function.name && toolCall.function.name !== 'AgentOutput') {
+			console.log(chalk.yellow(`[normalizeResponse] #1: fixing tool_call`))
+			resolvedArguments = { action: safeJsonParse(resolvedArguments) }
+		}
+	} else {
+		// case: sometimes the model returns json in content instead of tool_calls
+		if (message.content) {
+			const content = message.content.trim()
+			const jsonInContent = retrieveJsonFromString(content)
+			if (jsonInContent) {
+				resolvedArguments = safeJsonParse(jsonInContent)
+
+				// case: sometimes the content json includes upper level wrapper
+				if (resolvedArguments?.name === 'AgentOutput') {
+					console.log(chalk.yellow(`[normalizeResponse] #2: fixing tool_call`))
+					resolvedArguments = safeJsonParse(resolvedArguments.arguments)
+				}
+
+				// case: sometimes even 2-levels of wrapping
+				if (resolvedArguments?.type === 'function') {
+					console.log(chalk.yellow(`[normalizeResponse] #3: fixing tool_call`))
+					resolvedArguments = safeJsonParse(resolvedArguments.function.arguments)
+				}
+
+				// case: and sometimes action level only
+				// todo: needs better detection logic
+				if (
+					!resolvedArguments?.action &&
+					!resolvedArguments?.evaluation_previous_goal &&
+					!resolvedArguments?.memory &&
+					!resolvedArguments?.next_goal &&
+					!resolvedArguments?.thinking
+				) {
+					console.log(chalk.yellow(`[normalizeResponse] #4: fixing tool_call`))
+					resolvedArguments = { action: safeJsonParse(resolvedArguments) }
+				}
+			} else {
+				throw new Error('No tool_call and the message content does not contain valid JSON')
+			}
+		} else {
+			throw new Error('No tool_call nor message content is present')
+		}
+	}
+
+	// fix double stringified arguments
+	resolvedArguments = safeJsonParse(resolvedArguments)
+	if (resolvedArguments.action) {
+		resolvedArguments.action = safeJsonParse(resolvedArguments.action)
+	}
+
+	// fix incomplete formats
+	if (!resolvedArguments.action) {
+		console.log(chalk.yellow(`[normalizeResponse] #5: fixing tool_call`))
+		resolvedArguments.action = { name: 'wait', input: { seconds: 1 } }
+	}
+
+	// pack back to standard format
+	return {
+		...response,
+		choices: [
+			{
+				...choice,
+				message: {
+					...message,
+					tool_calls: [
+						{
+							...(toolCall || {}),
+							function: {
+								...(toolCall?.function || {}),
+								name: 'AgentOutput',
+								arguments: JSON.stringify(resolvedArguments),
+							},
+						},
+					],
+				},
+			},
+		],
+	}
+}
+
+/**
+ * Safely parse JSON, return original input if not json.
+ */
+function safeJsonParse(input: any): any {
+	if (typeof input === 'string') {
+		try {
+			return JSON.parse(input.trim())
+		} catch {
+			return input
+		}
+	}
+	return input
+}
+
+/**
+ * Extract and parse JSON from a string.
+ * - Treat content between the first `{` and the last `}` as JSON.
+ * - Try to parse that content as JSON and return the parsed value (object/array/primitive) if successful, otherwise return null.
+ */
+function retrieveJsonFromString(str: string): any {
+	try {
+		const json = /({[\s\S]*})/.exec(str) ?? []
+		if (json.length === 0) {
+			return null
+		}
+		return JSON.parse(json[0]!)
+	} catch {
+		return null
+	}
+}
+
+interface Choice {
+	message?: {
+		role?: 'assistant'
+		content?: string
+		tool_calls?: {
+			id?: string
+			type?: 'function'
+			function?: {
+				name?: string
+				arguments?: string
+			}
+		}[]
+	}
+	index?: 0
+	finish_reason?: 'tool_calls'
+}

packages/page-agent/src/utils/bus.ts

@@ -1,40 +1,16 @@
-/**
- * Type-safe event bus for decoupling PageAgent and Panel
- */
-import type { Step } from '../ui/UIState'
-
 /**
  * Event mapping definitions
  * @note Event bus callbacks must be repeatable without errors
  */
 export interface PageAgentEventMap {
-	// Panel control events
-	// call panel.show()
-	'panel:show': { params: undefined }
-	// call panel.hide()
-	'panel:hide': { params: undefined }
-	// call panel.reset()
-	'panel:reset': { params: undefined }
-	// call panel.update()
-	'panel:update': { params: Omit<Step, 'id' | 'stepNumber' | 'timestamp'> }
-	// call panel.expand()
-	'panel:expand': { params: undefined }
-	// call panel.collapse()
-	'panel:collapse': { params: undefined }
-
 	// PageAgent status events
-	// 'agent:beforeUpdate': { params: undefined }
-	// 'agent:afterUpdate': { params: undefined }
 	// 'agent:execute': { params: { task: string } }
 	// 'agent:done': { params: { text: string; success: boolean } }
-	// 'agent:paused': { params: undefined }
-	// 'agent:resumed': { params: undefined }
 	// 'agent:disposed': { params: undefined }
 	// 'agent:error': { params: { error: string | Error } }
 
 	// Task status change events
-	// 'task:start': { params: { task: string } }
+	'task:start': { params: { task: string } }
-	// 'task:step': { params: Omit<AgentStep, 'id' | 'stepNumber' | 'timestamp'> }
 	// 'task:complete': { params: { text: string; success: boolean } }
 	// 'task:error': { params: { error: string | Error } }
 

packages/page-agent/src/utils/index.ts

@@ -1,3 +1,5 @@
+export { normalizeResponse } from './autoFixer'
+
 /**
  * Wait until condition becomes true
  * @returns Returns when condition becomes true, throws otherwise
@@ -20,6 +22,10 @@ export async function waitUntil(check: () => boolean, timeout = 60 * 60_1000): P
 	})
 }
 
+export async function waitFor(seconds: number): Promise<void> {
+	await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
+}
+
 //
 
 export function truncate(text: string, maxLength: number): string {

packages/page-agent/tsconfig.dts.json

@@ -0,0 +1,9 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        // @workaround DTS bug
+        // dts do not work with monorepo path mapping
+        // disable path mapping for it
+        "paths": {}
+    }
+}

packages/page-agent/tsconfig.json

@@ -1,10 +1,24 @@
 {
-	"extends": "../../tsconfig.json",
+    "extends": "../../tsconfig.base.json",
-	"compilerOptions": {
+    "compilerOptions": {
-		"composite": true,
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
-		"noEmit": false,
+        "noEmit": false,
-		"outDir": "./dist",
+        "allowImportingTsExtensions": false,
-		"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo"
+        "baseUrl": ".",
-	},
+        "outDir": "dist",
-	"include": ["src", "env.d.ts"]
+        "paths": {
+            //
+            "@page-agent/llms": ["../llms/src/index.ts"],
+            "@page-agent/page-controller": ["../page-controller/src/PageController.ts"],
+            "@page-agent/ui": ["../ui/src/index.ts"]
+        }
+    },
+    "include": ["**/*.ts"],
+    "exclude": ["dist", "node_modules"],
+    "references": [
+        //
+        { "path": "../llms" },
+        { "path": "../page-controller" },
+        { "path": "../ui" }
+    ]
 }

packages/page-agent/vite.config.js

@@ -1,7 +1,4 @@
 // @ts-check
-import chalk from 'chalk'
-import 'dotenv/config'
-import process from 'node:process'
 import { dirname, resolve } from 'path'
 import dts from 'unplugin-dts/vite'
 import { fileURLToPath } from 'url'
@@ -10,14 +7,11 @@ import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
-// ============================================================================
+// ES Module for NPM Package
-// Library Config (ES Module for NPM Package)
+export default defineConfig({
-// ============================================================================
-/** @type {import('vite').UserConfig} */
-const libConfig = {
 	clearScreen: false,
 	plugins: [
-		dts({ tsconfigPath: './tsconfig.json', bundleTypes: true }),
+		dts({ tsconfigPath: './tsconfig.dts.json', bundleTypes: true }),
 		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
 	],
 	publicDir: false,
@@ -31,9 +25,14 @@ const libConfig = {
 			fileName: 'page-agent',
 			formats: ['es'],
 		},
-		outDir: resolve(__dirname, 'dist', 'lib'),
+		outDir: resolve(__dirname, 'dist', 'esm'),
 		rollupOptions: {
-			external: ['ai', 'ai-motion', 'chalk', 'zod'],
+			external: [
+				'chalk',
+				'zod',
+				// all the internal packages
+				/^@page-agent\//,
+			],
 		},
 		minify: false,
 		sourcemap: true,
@@ -42,44 +41,4 @@ const libConfig = {
 	define: {
 		'process.env.NODE_ENV': '"production"',
 	},
-}
+})
-
-// ============================================================================
-// UMD Config (Browser Bundle for CDN)
-// ============================================================================
-/** @type {import('vite').UserConfig} */
-const umdConfig = {
-	plugins: [cssInjectedByJsPlugin({ relativeCSSInjection: true })],
-	publicDir: false,
-	esbuild: {
-		keepNames: true,
-	},
-	build: {
-		lib: {
-			entry: resolve(__dirname, 'src/entry.ts'),
-			name: 'PageAgent',
-			fileName: 'page-agent',
-			formats: ['umd'],
-		},
-		outDir: resolve(__dirname, 'dist', 'umd'),
-		cssCodeSplit: true,
-	},
-	define: {
-		'process.env.NODE_ENV': '"production"',
-	},
-}
-
-// ============================================================================
-
-const MODE = process.env.MODE
-
-console.log(chalk.cyan(`📦 Build mode: ${chalk.bold(MODE || 'lib')}`))
-
-let config
-if (MODE === 'umd') {
-	config = umdConfig
-} else {
-	config = libConfig
-}
-
-export default defineConfig(config)

packages/page-agent/vite.iife.config.js

@@ -0,0 +1,56 @@
+// @ts-check
+import { config as dotenvConfig } from 'dotenv'
+import { dirname, resolve } from 'path'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// Load .env from repo root
+dotenvConfig({ path: resolve(__dirname, '../../.env') })
+
+// UMD Bundle for CDN
+// - alias all local packages so that they can be build in
+// - no external
+// - no d.ts. dts does not work with monorepo aliasing
+export default defineConfig(({ mode }) => ({
+	plugins: [cssInjectedByJsPlugin({ relativeCSSInjection: true })],
+	publicDir: false,
+	esbuild: {
+		keepNames: true,
+	},
+	resolve: {
+		alias: {
+			'@page-agent/page-controller': resolve(__dirname, '../page-controller/src/PageController.ts'),
+			'@page-agent/llms': resolve(__dirname, '../llms/src/index.ts'),
+			'@page-agent/ui': resolve(__dirname, '../ui/src/index.ts'),
+		},
+	},
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/iife.ts'),
+			name: 'PageAgent',
+			fileName: 'page-agent',
+			formats: ['iife'],
+		},
+		outDir: resolve(__dirname, 'dist', 'iife'),
+		cssCodeSplit: true,
+		minify: false,
+		rollupOptions: {
+			output: {
+				// force use .js as extension
+				entryFileNames: 'page-agent.js',
+			},
+			onwarn: function (message, handler) {
+				if (message.code === 'EVAL') return
+				handler(message)
+			},
+		},
+	},
+	define: {
+		'import.meta.env.LLM_MODEL_NAME': JSON.stringify(process.env.LLM_MODEL_NAME),
+		'import.meta.env.LLM_API_KEY': JSON.stringify(process.env.LLM_API_KEY),
+		'import.meta.env.LLM_BASE_URL': JSON.stringify(process.env.LLM_BASE_URL),
+	},
+}))

packages/page-controller/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@page-agent/page-controller",
+	"version": "0.2.5",
+	"type": "module",
+	"main": "./dist/lib/page-controller.js",
+	"module": "./dist/lib/page-controller.js",
+	"types": "./dist/lib/PageController.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/lib/PageController.d.ts",
+			"import": "./dist/lib/page-controller.js",
+			"default": "./dist/lib/page-controller.js"
+		}
+	},
+	"files": [
+		"dist/"
+	],
+	"description": "Page controller for page-agent - DOM operations and element interactions",
+	"keywords": [
+		"page-agent",
+		"dom",
+		"browser-automation",
+		"web-automation"
+	],
+	"author": "Simon<gaomeng1900>",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/alibaba/page-agent.git",
+		"directory": "packages/page-controller"
+	},
+	"homepage": "https://alibaba.github.io/page-agent/",
+	"scripts": {
+		"build": "vite build",
+		"prepublishOnly": "node -e \"const fs=require('fs');['LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
+		"postpublish": "node -e \"['LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
+	},
+	"dependencies": {
+		"ai-motion": "^0.4.8"
+	}
+}

packages/page-controller/src/PageController.ts

@@ -0,0 +1,393 @@
+/**
+ * Copyright (C) 2025 Alibaba Group Holding Limited
+ * All rights reserved.
+ *
+ * PageController - Manages DOM operations and element interactions.
+ * Designed to be independent of LLM and can be tested in unit tests.
+ * All public methods are async for potential remote calling support.
+ */
+import {
+	clickElement,
+	getElementByIndex,
+	inputTextElement,
+	scrollHorizontally,
+	scrollVertically,
+	selectOptionElement,
+} from './actions'
+import { VIEWPORT_EXPANSION } from './constants'
+import * as dom from './dom'
+import type { FlatDomTree, InteractiveElementDomNode } from './dom/dom_tree/type'
+import { getPageInfo } from './dom/getPageInfo'
+import { SimulatorMask } from './mask/SimulatorMask'
+import { patchReact } from './patches/react'
+
+export { SimulatorMask }
+
+/**
+ * Configuration for PageController
+ */
+export interface PageControllerConfig extends dom.DomConfig {
+	viewportExpansion?: number
+	/** Enable visual mask overlay during operations (default: false) */
+	enableMask?: boolean
+}
+
+/**
+ * Structured browser state for LLM consumption
+ */
+export interface BrowserState {
+	url: string
+	title: string
+	/** Page info + scroll position hint (e.g. "Page info: 1920x1080px...\n[Start of page]") */
+	header: string
+	/** Simplified HTML of interactive elements */
+	content: string
+	/** Page footer hint (e.g. "... 300 pixels below ..." or "[End of page]") */
+	footer: string
+}
+
+interface ActionResult {
+	success: boolean
+	message: string
+}
+
+/**
+ * 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 class PageController extends EventTarget {
+	private config: PageControllerConfig
+
+	/** Corresponds to eval_page in browser-use */
+	private flatTree: FlatDomTree | null = null
+
+	/**
+	 * All highlighted index-mapped interactive elements
+	 * Corresponds to DOMState.selector_map in browser-use
+	 */
+	private selectorMap = new Map<number, InteractiveElementDomNode>()
+
+	/** Index -> element text description mapping */
+	private elementTextMap = new Map<number, string>()
+
+	/**
+	 * Simplified HTML for LLM consumption.
+	 * Corresponds to clickable_elements_to_string in browser-use
+	 */
+	private simplifiedHTML = '<EMPTY>'
+
+	/** last time the tree was updated */
+	private lastTimeUpdate = 0
+
+	/** Visual mask overlay for blocking user interaction during automation */
+	private mask: SimulatorMask | null = null
+
+	constructor(config: PageControllerConfig = {}) {
+		super()
+
+		this.config = config
+
+		patchReact(this)
+
+		if (config.enableMask) {
+			this.mask = new SimulatorMask()
+		}
+	}
+
+	// ======= State Queries =======
+
+	/**
+	 * Get current page URL
+	 */
+	async getCurrentUrl(): Promise<string> {
+		return window.location.href
+	}
+
+	/**
+	 * Get last tree update timestamp
+	 */
+	async getLastUpdateTime(): Promise<number> {
+		return this.lastTimeUpdate
+	}
+
+	/**
+	 * Get structured browser state for LLM consumption.
+	 * Automatically calls updateTree() to refresh the DOM state.
+	 */
+	async getBrowserState(): Promise<BrowserState> {
+		const url = window.location.href
+		const title = document.title
+		const pi = getPageInfo()
+		const viewportExpansion = this.config.viewportExpansion ?? VIEWPORT_EXPANSION
+
+		await this.updateTree()
+
+		const content = this.simplifiedHTML
+
+		// Build header: page info + scroll position hint
+		const pageInfoLine = `Page info: ${pi.viewport_width}x${pi.viewport_height}px viewport, ${pi.page_width}x${pi.page_height}px total page size, ${pi.pages_above.toFixed(1)} pages above, ${pi.pages_below.toFixed(1)} pages below, ${pi.total_pages.toFixed(1)} total pages, at ${(pi.current_page_position * 100).toFixed(0)}% of page`
+
+		const elementsLabel =
+			viewportExpansion === -1
+				? 'Interactive elements from top layer of the current page (full page):'
+				: 'Interactive elements from top layer of the current page inside the viewport:'
+
+		const hasContentAbove = pi.pixels_above > 4
+		const scrollHintAbove =
+			hasContentAbove && viewportExpansion !== -1
+				? `... ${pi.pixels_above} pixels above (${pi.pages_above.toFixed(1)} pages) - scroll to see more ...`
+				: '[Start of page]'
+
+		const header = `${pageInfoLine}\n\n${elementsLabel}\n\n${scrollHintAbove}`
+
+		// Build footer: scroll position hint
+		const hasContentBelow = pi.pixels_below > 4
+		const footer =
+			hasContentBelow && viewportExpansion !== -1
+				? `... ${pi.pixels_below} pixels below (${pi.pages_below.toFixed(1)} pages) - scroll to see more ...`
+				: '[End of page]'
+
+		return { url, title, header, content, footer }
+	}
+
+	// ======= DOM Tree Operations =======
+
+	/**
+	 * Update DOM tree, returns simplified HTML for LLM.
+	 * This is the main method to refresh the page state.
+	 * Automatically bypasses mask during DOM extraction if enabled.
+	 */
+	async updateTree(): Promise<string> {
+		this.dispatchEvent(new Event('beforeUpdate'))
+
+		this.lastTimeUpdate = Date.now()
+
+		// Temporarily bypass mask to allow DOM extraction
+		if (this.mask) {
+			this.mask.wrapper.style.pointerEvents = 'none'
+		}
+
+		dom.cleanUpHighlights()
+
+		const blacklist = [
+			...(this.config.interactiveBlacklist || []),
+			...document.querySelectorAll('[data-page-agent-not-interactive]').values(),
+		]
+
+		this.flatTree = dom.getFlatTree({
+			...this.config,
+			interactiveBlacklist: blacklist,
+		})
+
+		this.simplifiedHTML = dom.flatTreeToString(this.flatTree, this.config.include_attributes)
+
+		this.selectorMap.clear()
+		this.selectorMap = dom.getSelectorMap(this.flatTree)
+
+		this.elementTextMap.clear()
+		this.elementTextMap = dom.getElementTextMap(this.simplifiedHTML)
+
+		// Restore mask blocking
+		if (this.mask) {
+			this.mask.wrapper.style.pointerEvents = 'auto'
+		}
+
+		this.dispatchEvent(new Event('afterUpdate'))
+
+		return this.simplifiedHTML
+	}
+
+	/**
+	 * Clean up all element highlights
+	 */
+	async cleanUpHighlights(): Promise<void> {
+		dom.cleanUpHighlights()
+	}
+
+	// ======= Element Actions =======
+
+	/**
+	 * Click element by index
+	 */
+	async clickElement(index: number): Promise<ActionResult> {
+		try {
+			const element = getElementByIndex(this.selectorMap, index)
+			const elemText = this.elementTextMap.get(index)
+			await clickElement(element)
+
+			// Handle links that open in new tabs
+			if (element instanceof HTMLAnchorElement && element.target === '_blank') {
+				return {
+					success: true,
+					message: `✅ Clicked element (${elemText ?? index}). ⚠️ Link opens in a new tab. You are not capable of reading new tabs.`,
+				}
+			}
+
+			return {
+				success: true,
+				message: `✅ Clicked element (${elemText ?? index}).`,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to click element: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Input text into element by index
+	 */
+	async inputText(index: number, text: string): Promise<ActionResult> {
+		try {
+			const element = getElementByIndex(this.selectorMap, index)
+			const elemText = this.elementTextMap.get(index)
+			await inputTextElement(element, text)
+
+			return {
+				success: true,
+				message: `✅ Input text (${text}) into element (${elemText ?? index}).`,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to input text: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Select dropdown option by index and option text
+	 */
+	async selectOption(index: number, optionText: string): Promise<ActionResult> {
+		try {
+			const element = getElementByIndex(this.selectorMap, index)
+			const elemText = this.elementTextMap.get(index)
+			await selectOptionElement(element as HTMLSelectElement, optionText)
+
+			return {
+				success: true,
+				message: `✅ Selected option (${optionText}) in element (${elemText ?? index}).`,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to select option: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Scroll vertically
+	 */
+	async scroll(options: {
+		down: boolean
+		numPages: number
+		pixels?: number
+		index?: number
+	}): Promise<ActionResult> {
+		try {
+			const { down, numPages, pixels, index } = options
+
+			const scrollAmount = pixels ?? numPages * (down ? 1 : -1) * window.innerHeight
+
+			const element = index !== undefined ? getElementByIndex(this.selectorMap, index) : null
+
+			const message = await scrollVertically(down, scrollAmount, element)
+
+			return {
+				success: true,
+				message,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to scroll: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Scroll horizontally
+	 */
+	async scrollHorizontally(options: {
+		right: boolean
+		pixels: number
+		index?: number
+	}): Promise<ActionResult> {
+		try {
+			const { right, pixels, index } = options
+
+			const scrollAmount = pixels * (right ? 1 : -1)
+
+			const element = index !== undefined ? getElementByIndex(this.selectorMap, index) : null
+
+			const message = await scrollHorizontally(right, scrollAmount, element)
+
+			return {
+				success: true,
+				message,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to scroll horizontally: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Execute arbitrary JavaScript on the page
+	 */
+	async executeJavascript(script: string): Promise<ActionResult> {
+		try {
+			// Wrap script in async function to support await
+			const asyncFunction = eval(`(async () => { ${script} })`)
+			const result = await asyncFunction()
+			return {
+				success: true,
+				message: `✅ Executed JavaScript. Result: ${result}`,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Error executing JavaScript: ${error}`,
+			}
+		}
+	}
+
+	// ======= Mask Operations =======
+
+	/**
+	 * Show the visual mask overlay.
+	 * Only works if enableMask was set to true in config.
+	 */
+	showMask(): void {
+		this.mask?.show()
+	}
+
+	/**
+	 * Hide the visual mask overlay.
+	 * Only works if enableMask was set to true in config.
+	 */
+	hideMask(): void {
+		this.mask?.hide()
+	}
+
+	/**
+	 * Dispose and clean up resources
+	 */
+	dispose(): void {
+		dom.cleanUpHighlights()
+		this.flatTree = null
+		this.selectorMap.clear()
+		this.elementTextMap.clear()
+		this.simplifiedHTML = '<EMPTY>'
+		this.mask?.dispose()
+		this.mask = null
+	}
+}

packages/page-controller/src/actions.ts

@@ -2,26 +2,14 @@
  * Copyright (C) 2025 Alibaba Group Holding Limited
  * All rights reserved.
  */
-import type { PageAgent } from '../PageAgent'
+import type { InteractiveElementDomNode } from './dom/dom_tree/type'
 
 // ======= general utils =======
 
-export async function waitFor(seconds: number): Promise<void> {
+async function waitFor(seconds: number): Promise<void> {
 	await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
 }
 
-let currentUrl = window.location.href
-export async function getSystemInfo() {
-	// If current URL is already up to date, no need to add message
-	if (currentUrl === window.location.href) return ''
-
-	await waitFor(0.3) // Wait a bit longer for page to load
-
-	currentUrl = window.location.href
-
-	return `\n<sys> Current URL changed to: ${currentUrl} </sys>`
-}
-
 // ======= dom utils =======
 
 export async function movePointerToElement(element: HTMLElement) {
@@ -35,10 +23,13 @@ export async function movePointerToElement(element: HTMLElement) {
 }
 
 /**
- * Get the HTMLElement by index from the selectorMap in PageAgent.
+ * Get the HTMLElement by index from a selectorMap.
  */
-export function getElementByIndex(pageAgent: PageAgent, index: number): HTMLElement {
+export function getElementByIndex(
-	const interactiveNode = pageAgent.selectorMap.get(index)
+	selectorMap: Map<number, InteractiveElementDomNode>,
+	index: number
+): HTMLElement {
+	const interactiveNode = selectorMap.get(index)
 	if (!interactiveNode) {
 		throw new Error(`No interactive element found at index ${index}`)
 	}
@@ -170,7 +161,6 @@ export async function selectOptionElement(selectElement: HTMLSelectElement, opti
 	await waitFor(0.1) // Wait to ensure change event processing completes
 }
 
-// eslint-disable-next-line @typescript-eslint/require-await
 export async function scrollIntoViewIfNeeded(element: HTMLElement) {
 	const el = element as any
 	if (el.scrollIntoViewIfNeeded) {
@@ -297,12 +287,52 @@ export async function scrollVertically(
 			(document.documentElement as HTMLElement)
 
 	if (el === document.scrollingElement || el === document.documentElement || el === document.body) {
+		// Page-level scroll
+		const scrollBefore = window.scrollY
+		const scrollMax = document.documentElement.scrollHeight - window.innerHeight
+
 		window.scrollBy(0, dy)
-		return `✅ Scrolled page by ${dy}px.`
+
+		const scrollAfter = window.scrollY
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dy > 0
+				? `⚠️ Already at the bottom of the page, cannot scroll down further.`
+				: `⚠️ Already at the top of the page, cannot scroll up further.`
+		}
+
+		const reachedBottom = dy > 0 && scrollAfter >= scrollMax - 1
+		const reachedTop = dy < 0 && scrollAfter <= 1
+
+		if (reachedBottom) return `✅ Scrolled page by ${scrolled}px. Reached the bottom of the page.`
+		if (reachedTop) return `✅ Scrolled page by ${scrolled}px. Reached the top of the page.`
+		return `✅ Scrolled page by ${scrolled}px.`
 	} else {
+		// Container scroll
+		const scrollBefore = el!.scrollTop
+		const scrollMax = el!.scrollHeight - el!.clientHeight
+
 		el!.scrollBy({ top: dy, behavior: 'smooth' })
-		await waitFor(0.1) // Animation playback
+		await waitFor(0.1)
-		return `✅ Scrolled container (${el!.tagName}) by ${dy}px.`
+
+		const scrollAfter = el!.scrollTop
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dy > 0
+				? `⚠️ Already at the bottom of container (${el!.tagName}), cannot scroll down further.`
+				: `⚠️ Already at the top of container (${el!.tagName}), cannot scroll up further.`
+		}
+
+		const reachedBottom = dy > 0 && scrollAfter >= scrollMax - 1
+		const reachedTop = dy < 0 && scrollAfter <= 1
+
+		if (reachedBottom)
+			return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the bottom.`
+		if (reachedTop)
+			return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the top.`
+		return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px.`
 	}
 }
 
@@ -420,11 +450,52 @@ export async function scrollHorizontally(
 			(document.documentElement as HTMLElement)
 
 	if (el === document.scrollingElement || el === document.documentElement || el === document.body) {
+		// Page-level scroll
+		const scrollBefore = window.scrollX
+		const scrollMax = document.documentElement.scrollWidth - window.innerWidth
+
 		window.scrollBy(dx, 0)
-		return `✅ Scrolled page horizontally by ${dx}px`
+
+		const scrollAfter = window.scrollX
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dx > 0
+				? `⚠️ Already at the right edge of the page, cannot scroll right further.`
+				: `⚠️ Already at the left edge of the page, cannot scroll left further.`
+		}
+
+		const reachedRight = dx > 0 && scrollAfter >= scrollMax - 1
+		const reachedLeft = dx < 0 && scrollAfter <= 1
+
+		if (reachedRight)
+			return `✅ Scrolled page by ${scrolled}px. Reached the right edge of the page.`
+		if (reachedLeft) return `✅ Scrolled page by ${scrolled}px. Reached the left edge of the page.`
+		return `✅ Scrolled page horizontally by ${scrolled}px.`
 	} else {
+		// Container scroll
+		const scrollBefore = el!.scrollLeft
+		const scrollMax = el!.scrollWidth - el!.clientWidth
+
 		el!.scrollBy({ left: dx, behavior: 'smooth' })
-		await waitFor(0.1) // Animation playback
+		await waitFor(0.1)
-		return `✅ Scrolled container (${el!.tagName}) horizontally by ${dx}px`
+
+		const scrollAfter = el!.scrollLeft
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dx > 0
+				? `⚠️ Already at the right edge of container (${el!.tagName}), cannot scroll right further.`
+				: `⚠️ Already at the left edge of container (${el!.tagName}), cannot scroll left further.`
+		}
+
+		const reachedRight = dx > 0 && scrollAfter >= scrollMax - 1
+		const reachedLeft = dx < 0 && scrollAfter <= 1
+
+		if (reachedRight)
+			return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the right edge.`
+		if (reachedLeft)
+			return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the left edge.`
+		return `✅ Scrolled container (${el!.tagName}) horizontally by ${scrolled}px.`
 	}
 }

packages/page-controller/src/constants.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (C) 2025 Alibaba Group Holding Limited
+ * All rights reserved.
+ */
+
+/**
+ * Viewport expansion for DOM tree extraction.
+ * -1 means full page (no viewport restriction)
+ * 0 means viewport only
+ * positive values expand the viewport by that many pixels
+ *
+ * @note Since isTopElement depends on elementFromPoint,
+ * it returns null when out of viewport, this feature has no practical use, only differ between -1 and 0
+ */
+// export const VIEWPORT_EXPANSION = 100
+export const VIEWPORT_EXPANSION = -1

packages/page-controller/src/dom/dom_tree/index.js

@@ -16,6 +16,7 @@
  * @edit scrollable element detection
  * @edit add `data-browser-use-ignore` attribute
  * @edit improve `sampleRect`, filter out rects with 0 area
+ * @edit exclude aria-hidden elements
  */
 
 export default (
@@ -1446,7 +1447,14 @@ export default (
 		 * @edit add `data-browser-use-ignore` attribute
 		 */
 		if (node.dataset?.browserUseIgnore === 'true') {
-			return true // Skip this node and its children
+			return null // Skip this node and its children
+		}
+
+		/**
+		 * @edit exclude aria-hidden elements
+		 */
+		if (node.getAttribute && node.getAttribute('aria-hidden') === 'true') {
+			return null // Skip this node and its children
 		}
 
 		// Special handling for root node (body)

packages/page-controller/src/dom/index.ts

@@ -1,5 +1,5 @@
-import { VIEWPORT_EXPANSION } from '../config/constants'
+import { VIEWPORT_EXPANSION } from '../constants'
-import domTree from './dom_tree/index'
+import domTree from './dom_tree/index.js'
 import {
 	ElementDomNode,
 	FlatDomTree,

packages/page-controller/src/mask/SimulatorMask.ts

@@ -1,6 +1,6 @@
 import { Motion } from 'ai-motion'
 
-import { isPageDark } from '../utils/checkDarkMode'
+import { isPageDark } from './checkDarkMode'
 
 import styles from './SimulatorMask.module.css'
 import cursorStyles from './cursor.module.css'

packages/page-controller/src/mask/checkDarkMode.ts

@@ -3,14 +3,14 @@
  * @returns {boolean} - True if a common dark mode class is found.
  */
 function hasDarkModeClass() {
-	const DFEAULT_DARK_MODE_CLASSES = ['dark', 'dark-mode', 'theme-dark', 'night', 'night-mode']
+	const DEFAULT_DARK_MODE_CLASSES = ['dark', 'dark-mode', 'theme-dark', 'night', 'night-mode']
 
 	const htmlElement = document.documentElement
-	const bodyElement = document.body
+	const bodyElement = document.body || document.documentElement // can be null in some cases
 
 	// Check class names on <html> and <body>
-	for (const className of DFEAULT_DARK_MODE_CLASSES) {
+	for (const className of DEFAULT_DARK_MODE_CLASSES) {
-		if (htmlElement.classList.contains(className) || bodyElement.classList.contains(className)) {
+		if (htmlElement.classList.contains(className) || bodyElement?.classList.contains(className)) {
 			return true
 		}
 	}
@@ -70,7 +70,7 @@ function isColorDark(colorString: string, threshold = 128) {
 function isBackgroundDark() {
 	// We check both <html> and <body> because some pages set the color on <html>
 	const htmlStyle = window.getComputedStyle(document.documentElement)
-	const bodyStyle = window.getComputedStyle(document.body)
+	const bodyStyle = window.getComputedStyle(document.body || document.documentElement)
 
 	// Get background colors
 	const htmlBgColor = htmlStyle.backgroundColor
@@ -93,18 +93,23 @@ function isBackgroundDark() {
  * @returns {boolean} - True if the page is likely dark.
  */
 export function isPageDark() {
-	// Strategy 1: Check for common dark mode classes
+	try {
-	if (hasDarkModeClass()) {
+		// Strategy 1: Check for common dark mode classes
-		return true
+		if (hasDarkModeClass()) {
+			return true
+		}
+
+		// Strategy 2: Analyze the computed background color
+		if (isBackgroundDark()) {
+			return true
+		}
+
+		// @TODO add more checks here, e.g., analyzing text color,
+		// or checking the background of major layout elements like <main> or #app.
+
+		return false
+	} catch (error) {
+		console.warn('Error determining if page is dark:', error)
+		return false
 	}
-
-	// Strategy 2: Analyze the computed background color
-	if (isBackgroundDark()) {
-		return true
-	}
-
-	// @TODO add more checks here, e.g., analyzing text color,
-	// or checking the background of major layout elements like <main> or #app.
-
-	return false
 }

packages/page-controller/src/patches/antd.ts

@@ -1,4 +1,4 @@
-import type { PageAgent } from '../PageAgent'
+import type { PageController } from '../PageController'
 
 const clearFunctions = [] as (() => void)[]
 
@@ -11,9 +11,9 @@ function fixAntdSelect() {
 	// for (const select of selects) {}
 }
 
-export function patchAntd(pageAgent: PageAgent) {
+export function patchAntd(pageController: PageController) {
-	pageAgent.addEventListener('beforeUpdate', fixAntdSelect)
+	pageController.addEventListener('beforeUpdate', fixAntdSelect)
-	pageAgent.addEventListener('afterUpdate', () => {
+	pageController.addEventListener('afterUpdate', () => {
 		for (const fn of clearFunctions) fn()
 		clearFunctions.length = 0
 	})

packages/page-controller/src/patches/react.ts

@@ -1,7 +1,7 @@
-import type { PageAgent } from '../PageAgent'
+import type { PageController } from '../PageController'
 
 // Find common React root elements and add data-page-agent-not-interactive attribute
-export function patchReact(pageAgent: PageAgent) {
+export function patchReact(pageController: PageController) {
 	const reactRootElements = document.querySelectorAll(
 		'[data-reactroot], [data-reactid], [data-react-checksum], #root, #app, [id^="root-"], [id^="app-"], #adex-wrapper, #adex-root'
 	)

packages/page-controller/tsconfig.dts.json

@@ -0,0 +1,9 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        // @workaround DTS bug
+        // dts do not work with monorepo path mapping
+        // disable path mapping for it
+        "paths": {}
+    }
+}

packages/page-controller/tsconfig.json

@@ -0,0 +1,12 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
+        "noEmit": false,
+        "allowImportingTsExtensions": false,
+        "baseUrl": ".",
+        "outDir": "dist"
+    },
+    "include": ["**/*.ts", "**/*.js"],
+    "exclude": ["dist", "node_modules"]
+}

packages/page-controller/vite.config.js

@@ -0,0 +1,45 @@
+// @ts-check
+import chalk from 'chalk'
+import { dirname, resolve } from 'path'
+import dts from 'unplugin-dts/vite'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+console.log(chalk.cyan(`📦 Building @page-agent/page-controller`))
+
+export default defineConfig({
+	clearScreen: false,
+	plugins: [
+		dts({ tsconfigPath: './tsconfig.dts.json', bundleTypes: true }),
+		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
+	],
+	publicDir: false,
+	esbuild: {
+		keepNames: true,
+	},
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/PageController.ts'),
+			name: 'PageController',
+			fileName: 'page-controller',
+			formats: ['es'],
+		},
+		outDir: resolve(__dirname, 'dist', 'lib'),
+		rollupOptions: {
+			external: ['@page-agent/*', 'ai-motion'],
+			onwarn: function (message, handler) {
+				if (message.code === 'EVAL') return
+				handler(message)
+			},
+		},
+		minify: false,
+		sourcemap: true,
+		cssCodeSplit: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})

packages/ui/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@page-agent/ui",
+	"version": "0.2.5",
+	"type": "module",
+	"main": "./dist/lib/page-agent-ui.js",
+	"module": "./dist/lib/page-agent-ui.js",
+	"types": "./dist/lib/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/lib/index.d.ts",
+			"import": "./dist/lib/page-agent-ui.js",
+			"default": "./dist/lib/page-agent-ui.js"
+		}
+	},
+	"files": [
+		"dist/"
+	],
+	"description": "UI components for page-agent - Panel and i18n",
+	"keywords": [
+		"page-agent",
+		"ui",
+		"panel",
+		"i18n"
+	],
+	"author": "Simon<gaomeng1900>",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/alibaba/page-agent.git",
+		"directory": "packages/ui"
+	},
+	"homepage": "https://alibaba.github.io/page-agent/",
+	"scripts": {
+		"build": "vite build",
+		"prepublishOnly": "node -e \"const fs=require('fs');['LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
+		"postpublish": "node -e \"['LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
+	}
+}

packages/ui/src/Panel.module.css

@@ -209,18 +209,6 @@
 			}
 		}
 
-		.pauseButton {
-			font-weight: 600;
-			&.paused {
-				background: rgba(34, 197, 94, 0.2); /* 绿色背景表示可以继续 */
-				color: rgb(34, 197, 94);
-
-				&:hover {
-					background: rgba(34, 197, 94, 0.3);
-				}
-			}
-		}
-
 		.stopButton {
 			background: rgba(239, 68, 68, 0.2);
 			color: rgb(255, 41, 41);
@@ -364,6 +352,11 @@
 				background: linear-gradient(135deg, rgba(255, 214, 0, 0.1), rgba(255, 214, 0, 0.05));
 			}
 
+			&.observation {
+				border-left-color: rgb(147, 51, 234);
+				background: linear-gradient(135deg, rgba(147, 51, 234, 0.1), rgba(147, 51, 234, 0.05));
+			}
+
 			/* 突出显示 done 成功结果 */
 			&.doneSuccess {
 				background: linear-gradient(

packages/ui/src/Panel.ts

@@ -1,11 +1,39 @@
-import type { PageAgent } from '../PageAgent'
-import type { I18n } from '../i18n'
-import { truncate } from '../utils'
-import type { EventBus } from '../utils/bus'
 import { type Step, UIState } from './UIState'
+import { I18n, type SupportedLanguage } from './i18n'
+import { escapeHtml, truncate } from './utils'
 
 import styles from './Panel.module.css'
 
+/**
+ * Panel configuration
+ */
+export interface PanelConfig {
+	language?: SupportedLanguage
+	onExecuteTask: (task: string) => void
+	onStop: () => void
+	/**
+	 * Whether to prompt for next task after task completion
+	 * @default true
+	 */
+	promptForNextTask?: boolean
+}
+
+/**
+ * Semantic update types - Panel handles i18n internally
+ */
+export type PanelUpdate =
+	| { type: 'thinking'; text?: string } // text is optional, defaults to i18n thinking text
+	| { type: 'input'; task: string }
+	| { type: 'question'; question: string }
+	| { type: 'userAnswer'; input: string }
+	| { type: 'retry'; current: number; max: number }
+	| { type: 'error'; message: string }
+	| { type: 'output'; text: string }
+	| { type: 'completed' }
+	| { type: 'toolExecuting'; toolName: string; args: any }
+	| { type: 'toolCompleted'; toolName: string; args: any; result?: string; duration?: number }
+	| { type: 'observation'; content: string }
+
 /**
  * Agent control panel
  */
@@ -15,15 +43,14 @@ export class Panel {
 	#statusText: HTMLElement
 	#historySection: HTMLElement
 	#expandButton: HTMLElement
-	#pauseButton: HTMLElement
 	#stopButton: HTMLElement
 	#inputSection: HTMLElement
 	#taskInput: HTMLInputElement
-	#bus: EventBus
 
 	#state = new UIState()
 	#isExpanded = false
-	#pageAgent: PageAgent
+	#config: PanelConfig
+	#i18n: I18n
 	#userAnswerResolver: ((input: string) => void) | null = null
 	#isWaitingForUserAnswer: boolean = false
 	#headerUpdateTimer: ReturnType<typeof setInterval> | null = null
@@ -34,31 +61,24 @@ export class Panel {
 		return this.#wrapper
 	}
 
-	constructor(pageAgent: PageAgent) {
+	constructor(config: PanelConfig) {
-		this.#pageAgent = pageAgent
+		this.#config = config
-		this.#bus = pageAgent.bus
+		this.#i18n = new I18n(config.language ?? 'en-US')
 		this.#wrapper = this.#createWrapper()
 		this.#indicator = this.#wrapper.querySelector(`.${styles.indicator}`)!
 		this.#statusText = this.#wrapper.querySelector(`.${styles.statusText}`)!
 		this.#historySection = this.#wrapper.querySelector(`.${styles.historySection}`)!
 		this.#expandButton = this.#wrapper.querySelector(`.${styles.expandButton}`)!
-		this.#pauseButton = this.#wrapper.querySelector(`.${styles.pauseButton}`)!
 		this.#stopButton = this.#wrapper.querySelector(`.${styles.stopButton}`)!
 		this.#inputSection = this.#wrapper.querySelector(`.${styles.inputSectionWrapper}`)!
 		this.#taskInput = this.#wrapper.querySelector(`.${styles.taskInput}`)!
 
 		this.#setupEventListeners()
 		this.#startHeaderUpdateLoop()
-		// this.#expand() // debug
 
 		this.#showInputArea()
 
-		this.#bus.on('panel:show', () => this.#show())
+		this.hide() // Start hidden
-		this.#bus.on('panel:hide', () => this.#hide())
-		this.#bus.on('panel:reset', () => this.#reset())
-		this.#bus.on('panel:update', (stepData) => this.#update(stepData))
-		this.#bus.on('panel:expand', () => this.#expand())
-		this.#bus.on('panel:collapse', () => this.#collapse())
 	}
 
 	/**
@@ -71,18 +91,62 @@ export class Panel {
 			this.#userAnswerResolver = resolve
 
 			// Update state to `running`
-			this.#update({
+			this.#updateInternal({
 				type: 'output',
-				displayText: this.#pageAgent.i18n.t('ui.panel.question', { question }),
+				displayText: this.#i18n.t('ui.panel.question', { question }),
 			}) // Expand history panel
 			if (!this.#isExpanded) {
 				this.#expand()
 			}
 
-			this.#showInputArea(this.#pageAgent.i18n.t('ui.panel.userAnswerPrompt'))
+			this.#showInputArea(this.#i18n.t('ui.panel.userAnswerPrompt'))
 		})
 	}
 
+	// ========== Public control methods ==========
+
+	show(): void {
+		this.wrapper.style.display = 'block'
+		void this.wrapper.offsetHeight
+		this.wrapper.style.opacity = '1'
+		this.wrapper.style.transform = 'translateX(-50%) translateY(0)'
+	}
+
+	hide(): void {
+		this.wrapper.style.opacity = '0'
+		this.wrapper.style.transform = 'translateX(-50%) translateY(20px)'
+		this.wrapper.style.display = 'none'
+	}
+
+	reset(): void {
+		this.#state.reset()
+		this.#statusText.textContent = this.#i18n.t('ui.panel.ready')
+		this.#updateStatusIndicator('thinking')
+		this.#updateHistory()
+		this.#collapse()
+		// Reset user input state
+		this.#isWaitingForUserAnswer = false
+		this.#userAnswerResolver = null
+		// Show input area
+		this.#showInputArea()
+	}
+
+	expand(): void {
+		this.#expand()
+	}
+
+	collapse(): void {
+		this.#collapse()
+	}
+
+	/**
+	 * Update panel with semantic data - i18n handled internally
+	 */
+	update(data: PanelUpdate): void {
+		const stepData = this.#toStepData(data)
+		this.#updateInternal(stepData)
+	}
+
 	/**
 	 * Dispose panel
 	 */
@@ -92,10 +156,104 @@ export class Panel {
 		this.wrapper.remove()
 	}
 
+	// ========== Private methods ==========
+
 	/**
-	 * Update status
+	 * Convert semantic update to step data with i18n
 	 */
-	#update(stepData: Omit<Step, 'id' | 'stepNumber' | 'timestamp'>): void {
+	#toStepData(data: PanelUpdate): Omit<Step, 'id' | 'stepNumber' | 'timestamp'> {
+		switch (data.type) {
+			case 'thinking':
+				return { type: 'thinking', displayText: data.text ?? this.#i18n.t('ui.panel.thinking') }
+			case 'input':
+				return { type: 'input', displayText: data.task }
+			case 'question':
+				return {
+					type: 'output',
+					displayText: this.#i18n.t('ui.panel.question', { question: data.question }),
+				}
+			case 'userAnswer':
+				return {
+					type: 'input',
+					displayText: this.#i18n.t('ui.panel.userAnswer', { input: data.input }),
+				}
+			case 'retry':
+				return { type: 'retry', displayText: `retry-ing (${data.current} / ${data.max})` }
+			case 'error':
+				return { type: 'error', displayText: data.message }
+			case 'output':
+				return { type: 'output', displayText: data.text }
+			case 'completed':
+				return { type: 'completed', displayText: this.#i18n.t('ui.panel.taskCompleted') }
+			case 'toolExecuting':
+				return {
+					type: 'tool_executing',
+					toolName: data.toolName,
+					toolArgs: data.args,
+					displayText: this.#getToolExecutingText(data.toolName, data.args),
+				}
+			case 'toolCompleted': {
+				const displayText = this.#getToolCompletedText(data.toolName, data.args)
+				if (!displayText) return { type: 'tool_executing', displayText: '' } // will be filtered
+				return {
+					type: 'tool_executing',
+					toolName: data.toolName,
+					toolArgs: data.args,
+					toolResult: data.result,
+					displayText,
+					duration: data.duration,
+				}
+			}
+			case 'observation':
+				return { type: 'observation', displayText: data.content }
+		}
+	}
+
+	#getToolExecutingText(toolName: string, args: any): string {
+		switch (toolName) {
+			case 'click_element_by_index':
+				return this.#i18n.t('ui.tools.clicking', { index: args.index })
+			case 'input_text':
+				return this.#i18n.t('ui.tools.inputting', { index: args.index })
+			case 'select_dropdown_option':
+				return this.#i18n.t('ui.tools.selecting', { text: args.text })
+			case 'scroll':
+				return this.#i18n.t('ui.tools.scrolling')
+			case 'wait':
+				return this.#i18n.t('ui.tools.waiting', { seconds: args.seconds })
+			case 'done':
+				return this.#i18n.t('ui.tools.done')
+			default:
+				return this.#i18n.t('ui.tools.executing', { toolName })
+		}
+	}
+
+	#getToolCompletedText(toolName: string, args: any): string | null {
+		switch (toolName) {
+			case 'click_element_by_index':
+				return this.#i18n.t('ui.tools.clicked', { index: args.index })
+			case 'input_text':
+				return this.#i18n.t('ui.tools.inputted', { text: args.text })
+			case 'select_dropdown_option':
+				return this.#i18n.t('ui.tools.selected', { text: args.text })
+			case 'scroll':
+				return this.#i18n.t('ui.tools.scrolled')
+			case 'wait':
+				return this.#i18n.t('ui.tools.waited')
+			case 'done':
+				return null
+			default:
+				return null
+		}
+	}
+
+	/**
+	 * Update status (internal)
+	 */
+	#updateInternal(stepData: Omit<Step, 'id' | 'stepNumber' | 'timestamp'>): void {
+		// Skip empty displayText (filtered toolCompleted for 'done')
+		if (!stepData.displayText) return
+
 		const step = this.#state.addStep(stepData)
 
 		// Queue header text update (will be processed by periodic check)
@@ -120,88 +278,17 @@ export class Panel {
 		}
 	}
 
-	/**
-	 * Show panel
-	 */
-	#show(): void {
-		this.wrapper.style.display = 'block'
-		// Force reflow to trigger animation
-		void this.wrapper.offsetHeight
-		this.wrapper.style.opacity = '1'
-		this.wrapper.style.transform = 'translateX(-50%) translateY(0)'
-	}
-
-	/**
-	 * Hide panel
-	 */
-	#hide(): void {
-		this.wrapper.style.opacity = '0'
-		this.wrapper.style.transform = 'translateX(-50%) translateY(20px)'
-		this.wrapper.style.display = 'none'
-	}
-
-	/**
-	 * Reset state
-	 */
-	#reset(): void {
-		this.#state.reset()
-		this.#statusText.textContent = this.#pageAgent.i18n.t('ui.panel.ready')
-		this.#updateStatusIndicator('thinking')
-		this.#updateHistory()
-		this.#collapse()
-		// Reset pause state
-		this.#pageAgent.paused = false
-		this.#updatePauseButton()
-		// Reset user input state
-		this.#isWaitingForUserAnswer = false
-		this.#userAnswerResolver = null
-		// Show input area
-		this.#showInputArea()
-	}
-
-	/**
-	 * Toggle pause state
-	 */
-	#togglePause(): void {
-		this.#pageAgent.paused = !this.#pageAgent.paused
-		this.#updatePauseButton()
-
-		// Update status display
-		if (this.#pageAgent.paused) {
-			this.#statusText.textContent = this.#pageAgent.i18n.t('ui.panel.paused')
-			this.#updateStatusIndicator('thinking') // Use existing thinking state
-		} else {
-			this.#statusText.textContent = this.#pageAgent.i18n.t('ui.panel.continueExecution')
-			this.#updateStatusIndicator('tool_executing') // Restore to execution state
-		}
-	}
-
-	/**
-	 * Update pause button state
-	 */
-	#updatePauseButton(): void {
-		if (this.#pageAgent.paused) {
-			this.#pauseButton.textContent = '▶'
-			this.#pauseButton.title = this.#pageAgent.i18n.t('ui.panel.continue')
-			this.#pauseButton.classList.add(styles.paused)
-		} else {
-			this.#pauseButton.textContent = '⏸︎'
-			this.#pauseButton.title = this.#pageAgent.i18n.t('ui.panel.pause')
-			this.#pauseButton.classList.remove(styles.paused)
-		}
-	}
-
 	/**
 	 * Stop Agent
 	 */
 	#stopAgent(): void {
 		// Update status display
-		this.#update({
+		this.#updateInternal({
 			type: 'error',
-			displayText: this.#pageAgent.i18n.t('ui.panel.taskTerminated'),
+			displayText: this.#i18n.t('ui.panel.taskTerminated'),
 		})
 
-		this.#pageAgent.dispose()
+		this.#config.onStop()
 	}
 
 	/**
@@ -218,7 +305,7 @@ export class Panel {
 			// Handle user input mode
 			this.#handleUserAnswer(input)
 		} else {
-			this.#pageAgent.execute(input)
+			this.#config.onExecuteTask(input)
 		}
 	}
 
@@ -227,9 +314,9 @@ export class Panel {
 	 */
 	#handleUserAnswer(input: string): void {
 		// Add user input to history
-		this.#update({
+		this.#updateInternal({
 			type: 'input',
-			displayText: this.#pageAgent.i18n.t('ui.panel.userAnswer', { input }),
+			displayText: this.#i18n.t('ui.panel.userAnswer', { input }),
 		})
 
 		// Reset state
@@ -248,7 +335,7 @@ export class Panel {
 	#showInputArea(placeholder?: string): void {
 		// Clear input field
 		this.#taskInput.value = ''
-		this.#taskInput.placeholder = placeholder || this.#pageAgent.i18n.t('ui.panel.taskInput')
+		this.#taskInput.placeholder = placeholder || this.#i18n.t('ui.panel.taskInput')
 		this.#inputSection.classList.remove(styles.hidden)
 		// Focus on input field
 		setTimeout(() => {
@@ -276,13 +363,20 @@ export class Panel {
 		}
 
 		const lastStep = steps[steps.length - 1]
-		return lastStep.type === 'completed' || lastStep.type === 'error'
+		const isTaskEnded = lastStep.type === 'completed' || lastStep.type === 'error'
+
+		// Only show input area after task completion if configured to do so
+		if (isTaskEnded) {
+			return this.#config.promptForNextTask ?? true
+		}
+
+		return false
 	}
 
 	#createWrapper(): HTMLElement {
 		const wrapper = document.createElement('div')
 		wrapper.id = 'page-agent-runtime_agent-panel'
-		wrapper.className = `${styles.wrapper} ${styles.collapsed}`
+		wrapper.className = styles.wrapper
 		wrapper.setAttribute('data-browser-use-ignore', 'true')
 
 		wrapper.innerHTML = `
@@ -294,23 +388,20 @@ export class Panel {
 						stepNumber: 0,
 						timestamp: new Date(),
 						type: 'thinking',
-						displayText: this.#pageAgent.i18n.t('ui.panel.waitingPlaceholder'),
+						displayText: this.#i18n.t('ui.panel.waitingPlaceholder'),
 					})}
 				</div>
 			</div>
 			<div class="${styles.header}">
 				<div class="${styles.statusSection}">
 					<div class="${styles.indicator} ${styles.thinking}"></div>
-					<div class="${styles.statusText}">${this.#pageAgent.i18n.t('ui.panel.ready')}</div>
+					<div class="${styles.statusText}">${this.#i18n.t('ui.panel.ready')}</div>
 				</div>
 				<div class="${styles.controls}">
-					<button class="${styles.controlButton} ${styles.expandButton}" title="${this.#pageAgent.i18n.t('ui.panel.expand')}">
+					<button class="${styles.controlButton} ${styles.expandButton}" title="${this.#i18n.t('ui.panel.expand')}">
 						▼
 					</button>
-					<button class="${styles.controlButton} ${styles.pauseButton}" title="${this.#pageAgent.i18n.t('ui.panel.pause')}">
+					<button class="${styles.controlButton} ${styles.stopButton}" title="${this.#i18n.t('ui.panel.stop')}">
-						⏸︎
-					</button>
-					<button class="${styles.controlButton} ${styles.stopButton}" title="${this.#pageAgent.i18n.t('ui.panel.stop')}">
 						X
 					</button>
 				</div>
@@ -347,12 +438,6 @@ export class Panel {
 			this.#toggle()
 		})
 
-		// Pause/continue button
-		this.#pauseButton.addEventListener('click', (e) => {
-			e.stopPropagation()
-			this.#togglePause()
-		})
-
 		// Stop button
 		this.#stopButton.addEventListener('click', (e) => {
 			e.stopPropagation()
@@ -384,7 +469,6 @@ export class Panel {
 
 	#expand(): void {
 		this.#isExpanded = true
-		this.wrapper.classList.remove(styles.collapsed)
 		this.wrapper.classList.add(styles.expanded)
 		this.#expandButton.textContent = '▲'
 	}
@@ -392,7 +476,6 @@ export class Panel {
 	#collapse(): void {
 		this.#isExpanded = false
 		this.wrapper.classList.remove(styles.expanded)
-		this.wrapper.classList.add(styles.collapsed)
 		this.#expandButton.textContent = '▼'
 	}
 
@@ -471,10 +554,7 @@ export class Panel {
 
 	#updateHistory(): void {
 		const steps = this.#state.getAllSteps()
-
 		this.#historySection.innerHTML = steps.map((step) => this.#createHistoryItem(step)).join('')
-
-		// Scroll to bottom to show latest records
 		this.#scrollToBottom()
 	}
 
@@ -501,8 +581,8 @@ export class Panel {
 			// Check if this is a result from done tool
 			if (step.toolName === 'done') {
 				// Judge success or failure based on result
-				const failureKeyword = this.#pageAgent.i18n.t('ui.tools.resultFailure')
+				const failureKeyword = this.#i18n.t('ui.tools.resultFailure')
-				const errorKeyword = this.#pageAgent.i18n.t('ui.tools.resultError')
+				const errorKeyword = this.#i18n.t('ui.tools.resultError')
 				const isSuccess =
 					!step.toolResult ||
 					(!step.toolResult.includes(failureKeyword) && !step.toolResult.includes(errorKeyword))
@@ -516,7 +596,7 @@ export class Panel {
 			typeClass = styles.error
 			statusIcon = '❌'
 		} else if (step.type === 'tool_executing') {
-			statusIcon = '⚙️'
+			statusIcon = '🔨'
 		} else if (step.type === 'output') {
 			typeClass = styles.output
 			statusIcon = '🤖'
@@ -526,12 +606,15 @@ export class Panel {
 		} else if (step.type === 'retry') {
 			typeClass = styles.retry
 			statusIcon = '🔄'
+		} else if (step.type === 'observation') {
+			typeClass = styles.observation
+			statusIcon = '👁️'
 		} else {
 			statusIcon = '🧠'
 		}
 
 		const durationText = step.duration ? ` · ${step.duration}ms` : ''
-		const stepLabel = this.#pageAgent.i18n.t('ui.panel.step', {
+		const stepLabel = this.#i18n.t('ui.panel.step', {
 			number: step.stepNumber.toString(),
 			time,
 			duration: durationText || '', // Explicitly pass empty string to replace template
@@ -541,7 +624,7 @@ export class Panel {
 			<div class="${styles.historyItem} ${typeClass}">
 				<div class="${styles.historyContent}">
 					<span class="${styles.statusIcon}">${statusIcon}</span>
-					<span>${step.displayText}</span>
+					<span>${escapeHtml(step.displayText)}</span>
 				</div>
 				<div class="${styles.historyMeta}">
 					${stepLabel}
@@ -550,47 +633,3 @@ export class Panel {
 		`
 	}
 }
-
-/**
- * Get display text for tool execution
- */
-export function getToolExecutingText(toolName: string, args: any, i18n: I18n): string {
-	switch (toolName) {
-		case 'click_element_by_index':
-			return i18n.t('ui.tools.clicking', { index: args.index })
-		case 'input_text':
-			return i18n.t('ui.tools.inputting', { index: args.index })
-		case 'select_dropdown_option':
-			return i18n.t('ui.tools.selecting', { text: args.text })
-		case 'scroll':
-			return i18n.t('ui.tools.scrolling')
-		case 'wait':
-			return i18n.t('ui.tools.waiting', { seconds: args.seconds })
-		case 'done':
-			return i18n.t('ui.tools.done')
-		default:
-			return i18n.t('ui.tools.executing', { toolName })
-	}
-}
-
-/**
- * Get display text for tool completion
- */
-export function getToolCompletedText(toolName: string, args: any, i18n: I18n): string | null {
-	switch (toolName) {
-		case 'click_element_by_index':
-			return i18n.t('ui.tools.clicked', { index: args.index })
-		case 'input_text':
-			return i18n.t('ui.tools.inputted', { text: args.text })
-		case 'select_dropdown_option':
-			return i18n.t('ui.tools.selected', { text: args.text })
-		case 'scroll':
-			return i18n.t('ui.tools.scrolled')
-		case 'wait':
-			return i18n.t('ui.tools.waited')
-		case 'done':
-			return null
-		default:
-			return null
-	}
-}

packages/ui/src/UIState.ts

@@ -6,7 +6,15 @@ export interface Step {
 	id: string
 	stepNumber: number
 	timestamp: Date
-	type: 'thinking' | 'tool_executing' | 'completed' | 'error' | 'output' | 'input' | 'retry'
+	type:
+		| 'thinking'
+		| 'tool_executing'
+		| 'completed'
+		| 'error'
+		| 'output'
+		| 'input'
+		| 'retry'
+		| 'observation'
 
 	// Tool execution related
 	toolName?: string
@@ -18,7 +26,7 @@ export interface Step {
 	duration?: number
 }
 
-export type AgentStatus = 'idle' | 'running' | 'paused' | 'completed' | 'error'
+export type AgentStatus = 'idle' | 'running' | 'completed' | 'error'
 
 export class UIState {
 	private steps: Step[] = []

packages/ui/src/env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="vite/client" />
+
+declare module '*.module.css' {
+	const classes: Record<string, string>
+	export default classes
+}

packages/ui/src/i18n/index.ts

@@ -12,7 +12,7 @@ export class I18n {
 
 	constructor(language: SupportedLanguage = 'en-US') {
 		this.language = language in locales ? language : 'en-US'
-		this.translations = locales[language]
+		this.translations = locales[this.language]
 	}
 
 	// 类型安全的翻译方法

packages/ui/src/i18n/locales.ts

@@ -4,17 +4,13 @@ const enUS = {
 		panel: {
 			ready: 'Ready',
 			thinking: 'Thinking...',
-			paused: 'Paused',
 			taskInput: 'Enter new task, describe steps in detail, press Enter to submit',
 			userAnswerPrompt: 'Please answer the question above, press Enter to submit',
 			taskTerminated: 'Task terminated',
 			taskCompleted: 'Task completed',
-			continueExecution: 'Continue execution',
 			userAnswer: 'User answer: {{input}}',
 			question: 'Question: {{question}}',
 			waitingPlaceholder: 'Waiting for task to start...',
-			pause: 'Pause',
-			continue: 'Continue',
 			stop: 'Stop',
 			expand: 'Expand history',
 			collapse: 'Collapse history',
@@ -54,17 +50,13 @@ const zhCN = {
 		panel: {
 			ready: '准备就绪',
 			thinking: '正在思考...',
-			paused: '暂停中，稍后',
 			taskInput: '输入新任务，详细描述步骤，回车提交',
 			userAnswerPrompt: '请回答上面问题，回车提交',
 			taskTerminated: '任务已终止',
 			taskCompleted: '任务结束',
-			continueExecution: '继续执行',
 			userAnswer: '用户回答: {{input}}',
 			question: '询问: {{question}}',
 			waitingPlaceholder: '等待任务开始...',
-			pause: '暂停',
-			continue: '继续',
 			stop: '终止',
 			expand: '展开历史',
 			collapse: '收起历史',

packages/ui/src/index.ts

@@ -0,0 +1,3 @@
+export { Panel, type PanelConfig, type PanelUpdate } from './Panel'
+export { UIState, type Step, type AgentStatus } from './UIState'
+export { I18n, type SupportedLanguage, type TranslationKey } from './i18n'

packages/ui/src/motion-css/readme

@@ -2,4 +2,4 @@ This is the CSS implementation of ai-motion.
 
 Easy to use but Terrible performance. Causing full screen glitching in some browsers.
 
-Use it only in a small area.
+Use it only in a small area.

packages/ui/src/utils.ts

@@ -0,0 +1,18 @@
+export function truncate(text: string, maxLength: number): string {
+	if (text.length > maxLength) {
+		return text.substring(0, maxLength) + '...'
+	}
+	return text
+}
+
+/**
+ * Escape HTML special characters to prevent XSS and rendering issues
+ */
+export function escapeHtml(text: string): string {
+	return text
+		.replace(/&/g, '&')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#039;')
+}

packages/ui/tsconfig.dts.json

@@ -0,0 +1,9 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        // @workaround DTS bug
+        // dts do not work with monorepo path mapping
+        // disable path mapping for it
+        "paths": {}
+    }
+}

packages/ui/tsconfig.json

@@ -0,0 +1,12 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
+        "noEmit": false,
+        "allowImportingTsExtensions": false,
+        "baseUrl": ".",
+        "outDir": "dist"
+    },
+    "include": ["**/*.ts", "**/*.js"],
+    "exclude": ["dist", "node_modules"]
+}

packages/ui/vite.config.js

@@ -0,0 +1,41 @@
+// @ts-check
+import chalk from 'chalk'
+import { dirname, resolve } from 'path'
+import dts from 'unplugin-dts/vite'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+console.log(chalk.cyan(`📦 Building @page-agent/ui`))
+
+export default defineConfig({
+	clearScreen: false,
+	plugins: [
+		dts({ tsconfigPath: './tsconfig.dts.json', bundleTypes: true }),
+		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
+	],
+	publicDir: false,
+	esbuild: {
+		keepNames: true,
+	},
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/index.ts'),
+			name: 'PageAgentUI',
+			fileName: 'page-agent-ui',
+			formats: ['es'],
+		},
+		outDir: resolve(__dirname, 'dist', 'lib'),
+		rollupOptions: {
+			external: [],
+		},
+		minify: false,
+		sourcemap: true,
+		cssCodeSplit: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})

packages/website/AGENTS.md

@@ -0,0 +1,110 @@
+# Website Package - Instructions for Coding Assistants
+
+## Tech Stack
+
+- **React** with TypeScript
+- **Vite** for dev server and build
+- **Tailwind CSS** for styling
+- **shadcn/ui** (new-york style) for UI components
+- **Magic UI** for animations and effects
+- **wouter** with hash routing for static hosting
+- **lucide-react** for icons
+
+## Component Guidelines
+
+### Use shadcn/ui Components First
+
+**ALWAYS prefer shadcn/ui components over custom implementations.**
+
+Before creating any UI component, check if shadcn already provides it:
+
+```bash
+# IMPORTANT: Run from packages/website/, NOT from repo root
+cd packages/website
+
+# Add a new shadcn component
+npx shadcn@latest add <component-name>
+
+# Add a Magic UI component
+npx shadcn@latest add "@magicui/<component-name>"
+```
+
+Available shadcn components: https://ui.shadcn.com/docs/components
+Available Magic UI components: https://magicui.design/docs/components
+
+### Current UI Components
+
+Located in `src/components/ui/`:
+
+**From shadcn/ui:**
+
+- `alert`, `badge`, `button`, `separator`, `sonner`, `switch`, `tooltip`
+
+**From Magic UI:**
+
+- `animated-gradient-text`, `animated-shiny-text`, `aurora-text`
+- `hyper-text`, `magic-card`, `neon-gradient-card`, `particles`
+- `sparkles-text`, `text-animate`, `typing-animation`
+
+**Custom:**
+
+- `highlighter`, `kbd`, `spinner`
+
+### Styling Rules
+
+1. **Prefer Tailwind classes** over custom CSS
+2. Use CSS modules only for complex component-specific styles
+3. Support dark mode via `dark:` classes
+4. Use CSS variables from `src/index.css` for theme colors
+
+## Project Structure
+
+```
+src/
+├── pages/
+│   ├── Home.tsx         # Homepage
+│   └── docs/
+│       ├── Layout.tsx   # Documentation sidebar
+│       └── [section]/[topic]/page.tsx
+├── components/
+│   ├── ui/              # shadcn/ui + Magic UI components
+│   ├── Header.tsx       # Site header
+│   └── Footer.tsx       # Site footer
+├── i18n/                # Internationalization
+├── router.tsx           # Central routing
+└── main.tsx             # App entry
+```
+
+## Adding New Pages
+
+### Documentation Page
+
+1. Create `src/pages/docs/<section>/<slug>/page.tsx`
+2. Add route to `src/router.tsx` with `<Header /> + <DocsLayout>` wrapper
+3. Add navigation item to `pages/docs/Layout.tsx`
+
+## Routing
+
+Uses hash-based routing for static hosting:
+
+```tsx
+import { Router } from 'wouter'
+import { useHashLocation } from 'wouter/use-hash-location'
+
+;<Router hook={useHashLocation}>{/* routes */}</Router>
+```
+
+## Configuration Files
+
+| File              | Purpose                 |
+| ----------------- | ----------------------- |
+| `components.json` | shadcn/ui configuration |
+| `vite.config.js`  | Vite build settings     |
+| `tsconfig.json`   | TypeScript config       |
+
+## Commands
+
+```bash
+npm start        # Dev server (from root)
+npm run build:website    # Build website (from root)
+```

packages/website/README.md

@@ -1 +0,0 @@
-# Landing Page & Docs

packages/website/components.json

@@ -0,0 +1,24 @@
+{
+    "$schema": "https://ui.shadcn.com/schema.json",
+    "style": "new-york",
+    "rsc": false,
+    "tsx": true,
+    "tailwind": {
+        "config": "",
+        "css": "src/index.css",
+        "baseColor": "neutral",
+        "cssVariables": true,
+        "prefix": ""
+    },
+    "iconLibrary": "lucide",
+    "aliases": {
+        "components": "@/components",
+        "utils": "@/lib/utils",
+        "ui": "@/components/ui",
+        "lib": "@/lib",
+        "hooks": "@/hooks"
+    },
+    "registries": {
+        "@magicui": "https://magicui.design/r/{name}.json"
+    }
+}

packages/website/package.json

@@ -1,28 +1,42 @@
 {
 	"name": "@page-agent/website",
 	"private": true,
-	"version": "0.0.5",
+	"version": "0.2.5",
 	"type": "module",
 	"scripts": {
-		"dev": "vite",
+		"dev": "vite --host 0.0.0.0",
-		"build": "vite build",
+		"build:website": "vite build",
 		"preview": "vite preview",
 		"typecheck": "tsc --noEmit"
 	},
-	"dependencies": {
-		"page-agent": "*"
-	},
 	"devDependencies": {
-		"@tailwindcss/vite": "^4.1.14",
+		"@tailwindcss/vite": "^4.1.18",
-		"@types/react": "^19.2.2",
+		"@types/react": "^19.2.8",
 		"@types/react-dom": "^19.2.1",
 		"@vitejs/plugin-react-swc": "^4.1.0",
-		"i18next": "^25.6.0",
+		"i18next": "^25.7.4",
 		"i18next-browser-languagedetector": "^8.2.0",
-		"react": "^19.2.0",
+		"react": "^19.2.3",
-		"react-dom": "^19.2.0",
+		"react-dom": "^19.2.3",
-		"react-i18next": "^16.1.4",
+		"react-i18next": "^16.5.2",
 		"tailwindcss": "^4.1.14",
-		"wouter": "^3.7.1"
+		"tw-animate-css": "^1.4.0",
+		"wouter": "^3.9.0"
+	},
+	"dependencies": {
+		"@radix-ui/react-icons": "^1.3.2",
+		"@radix-ui/react-separator": "^1.1.8",
+		"@radix-ui/react-slot": "^1.2.4",
+		"@radix-ui/react-switch": "^1.2.6",
+		"@radix-ui/react-tooltip": "^1.2.8",
+		"class-variance-authority": "^0.7.1",
+		"clsx": "^2.1.1",
+		"lucide-react": "^0.562.0",
+		"motion": "^12.26.1",
+		"next-themes": "^0.4.6",
+		"rough-notation": "^0.5.1",
+		"simple-icons": "^16.5.0",
+		"sonner": "^2.0.7",
+		"tailwind-merge": "^3.4.0"
 	}
 }

packages/website/src/components/Footer.tsx

@@ -1,4 +1,5 @@
 import { useTranslation } from 'react-i18next'
+import { siGithub } from 'simple-icons'
 
 export default function Footer() {
 	const { t } = useTranslation('common')
@@ -19,8 +20,13 @@ export default function Footer() {
 							className="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-white transition-colors duration-200"
 							aria-label={t('footer.github_label')}
 						>
-							<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+							<svg
-								<path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z" />
+								role="img"
+								viewBox="0 0 24 24"
+								className="w-5 h-5 fill-current"
+								aria-hidden="true"
+							>
+								<path d={siGithub.path} />
 							</svg>
 						</a>
 					</div>

packages/website/src/components/Header.tsx

@@ -1,10 +1,12 @@
+import { BookOpen, Menu, X } from 'lucide-react'
 import { useState } from 'react'
 import { useTranslation } from 'react-i18next'
+import { siGithub } from 'simple-icons'
 import { Link } from 'wouter'
 
 import LanguageSwitcher from './LanguageSwitcher'
 import ThemeSwitcher from './ThemeSwitcher'
-import { BookIcon, CloseIcon, GithubIcon, MenuIcon } from './icons'
+import { HyperText } from './ui/hyper-text'
 
 export default function Header() {
 	const { t } = useTranslation('common')
@@ -20,7 +22,7 @@ export default function Header() {
 					<div className="flex items-center justify-between gap-2">
 						{/* Logo */}
 						<Link
-							href="/"
+							href="~/"
 							className="flex items-center gap-2 sm:gap-3 group shrink-0"
 							aria-label={t('header.logo_alt')}
 							onClick={() => setMobileMenuOpen(false)}
@@ -34,9 +36,15 @@ export default function Header() {
 								<span className="text-base sm:text-xl font-bold text-gray-900 dark:text-white block leading-tight">
 									page-agent
 								</span>
-								<p className="hidden sm:block text-xs text-gray-600 dark:text-gray-300">
+								<HyperText
+									as="p"
+									className="hidden sm:block text-xs text-gray-600 dark:text-gray-300 py-0 font-normal overflow-visible"
+									duration={600}
+									animateOnHover={true}
+									aria-hidden="true"
+								>
 									{t('header.slogan')}
-								</p>
+								</HyperText>
 							</div>
 						</Link>
 
@@ -47,11 +55,11 @@ export default function Header() {
 							aria-label="Mobile navigation"
 						>
 							<Link
-								href="/docs/introduction/overview"
+								href="~/docs/introduction/overview"
 								className="p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200 shrink-0"
 								aria-label={t('header.nav_docs')}
 							>
-								<BookIcon className="w-5 h-5" />
+								<BookOpen className="w-5 h-5" />
 							</Link>
 							<a
 								href="https://github.com/alibaba/page-agent"
@@ -60,7 +68,14 @@ export default function Header() {
 								className="p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200 shrink-0"
 								aria-label={t('header.nav_source')}
 							>
-								<GithubIcon className="w-5 h-5" />
+								<svg
+									role="img"
+									viewBox="0 0 24 24"
+									className="w-5 h-5 fill-current"
+									aria-hidden="true"
+								>
+									<path d={siGithub.path} />
+								</svg>
 							</a>
 						</nav>
 
@@ -70,11 +85,14 @@ export default function Header() {
 							role="navigation"
 							aria-label={t('header.nav_docs')}
 						>
+							<span className="text-xs font-mono text-gray-400 dark:text-gray-500 tabular-nums before:content-['v']">
+								{import.meta.env.VERSION}
+							</span>
 							<Link
-								href="/docs/introduction/overview"
+								href="~/docs/introduction/overview"
 								className="flex items-center gap-1.5 text-gray-600 dark:text-gray-300 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
 							>
-								<BookIcon />
+								<BookOpen className="w-4 h-4" />
 								{t('header.nav_docs')}
 							</Link>
 							<a
@@ -84,7 +102,14 @@ export default function Header() {
 								className="flex items-center gap-1.5 text-gray-600 dark:text-gray-300 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
 								aria-label={t('header.nav_source')}
 							>
-								<GithubIcon />
+								<svg
+									role="img"
+									viewBox="0 0 24 24"
+									className="w-4 h-4 fill-current"
+									aria-hidden="true"
+								>
+									<path d={siGithub.path} />
+								</svg>
 								{t('header.nav_source')}
 							</a>
 							<ThemeSwitcher />
@@ -100,7 +125,7 @@ export default function Header() {
 							aria-controls="mobile-menu"
 							onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
 						>
-							{mobileMenuOpen ? <CloseIcon /> : <MenuIcon />}
+							{mobileMenuOpen ? <X className="w-6 h-6" /> : <Menu className="w-6 h-6" />}
 						</button>
 					</div>
 
@@ -112,11 +137,11 @@ export default function Header() {
 							role="navigation"
 						>
 							<Link
-								href="/docs/introduction/overview"
+								href="~/docs/introduction/overview"
 								className="flex items-center gap-2 px-3 py-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
 								onClick={() => setMobileMenuOpen(false)}
 							>
-								<BookIcon className="w-5 h-5" />
+								<BookOpen className="w-5 h-5" />
 								{t('header.nav_docs')}
 							</Link>
 							<a
@@ -126,7 +151,14 @@ export default function Header() {
 								className="flex items-center gap-2 px-3 py-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
 								aria-label={t('header.nav_source')}
 							>
-								<GithubIcon className="w-5 h-5" />
+								<svg
+									role="img"
+									viewBox="0 0 24 24"
+									className="w-5 h-5 fill-current"
+									aria-hidden="true"
+								>
+									<path d={siGithub.path} />
+								</svg>
 								{t('header.nav_source')}
 							</a>
 							<div className="flex items-center gap-3 px-3 py-2">

packages/website/src/components/icons.tsx

@@ -1,75 +0,0 @@
-// SVG图标组件集合，用于Header等地方复用
-
-interface IconProps {
-	className?: string
-	'aria-hidden'?: boolean
-}
-
-export function BookIcon({ className = 'w-4 h-4', ...props }: IconProps) {
-	return (
-		<svg
-			className={className}
-			fill="none"
-			stroke="currentColor"
-			viewBox="0 0 24 24"
-			aria-hidden="true"
-			{...props}
-		>
-			<path
-				strokeLinecap="round"
-				strokeLinejoin="round"
-				strokeWidth={2}
-				d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 5c1.747 0 3.332.477 4.5 1.253v13C19.832 18.477 18.247 18 16.5 18c-1.746 0-3.332.477-4.5 1.253"
-			/>
-		</svg>
-	)
-}
-
-export function GithubIcon({ className = 'w-4 h-4', ...props }: IconProps) {
-	return (
-		<svg
-			className={className}
-			fill="currentColor"
-			viewBox="0 0 24 24"
-			aria-hidden="true"
-			{...props}
-		>
-			<path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z" />
-		</svg>
-	)
-}
-
-export function MenuIcon({ className = 'w-6 h-6', ...props }: IconProps) {
-	return (
-		<svg
-			className={className}
-			fill="none"
-			stroke="currentColor"
-			viewBox="0 0 24 24"
-			aria-hidden="true"
-			{...props}
-		>
-			<path
-				strokeLinecap="round"
-				strokeLinejoin="round"
-				strokeWidth={2}
-				d="M4 6h16M4 12h16M4 18h16"
-			/>
-		</svg>
-	)
-}
-
-export function CloseIcon({ className = 'w-6 h-6', ...props }: IconProps) {
-	return (
-		<svg
-			className={className}
-			fill="none"
-			stroke="currentColor"
-			viewBox="0 0 24 24"
-			aria-hidden="true"
-			{...props}
-		>
-			<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-		</svg>
-	)
-}

packages/website/src/components/ui/alert.tsx

@@ -0,0 +1,60 @@
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+const alertVariants = cva(
+	'relative w-full rounded-lg border px-4 py-3 text-sm grid has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] grid-cols-[0_1fr] has-[>svg]:gap-x-3 gap-y-0.5 items-start [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current',
+	{
+		variants: {
+			variant: {
+				default: 'bg-card text-card-foreground',
+				destructive:
+					'text-destructive bg-card [&>svg]:text-current *:data-[slot=alert-description]:text-destructive/90',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+		},
+	}
+)
+
+function Alert({
+	className,
+	variant,
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof alertVariants>) {
+	return (
+		<div
+			data-slot="alert"
+			role="alert"
+			className={cn(alertVariants({ variant }), className)}
+			{...props}
+		/>
+	)
+}
+
+function AlertTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="alert-title"
+			className={cn('col-start-2 line-clamp-1 min-h-4 font-medium tracking-tight', className)}
+			{...props}
+		/>
+	)
+}
+
+function AlertDescription({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="alert-description"
+			className={cn(
+				'text-muted-foreground col-start-2 grid justify-items-start gap-1 text-sm [&_p]:leading-relaxed',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export { Alert, AlertTitle, AlertDescription }

packages/website/src/components/ui/animated-gradient-text.tsx

@@ -0,0 +1,37 @@
+import { ComponentPropsWithoutRef } from 'react'
+
+import { cn } from '@/lib/utils'
+
+export interface AnimatedGradientTextProps extends ComponentPropsWithoutRef<'div'> {
+	speed?: number
+	colorFrom?: string
+	colorTo?: string
+}
+
+export function AnimatedGradientText({
+	children,
+	className,
+	speed = 1,
+	colorFrom = '#ffaa40',
+	colorTo = '#9c40ff',
+	...props
+}: AnimatedGradientTextProps) {
+	return (
+		<span
+			style={
+				{
+					'--bg-size': `${speed * 300}%`,
+					'--color-from': colorFrom,
+					'--color-to': colorTo,
+				} as React.CSSProperties
+			}
+			className={cn(
+				`animate-gradient inline bg-gradient-to-r from-[var(--color-from)] via-[var(--color-to)] to-[var(--color-from)] bg-[length:var(--bg-size)_100%] bg-clip-text text-transparent`,
+				className
+			)}
+			{...props}
+		>
+			{children}
+		</span>
+	)
+}

packages/website/src/components/ui/animated-shiny-text.tsx

@@ -0,0 +1,38 @@
+import { CSSProperties, ComponentPropsWithoutRef, FC } from 'react'
+
+import { cn } from '@/lib/utils'
+
+export interface AnimatedShinyTextProps extends ComponentPropsWithoutRef<'span'> {
+	shimmerWidth?: number
+}
+
+export const AnimatedShinyText: FC<AnimatedShinyTextProps> = ({
+	children,
+	className,
+	shimmerWidth = 100,
+	...props
+}) => {
+	return (
+		<span
+			style={
+				{
+					'--shiny-width': `${shimmerWidth}px`,
+				} as CSSProperties
+			}
+			className={cn(
+				'mx-auto max-w-md text-neutral-600/70 dark:text-neutral-400/70',
+
+				// Shine effect
+				'animate-shiny-text [background-size:var(--shiny-width)_100%] bg-clip-text [background-position:0_0] bg-no-repeat [transition:background-position_1s_cubic-bezier(.6,.6,0,1)_infinite]',
+
+				// Shine gradient
+				'bg-gradient-to-r from-transparent via-black/80 via-50% to-transparent dark:via-white/80',
+
+				className
+			)}
+			{...props}
+		>
+			{children}
+		</span>
+	)
+}

packages/website/src/components/ui/aurora-text.tsx

@@ -0,0 +1,39 @@
+import React, { memo } from 'react'
+
+interface AuroraTextProps {
+	children: React.ReactNode
+	className?: string
+	colors?: string[]
+	speed?: number
+}
+
+export const AuroraText = memo(
+	({
+		children,
+		className = '',
+		colors = ['#FF0080', '#7928CA', '#0070F3', '#38bdf8'],
+		speed = 1,
+	}: AuroraTextProps) => {
+		const gradientStyle = {
+			backgroundImage: `linear-gradient(135deg, ${colors.join(', ')}, ${colors[0]})`,
+			WebkitBackgroundClip: 'text',
+			WebkitTextFillColor: 'transparent',
+			animationDuration: `${10 / speed}s`,
+		}
+
+		return (
+			<span className={`relative inline-block ${className}`}>
+				<span className="sr-only">{children}</span>
+				<span
+					className="animate-aurora relative bg-[length:200%_auto] bg-clip-text text-transparent"
+					style={gradientStyle}
+					aria-hidden="true"
+				>
+					{children}
+				</span>
+			</span>
+		)
+	}
+)
+
+AuroraText.displayName = 'AuroraText'

packages/website/src/components/ui/badge.tsx

@@ -0,0 +1,37 @@
+import { Slot } from '@radix-ui/react-slot'
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+const badgeVariants = cva(
+	'inline-flex items-center justify-center rounded-full border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden',
+	{
+		variants: {
+			variant: {
+				default: 'border-transparent bg-primary text-primary-foreground [a&]:hover:bg-primary/90',
+				secondary:
+					'border-transparent bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90',
+				destructive:
+					'border-transparent bg-destructive text-white [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60',
+				outline: 'text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+		},
+	}
+)
+
+function Badge({
+	className,
+	variant,
+	asChild = false,
+	...props
+}: React.ComponentProps<'span'> & VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
+	const Comp = asChild ? Slot : 'span'
+
+	return <Comp data-slot="badge" className={cn(badgeVariants({ variant }), className)} {...props} />
+}
+
+export { Badge, badgeVariants }

packages/website/src/components/ui/bento-grid.tsx

@@ -0,0 +1,91 @@
+import { ArrowRightIcon } from '@radix-ui/react-icons'
+import { ComponentPropsWithoutRef, ReactNode } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { cn } from '@/lib/utils'
+
+interface BentoGridProps extends ComponentPropsWithoutRef<'div'> {
+	children: ReactNode
+	className?: string
+}
+
+interface BentoCardProps extends ComponentPropsWithoutRef<'div'> {
+	name: string
+	className: string
+	background: ReactNode
+	Icon: React.ElementType
+	description: string
+	href: string
+	cta: string
+}
+
+const BentoGrid = ({ children, className, ...props }: BentoGridProps) => {
+	return (
+		<div className={cn('grid w-full auto-rows-[22rem] grid-cols-3 gap-4', className)} {...props}>
+			{children}
+		</div>
+	)
+}
+
+const BentoCard = ({
+	name,
+	className,
+	background,
+	Icon,
+	description,
+	href,
+	cta,
+	...props
+}: BentoCardProps) => (
+	<div
+		key={name}
+		className={cn(
+			'group relative col-span-3 flex flex-col justify-between overflow-hidden rounded-xl',
+			// light styles
+			'bg-background [box-shadow:0_0_0_1px_rgba(0,0,0,.03),0_2px_4px_rgba(0,0,0,.05),0_12px_24px_rgba(0,0,0,.05)]',
+			// dark styles
+			'dark:bg-background transform-gpu dark:[box-shadow:0_-20px_80px_-20px_#ffffff1f_inset] dark:[border:1px_solid_rgba(255,255,255,.1)]',
+			className
+		)}
+		{...props}
+	>
+		<div>{background}</div>
+		<div className="p-4">
+			<div className="pointer-events-none z-10 flex transform-gpu flex-col gap-1 transition-all duration-300 lg:group-hover:-translate-y-10">
+				<Icon className="h-12 w-12 origin-left transform-gpu text-neutral-700 transition-all duration-300 ease-in-out group-hover:scale-75" />
+				<h3 className="text-xl font-semibold text-neutral-700 dark:text-neutral-300">{name}</h3>
+				<p className="max-w-lg text-neutral-400">{description}</p>
+			</div>
+
+			<div
+				className={cn(
+					'pointer-events-none flex w-full translate-y-0 transform-gpu flex-row items-center transition-all duration-300 group-hover:translate-y-0 group-hover:opacity-100 lg:hidden'
+				)}
+			>
+				<Button variant="link" asChild size="sm" className="pointer-events-auto p-0">
+					<a href={href}>
+						{cta}
+						<ArrowRightIcon className="ms-2 h-4 w-4 rtl:rotate-180" />
+					</a>
+				</Button>
+			</div>
+		</div>
+
+		<div
+			className={cn(
+				'pointer-events-none absolute bottom-0 hidden w-full translate-y-10 transform-gpu flex-row items-center p-4 opacity-0 transition-all duration-300 group-hover:translate-y-0 group-hover:opacity-100 lg:flex'
+			)}
+		>
+			<Button variant="link" asChild size="sm" className="pointer-events-auto p-0">
+				<a href={href}>
+					{cta}
+					<ArrowRightIcon className="ms-2 h-4 w-4 rtl:rotate-180" />
+				</a>
+			</Button>
+		</div>
+
+		<div className="pointer-events-none absolute inset-0 transform-gpu transition-all duration-300 group-hover:bg-black/[.03] group-hover:dark:bg-neutral-800/10" />
+	</div>
+)
+
+export { BentoCard, BentoGrid }