chore(version): bump version to 0.3.0-beta.2

feat!: decouple `DOM` from `Agent`

.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/release.yml

@@ -6,7 +6,7 @@ on:
       - 'v*'
 
 permissions:
-  id-token: write  # Required for OIDC
+  id-token: write # Required for OIDC
   contents: read
 
 jobs:
@@ -24,7 +24,7 @@ jobs:
       # Ensure npm 11.5.1 or later is installed
       - name: Update npm
         run: npm install -g npm@latest
-        
+
       - name: Install dependencies
         run: npm ci
 
@@ -32,4 +32,12 @@ jobs:
         run: npm run build:libs
 
       - name: Publish all public packages
-        run: npm publish --workspaces --access public
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          if [[ "$VERSION" == *"-"* ]]; then
+            # Prerelease version (e.g., 0.3.0-beta.1) -> extract tag name before the dot
+            TAG=$(echo "$VERSION" | sed 's/.*-\([a-zA-Z]*\).*/\1/')
+            npm publish --workspaces --access public --tag "$TAG"
+          else
+            npm publish --workspaces --access public
+          fi

.vscode/extensions.json

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

.vscode/settings.json

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

AGENTS.md

@@ -4,14 +4,15 @@
 
 This is a **monorepo** with npm workspaces:
 
-- **Core Library** (`packages/page-agent/`) - AI agent for browser DOM automation, published as `page-agent` on npm
+- **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel, published as `page-agent` on npm
 - **Website** (`packages/website/`) - React docs and landing page. **When working on website, follow `packages/website/AGENTS.md`**
 
 Internal packages:
 
+- **Core** (`packages/core/`) - PageAgentCore without UI (npm: `@page-agent/core`)
 - **LLMs** (`packages/llms/`) - LLM client with reflection-before-action mental model
-- **Page Controller** (`packages/page-controller/`) - DOM operations, independent of LLM
+- **Page Controller** (`packages/page-controller/`) - DOM operations and visual feedback (SimulatorMask), independent of LLM
-- **UI** (`packages/ui/`) - Panel, SimulatorMask, i18n. Decoupled from PageAgent
+- **UI** (`packages/ui/`) - Panel and i18n. Decoupled from PageAgent
 
 ## Development Commands
 
@@ -30,7 +31,8 @@ Simple monorepo solution: TypeScript references + Vite aliases. Update tsconfig
 
 ```
 packages/
-├── page-agent/              # npm: "page-agent" ⭐ MAIN
+├── page-agent/              # npm: "page-agent" ⭐ MAIN (with Panel UI + IIFE builds)
+├── core/                    # npm: "@page-agent/core" (headless, no UI)
 ├── website/                 # @page-agent/website (private)
 ├── llms/                    # @page-agent/llms
 ├── page-controller/         # @page-agent/page-controller
@@ -41,10 +43,11 @@ packages/
 
 ### Module Boundaries
 
-- **Page Agent**: Core lib. Imports from `@page-agent/llms`, `@page-agent/page-controller`, `@page-agent/ui`
+- **Page Agent**: Main entry with UI. Extends PageAgentCore and adds Panel. Imports from `@page-agent/core`, `@page-agent/ui`
+- **Core**: PageAgentCore without UI. Imports from `@page-agent/llms`, `@page-agent/page-controller`
 - **LLMs**: LLM client with MacroToolInput contract. No dependency on page-agent
-- **UI**: Panel, Mask, i18n. No dependency on page-agent
+- **UI**: Panel and i18n. Decoupled from PageAgent via PanelAgentAdapter interface
-- **Page Controller**: Pure DOM operations. No LLM or UI dependency
+- **Page Controller**: DOM operations with optional visual feedback (SimulatorMask). No LLM dependency. Enable mask via `enableMask: true` config
 
 ### PageController ↔ PageAgent Communication
 
@@ -69,47 +72,60 @@ const pageInfo = await this.pageController.getPageInfo()
 3. **LLM Processing**: AI returns action plans (page-agent)
 4. **Indexed Operations**: PageAgent calls PageController by element index
 
-### CDN Auto-Injection
+### IIFE Builds (`packages/page-agent/dist/iife/`)
 
-Library auto-initializes via script tag:
+Two IIFE builds for script tag usage:
 
-```html
+| Build | File                 | Description                      |
-<script src="page-agent.js?model=gpt-4"></script>
+| ----- | -------------------- | -------------------------------- |
-```
+| Demo  | `page-agent.demo.js` | Auto-init with built-in test API |
+| Full  | `page-agent.js`      | Exposes `PageAgent` class only   |
 
-Query params configure `PageAgentConfig` in `src/umd.ts`.
+Demo build supports query params (e.g., `?model=gpt-4&lang=en-US`).
+
+Build with `npm run build:iife --workspace=page-agent`.
 
 ## Key Files Reference
 
 ### Page Agent (`packages/page-agent/`)
 
-| File | Description |
+| File                    | Description                                  |
-|------|-------------|
+| ----------------------- | -------------------------------------------- |
-| `src/PageAgent.ts` | ⭐ Main AI agent class |
+| `src/PageAgent.ts`      | ⭐ Main class with UI, extends PageAgentCore |
-| `src/umd.ts` | CDN/UMD entry with auto-init |
+| `src/entry-iife.ts`     | IIFE entry (exposes PageAgent class)         |
-| `src/tools/` | Tool definitions calling PageController |
+| `src/entry-iife-demo.ts`| IIFE demo entry (auto-init with demo API)    |
+
+### Core (`packages/core/`)
+
+| File                    | Description                                 |
+| ----------------------- | ------------------------------------------- |
+| `src/PageAgentCore.ts`  | ⭐ Core agent class without UI              |
+| `src/tools/`            | Tool definitions calling PageController     |
+| `src/config/`           | Configuration types and constants           |
+| `src/prompts/`          | System prompt templates                     |
 
 ### LLMs (`packages/llms/`)
 
-| File | Description |
+| File                         | Description                           |
-|------|-------------|
+| ---------------------------- | ------------------------------------- |
-| `src/index.ts` | ⭐ LLM class with retry logic |
+| `src/index.ts`               | ⭐ LLM class with retry logic         |
-| `src/types.ts` | MacroToolInput, AgentBrain, LLMConfig |
+| `src/types.ts`               | MacroToolInput, AgentBrain, LLMConfig |
-| `src/OpenAILenientClient.ts` | OpenAI-compatible client |
+| `src/OpenAILenientClient.ts` | OpenAI-compatible client              |
 
 ### Page Controller (`packages/page-controller/`)
 
-| File | Description |
+| File                        | Description                                                |
-|------|-------------|
+| --------------------------- | ---------------------------------------------------------- |
-| `src/PageController.ts` | ⭐ Main controller class |
+| `src/PageController.ts`     | ⭐ Main controller class with optional mask support        |
-| `src/actions.ts` | Element interactions (click, input, scroll) |
+| `src/SimulatorMask.ts`      | Visual overlay blocking user interaction during automation |
-| `src/dom/dom_tree/index.js` | Core DOM extraction engine |
+| `src/actions.ts`            | Element interactions (click, input, scroll)                |
+| `src/dom/dom_tree/index.js` | Core DOM extraction engine                                 |
 
 ## Adding New Features
 
 ### New Agent Tool
 
-1. Implement in `packages/page-agent/src/tools/index.ts`
+1. Implement in `packages/core/src/tools/index.ts`
 2. If tool needs DOM ops, add method to PageController first
 3. Tool calls `this.pageController.methodName()` for DOM interactions
 
@@ -123,4 +139,5 @@ Query params configure `PageAgentConfig` in `src/umd.ts`.
 
 - 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
 - All code and comments must be in English.

CONTRIBUTING.md

@@ -7,29 +7,30 @@ Thank you for your interest in contributing to Page-Agent! We welcome contributi
 ### Development Setup
 
 1. **Prerequisites**
-   - `node.js >= 20` with `npm >= 10`
+    - `node.js >= 20` with `npm >= 10`
-   - An editor that supports `ts/eslint/prettier`
+    - An editor that supports `ts/eslint/prettier`
-   - Make sure `eslint`, `prettier` and `commitlint` work well
+    - Make sure `eslint`, `prettier` and `commitlint` work well
 
 2. **Setup**
 
-   ```bash
+    ```bash
-   npm install
+    npm ci
-   npm start          # Start demo and documentation site
+    npm start          # Start demo and documentation site
-   ```
+    ```
 
 ### Project Structure
 
-This is a **monorepo** with npm workspaces containing **two main packages**:
+This is a **monorepo** with npm workspaces containing **3 main packages**:
 
-1. **Core Library** (`packages/page-agent/`) - Pure JavaScript/TypeScript AI agent library for browser DOM automation, published as `page-agent` on npm
+- **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel, 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`
+- **Core** (`packages/core/`) - Core agent logic without UI (npm: `@page-agent/core`)
+- **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 + ts reference + vite alias`. 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 `UMD` and `Website`. Bundle everything including local packages.
+- When bundling `IIFE` and `Website`. Bundle everything including local packages.
 
 ## 🤝 How to Contribute
 
@@ -44,40 +45,39 @@ We use a simplified monorepo solution with `native npm-workspace + ts reference
 
 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
 
@@ -94,41 +94,52 @@ We use a simplified monorepo solution with `native npm-workspace + ts reference
 - 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`
 
 ## 🔧 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
 
-> @TODO this part is outdated. Update this.
+- Start and serve a local `iife` script
 
-- Config your LLM API
+    ```bash
-- Start and serve a local umd script
+    npm run dev:iife # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.js
+    ```
 
-   ```bash
+- Add a new bookmark
-   npm run dev:umd # Serving UMD with auto rebuild at http://localhost:5173/page-agent.umd.cjs
-   ```
 
-- Add a new bookmark enable it on other website
+    ```javascript
+    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
-   javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5173/page-agent.umd.cjs?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
+
-   ```
+> Warning: AK in your local `.env` will be inlined in the iife script.
 
 ### Adding Documentation
 
-1. Create `website/src/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 `website/src/router.tsx`
+
-3. Add navigation link to `website/src/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
 
@@ -143,7 +154,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,22 +27,28 @@
 
 ## 🗺️ Roadmap
 
-👉 [**Roadmap**](./ROADMAP.md)
+👉 [**Roadmap**](https://github.com/alibaba/page-agent/issues/96)
 
 ## 🚀 快速开始
 
-### CDN 集成
+### 快速体验 (With Testing LLM)
+
+最快的体验方式：
 
 ```html
-// CDN        - https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js
+<script
-// Mirror(CN) - https://registry.npmmirror.com/page-agent/latest/files/dist/umd/page-agent.js
+    src="https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js"
-<script 
+    crossorigin="true"
-	src="https://registry.npmmirror.com/page-agent/latest/files/dist/umd/page-agent.js" 
-	crossorigin="true" 
-	type="text/javascript"
 ></script>
 ```
 
+> ⚠️ **仅用于技术评估。** Demo 模型有速率限制和使用限制，生产环境请使用 NPM 方式。
+
+| 镜像   | URL                                                                                 |
+| ------ | ----------------------------------------------------------------------------------- |
+| Global | https://cdn.jsdelivr.net/npm/page-agent/dist/iife/page-agent.demo.js                |
+| China  | https://registry.npmmirror.com/page-agent/latest/files/dist/iife/page-agent.demo.js |
+
 ### NPM 安装
 
 ```bash
@@ -49,33 +58,29 @@ 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({
-	model: 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 adopts a simplified monorepo structure:
 
 ```
 packages/
-├── page-agent/          # AI agent (npm: page-agent)
+├── page-agent/          # AI agent and demo(npm: page-agent)
+├── core/                # Agent core logic without UI(npm: @page-agent/core)
 ├── llms/                # LLM 客户端 (npm: @page-agent/llms)
-├── page-controller/     # DOM 操作 (npm: @page-agent/page-controller)
+├── page-controller/     # DOM 操作 & 蒙层 & 模拟鼠标 (npm: @page-agent/page-controller)
-├── ui/                  # 面板 & 蒙层 & 模拟鼠标 (npm: @page-agent/ui)
+├── ui/                  # 面板 & i18n (npm: @page-agent/ui)
 └── website/             # 文档站点
 ```
 
@@ -83,28 +88,19 @@ packages/
 
 欢迎社区贡献！以下是参与方式：
 
-### 开发环境
+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/i3/O1CN01MyVCS21EoKkIHUT1s_!!6000000000398-49-tps-1280-353.webp)
+<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,22 +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
-// CDN        - https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js
+<script
-// Mirror(CN) - https://registry.npmmirror.com/page-agent/latest/files/dist/umd/page-agent.js
+    src="https://cdn.jsdelivr.net/npm/page-agent/dist/iife/page-agent.demo.js"
-<script 
+    crossorigin="true"
-	src="https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js" 
-	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/dist/iife/page-agent.demo.js                |
+| China   | https://registry.npmmirror.com/page-agent/latest/files/dist/iife/page-agent.demo.js |
+
 ### NPM Installation
 
 ```bash
@@ -49,18 +58,11 @@ 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({
-	model: 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')
@@ -72,10 +74,11 @@ PageAgent adopts a simplified monorepo structure:
 
 ```
 packages/
-├── page-agent/          # AI agent (npm: page-agent)
+├── page-agent/          # AI agent and demo(npm: page-agent)
+├── core/                # Agent core logic without UI(npm: @page-agent/core)
 ├── llms/                # LLM client (npm: @page-agent/llms)
-├── page-controller/     # DOM operations (npm: @page-agent/page-controller)
+├── page-controller/     # DOM operations & Visual Mask (npm: @page-agent/page-controller)
-├── ui/                  # Panel & Mask & Mouse Animation (npm: @page-agent/ui)
+├── ui/                  # Panel & i18n (npm: @page-agent/ui)
 └── website/             # Demo & Documentation site
 ```
 
@@ -83,28 +86,19 @@ packages/
 
 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 +117,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**
-- [ ] **User takeover** 
-  - [#64](https://github.com/alibaba/page-agent/issues/64)
-- [ ] **❗Hijack `page_open/page_change/page_unload` behavior**
-- [ ] **Custom knowledge base and instructions**
-  - [#45](https://github.com/alibaba/page-agent/issues/45)
-- [ ] **Black/white-list safeguard**
-- [ ] **Data-masking**
-  - [#44](https://github.com/alibaba/page-agent/issues/44)
-- [ ] **Improve Memory**
-  - [#66](https://github.com/alibaba/page-agent/issues/66)
-  - [#65](https://github.com/alibaba/page-agent/issues/65)
-- [ ] **Optimize for popular UI frameworks**
-- [x] **i18n of the website**
-  - [x] Chinese version
-  - [x] English version
-- [x] **Refactor: Separate `Agent` and `PageController`** 
-- [ ] **Chrome-ext wrapper for multi-page tasks**
-
-♻️ Following browser-use's update and contribute back.
-
-## 📋 Pending Features
-
-- [ ] **Tools for more complex tasks**
-  - todo list
-  - file sys
-- [x] **Support custom llm fetch**
-- [ ] **Testing suits**
-- [ ] **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,12 +8,7 @@ import globals from 'globals'
 import tseslint from 'typescript-eslint'
 
 export default defineConfig([
-	globalIgnores([
+	globalIgnores(['**/dist', '**/node_modules', 'packages/website/src/components/ui']),
-		'**/dist',
-		'**/test-pages',
-		'**/node_modules',
-		'packages/website/src/components/ui',
-	]),
 	{
 		plugins: {
 			'react-hooks': reactHooks,

package.json

@@ -1,12 +1,13 @@
 {
 	"name": "root",
 	"private": true,
-	"version": "0.0.19",
+	"version": "0.3.0-beta.2",
 	"type": "module",
 	"workspaces": [
 		"packages/page-controller",
 		"packages/ui",
 		"packages/llms",
+		"packages/core",
 		"packages/page-agent",
 		"packages/website"
 	],
@@ -28,36 +29,39 @@
 		"build:website": "npm run build:website --workspace=@page-agent/website",
 		"build:libs": "npm run build --workspaces --if-present",
 		"build": "npm run build:libs && npm run build:website",
-		"dev:umd": "npm run dev:umd --workspace=page-agent",
+		"dev:iife": "npm run dev:iife --workspace=page-agent",
 		"version": "node scripts/sync-version.js",
 		"lint": "eslint .",
 		"prepare": "husky"
 	},
 	"devDependencies": {
-		"@commitlint/cli": "^20.3.0",
+		"@commitlint/cli": "^20.3.1",
-		"@commitlint/config-conventional": "^20.3.0",
+		"@commitlint/config-conventional": "^20.3.1",
 		"@eslint/js": "^9.39.2",
 		"@microsoft/api-extractor": "^7.55.2",
-		"@trivago/prettier-plugin-sort-imports": "^6.0.1",
+		"@trivago/prettier-plugin-sort-imports": "^6.0.2",
-		"@types/node": "^25.0.3",
+		"@types/node": "^25.0.7",
 		"concurrently": "^9.2.1",
 		"dotenv": "^17.2.3",
 		"eslint": "^9.39.2",
 		"eslint-config-prettier": "^10.1.8",
-		"eslint-plugin-react-dom": "^2.5.1",
+		"eslint-plugin-react-dom": "^2.5.7",
 		"eslint-plugin-react-hooks": "^7.0.1",
 		"eslint-plugin-react-refresh": "^0.4.26",
-		"eslint-plugin-react-x": "^2.5.1",
+		"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.7.4",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.52.0",
+		"typescript-eslint": "^8.53.0",
 		"unplugin-dts": "^1.0.0-beta.6",
-		"vite": "^7.3.0",
+		"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}": [
 			"npx prettier --write --ignore-unknown",
@@ -98,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/core/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@page-agent/core",
+	"private": false,
+	"version": "0.3.0-beta.2",
+	"type": "module",
+	"main": "./dist/esm/page-agent-core.js",
+	"module": "./dist/esm/page-agent-core.js",
+	"types": "./dist/esm/PageAgentCore.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/esm/PageAgentCore.d.ts",
+			"import": "./dist/esm/page-agent-core.js",
+			"default": "./dist/esm/page-agent-core.js"
+		}
+	},
+	"files": [
+		"dist/"
+	],
+	"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",
+		"web-automation",
+		"GUI-simulation"
+	],
+	"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",
+		"dev:iife": "concurrently \"vite build --config vite.iife.config.js --watch\" \"npx serve dist/iife -p 5174\"",
+		"prepublishOnly": "node -e \"const fs=require('fs');['README.md','LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
+		"postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
+	},
+	"dependencies": {
+		"chalk": "^5.6.2",
+		"zod": "^4.3.5",
+		"@page-agent/llms": "0.3.0-beta.2",
+		"@page-agent/page-controller": "0.3.0-beta.2"
+	}
+}

packages/core/src/PageAgentCore.ts

@@ -0,0 +1,588 @@
+/**
+ * Copyright (C) 2025 Alibaba Group Holding Limited
+ * All rights reserved.
+ */
+import { LLM, type Tool } from '@page-agent/llms'
+import type { PageController } from '@page-agent/page-controller'
+import chalk from 'chalk'
+import zod from 'zod'
+
+import { type PageAgentConfig } from './config'
+import { MAX_STEPS } from './config/constants'
+import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
+import { tools } from './tools'
+import {
+	AgentActivity,
+	AgentReflection,
+	AgentStatus,
+	AgentStep,
+	ExecutionResult,
+	HistoricalEvent,
+	MacroToolInput,
+	MacroToolResult,
+} from './types'
+import { normalizeResponse, trimLines, uid } from './utils'
+import { assert } from './utils/assert'
+
+export { type PageAgentConfig }
+export { tool, type PageAgentTool } from './tools'
+
+/**
+ * AI agent for browser DOM automation.
+ *
+ * @remarks
+ * ## Event System
+ * - `statuschange` - Agent status transitions (idle → running → completed/error)
+ * - `historychange` - History events updated (persistent, part of agent memory)
+ * - `activity` - Real-time activity feedback (transient, for UI only)
+ * - `dispose` - Agent cleanup triggered
+ *
+ * ## Information Streams
+ * 1. **History Events** (`history` array)
+ *    - Persistent event stream that forms agent's memory
+ *    - Included in LLM context across steps
+ *    - Types: steps, observations, user takeovers, llm errors
+ *
+ * 2. **Activity Events** (via `activity` event)
+ *    - Transient UI feedback during task execution
+ *    - NOT included in LLM context
+ *    - Types: thinking, executing, executed, retrying, error
+ */
+export class PageAgentCore extends EventTarget {
+	config: PageAgentConfig
+	id = uid()
+	tools: typeof tools
+	disposed = false
+	task = ''
+	taskId = ''
+
+	/** Agent execution status */
+	#status: AgentStatus = 'idle'
+
+	/**
+	 * Callback for when agent needs user input (ask_user tool)
+	 * If not set, ask_user tool will be disabled
+	 * @example onAskUser: (q) => window.prompt(q) || ''
+	 */
+	onAskUser?: (question: string) => Promise<string>
+
+	#llm: LLM
+	#abortController = new AbortController()
+
+	/** PageController for DOM operations */
+	pageController: PageController
+
+	/** Runtime states for tracking across steps */
+	states = {
+		/** Accumulated wait time in seconds, used by wait tool */
+		totalWaitTime: 0,
+		/** Last known URL for detecting navigation */
+		lastURL: '',
+	}
+
+	/** History events */
+	history: HistoricalEvent[] = []
+
+	constructor(config: PageAgentConfig & { pageController: PageController }) {
+		super()
+
+		this.config = config
+		this.#llm = new LLM(this.config)
+		this.tools = new Map(tools)
+		this.pageController = config.pageController
+
+		// Listen to LLM retry events
+		this.#llm.addEventListener('retry', (e) => {
+			const { attempt, maxAttempts } = (e as CustomEvent).detail
+			this.emitActivity({ type: 'retrying', attempt, maxAttempts })
+			// Also push to history for panel rendering
+			this.history.push({
+				type: 'error',
+				errorType: 'retry',
+				message: `LLM retry attempt ${attempt} of ${maxAttempts}`,
+				attempt,
+				maxAttempts,
+			})
+			this.#emitHistoryChange()
+		})
+		this.#llm.addEventListener('error', (e) => {
+			const { error } = (e as CustomEvent).detail
+			const message = String(error)
+			this.emitActivity({ type: 'error', message })
+			// Also push to history for panel rendering
+			this.history.push({
+				type: 'error',
+				errorType: 'error',
+				message,
+			})
+			this.#emitHistoryChange()
+		})
+
+		if (this.config.customTools) {
+			for (const [name, tool] of Object.entries(this.config.customTools)) {
+				if (tool === null) {
+					this.tools.delete(name)
+					continue
+				}
+				this.tools.set(name, tool)
+			}
+		}
+
+		if (!this.config.experimentalScriptExecutionTool) {
+			this.tools.delete('execute_javascript')
+		}
+	}
+
+	/** Get current agent status */
+	get status(): AgentStatus {
+		return this.#status
+	}
+
+	/** Emit statuschange event */
+	#emitStatusChange(): void {
+		this.dispatchEvent(new Event('statuschange'))
+	}
+
+	/** Emit historychange event */
+	#emitHistoryChange(): void {
+		this.dispatchEvent(new Event('historychange'))
+	}
+
+	/**
+	 * Emit activity event - for transient UI feedback
+	 * @param activity - Current agent activity
+	 */
+	emitActivity(activity: AgentActivity): void {
+		this.dispatchEvent(new CustomEvent('activity', { detail: activity }))
+	}
+
+	/** Update status and emit event */
+	#setStatus(status: AgentStatus): void {
+		if (this.#status !== status) {
+			this.#status = status
+			this.#emitStatusChange()
+		}
+	}
+
+	/**
+	 * 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.#emitHistoryChange()
+	}
+
+	async execute(task: string): Promise<ExecutionResult> {
+		if (!task) throw new Error('Task is required')
+		this.task = task
+		this.taskId = uid()
+
+		// Disable ask_user tool if onAskUser is not set
+		if (!this.onAskUser) {
+			this.tools.delete('ask_user')
+		}
+
+		const onBeforeStep = this.config.onBeforeStep || (() => void 0)
+		const onAfterStep = this.config.onAfterStep || (() => void 0)
+		const onBeforeTask = this.config.onBeforeTask || (() => void 0)
+		const onAfterTask = this.config.onAfterTask || (() => void 0)
+
+		await onBeforeTask.call(this)
+
+		// Show mask
+		await this.pageController.showMask()
+
+		if (this.#abortController) {
+			this.#abortController.abort()
+			this.#abortController = new AbortController()
+		}
+
+		this.history = []
+		this.#setStatus('running')
+		this.#emitHistoryChange()
+
+		// 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}`)
+
+				// abort
+				if (this.#abortController.signal.aborted) throw new Error('AbortError')
+
+				// Thinking
+				console.log(chalk.blue('Thinking...'))
+				this.emitActivity({ type: 'thinking' })
+
+				const result = await this.#llm.invoke(
+					[
+						{
+							role: 'system',
+							content: this.#getSystemPrompt(),
+						},
+						{
+							role: 'user',
+							content: await this.#assembleUserPrompt(),
+						},
+					],
+					{ AgentOutput: this.#packMacroTool() },
+					this.#abortController.signal,
+					{
+						toolChoiceName: 'AgentOutput',
+						normalizeResponse,
+					}
+				)
+
+				const macroResult = result.toolResult as MacroToolResult
+				const input = macroResult.input
+				const output = macroResult.output
+				const reflection: Partial<AgentReflection> = {
+					evaluation_previous_goal: input.evaluation_previous_goal,
+					memory: input.memory,
+					next_goal: input.next_goal,
+				}
+				const actionName = Object.keys(input.action)[0]
+				const action: AgentStep['action'] = {
+					name: actionName,
+					input: input.action[actionName],
+					output: output,
+				}
+
+				this.history.push({
+					type: 'step',
+					reflection,
+					action,
+					usage: result.usage,
+				} as AgentStep)
+				this.#emitHistoryChange()
+
+				console.log(chalk.green('Step finished:'), actionName)
+				console.groupEnd()
+
+				await onAfterStep.call(this, this.history)
+
+				step++
+				if (step > MAX_STEPS) {
+					this.#onDone('Step count exceeded maximum limit', false)
+					const result: ExecutionResult = {
+						success: false,
+						data: 'Step count exceeded maximum limit',
+						history: this.history,
+					}
+					await onAfterTask.call(this, result)
+					return result
+				}
+				if (actionName === 'done') {
+					const success = action.input?.success ?? false
+					const text = action.input?.text || 'no text provided'
+					console.log(chalk.green.bold('Task completed'), success, text)
+					this.#onDone(text, success)
+					const result: ExecutionResult = {
+						success,
+						data: text,
+						history: this.history,
+					}
+					await onAfterTask.call(this, result)
+					return result
+				}
+			}
+		} catch (error: unknown) {
+			console.error('Task failed', error)
+			const errorMessage = String(error)
+			this.emitActivity({ type: 'error', message: errorMessage })
+			this.#onDone(errorMessage, false)
+			const result: ExecutionResult = {
+				success: false,
+				data: errorMessage,
+				history: this.history,
+			}
+			await onAfterTask.call(this, result)
+			return result
+		}
+	}
+
+	/**
+	 * Merge all tools into a single MacroTool with the following input:
+	 * - thinking: string
+	 * - evaluation_previous_goal: string
+	 * - memory: string
+	 * - next_goal: string
+	 * - action: { toolName: toolInput }
+	 * where action must be selected from tools defined in this.tools
+	 */
+	#packMacroTool(): Tool<MacroToolInput, MacroToolResult> {
+		const tools = this.tools
+
+		const actionSchemas = Array.from(tools.entries()).map(([toolName, tool]) => {
+			return zod.object({ [toolName]: tool.inputSchema }).describe(tool.description)
+		})
+
+		const actionSchema = zod.union(
+			actionSchemas as unknown as [zod.ZodType, zod.ZodType, ...zod.ZodType[]]
+		)
+
+		const macroToolSchema = zod.object({
+			// thinking: zod.string().optional(),
+			evaluation_previous_goal: zod.string().optional(),
+			memory: zod.string().optional(),
+			next_goal: zod.string().optional(),
+			action: actionSchema,
+		})
+
+		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')
+
+				console.log(chalk.blue.bold('MacroTool execute'), input)
+				const action = input.action
+
+				const toolName = Object.keys(action)[0]
+				const toolInput = action[toolName]
+
+				// Build reflection text, only include non-empty fields
+				const reflectionLines: string[] = []
+				if (input.evaluation_previous_goal)
+					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)
+				}
+
+				// 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)
+
+				// Emit executing activity
+				this.emitActivity({ type: 'executing', tool: toolName, input: toolInput })
+
+				const startTime = Date.now()
+
+				// Execute tool, bind `this` to PageAgent
+				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)
+
+				// Emit executed activity
+				this.emitActivity({
+					type: 'executed',
+					tool: toolName,
+					input: toolInput,
+					output: result,
+					duration,
+				})
+
+				// Reset wait time for non-wait tools
+				if (toolName !== 'wait') {
+					this.states.totalWaitTime = 0
+				}
+
+				// Return structured result
+				return {
+					input,
+					output: result,
+				}
+			},
+		}
+	}
+
+	/**
+	 * Get system prompt, dynamically replace language settings based on configured language
+	 */
+	#getSystemPrompt(): string {
+		let systemPrompt = SYSTEM_PROMPT
+
+		const targetLanguage = this.config.language === 'zh-CN' ? '中文' : 'English'
+		systemPrompt = systemPrompt.replace(
+			/Default working language: \*\*.*?\*\*/,
+			`Default working language: **${targetLanguage}**`
+		)
+
+		return systemPrompt
+	}
+
+	/**
+	 * 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 = ''
+
+		// <instructions> (optional)
+		prompt += await this.#getInstructions()
+
+		// <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 ${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`
+			} else if (event.type === 'error') {
+				// Error events are mainly for panel rendering, not included in LLM context
+				// to avoid polluting the agent's reasoning with transient errors
+			}
+		}
+
+		prompt += '</agent_history>\n\n'
+
+		// <browser_state>
+
+		prompt += await this.#getBrowserState()
+
+		return trimLines(prompt)
+	}
+
+	#onDone(text: string, success = true) {
+		this.pageController.cleanUpHighlights()
+		this.pageController.hideMask() // No await - fire and forget
+		this.#setStatus(success ? 'completed' : 'error')
+		this.#abortController.abort()
+	}
+
+	async #getBrowserState(): Promise<string> {
+		const state = await this.pageController.getBrowserState()
+
+		let content = state.content
+		if (this.config.transformPageContent) {
+			content = await this.config.transformPageContent(content)
+		}
+
+		return trimLines(`<browser_state>
+			Current Page: [${state.title}](${state.url})
+
+			${state.header}
+			${content}
+			${state.footer}
+
+			</browser_state>
+		`)
+	}
+
+	dispose(reason?: string) {
+		console.log('Disposing PageAgent...')
+		this.disposed = true
+		this.pageController.dispose()
+		this.history = []
+		this.#abortController.abort(reason ?? 'PageAgent disposed')
+
+		// Emit dispose event for UI cleanup
+		this.dispatchEvent(new Event('dispose'))
+
+		this.config.onDispose?.call(this, reason)
+	}
+}

packages/core/src/config/index.ts

@@ -1,12 +1,15 @@
 import type { LLMConfig } from '@page-agent/llms'
-import type { PageControllerConfig } from '@page-agent/page-controller'
+import type { PageController, PageControllerConfig } from '@page-agent/page-controller'
-import type { SupportedLanguage } from '@page-agent/ui'
 
-import type { AgentHistory, ExecutionResult, PageAgent } from '../PageAgent'
+import type { PageAgentCore } from '../PageAgentCore'
 import type { PageAgentTool } from '../tools'
+import type { ExecutionResult, HistoricalEvent } from '../types'
 
 export type { LLMConfig }
 
+/** Supported UI languages */
+export type SupportedLanguage = 'en-US' | 'zh-CN'
+
 export interface AgentConfig {
 	// theme?: 'light' | 'dark'
 	language?: SupportedLanguage
@@ -15,7 +18,7 @@ export interface AgentConfig {
 	 * Custom tools to extend PageAgent capabilities
 	 * @experimental
 	 * @note You can also override or remove internal tools by using the same name.
-	 * @see [tools](../tools/index.ts)
+	 * @see PageAgentTool
 	 *
 	 * @example
 	 * // override internal tool
@@ -62,17 +65,18 @@ export interface AgentConfig {
 
 	// 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
+	onBeforeStep?: (this: PageAgentCore, stepCnt: number) => Promise<void> | void
-	onAfterStep?: (this: PageAgent, stepCnt: number, history: AgentHistory[]) => Promise<void> | void
+	onAfterStep?: (this: PageAgentCore, history: HistoricalEvent[]) => Promise<void> | void
-	onBeforeTask?: (this: PageAgent) => Promise<void> | void
+	onBeforeTask?: (this: PageAgentCore) => Promise<void> | void
-	onAfterTask?: (this: PageAgent, result: ExecutionResult) => Promise<void> | void
+	onAfterTask?: (this: PageAgentCore, 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
+	onDispose?: (this: PageAgentCore, reason?: string) => void
 
 	// page behavior hooks
 
@@ -84,19 +88,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 & PageControllerConfig

packages/core/src/env.d.ts

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

packages/core/src/prompts/.prettierignore

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

packages/core/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/core/src/tools/index.ts

@@ -4,7 +4,7 @@
  */
 import zod, { type z } from 'zod'
 
-import type { PageAgent } from '../PageAgent'
+import type { PageAgentCore } from '../PageAgentCore'
 import { waitFor } from '../utils'
 
 /**
@@ -14,7 +14,7 @@ export interface PageAgentTool<TParams = any> {
 	// name: string
 	description: string
 	inputSchema: z.ZodType<TParams>
-	execute: (this: PageAgent, args: TParams) => Promise<string>
+	execute: (this: PageAgentCore, args: TParams) => Promise<string>
 }
 
 export function tool<TParams>(options: PageAgentTool<TParams>): PageAgentTool<TParams> {
@@ -36,7 +36,7 @@ tools.set(
 			text: zod.string(),
 			success: zod.boolean().default(true),
 		}),
-		execute: async function (this: PageAgent, input) {
+		execute: async function (this: PageAgentCore, input) {
 			// @note main loop will handle this one
 			// this.onDone(input.text, input.success)
 			return Promise.resolve('Task completed')
@@ -52,11 +52,20 @@ tools.set(
 		inputSchema: zod.object({
 			seconds: zod.number().min(1).max(10).default(1),
 		}),
-		execute: async function (this: PageAgent, input) {
+		execute: async function (this: PageAgentCore, input) {
 			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)
+
+			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.`
 		},
 	})
@@ -70,9 +79,12 @@ tools.set(
 		inputSchema: zod.object({
 			question: zod.string(),
 		}),
-		execute: async function (this: PageAgent, input) {
+		execute: async function (this: PageAgentCore, input) {
-			const answer = await this.panel.askUser(input.question)
+			if (!this.onAskUser) {
-			return `✅ Received user answer: ${answer}`
+				throw new Error('ask_user tool requires onAskUser callback to be set')
+			}
+			const answer = await this.onAskUser(input.question)
+			return `User answered: ${answer}`
 		},
 	})
 )
@@ -84,7 +96,7 @@ tools.set(
 		inputSchema: zod.object({
 			index: zod.int().min(0),
 		}),
-		execute: async function (this: PageAgent, input) {
+		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.clickElement(input.index)
 			return result.message
 		},
@@ -99,7 +111,7 @@ tools.set(
 			index: zod.int().min(0),
 			text: zod.string(),
 		}),
-		execute: async function (this: PageAgent, input) {
+		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.inputText(input.index, input.text)
 			return result.message
 		},
@@ -115,7 +127,7 @@ tools.set(
 			index: zod.int().min(0),
 			text: zod.string(),
 		}),
-		execute: async function (this: PageAgent, input) {
+		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.selectOption(input.index, input.text)
 			return result.message
 		},
@@ -136,7 +148,7 @@ tools.set(
 			pixels: zod.number().int().min(0).optional(),
 			index: zod.number().int().min(0).optional(),
 		}),
-		execute: async function (this: PageAgent, input) {
+		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.scroll({
 				...input,
 				numPages: input.num_pages,
@@ -156,7 +168,7 @@ tools.set(
 			pixels: zod.number().int().min(0),
 			index: zod.number().int().min(0).optional(),
 		}),
-		execute: async function (this: PageAgent, input) {
+		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.scrollHorizontally(input)
 			return result.message
 		},
@@ -171,7 +183,7 @@ tools.set(
 		inputSchema: zod.object({
 			script: zod.string(),
 		}),
-		execute: async function (this: PageAgent, input) {
+		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.executeJavascript(input.script)
 			return result.message
 		},

packages/core/src/types.ts

@@ -0,0 +1,109 @@
+/**
+ * Agent reflection state - the reflection-before-action model
+ *
+ * Every tool call must first reflect on:
+ * - 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
+}
+
+/**
+ * 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 extends Partial<AgentReflection> {
+	action: Record<string, any>
+}
+
+/**
+ * MacroTool output structure
+ */
+export interface MacroToolResult {
+	input: MacroToolInput
+	output: string
+}
+
+/**
+ * A single agent step with reflection and action
+ */
+export interface AgentStep {
+	type: 'step'
+	reflection: Partial<AgentReflection>
+	action: {
+		name: string
+		input: any
+		output: string
+	}
+	usage: {
+		promptTokens: number
+		completionTokens: number
+		totalTokens: number
+		cachedTokens?: number
+		reasoningTokens?: number
+	}
+}
+
+/**
+ * Persistent observation event (stays in memory)
+ */
+export interface ObservationEvent {
+	type: 'observation'
+	content: string
+}
+
+/**
+ * User takeover event
+ */
+export interface UserTakeoverEvent {
+	type: 'user_takeover'
+}
+
+/**
+ * Error event (retry or error from LLM)
+ */
+export interface ErrorEvent {
+	type: 'error'
+	errorType: 'retry' | 'error'
+	message: string
+	attempt?: number
+	maxAttempts?: number
+}
+
+/**
+ * Union type for all history events
+ */
+export type HistoricalEvent = AgentStep | ObservationEvent | UserTakeoverEvent | ErrorEvent
+
+/**
+ * Agent execution status
+ */
+export type AgentStatus = 'idle' | 'running' | 'completed' | 'error'
+
+/**
+ * Agent activity - transient state for immediate UI feedback.
+ *
+ * Unlike historical events (which are persisted), activities are ephemeral
+ * and represent "what the agent is doing right now". UI components should
+ * listen to 'activity' events to show real-time feedback.
+ *
+ * Note: There is no 'idle' activity - absence of activity events means idle.
+ */
+export type AgentActivity =
+	| { type: 'thinking' }
+	| { type: 'executing'; tool: string; input: unknown }
+	| { type: 'executed'; tool: string; input: unknown; output: string; duration: number }
+	| { type: 'retrying'; attempt: number; maxAttempts: number }
+	| { type: 'error'; message: string }
+
+export interface ExecutionResult {
+	success: boolean
+	data: string
+	history: HistoricalEvent[]
+}

packages/core/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/core/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
@@ -66,12 +68,13 @@ export function randomID(existingIDs?: string[]): string {
 }
 
 //
+const _global = globalThis as any
 
-if (!window.__PAGE_AGENT_IDS__) {
+if (!_global.__PAGE_AGENT_IDS__) {
-	window.__PAGE_AGENT_IDS__ = []
+	_global.__PAGE_AGENT_IDS__ = []
 }
 
-const ids = window.__PAGE_AGENT_IDS__
+const ids = _global.__PAGE_AGENT_IDS__
 
 /**
  * Generate a random ID.

packages/core/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/core/tsconfig.json

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

packages/core/vite.config.js

@@ -0,0 +1,44 @@
+// @ts-check
+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))
+
+// ES Module for NPM Package
+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/PageAgentCore.ts'),
+			name: 'PageAgentCore',
+			fileName: 'page-agent-core',
+			formats: ['es'],
+		},
+		outDir: resolve(__dirname, 'dist', 'esm'),
+		rollupOptions: {
+			external: [
+				'chalk',
+				'zod',
+				// all the internal packages
+				/^@page-agent\//,
+			],
+		},
+		minify: false,
+		sourcemap: true,
+		cssCodeSplit: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})

packages/llms/README.md

@@ -1,41 +0,0 @@
-# @page-agent/llms
-
-LLM client with a **reflection-before-action** mental model for page-agent.
-
-## Why This Package Exists
-
-The LLM module and the agent logic are inherently coupled. This package exists not to decouple them, but to **define the interface contract** between the LLM and the agent.
-
-The core abstraction is the `MacroToolInput` — a structured output format that **forces the model to reflect before acting**.
-
-## The Reflection-Before-Action Model
-
-Every tool call must first output its reasoning state before the actual action:
-
-```typescript
-interface MacroToolInput {
-  // Reflection (mandatory before any action)
-  evaluation_previous_goal?: string  // How well did the previous action work?
-  memory?: string                     // Key information to remember
-  next_goal?: string                  // What to accomplish next
-
-  // Action (the actual operation)
-  action: Record<string, any>
-}
-```
-
-This design ensures that:
-
-1. **The model evaluates its previous action** before deciding the next step
-2. **Working memory is explicitly maintained** across conversation turns
-3. **Goals are clearly stated**, making the agent's reasoning transparent and debuggable
-
-## Key Components
-
-| Export | Description |
-|--------|-------------|
-| `LLM` | Main LLM client class with retry logic |
-| `MacroToolInput` | The reflection-before-action input schema |
-| `AgentBrain` | Agent's thinking state (eval, memory, goal) |
-| `LLMConfig` | Configuration for LLM connection |
-| `parseLLMConfig` | Parse and apply defaults to config |

packages/llms/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@page-agent/llms",
-	"version": "0.0.19",
+	"version": "0.3.0-beta.2",
 	"type": "module",
 	"main": "./dist/lib/page-agent-llms.js",
 	"module": "./dist/lib/page-agent-llms.js",

packages/llms/src/OpenAIClient.ts

@@ -1,60 +1,58 @@
 /**
  * OpenAI Client implementation
- * @note This client is only for demonstrating how to implement a LLM client.
- * @note Use OpenAILenientClient instead.
  */
 import { InvokeError, InvokeErrorType } from './errors'
-import type { InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
+import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
 import { modelPatch, zodToOpenAITool } from './utils'
 
 /**
- * @deprecated Use OpenAILenientClient instead.
+ * Client for OpenAI compatible APIs
  */
 export class OpenAIClient implements LLMClient {
-	config: LLMConfig
+	config: Required<LLMConfig>
+	private fetch: typeof globalThis.fetch
 
-	constructor(config: LLMConfig) {
+	constructor(config: Required<LLMConfig>) {
 		this.config = config
+		this.fetch = config.customFetch
 	}
 
 	async invoke(
 		messages: Message[],
 		tools: Record<string, Tool>,
-		abortSignal?: AbortSignal
+		abortSignal?: AbortSignal,
+		options?: InvokeOptions
 	): Promise<InvokeResult> {
 		// 1. Convert tools to OpenAI format
-		const openaiTools = Object.entries(tools).map(([name, tool]) => zodToOpenAITool(name, tool))
+		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 fetch(`${this.config.baseURL}/chat/completions`, {
+			response = await this.fetch(`${this.config.baseURL}/chat/completions`, {
 				method: 'POST',
 				headers: {
 					'Content-Type': 'application/json',
 					Authorization: `Bearer ${this.config.apiKey}`,
 				},
-				body: JSON.stringify(
+				body: JSON.stringify(modelPatch(requestBody)),
-					modelPatch({
-						model: this.config.model,
-						temperature: this.config.temperature,
-						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
+			console.error(error)
 			throw new InvokeError(InvokeErrorType.NETWORK_ERROR, 'Network request failed', error)
 		}
 
@@ -92,77 +90,94 @@ export class OpenAIClient implements LLMClient {
 			)
 		}
 
+		// 4. Parse and validate response
 		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)
 		}
 
+		// Check finish_reason
 		switch (choice.finish_reason) {
 			case 'tool_calls':
-				// ✅ Normal
+			case 'function_call': // gemini
+			case 'stop': // some models use this even with tool calls
 				break
 			case 'length':
-				// ⚠️ Token limit reached
 				throw new InvokeError(
 					InvokeErrorType.CONTEXT_LENGTH,
-					'Response truncated: max tokens reached',
+					'Response truncated: max tokens reached'
-					data
 				)
 			case 'content_filter':
-				// ❌ Content filtered
+				throw new InvokeError(InvokeErrorType.CONTENT_FILTER, 'Content filtered by safety system')
-				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}`,
+					`Unexpected finish_reason: ${choice.finish_reason}`
-					data
 				)
 		}
 
-		// 5. Parse tool call
+		// Apply normalizeResponse if provided (for fixing format issues automatically)
-		const toolCall = choice.message?.tool_calls?.[0]
+		const normalizedData = options?.normalizeResponse ? options.normalizeResponse(data) : data
-		if (!toolCall) {
+		const normalizedChoice = (normalizedData as any).choices?.[0]
-			throw new InvokeError(InvokeErrorType.NO_TOOL_CALL, 'No tool call found in response', data)
-		}
 
-		const toolName = toolCall.function.name
+		// Get tool name from response
-		const tool = tools[toolName]
+		const toolCallName = normalizedChoice?.message?.tool_calls?.[0]?.function?.name
-		if (!tool) {
+		if (!toolCallName) {
-			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,
+				InvokeErrorType.NO_TOOL_CALL,
-				`Tool arguments validation failed: ${validation.error.message}`,
+				'No tool call found in response',
-				validation.error
+				normalizedData
 			)
 		}
 
-		// 7. Execute tool
+		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(validation.data)
+			toolResult = await tool.execute(toolInput)
 		} catch (e) {
 			throw new InvokeError(
 				InvokeErrorType.TOOL_EXECUTION_ERROR,
@@ -171,12 +186,11 @@ export class OpenAIClient implements LLMClient {
 			)
 		}
 
-		// 8. Return result (including cache tokens)
+		// Return result
 		return {
 			toolCall: {
-				// id: toolCall.id,
+				name: toolCallName,
-				name: toolName,
+				args: toolInput,
-				args: validation.data as Record<string, unknown>,
 			},
 			toolResult,
 			usage: {

packages/llms/src/OpenAILenientClient.ts

@@ -1,124 +0,0 @@
-/**
- * OpenAI Client implementation
- */
-import { InvokeError, InvokeErrorType } from './errors'
-import type { InvokeResult, LLMClient, LLMConfig, MacroToolInput, Message, Tool } from './types'
-import { lenientParseMacroToolCall, modelPatch, zodToOpenAITool } from './utils'
-
-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: { 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 this.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,
-						messages,
-
-						tools: openaiTools,
-						// tool_choice: 'required',
-						tool_choice: { type: 'function', function: { name: 'AgentOutput' } },
-						parallel_tool_calls: false,
-					})
-				),
-				signal: abortSignal,
-			})
-		} catch (error: unknown) {
-			// Network error
-			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
-			)
-		}
-
-		// 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/llms/src/constants.ts

@@ -1,20 +1,3 @@
-// Dev environment: use .env config if available, otherwise fallback to testing api
+// Internal constants
-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 DEFAULT_TEMPERATURE = 0.7 // higher randomness helps auto-recovery

packages/llms/src/index.ts

@@ -1,72 +1,23 @@
-/**
+import { OpenAIClient } from './OpenAIClient'
- * @topic LLM 与主流程的隔离
+import { DEFAULT_TEMPERATURE, LLM_MAX_RETRIES } from './constants'
- * @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 { OpenAIClient } from './OpenAILenientClient'
-import {
-	DEFAULT_API_KEY,
-	DEFAULT_BASE_URL,
-	DEFAULT_MODEL_NAME,
-	DEFAULT_TEMPERATURE,
-	LLM_MAX_RETRIES,
-} from './constants'
 import { InvokeError } from './errors'
-import type {
+import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
-	AgentBrain,
-	InvokeResult,
-	LLMClient,
-	LLMConfig,
-	MacroToolInput,
-	MacroToolResult,
-	Message,
-	Tool,
-} from './types'
 
-export type {
+export type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool }
-	AgentBrain,
-	InvokeResult,
-	LLMClient,
-	LLMConfig,
-	MacroToolInput,
-	MacroToolResult,
-	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 ?? DEFAULT_BASE_URL,
+		baseURL: config.baseURL,
-		apiKey: config.apiKey ?? DEFAULT_API_KEY,
+		apiKey: config.apiKey,
-		model: config.model ?? DEFAULT_MODEL_NAME,
+		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
@@ -93,20 +44,21 @@ export class LLM extends EventTarget {
 	async invoke(
 		messages: Message[],
 		tools: Record<string, Tool>,
-		abortSignal: AbortSignal
+		abortSignal: AbortSignal,
+		options?: InvokeOptions
 	): Promise<InvokeResult> {
 		return await withRetry(
 			async () => {
-				const result = await this.client.invoke(messages, tools, abortSignal)
+				const result = await this.client.invoke(messages, tools, abortSignal, options)
 
 				return result
 			},
 			// retry settings
 			{
 				maxRetries: this.config.maxRetries,
-				onRetry: (current: number) => {
+				onRetry: (attempt: number) => {
 					this.dispatchEvent(
-						new CustomEvent('retry', { detail: { current, max: this.config.maxRetries } })
+						new CustomEvent('retry', { detail: { attempt, maxAttempts: this.config.maxRetries } })
 					)
 				},
 				onError: (error: Error) => {
@@ -121,15 +73,15 @@ async function withRetry<T>(
 	fn: () => Promise<T>,
 	settings: {
 		maxRetries: number
-		onRetry: (retries: number) => void
+		onRetry: (attempt: number) => void
 		onError: (error: Error) => void
 	}
 ): Promise<T> {
-	let retries = 0
+	let attempt = 0
 	let lastError: Error | null = null
-	while (retries <= settings.maxRetries) {
+	while (attempt <= settings.maxRetries) {
-		if (retries > 0) {
+		if (attempt > 0) {
-			settings.onRetry(retries)
+			settings.onRetry(attempt)
 			await new Promise((resolve) => setTimeout(resolve, 100))
 		}
 
@@ -146,7 +98,7 @@ async function withRetry<T>(
 			if (error instanceof InvokeError && !error.retryable) throw error
 
 			lastError = error as Error
-			retries++
+			attempt++
 
 			await new Promise((resolve) => setTimeout(resolve, 100))
 		}

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>
 }
 
@@ -68,9 +87,9 @@ export interface InvokeResult<TResult = unknown> {
  * LLM configuration
  */
 export interface LLMConfig {
-	baseURL?: string
+	baseURL: string
-	apiKey?: string
+	apiKey: string
-	model?: string
+	model: string
 
 	temperature?: number
 	maxRetries?: number
@@ -82,36 +101,3 @@ export interface LLMConfig {
 	 */
 	customFetch?: typeof globalThis.fetch
 }
-
-/**
- * Agent brain state - the reflection-before-action model
- *
- * Every tool call must first reflect on:
- * - 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 AgentBrain {
-	// thinking?: string
-	evaluation_previous_goal: string
-	memory: string
-	next_goal: string
-}
-
-/**
- * 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 extends AgentBrain {
-	action: Record<string, any>
-}
-
-/**
- * MacroTool output structure
- */
-export interface MacroToolResult {
-	input: MacroToolInput
-	output: string
-}

packages/llms/src/utils.ts

@@ -4,8 +4,7 @@
 import chalk from 'chalk'
 import { z } from 'zod'
 
-import { InvokeError, InvokeErrorType } from './errors'
+import type { Tool } from './types'
-import type { MacroToolInput, Tool } from './types'
 
 function debug(message: string) {
 	console.debug(chalk.gray('[LLM]'), message)
@@ -26,176 +25,6 @@ export function zodToOpenAITool(name: string, tool: Tool) {
 	}
 }
 
-/**
- * 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
-		)
-	}
-}
-
 /**
  * Patch model specific parameters
  */
@@ -205,11 +34,25 @@ export function modelPatch(body: Record<string, any>) {
 
 	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: change tool_choice and disable thinking')
+		debug('Applying Claude patch: disable thinking')
-		body.tool_choice = { type: 'tool', name: 'AgentOutput' }
 		body.thinking = { type: 'disabled' }
-		// body.reasoning = { enabled: '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')) {

packages/llms/tsconfig.dts.json

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

packages/llms/tsconfig.json

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

packages/llms/vite.config.js

@@ -34,4 +34,3 @@ export default defineConfig({
 		'process.env.NODE_ENV': '"production"',
 	},
 })
-

packages/page-agent/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "page-agent",
 	"private": false,
-	"version": "0.0.19",
+	"version": "0.3.0-beta.2",
 	"type": "module",
 	"main": "./dist/esm/page-agent.js",
 	"module": "./dist/esm/page-agent.js",
@@ -37,17 +37,18 @@
 	},
 	"homepage": "https://alibaba.github.io/page-agent/",
 	"scripts": {
-		"build": "vite build && vite build --config vite.umd.config.js",
+		"build": "vite build && npm run build:demo",
-		"serve": "npx serve dist/umd -p 5173",
+		"build:demo": "vite build --config vite.iife.config.js",
-		"dev:umd": "concurrently \"vite build --config vite.umd.config.js --watch\" \"npm run serve\"",
+		"dev:demo": "concurrently \"vite build --config vite.iife.config.js --watch\" \"npx serve dist/iife -p 5174\"",
 		"prepublishOnly": "node -e \"const fs=require('fs');['README.md','LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
 		"postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
 	},
 	"dependencies": {
 		"chalk": "^5.6.2",
 		"zod": "^4.3.5",
-		"@page-agent/llms": "0.0.19",
+		"@page-agent/llms": "0.3.0-beta.2",
-		"@page-agent/page-controller": "0.0.19",
+		"@page-agent/page-controller": "0.3.0-beta.2",
-		"@page-agent/ui": "0.0.19"
+		"@page-agent/core": "0.3.0-beta.2",
+		"@page-agent/ui": "0.3.0-beta.2"
 	}
 }

packages/page-agent/src/PageAgent.ts

@@ -2,538 +2,25 @@
  * Copyright (C) 2025 Alibaba Group Holding Limited
  * All rights reserved.
  */
-import {
+import { type PageAgentConfig, PageAgentCore } from '@page-agent/core'
-	type AgentBrain,
-	LLM,
-	type MacroToolInput,
-	type MacroToolResult,
-	type Tool,
-} from '@page-agent/llms'
 import { PageController } from '@page-agent/page-controller'
-import { Panel, SimulatorMask } from '@page-agent/ui'
+import { Panel } from '@page-agent/ui'
-import chalk from 'chalk'
-import zod from 'zod'
-
-import type { PageAgentConfig } from './config'
-import { MAX_STEPS } from './config/constants'
-import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
-import { tools } from './tools'
-import { trimLines, uid, waitUntil } from './utils'
-import { assert } from './utils/assert'
 
 export type { PageAgentConfig }
-export { tool, type PageAgentTool } from './tools'
-export type { AgentBrain, MacroToolInput, MacroToolResult }
 
-export interface AgentHistory {
+export class PageAgent extends PageAgentCore {
-	brain: AgentBrain
-	action: {
-		name: string
-		input: any
-		output: string
-	}
-	usage: {
-		promptTokens: number
-		completionTokens: number
-		totalTokens: number
-		cachedTokens?: number
-		reasoningTokens?: number
-	}
-}
-
-export interface ExecutionResult {
-	success: boolean
-	data: string
-	history: AgentHistory[]
-}
-
-export class PageAgent extends EventTarget {
-	config: PageAgentConfig
-	id = uid()
 	panel: Panel
-	tools: typeof tools
-	paused = false
-	disposed = false
-	task = ''
-	taskId = ''
 
-	#llm: LLM
+	constructor(config: PageAgentConfig) {
-	#totalWaitTime = 0
+		const pageController = new PageController({
-	#abortController = new AbortController()
+			...config,
-	#llmRetryListener: ((e: Event) => void) | null = null
+			enableMask: config.enableMask ?? true,
-	#llmErrorListener: ((e: Event) => void) | null = null
-	#beforeUnloadListener: ((e: Event) => void) | null = null
-
-	/** PageController for DOM operations */
-	pageController: PageController
-
-	/** Fullscreen mask */
-	mask = new SimulatorMask()
-	/** History records */
-	history: AgentHistory[] = []
-
-	constructor(config: PageAgentConfig = {}) {
-		super()
-
-		this.config = config
-		this.#llm = new LLM(this.config)
-		this.panel = new Panel({
-			language: this.config.language,
-			onExecuteTask: (task) => this.execute(task),
-			onStop: () => this.dispose(),
-			onPauseToggle: () => {
-				this.paused = !this.paused
-				return this.paused
-			},
-			getPaused: () => this.paused,
-		})
-		this.tools = new Map(tools)
-
-		// Initialize PageController with config
-		this.pageController = new PageController(this.config)
-
-		// 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) {
-					this.tools.delete(name)
-					continue
-				}
-				this.tools.set(name, tool)
-			}
-		}
-
-		if (!this.config.experimentalScriptExecutionTool) {
-			this.tools.delete('execute_javascript')
-		}
-
-		this.#beforeUnloadListener = (e) => {
-			if (!this.disposed) this.dispose('PAGE_UNLOADING')
-		}
-		window.addEventListener('beforeunload', this.#beforeUnloadListener)
-	}
-
-	/**
-	 * @todo maybe return something?
-	 */
-	async execute(task: string): Promise<ExecutionResult> {
-		if (!task) throw new Error('Task is required')
-		this.task = task
-		this.taskId = uid()
-
-		const onBeforeStep = this.config.onBeforeStep || (() => void 0)
-		const onAfterStep = this.config.onAfterStep || (() => void 0)
-		const onBeforeTask = this.config.onBeforeTask || (() => void 0)
-		const onAfterTask = this.config.onAfterTask || (() => void 0)
-
-		await onBeforeTask.call(this)
-
-		// Show mask and panel
-		this.mask.show()
-
-		this.panel.show()
-		this.panel.reset()
-
-		this.panel.update({ type: 'input', task: this.task })
-
-		if (this.#abortController) {
-			this.#abortController.abort()
-			this.#abortController = new AbortController()
-		}
-
-		this.history = []
-
-		try {
-			let step = 0
-
-			while (true) {
-				await onBeforeStep.call(this, step)
-
-				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.panel.update({ type: 'thinking' })
-
-				const result = await this.#llm.invoke(
-					[
-						{
-							role: 'system',
-							content: this.#getSystemPrompt(),
-						},
-						{
-							role: 'user',
-							content: await this.#assembleUserPrompt(),
-						},
-					],
-					{ AgentOutput: this.#packMacroTool() },
-					this.#abortController.signal
-				)
-
-				const macroResult = result.toolResult as MacroToolResult
-				const input = macroResult.input
-				const output = macroResult.output
-				const brain = {
-					evaluation_previous_goal: input.evaluation_previous_goal || '',
-					memory: input.memory || '',
-					next_goal: input.next_goal || '',
-				}
-				const actionName = Object.keys(input.action)[0]
-				const action = {
-					name: actionName,
-					input: input.action[actionName],
-					output: output,
-				}
-
-				this.history.push({
-					brain,
-					action,
-					usage: result.usage,
-				})
-
-				console.log(chalk.green('Step finished:'), actionName)
-				console.groupEnd()
-
-				await onAfterStep.call(this, step, this.history)
-
-				step++
-				if (step > MAX_STEPS) {
-					this.#onDone('Step count exceeded maximum limit', false)
-					const result: ExecutionResult = {
-						success: false,
-						data: 'Step count exceeded maximum limit',
-						history: this.history,
-					}
-					await onAfterTask.call(this, result)
-					return result
-				}
-				if (actionName === 'done') {
-					const success = action.input?.success ?? false
-					const text = action.input?.text || 'no text provided'
-					console.log(chalk.green.bold('Task completed'), success, text)
-					this.#onDone(text, success)
-					const result: ExecutionResult = {
-						success,
-						data: text,
-						history: this.history,
-					}
-					await onAfterTask.call(this, result)
-					return result
-				}
-			}
-		} catch (error: unknown) {
-			console.error('Task failed', error)
-			this.#onDone(String(error), false)
-			const result: ExecutionResult = {
-				success: false,
-				data: String(error),
-				history: this.history,
-			}
-			await onAfterTask.call(this, result)
-			return result
-		}
-	}
-
-	/**
-	 * Merge all tools into a single MacroTool with the following input:
-	 * - thinking: string
-	 * - evaluation_previous_goal: string
-	 * - memory: string
-	 * - next_goal: string
-	 * - action: { toolName: toolInput }
-	 * where action must be selected from tools defined in this.tools
-	 */
-	#packMacroTool(): Tool<MacroToolInput, MacroToolResult> {
-		const tools = this.tools
-
-		const actionSchemas = Array.from(tools.entries()).map(([toolName, tool]) => {
-			return zod.object({ [toolName]: tool.inputSchema }).describe(tool.description)
 		})
 
-		const actionSchema = zod.union(
+		super({ ...config, pageController })
-			actionSchemas as unknown as [zod.ZodType, zod.ZodType, ...zod.ZodType[]]
-		)
 
-		const macroToolSchema = zod.object({
+		this.panel = new Panel(this, {
-			// thinking: zod.string().optional(),
+			language: config.language,
-			evaluation_previous_goal: zod.string().optional(),
-			memory: zod.string().optional(),
-			next_goal: zod.string().optional(),
-			action: actionSchema,
 		})
-
-		return {
-			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)
-				this.panel.update({ type: 'thinking', text: brain })
-
-				// 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.panel.update({ type: 'toolExecuting', toolName, args: toolInput })
-
-				const startTime = Date.now()
-
-				// Execute tool, bind `this` to PageAgent
-				let 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') {
-					this.#totalWaitTime += Math.round(toolInput.seconds + duration / 1000)
-					result += `\n<sys> You have waited ${this.#totalWaitTime} seconds accumulatively.`
-					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
-				this.panel.update({
-					type: 'toolCompleted',
-					toolName,
-					args: toolInput,
-					result,
-					duration,
-				})
-
-				// Wait a moment to let user see the result
-				await new Promise((resolve) => setTimeout(resolve, 100))
-
-				// Return structured result
-				return {
-					input,
-					output: result,
-				}
-			},
-		}
-	}
-
-	/**
-	 * Get system prompt, dynamically replace language settings based on configured language
-	 */
-	#getSystemPrompt(): string {
-		let systemPrompt = SYSTEM_PROMPT
-
-		const targetLanguage = this.config.language === 'zh-CN' ? '中文' : 'English'
-		systemPrompt = systemPrompt.replace(
-			/Default working language: \*\*.*?\*\*/,
-			`Default working language: **${targetLanguage}**`
-		)
-
-		return systemPrompt
-	}
-
-	/**
-	 * 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
-	}
-
-	async #assembleUserPrompt(): Promise<string> {
-		let prompt = ''
-
-		// <instructions> (optional)
-		prompt += await this.#getInstructions()
-
-		// <agent_state>
-		//  - <user_request>
-		//  - <step_info>
-		// <agent_state>
-
-		prompt += `<agent_state>
-			<user_request>
-			${this.task}
-			</user_request>
-			<step_info>
-			Step ${this.history.length + 1} of ${MAX_STEPS} max possible steps
-			Current date and time: ${new Date().toISOString()}
-			</step_info>
-			</agent_state>
-		`
-
-		// <agent_history>
-		//  - <step_>
-
-		prompt += '\n<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'
-
-		// <browser_state>
-
-		prompt += await this.#getBrowserState()
-
-		return trimLines(prompt)
-	}
-
-	#onDone(text: string, success = true) {
-		this.pageController.cleanUpHighlights()
-
-		// Update panel status
-		if (success) {
-			this.panel.update({ type: 'output', text })
-		} else {
-			this.panel.update({ type: 'error', message: text })
-		}
-
-		// Task completed
-		this.panel.update({ type: 'completed' })
-
-		this.mask.hide()
-
-		this.#abortController.abort()
-	}
-
-	async #getBrowserState(): Promise<string> {
-		const pageUrl = await this.pageController.getCurrentUrl()
-		const pageTitle = await this.pageController.getPageTitle()
-		const pi = await this.pageController.getPageInfo()
-		const viewportExpansion = await this.pageController.getViewportExpansion()
-
-		this.mask.wrapper.style.pointerEvents = 'none'
-		await this.pageController.updateTree()
-		this.mask.wrapper.style.pointerEvents = 'auto'
-
-		const simplifiedHTML = await this.pageController.getSimplifiedHTML()
-
-		let prompt = trimLines(`<browser_state>
-			Current Page: [${pageTitle}](${pageUrl})
-
-			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
-
-			${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:'}
-
-		`)
-
-		// Page header info
-		const has_content_above = pi.pixels_above > 4
-		if (has_content_above && viewportExpansion !== -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 += simplifiedHTML
-		prompt += `\n`
-
-		// Page footer info
-		const has_content_below = pi.pixels_below > 4
-		if (has_content_below && viewportExpansion !== -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
-	}
-
-	dispose(reason?: string) {
-		console.log('Disposing PageAgent...')
-		this.disposed = true
-		this.pageController.dispose()
-		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/demo.ts

@@ -1,5 +1,5 @@
 /**
- * Auto-run entry for page-agent.js. Insert this script into your page to get page-agent functionality.
+ * IIFE demo entry - auto-initializes with built-in demo API for testing
  */
 import { PageAgent, type PageAgentConfig } from './PageAgent'
 
@@ -11,9 +11,6 @@ if (window.pageAgent) {
 // 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'
@@ -21,9 +18,10 @@ const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm
 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
+	let config: PageAgentConfig
+
 	if (currentScript) {
 		console.log('🚀 page-agent.js detected current script:', currentScript.src)
 		const url = new URL(currentScript.src)
@@ -31,14 +29,18 @@ setTimeout(() => {
 		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 }
+		config = { 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()
+		config = {
+			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,
+		}
 	}
 
-	console.log('🚀 page-agent.js initialized with config:', window.pageAgent.config)
+	// Create agent
+	window.pageAgent = new PageAgent(config)
 
-	window.pageAgent.panel.show() // Show panel
+	console.log('🚀 page-agent.js initialized with config:', window.pageAgent.config)
 })

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

@@ -1,20 +1,9 @@
 /// <reference types="vite/client" />
 import type { PageAgent } from './PageAgent'
 
-declare module '*.module.css' {
-	const classes: Record<string, string>
-	export default classes
-}
-
-declare module '*.md?raw' {
-	const content: string
-	export default content
-}
-
 declare global {
 	interface Window {
 		pageAgent?: PageAgent
 		PageAgent: typeof PageAgent
-		__PAGE_AGENT_IDS__: string[]
 	}
 }

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

@@ -1,100 +0,0 @@
-/**
- * Event mapping definitions
- * @note Event bus callbacks must be repeatable without errors
- */
-export interface PageAgentEventMap {
-	// PageAgent status events
-	// '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:complete': { params: { text: string; success: boolean } }
-	// 'task:error': { params: { error: string | Error } }
-
-	// Index signature for dynamic event names
-	// [key: string]: { params: any }
-}
-
-/**
- * Event handler type definitions
- */
-export type EventHandler<T extends keyof PageAgentEventMap> =
-	PageAgentEventMap[T]['params'] extends undefined
-		? () => void
-		: (params: PageAgentEventMap[T]['params']) => void
-
-/**
- * Async event handler type definitions
- */
-export type AsyncEventHandler<T extends keyof PageAgentEventMap> =
-	PageAgentEventMap[T]['params'] extends undefined
-		? () => Promise<void>
-		: (params: PageAgentEventMap[T]['params']) => Promise<void>
-
-/**
- * Type-safe event bus
- * @note Mainly used to decouple logic and UI
- * @note All modules of a PageAgent instance share the same EventBus instance for communication
- * @note Use with caution if delivery guarantee is needed for logic communication
- * @note `on` `once` `emit` methods handle built-in events with type protection, use `addEventListener` for other events
- */
-class EventBus extends EventTarget {
-	/**
-	 * Listen to built-in events
-	 */
-	on<T extends keyof PageAgentEventMap>(event: T, handler: EventHandler<T>): void {
-		const wrappedHandler = (e: Event) => {
-			const customEvent = e as CustomEvent
-			const params = customEvent.detail?.[0]
-			return handler(params)
-		}
-		this.addEventListener(event, wrappedHandler)
-	}
-
-	/**
-	 * Listen to built-in events (one-time)
-	 */
-	once<T extends keyof PageAgentEventMap>(event: T, handler: EventHandler<T>): void {
-		const wrappedHandler = (e: Event) => {
-			const customEvent = e as CustomEvent
-			const params = customEvent.detail?.[0]
-			return handler(params)
-		}
-		this.addEventListener(event, wrappedHandler, { once: true })
-	}
-
-	/**
-	 * Emit built-in events
-	 */
-	emit<T extends keyof PageAgentEventMap>(
-		event: T,
-		...args: PageAgentEventMap[T]['params'] extends undefined
-			? []
-			: [PageAgentEventMap[T]['params']]
-	): void {
-		const customEvent = new CustomEvent(event, { detail: args })
-		this.dispatchEvent(customEvent)
-		return
-	}
-}
-
-const buses = new Map<string, EventBus>()
-
-/**
- * Get the event bus for a given channel
- */
-export function getEventBus(channel: string) {
-	if (buses.has(channel)) {
-		return buses.get(channel)!
-	}
-	const bus = new EventBus()
-	buses.set(channel, bus)
-	return bus
-}
-
-export type { EventBus }

packages/page-agent/tsconfig.dts.json

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

packages/page-agent/tsconfig.json

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

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

@@ -1,4 +1,5 @@
 // @ts-check
+import { config as dotenvConfig } from 'dotenv'
 import { dirname, resolve } from 'path'
 import { fileURLToPath } from 'url'
 import { defineConfig } from 'vite'
@@ -6,11 +7,14 @@ 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({
+export default defineConfig(({ mode }) => ({
 	plugins: [cssInjectedByJsPlugin({ relativeCSSInjection: true })],
 	publicDir: false,
 	esbuild: {
@@ -20,26 +24,34 @@ export default defineConfig({
 		alias: {
 			'@page-agent/page-controller': resolve(__dirname, '../page-controller/src/PageController.ts'),
 			'@page-agent/llms': resolve(__dirname, '../llms/src/index.ts'),
+			'@page-agent/core': resolve(__dirname, '../core/src/PageAgentCore.ts'),
 			'@page-agent/ui': resolve(__dirname, '../ui/src/index.ts'),
 		},
 	},
 	build: {
 		lib: {
-			entry: resolve(__dirname, 'src/umd.ts'),
+			entry: resolve(__dirname, 'src/demo.ts'),
 			name: 'PageAgent',
-			fileName: 'page-agent',
+			fileName: () => `page-agent.demo.js`,
-			formats: ['umd'],
+			formats: ['iife'],
 		},
-		outDir: resolve(__dirname, 'dist', 'umd'),
+		outDir: resolve(__dirname, 'dist', 'iife'),
+		cssCodeSplit: true,
+		// minify: false,
 		rollupOptions: {
-			output: {
+			// output: {
-				// force use .js as extension
+			// 	// force use .js as extension
-				entryFileNames: 'page-agent.js',
+			// 	entryFileNames: 'page-agent.js',
+			// },
+			onwarn: function (message, handler) {
+				if (message.code === 'EVAL') return
+				handler(message)
 			},
 		},
-		cssCodeSplit: true,
 	},
 	define: {
-		'process.env.NODE_ENV': '"production"',
+		'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

@@ -1,6 +1,6 @@
 {
 	"name": "@page-agent/page-controller",
-	"version": "0.0.19",
+	"version": "0.3.0-beta.2",
 	"type": "module",
 	"main": "./dist/lib/page-controller.js",
 	"module": "./dist/lib/page-controller.js",
@@ -34,5 +34,8 @@
 		"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

@@ -25,6 +25,22 @@ import { patchReact } from './patches/react'
  */
 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 {
@@ -64,14 +80,29 @@ export class PageController extends EventTarget {
 	/** last time the tree was updated */
 	private lastTimeUpdate = 0
 
+	/** Visual mask overlay for blocking user interaction during automation */
+	private mask: InstanceType<typeof import('./mask/SimulatorMask').SimulatorMask> | null = null
+	private maskReady: Promise<void> | null = null
+
 	constructor(config: PageControllerConfig = {}) {
 		super()
 
 		this.config = config
 
 		patchReact(this)
+
+		if (config.enableMask) {
+			this.maskReady = this.initMask()
+		}
 	}
 
+	/**
+	 * Initialize mask asynchronously (dynamic import to avoid CSS loading in Node)
+	 */
+	private async initMask(): Promise<void> {
+		const { SimulatorMask } = await import('./mask/SimulatorMask')
+		this.mask = new SimulatorMask()
+	}
 	// ======= State Queries =======
 
 	/**
@@ -81,42 +112,6 @@ export class PageController extends EventTarget {
 		return window.location.href
 	}
 
-	/**
-	 * Get current page title
-	 */
-	async getPageTitle(): Promise<string> {
-		return document.title
-	}
-
-	/**
-	 * Get page scroll and size info
-	 */
-	async getPageInfo() {
-		return getPageInfo()
-	}
-
-	/**
-	 * Get the simplified HTML representation of the page.
-	 * This is used by LLM to understand the page structure.
-	 */
-	async getSimplifiedHTML(): Promise<string> {
-		return this.simplifiedHTML
-	}
-
-	/**
-	 * Get text description for an element by index
-	 */
-	async getElementText(index: number): Promise<string | undefined> {
-		return this.elementTextMap.get(index)
-	}
-
-	/**
-	 * Get total number of indexed interactive elements
-	 */
-	async getElementCount(): Promise<number> {
-		return this.selectorMap.size
-	}
-
 	/**
 	 * Get last tree update timestamp
 	 */
@@ -125,10 +120,43 @@ export class PageController extends EventTarget {
 	}
 
 	/**
-	 * Get the viewport expansion setting
+	 * Get structured browser state for LLM consumption.
+	 * Automatically calls updateTree() to refresh the DOM state.
 	 */
-	async getViewportExpansion(): Promise<number> {
+	async getBrowserState(): Promise<BrowserState> {
-		return this.config.viewportExpansion ?? VIEWPORT_EXPANSION
+		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 =======
@@ -136,12 +164,18 @@ export class PageController extends EventTarget {
 	/**
 	 * 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 = [
@@ -162,6 +196,11 @@ export class PageController extends EventTarget {
 		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
@@ -326,6 +365,26 @@ export class PageController extends EventTarget {
 		}
 	}
 
+	// ======= Mask Operations =======
+
+	/**
+	 * Show the visual mask overlay.
+	 * Only works if enableMask was set to true in config.
+	 */
+	async showMask(): Promise<void> {
+		await this.maskReady
+		this.mask?.show()
+	}
+
+	/**
+	 * Hide the visual mask overlay.
+	 * Only works if enableMask was set to true in config.
+	 */
+	async hideMask(): Promise<void> {
+		await this.maskReady
+		this.mask?.hide()
+	}
+
 	/**
 	 * Dispose and clean up resources
 	 */
@@ -335,5 +394,7 @@ export class PageController extends EventTarget {
 		this.selectorMap.clear()
 		this.elementTextMap.clear()
 		this.simplifiedHTML = '<EMPTY>'
+		this.mask?.dispose()
+		this.mask = null
 	}
 }

packages/page-controller/src/actions.ts

@@ -287,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.`
 	}
 }
 
@@ -410,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/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/env.d.ts

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

packages/page-controller/tsconfig.dts.json

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

packages/page-controller/tsconfig.json

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

packages/page-controller/vite.config.js

@@ -29,7 +29,11 @@ export default defineConfig({
 		},
 		outDir: resolve(__dirname, 'dist', 'lib'),
 		rollupOptions: {
-			external: ['@page-agent/*'],
+			external: ['@page-agent/*', 'ai-motion'],
+			onwarn: function (message, handler) {
+				if (message.code === 'EVAL') return
+				handler(message)
+			},
 		},
 		minify: false,
 		sourcemap: true,

packages/ui/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@page-agent/ui",
-	"version": "0.0.19",
+	"version": "0.3.0-beta.2",
 	"type": "module",
 	"main": "./dist/lib/page-agent-ui.js",
 	"module": "./dist/lib/page-agent-ui.js",
@@ -15,7 +15,7 @@
 	"files": [
 		"dist/"
 	],
-	"description": "UI components for page-agent - Panel, SimulatorMask, and i18n",
+	"description": "UI components for page-agent - Panel and i18n",
 	"keywords": [
 		"page-agent",
 		"ui",
@@ -34,8 +34,5 @@
 		"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.7"
 	}
 }

packages/ui/src/UIState.ts

@@ -1,93 +0,0 @@
-/**
- * Agent execution state management
- */
-
-export interface Step {
-	id: string
-	stepNumber: number
-	timestamp: Date
-	type: 'thinking' | 'tool_executing' | 'completed' | 'error' | 'output' | 'input' | 'retry'
-
-	// Tool execution related
-	toolName?: string
-	toolArgs?: any
-	toolResult?: any
-
-	// Display data
-	displayText: string
-	duration?: number
-}
-
-export type AgentStatus = 'idle' | 'running' | 'paused' | 'completed' | 'error'
-
-export class UIState {
-	private steps: Step[] = []
-	private currentStep: Step | null = null
-	private status: AgentStatus = 'idle'
-	private stepCounter = 0
-
-	addStep(stepData: Omit<Step, 'id' | 'stepNumber' | 'timestamp'>): Step {
-		const step: Step = {
-			id: this.generateId(),
-			stepNumber: ++this.stepCounter,
-			timestamp: new Date(),
-			...stepData,
-		}
-
-		this.steps.push(step)
-		this.currentStep = step
-
-		// Update overall status
-		this.updateStatus(step.type)
-
-		return step
-	}
-
-	updateCurrentStep(updates: Partial<Step>): Step | null {
-		if (!this.currentStep) return null
-
-		Object.assign(this.currentStep, updates)
-		return this.currentStep
-	}
-
-	getCurrentStep(): Step | null {
-		return this.currentStep
-	}
-
-	getAllSteps(): Step[] {
-		return [...this.steps]
-	}
-
-	getStatus(): AgentStatus {
-		return this.status
-	}
-
-	reset(): void {
-		this.steps = []
-		this.currentStep = null
-		this.status = 'idle'
-		this.stepCounter = 0
-	}
-
-	private updateStatus(stepType: Step['type']): void {
-		switch (stepType) {
-			case 'thinking':
-			case 'tool_executing':
-			case 'output':
-			case 'input':
-			case 'retry':
-				this.status = 'running'
-				break
-			case 'completed':
-				this.status = 'completed'
-				break
-			case 'error':
-				this.status = 'error'
-				break
-		}
-	}
-
-	private generateId(): string {
-		return `step_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`
-	}
-}

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',
@@ -26,6 +22,7 @@ const enUS = {
 			selecting: 'Selecting option "{{text}}"...',
 			scrolling: 'Scrolling page...',
 			waiting: 'Waiting {{seconds}} seconds...',
+			askingUser: 'Asking user...',
 			done: 'Task done',
 			clicked: '🖱️ Clicked element [{{index}}]',
 			inputted: '⌨️ Inputted text "{{text}}"',
@@ -54,17 +51,13 @@ const zhCN = {
 		panel: {
 			ready: '准备就绪',
 			thinking: '正在思考...',
-			paused: '暂停中，稍后',
 			taskInput: '输入新任务，详细描述步骤，回车提交',
 			userAnswerPrompt: '请回答上面问题，回车提交',
 			taskTerminated: '任务已终止',
 			taskCompleted: '任务结束',
-			continueExecution: '继续执行',
 			userAnswer: '用户回答: {{input}}',
 			question: '询问: {{question}}',
 			waitingPlaceholder: '等待任务开始...',
-			pause: '暂停',
-			continue: '继续',
 			stop: '终止',
 			expand: '展开历史',
 			collapse: '收起历史',
@@ -76,6 +69,7 @@ const zhCN = {
 			selecting: '正在选择选项 "{{text}}"...',
 			scrolling: '正在滚动页面...',
 			waiting: '等待 {{seconds}} 秒...',
+			askingUser: '正在询问用户...',
 			done: '结束任务',
 			clicked: '🖱️ 已点击元素 [{{index}}]',
 			inputted: '⌨️ 已输入文本 "{{text}}"',

packages/ui/src/index.ts

@@ -1,4 +1,3 @@
-export { Panel, type PanelConfig, type PanelUpdate } from './Panel'
+export { Panel, type PanelConfig } from './panel/Panel'
-export { SimulatorMask } from './SimulatorMask'
+export type { AgentActivity, PanelAgentAdapter } from './panel/types'
-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/panel/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,16 @@
 				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));
+			}
+
+			&.question {
+				border-left-color: rgb(255, 159, 67);
+				background: linear-gradient(135deg, rgba(255, 159, 67, 0.15), rgba(255, 159, 67, 0.08));
+			}
+
 			/* 突出显示 done 成功结果 */
 			&.doneSuccess {
 				background: linear-gradient(
@@ -446,7 +444,7 @@
 
 			.historyContent {
 				display: flex;
-				align-items: center;
+				align-items: flex-start;
 				gap: 8px;
 
 				word-break: break-all;
@@ -460,6 +458,12 @@
 					line-height: 1;
 					transition: all 0.3s ease;
 				}
+
+				.reflectionLines {
+					display: flex;
+					flex-direction: column;
+					gap: 4px;
+				}
 			}
 
 			.historyMeta {

packages/ui/src/panel/Panel.ts

@@ -1,6 +1,7 @@
-import { type Step, UIState } from './UIState'
+import { I18n, type SupportedLanguage } from '../i18n'
-import { I18n, type SupportedLanguage } from './i18n'
+import { truncate } from '../utils'
-import { truncate } from './utils'
+import { createCard, createReflectionLines, formatTime } from './cards'
+import type { AgentActivity, PanelAgentAdapter } from './types'
 
 import styles from './Panel.module.css'
 
@@ -9,29 +10,22 @@ import styles from './Panel.module.css'
  */
 export interface PanelConfig {
 	language?: SupportedLanguage
-	onExecuteTask: (task: string) => void
+	/**
-	onStop: () => void
+	 * Whether to prompt for next task after task completion
-	onPauseToggle: () => boolean // returns new paused state
+	 * @default true
-	getPaused: () => boolean
+	 */
+	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 }
-
 /**
  * Agent control panel
+ *
+ * Architecture:
+ * - History list: renders directly from agent.history (historical events)
+ * - Header bar: shows activity events (transient state) and agent status
+ *
+ * This separation ensures data consistency - history is the single source of truth
+ * for what has been done, while activity shows what is happening now.
  */
 export class Panel {
 	#wrapper: HTMLElement
@@ -39,14 +33,13 @@ export class Panel {
 	#statusText: HTMLElement
 	#historySection: HTMLElement
 	#expandButton: HTMLElement
-	#pauseButton: HTMLElement
 	#stopButton: HTMLElement
 	#inputSection: HTMLElement
 	#taskInput: HTMLInputElement
 
-	#state = new UIState()
+	#agent: PanelAgentAdapter
-	#isExpanded = false
 	#config: PanelConfig
+	#isExpanded = false
 	#i18n: I18n
 	#userAnswerResolver: ((input: string) => void) | null = null
 	#isWaitingForUserAnswer: boolean = false
@@ -54,47 +47,145 @@ export class Panel {
 	#pendingHeaderText: string | null = null
 	#isAnimating = false
 
+	// Event handlers (bound for removal)
+	#onStatusChange = () => this.#handleStatusChange()
+	#onHistoryChange = () => this.#handleHistoryChange()
+	#onActivity = (e: Event) => this.#handleActivity((e as CustomEvent<AgentActivity>).detail)
+	#onAgentDispose = () => this.dispose()
+
 	get wrapper(): HTMLElement {
 		return this.#wrapper
 	}
 
-	constructor(config: PanelConfig) {
+	/**
+	 * Create a Panel bound to an agent
+	 * @param agent - Agent instance that implements PanelAgentAdapter
+	 * @param config - Optional panel configuration
+	 */
+	constructor(agent: PanelAgentAdapter, config: PanelConfig = {}) {
+		this.#agent = agent
 		this.#config = config
 		this.#i18n = new I18n(config.language ?? 'en-US')
+
+		// Set up askUser callback on agent
+		this.#agent.onAskUser = (question) => this.#askUser(question)
+
+		// Create UI elements
 		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}`)!
 
+		// Listen to agent events
+		this.#agent.addEventListener('statuschange', this.#onStatusChange)
+		this.#agent.addEventListener('historychange', this.#onHistoryChange)
+		this.#agent.addEventListener('activity', this.#onActivity)
+		this.#agent.addEventListener('dispose', this.#onAgentDispose)
+
 		this.#setupEventListeners()
 		this.#startHeaderUpdateLoop()
 
 		this.#showInputArea()
+
+		this.hide() // Start hidden
+	}
+
+	// ========== Agent event handlers ==========
+
+	/** Handle agent status change */
+	#handleStatusChange(): void {
+		const status = this.#agent.status
+
+		// Map agent status to UI indicator type
+		const indicatorType =
+			status === 'running' ? 'thinking' : status === 'idle' ? 'thinking' : status
+		this.#updateStatusIndicator(indicatorType)
+
+		// Show/hide based on status
+		if (status === 'running') {
+			this.show()
+			this.#hideInputArea() // Hide input while running
+		}
+
+		// Handle completion
+		if (status === 'completed' || status === 'error') {
+			if (!this.#isExpanded) {
+				this.#expand()
+			}
+			if (this.#shouldShowInputArea()) {
+				this.#showInputArea()
+			}
+		}
+	}
+
+	/** Handle agent history change - re-render history list from agent.history */
+	#handleHistoryChange(): void {
+		this.#renderHistory()
 	}
 
 	/**
-	 * Ask for user input
+	 * Handle agent activity - transient state for immediate UI feedback
+	 * Activity events are NOT persisted in history, only used for header bar updates
 	 */
-	async askUser(question: string): Promise<string> {
+	#handleActivity(activity: AgentActivity): void {
+		switch (activity.type) {
+			case 'thinking':
+				this.#pendingHeaderText = this.#i18n.t('ui.panel.thinking')
+				this.#updateStatusIndicator('thinking')
+				break
+
+			case 'executing':
+				this.#pendingHeaderText = this.#getToolExecutingText(activity.tool, activity.input)
+				this.#updateStatusIndicator('executing')
+				break
+
+			case 'executed':
+				this.#pendingHeaderText = truncate(activity.output, 50)
+				break
+
+			case 'retrying':
+				this.#pendingHeaderText = `Retrying (${activity.attempt}/${activity.maxAttempts})`
+				this.#updateStatusIndicator('retrying')
+				break
+
+			case 'error':
+				this.#pendingHeaderText = truncate(activity.message, 50)
+				this.#updateStatusIndicator('error')
+				break
+		}
+	}
+
+	/**
+	 * Ask for user input (internal, called by agent via onAskUser)
+	 */
+	#askUser(question: string): Promise<string> {
 		return new Promise((resolve) => {
 			// Set `waiting for user answer` state
 			this.#isWaitingForUserAnswer = true
 			this.#userAnswerResolver = resolve
 
-			// Update state to `running`
+			// Expand history panel
-			this.#updateInternal({
-				type: 'output',
-				displayText: this.#i18n.t('ui.panel.question', { question }),
-			}) // Expand history panel
 			if (!this.#isExpanded) {
 				this.#expand()
 			}
 
+			// Add temporary question card so user can see the full question
+			const tempCard = document.createElement('div')
+			tempCard.innerHTML = createCard({
+				icon: '❓',
+				content: `Question: ${question}`,
+				meta: formatTime(this.#config.language ?? 'en-US'),
+				type: 'question',
+			})
+			const cardElement = tempCard.firstElementChild as HTMLElement
+			cardElement.setAttribute('data-temp-card', 'true')
+			this.#historySection.appendChild(cardElement)
+			this.#scrollToBottom()
+
 			this.#showInputArea(this.#i18n.t('ui.panel.userAnswerPrompt'))
 		})
 	}
@@ -115,16 +206,10 @@ export class Panel {
 	}
 
 	reset(): void {
-		this.#state.reset()
 		this.#statusText.textContent = this.#i18n.t('ui.panel.ready')
 		this.#updateStatusIndicator('thinking')
-		this.#updateHistory()
+		this.#renderHistory()
 		this.#collapse()
-		// Reset pause state via callback
-		if (this.#config.getPaused()) {
-			this.#config.onPauseToggle()
-		}
-		this.#updatePauseButton()
 		// Reset user input state
 		this.#isWaitingForUserAnswer = false
 		this.#userAnswerResolver = null
@@ -141,17 +226,16 @@ export class Panel {
 	}
 
 	/**
-	 * Update panel with semantic data - i18n handled internally
+	 * Dispose panel and clean up event listeners
-	 */
-	update(data: PanelUpdate): void {
-		const stepData = this.#toStepData(data)
-		this.#updateInternal(stepData)
-	}
-
-	/**
-	 * Dispose panel
 	 */
 	dispose(): void {
+		// Remove agent event listeners
+		this.#agent.removeEventListener('statuschange', this.#onStatusChange)
+		this.#agent.removeEventListener('historychange', this.#onHistoryChange)
+		this.#agent.removeEventListener('activity', this.#onActivity)
+		this.#agent.removeEventListener('dispose', this.#onAgentDispose)
+
+		// Clean up UI
 		this.#isWaitingForUserAnswer = false
 		this.#stopHeaderUpdateLoop()
 		this.wrapper.remove()
@@ -159,67 +243,21 @@ export class Panel {
 
 	// ========== Private methods ==========
 
-	/**
+	#getToolExecutingText(toolName: string, args: unknown): string {
-	 * Convert semantic update to step data with i18n
+		const a = args as Record<string, string | number>
-	 */
-	#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,
-				}
-			}
-		}
-	}
-
-	#getToolExecutingText(toolName: string, args: any): string {
 		switch (toolName) {
 			case 'click_element_by_index':
-				return this.#i18n.t('ui.tools.clicking', { index: args.index })
+				return this.#i18n.t('ui.tools.clicking', { index: a.index })
 			case 'input_text':
-				return this.#i18n.t('ui.tools.inputting', { index: args.index })
+				return this.#i18n.t('ui.tools.inputting', { index: a.index })
 			case 'select_dropdown_option':
-				return this.#i18n.t('ui.tools.selecting', { text: args.text })
+				return this.#i18n.t('ui.tools.selecting', { text: a.text })
 			case 'scroll':
 				return this.#i18n.t('ui.tools.scrolling')
 			case 'wait':
-				return this.#i18n.t('ui.tools.waiting', { seconds: args.seconds })
+				return this.#i18n.t('ui.tools.waiting', { seconds: a.seconds })
+			case 'ask_user':
+				return this.#i18n.t('ui.tools.askingUser')
 			case 'done':
 				return this.#i18n.t('ui.tools.done')
 			default:
@@ -227,100 +265,11 @@ export class Panel {
 		}
 	}
 
-	#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)
-		const headerText = truncate(step.displayText, 20)
-		this.#pendingHeaderText = headerText
-
-		this.#updateStatusIndicator(step.type)
-		this.#updateHistory()
-
-		// Auto-expand history after task completion
-		if (step.type === 'completed' || step.type === 'error') {
-			if (!this.#isExpanded) {
-				this.#expand()
-			}
-		}
-
-		// Control input area display based on status
-		if (this.#shouldShowInputArea()) {
-			this.#showInputArea()
-		} else {
-			this.#hideInputArea()
-		}
-	}
-
-	/**
-	 * Toggle pause state
-	 */
-	#togglePause(): void {
-		const paused = this.#config.onPauseToggle()
-		this.#updatePauseButton()
-
-		// Update status display
-		if (paused) {
-			this.#statusText.textContent = this.#i18n.t('ui.panel.paused')
-			this.#updateStatusIndicator('thinking')
-		} else {
-			this.#statusText.textContent = this.#i18n.t('ui.panel.continueExecution')
-			this.#updateStatusIndicator('tool_executing')
-		}
-	}
-
-	/**
-	 * Update pause button state
-	 */
-	#updatePauseButton(): void {
-		const paused = this.#config.getPaused()
-		if (paused) {
-			this.#pauseButton.textContent = '▶'
-			this.#pauseButton.title = this.#i18n.t('ui.panel.continue')
-			this.#pauseButton.classList.add(styles.paused)
-		} else {
-			this.#pauseButton.textContent = '⏸︎'
-			this.#pauseButton.title = this.#i18n.t('ui.panel.pause')
-			this.#pauseButton.classList.remove(styles.paused)
-		}
-	}
-
 	/**
 	 * Stop Agent
 	 */
 	#stopAgent(): void {
-		// Update status display
+		this.#agent.dispose()
-		this.#updateInternal({
-			type: 'error',
-			displayText: this.#i18n.t('ui.panel.taskTerminated'),
-		})
-
-		this.#config.onStop()
 	}
 
 	/**
@@ -337,7 +286,8 @@ export class Panel {
 			// Handle user input mode
 			this.#handleUserAnswer(input)
 		} else {
-			this.#config.onExecuteTask(input)
+			// Execute task via agent
+			this.#agent.execute(input)
 		}
 	}
 
@@ -345,10 +295,11 @@ export class Panel {
 	 * Handle user answer
 	 */
 	#handleUserAnswer(input: string): void {
-		// Add user input to history
+		// Remove temporary question cards (only direct children for safety)
-		this.#updateInternal({
+		Array.from(this.#historySection.children).forEach((child) => {
-			type: 'input',
+			if (child.getAttribute('data-temp-card') === 'true') {
-			displayText: this.#i18n.t('ui.panel.userAnswer', { input }),
+				child.remove()
+			}
 		})
 
 		// Reset state
@@ -389,32 +340,38 @@ export class Panel {
 		// Always show input area if waiting for user input
 		if (this.#isWaitingForUserAnswer) return true
 
-		const steps = this.#state.getAllSteps()
+		const history = this.#agent.history
-		if (steps.length === 0) {
+		if (history.length === 0) {
 			return true // Initial state
 		}
 
-		const lastStep = steps[steps.length - 1]
+		const status = this.#agent.status
-		return lastStep.type === 'completed' || lastStep.type === 'error'
+		const isTaskEnded = status === 'completed' || status === '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 = `
 			<div class="${styles.background}"></div>
 			<div class="${styles.historySectionWrapper}">
 				<div class="${styles.historySection}">
-					${this.#createHistoryItem({
+					<div class="${styles.historyItem}">
-						id: 'placeholder',
+						<div class="${styles.historyContent}">
-						stepNumber: 0,
+							<span class="${styles.statusIcon}">🧠</span>
-						timestamp: new Date(),
+							<span>${this.#i18n.t('ui.panel.waitingPlaceholder')}</span>
-						type: 'thinking',
+						</div>
-						displayText: this.#i18n.t('ui.panel.waitingPlaceholder'),
+					</div>
-					})}
 				</div>
 			</div>
 			<div class="${styles.header}">
@@ -426,9 +383,6 @@ export class Panel {
 					<button class="${styles.controlButton} ${styles.expandButton}" title="${this.#i18n.t('ui.panel.expand')}">
 						▼
 					</button>
-					<button class="${styles.controlButton} ${styles.pauseButton}" title="${this.#i18n.t('ui.panel.pause')}">
-						⏸︎
-					</button>
 					<button class="${styles.controlButton} ${styles.stopButton}" title="${this.#i18n.t('ui.panel.stop')}">
 						X
 					</button>
@@ -466,12 +420,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()
@@ -503,7 +451,6 @@ export class Panel {
 
 	#expand(): void {
 		this.#isExpanded = true
-		this.wrapper.classList.remove(styles.collapsed)
 		this.wrapper.classList.add(styles.expanded)
 		this.#expandButton.textContent = '▲'
 	}
@@ -511,7 +458,6 @@ export class Panel {
 	#collapse(): void {
 		this.#isExpanded = false
 		this.wrapper.classList.remove(styles.expanded)
-		this.wrapper.classList.add(styles.collapsed)
 		this.#expandButton.textContent = '▼'
 	}
 
@@ -580,7 +526,9 @@ export class Panel {
 		}, 150) // Half the duration of fade out animation
 	}
 
-	#updateStatusIndicator(type: Step['type']): void {
+	#updateStatusIndicator(
+		type: 'thinking' | 'executing' | 'executed' | 'retrying' | 'completed' | 'error'
+	): void {
 		// Clear all status classes
 		this.#indicator.className = styles.indicator
 
@@ -588,15 +536,6 @@ export class Panel {
 		this.#indicator.classList.add(styles[type])
 	}
 
-	#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()
-	}
-
 	#scrollToBottom(): void {
 		// Execute in next event loop to ensure DOM update completion
 		setTimeout(() => {
@@ -604,68 +543,107 @@ export class Panel {
 		}, 0)
 	}
 
-	#createHistoryItem(step: Step): string {
+	/**
-		const time = step.timestamp.toLocaleTimeString('zh-CN', {
+	 * Render history directly from agent.history
-			hour12: false,
+	 *
-			hour: '2-digit',
+	 * Renders:
-			minute: '2-digit',
+	 * 1. Task (first item, from agent.task)
-			second: '2-digit',
+	 * 2. Reflection cards (evaluation, memory, next_goal)
-		})
+	 * 3. Tool execution with output
+	 * 4. Observations
+	 */
+	#renderHistory(): void {
+		const items: string[] = []
 
-		let typeClass = ''
+		// 1. Task card (always first)
-		let statusIcon = ''
+		const task = this.#agent.task
-
+		if (task) {
-		// Set styles and icons based on step type
+			items.push(this.#createTaskCard(task))
-		if (step.type === 'completed') {
-			// Check if this is a result from done tool
-			if (step.toolName === 'done') {
-				// Judge success or failure based on result
-				const failureKeyword = this.#i18n.t('ui.tools.resultFailure')
-				const errorKeyword = this.#i18n.t('ui.tools.resultError')
-				const isSuccess =
-					!step.toolResult ||
-					(!step.toolResult.includes(failureKeyword) && !step.toolResult.includes(errorKeyword))
-				typeClass = isSuccess ? styles.doneSuccess : styles.doneError
-				statusIcon = isSuccess ? '🎉' : '❌'
-			} else {
-				typeClass = styles.completed
-				statusIcon = '✅'
-			}
-		} else if (step.type === 'error') {
-			typeClass = styles.error
-			statusIcon = '❌'
-		} else if (step.type === 'tool_executing') {
-			statusIcon = '⚙️'
-		} else if (step.type === 'output') {
-			typeClass = styles.output
-			statusIcon = '🤖'
-		} else if (step.type === 'input') {
-			typeClass = styles.input
-			statusIcon = '🎯'
-		} else if (step.type === 'retry') {
-			typeClass = styles.retry
-			statusIcon = '🔄'
-		} else {
-			statusIcon = '🧠'
 		}
 
-		const durationText = step.duration ? ` · ${step.duration}ms` : ''
+		// 2. Render each history event
-		const stepLabel = this.#i18n.t('ui.panel.step', {
+		const history = this.#agent.history
-			number: step.stepNumber.toString(),
+		for (let i = 0; i < history.length; i++) {
+			const event = history[i]
+			items.push(...this.#createHistoryCards(event, i + 1))
+		}
+
+		this.#historySection.innerHTML = items.join('')
+		this.#scrollToBottom()
+	}
+
+	#createTaskCard(task: string): string {
+		return createCard({ icon: '🎯', content: task, type: 'input' })
+	}
+
+	/** Create cards for a history event */
+	#createHistoryCards(event: PanelAgentAdapter['history'][number], stepNumber: number): string[] {
+		const cards: string[] = []
+		const time = formatTime(this.#config.language ?? 'en-US')
+		const meta = this.#i18n.t('ui.panel.step', {
+			number: stepNumber.toString(),
 			time,
-			duration: durationText || '', // Explicitly pass empty string to replace template
+			duration: '',
 		})
 
-		return `
+		if (event.type === 'step') {
-			<div class="${styles.historyItem} ${typeClass}">
+			// Reflection card
-				<div class="${styles.historyContent}">
+			if (event.reflection) {
-					<span class="${styles.statusIcon}">${statusIcon}</span>
+				const lines = createReflectionLines(event.reflection)
-					<span>${step.displayText}</span>
+				if (lines.length > 0) {
-				</div>
+					cards.push(createCard({ icon: '🧠', content: lines, meta }))
-				<div class="${styles.historyMeta}">
+				}
-					${stepLabel}
+			}
-				</div>
+
-			</div>
+			// Action card
-		`
+			const action = event.action
+			if (action) {
+				cards.push(...this.#createActionCards(action, meta))
+			}
+		} else if (event.type === 'observation') {
+			cards.push(
+				createCard({ icon: '👁️', content: event.content || '', meta, type: 'observation' })
+			)
+		} else if (event.type === 'user_takeover') {
+			cards.push(createCard({ icon: '👤', content: 'User takeover', meta, type: 'input' }))
+		}
+
+		return cards
+	}
+
+	/** Create cards for an action */
+	#createActionCards(
+		action: { name: string; input: unknown; output: string },
+		meta: string
+	): string[] {
+		const cards: string[] = []
+
+		if (action.name === 'done') {
+			const input = action.input as { text?: string }
+			const text = input.text || action.output || ''
+			if (text) {
+				cards.push(createCard({ icon: '🤖', content: text, meta, type: 'output' }))
+			}
+		} else if (action.name === 'ask_user') {
+			const input = action.input as { question?: string }
+			const answer = action.output.replace(/^User answered:\s*/i, '')
+			cards.push(
+				createCard({
+					icon: '❓',
+					content: `Question: ${input.question || ''}`,
+					meta,
+					type: 'question',
+				})
+			)
+			cards.push(createCard({ icon: '💬', content: `Answer: ${answer}`, meta, type: 'input' }))
+		} else {
+			const toolText = this.#getToolExecutingText(action.name, action.input)
+			cards.push(createCard({ icon: '🔨', content: toolText, meta }))
+			if (action.output?.length > 0) {
+				cards.push(createCard({ icon: '🔨', content: action.output, meta, type: 'output' }))
+			}
+		}
+
+		return cards
 	}
 }

packages/ui/src/panel/cards.ts

@@ -0,0 +1,62 @@
+/**
+ * Card HTML generation utilities for Panel
+ */
+import { escapeHtml } from '../utils'
+
+import styles from './Panel.module.css'
+
+type CardType = 'default' | 'input' | 'output' | 'question' | 'observation'
+
+interface CardOptions {
+	icon: string
+	content: string | string[]
+	meta?: string
+	type?: CardType
+}
+
+/** Create a single history card */
+export function createCard({ icon, content, meta, type }: CardOptions): string {
+	const typeClass = type ? styles[type] : ''
+	const contentHtml = Array.isArray(content)
+		? `<div class="${styles.reflectionLines}">${content.join('')}</div>`
+		: `<span>${escapeHtml(content)}</span>`
+
+	return `
+		<div class="${styles.historyItem} ${typeClass}">
+			<div class="${styles.historyContent}">
+				<span class="${styles.statusIcon}">${icon}</span>
+				${contentHtml}
+			</div>
+			${meta ? `<div class="${styles.historyMeta}">${meta}</div>` : ''}
+		</div>
+	`
+}
+
+/** Format timestamp for cards */
+export function formatTime(locale: string = 'en-US'): string {
+	return new Date().toLocaleTimeString(locale, {
+		hour12: false,
+		hour: '2-digit',
+		minute: '2-digit',
+		second: '2-digit',
+	})
+}
+
+/** Create reflection lines from reflection object */
+export function createReflectionLines(reflection: {
+	evaluation_previous_goal?: string
+	memory?: string
+	next_goal?: string
+}): string[] {
+	const lines: string[] = []
+	if (reflection.evaluation_previous_goal) {
+		lines.push(`<div>🔍 ${escapeHtml(reflection.evaluation_previous_goal)}</div>`)
+	}
+	if (reflection.memory) {
+		lines.push(`<div>💾 ${escapeHtml(reflection.memory)}</div>`)
+	}
+	if (reflection.next_goal) {
+		lines.push(`<div>🎯 ${escapeHtml(reflection.next_goal)}</div>`)
+	}
+	return lines
+}

packages/ui/src/panel/types.ts

@@ -0,0 +1,67 @@
+/**
+ * Agent activity - transient state for immediate UI feedback.
+ *
+ * Unlike historical events (which are persisted), activities are ephemeral
+ * and represent "what the agent is doing right now". UI components should
+ * listen to 'activity' events to show real-time feedback.
+ *
+ * Note: There is no 'idle' activity - absence of activity events means idle.
+ *
+ * Events dispatched: CustomEvent<AgentActivity>
+ */
+export type AgentActivity =
+	| { type: 'thinking' }
+	| { type: 'executing'; tool: string; input: unknown }
+	| { type: 'executed'; tool: string; input: unknown; output: string; duration: number }
+	| { type: 'retrying'; attempt: number; maxAttempts: number }
+	| { type: 'error'; message: string }
+
+/**
+ * Minimal interface that Panel expects from an agent.
+ * Panel does not depend on PageAgent directly - it only requires this interface.
+ * This enables decoupling and allows any agent implementation to work with Panel.
+ *
+ * Events:
+ * - 'statuschange': Agent status changed (idle/running/completed/error)
+ * - 'historychange': Historical events updated (persisted)
+ * - 'activity': Transient activity for immediate UI feedback (thinking/executing/etc)
+ * - 'dispose': Agent is being disposed
+ */
+export interface PanelAgentAdapter extends EventTarget {
+	/** Current agent status */
+	readonly status: 'idle' | 'running' | 'completed' | 'error'
+
+	/** History of agent events */
+	readonly history: readonly {
+		type: 'step' | 'observation' | 'user_takeover' | 'error'
+		/** For 'step' type */
+		reflection?: {
+			evaluation_previous_goal?: string
+			memory?: string
+			next_goal?: string
+		}
+		/** For 'step' type */
+		action?: {
+			name: string
+			input: unknown
+			output: string
+		}
+		/** For 'observation' type */
+		content?: string
+	}[]
+
+	/** Current task being executed */
+	readonly task: string
+
+	/**
+	 * Callback for when agent needs user input.
+	 * Panel will set this to handle user questions via its UI.
+	 */
+	onAskUser?: (question: string) => Promise<string>
+
+	/** Execute a task */
+	execute(task: string): Promise<unknown>
+
+	/** Dispose the agent */
+	dispose(): void
+}

packages/ui/src/utils.ts

@@ -4,3 +4,15 @@ export function truncate(text: string, maxLength: number): string {
 	}
 	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

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

packages/ui/tsconfig.json

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

packages/ui/vite.config.js

@@ -29,7 +29,7 @@ export default defineConfig({
 		},
 		outDir: resolve(__dirname, 'dist', 'lib'),
 		rollupOptions: {
-			external: ['ai-motion'],
+			external: [],
 		},
 		minify: false,
 		sourcemap: true,

packages/website/AGENTS.md

@@ -37,14 +37,17 @@ Available Magic UI components: https://magicui.design/docs/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
@@ -58,17 +61,17 @@ Located in `src/components/ui/`:
 
 ```
 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
+│   └── Footer.tsx       # Site footer
-│   └── DocsLayout.tsx   # Documentation sidebar
-├── docs/                # Documentation pages
-│   └── [section]/[topic]/page.tsx
-├── test-pages/          # Library integration tests
 ├── i18n/                # Internationalization
 ├── router.tsx           # Central routing
-├── page.tsx             # Homepage
 └── main.tsx             # App entry
 ```
 
@@ -76,14 +79,9 @@ src/
 
 ### Documentation Page
 
-1. Create `src/docs/<section>/<slug>/page.tsx`
+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 `DocsLayout.tsx`
+3. Add navigation item to `pages/docs/Layout.tsx`
-
-### Test Page
-
-1. Create `src/test-pages/<name>.tsx`
-2. Add route to `src/test-pages/router.tsx`
 
 ## Routing
 
@@ -93,18 +91,16 @@ Uses hash-based routing for static hosting:
 import { Router } from 'wouter'
 import { useHashLocation } from 'wouter/use-hash-location'
 
-<Router hook={useHashLocation}>
+;<Router hook={useHashLocation}>{/* routes */}</Router>
-  {/* routes */}
-</Router>
 ```
 
 ## Configuration Files
 
-| File | Purpose |
+| File              | Purpose                 |
-|------|---------|
+| ----------------- | ----------------------- |
 | `components.json` | shadcn/ui configuration |
-| `vite.config.js` | Vite build settings |
+| `vite.config.js`  | Vite build settings     |
-| `tsconfig.json` | TypeScript config |
+| `tsconfig.json`   | TypeScript config       |
 
 ## Commands
 
@@ -112,4 +108,3 @@ import { useHashLocation } from 'wouter/use-hash-location'
 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

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

packages/website/package.json

@@ -1,24 +1,24 @@
 {
 	"name": "@page-agent/website",
 	"private": true,
-	"version": "0.0.19",
+	"version": "0.3.0-beta.2",
 	"type": "module",
 	"scripts": {
-		"dev": "vite",
+		"dev": "vite --host 0.0.0.0",
 		"build:website": "vite build",
 		"preview": "vite preview",
 		"typecheck": "tsc --noEmit"
 	},
 	"devDependencies": {
 		"@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.7.3",
+		"i18next": "^25.7.4",
 		"i18next-browser-languagedetector": "^8.2.0",
 		"react": "^19.2.3",
 		"react-dom": "^19.2.3",
-		"react-i18next": "^16.5.1",
+		"react-i18next": "^16.5.2",
 		"tailwindcss": "^4.1.14",
 		"tw-animate-css": "^1.4.0",
 		"wouter": "^3.9.0"
@@ -32,10 +32,10 @@
 		"class-variance-authority": "^0.7.1",
 		"clsx": "^2.1.1",
 		"lucide-react": "^0.562.0",
-		"motion": "^12.24.0",
+		"motion": "^12.26.1",
 		"next-themes": "^0.4.6",
 		"rough-notation": "^0.5.1",
-		"simple-icons": "^16.4.0",
+		"simple-icons": "^16.5.0",
 		"sonner": "^2.0.7",
 		"tailwind-merge": "^3.4.0"
 	}

packages/website/src/components/Header.tsx

@@ -22,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)}
@@ -41,6 +41,7 @@ export default function Header() {
 									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')}
 								</HyperText>
@@ -54,7 +55,7 @@ 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')}
 							>
@@ -84,8 +85,11 @@ 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"
 							>
 								<BookOpen className="w-4 h-4" />
@@ -133,7 +137,7 @@ 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)}
 							>

packages/website/src/components/ui/api-reference.tsx

@@ -0,0 +1,167 @@
+/**
+ * API Reference component for displaying TypeScript interface definitions
+ *
+ * Provides a beautiful, readable table for documenting API interfaces
+ */
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+import { Badge } from './badge'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PropDefinition {
+	/** Property name */
+	name: string
+	/** TypeScript type (can include generics, unions, etc.) */
+	type: string
+	/** Whether the property is required */
+	required?: boolean
+	/** Default value if any */
+	defaultValue?: string
+	/** Description of the property */
+	description: React.ReactNode
+	/** Mark as experimental/deprecated */
+	status?: 'experimental' | 'deprecated'
+}
+
+export interface APIReferenceProps {
+	/** Title for the API section */
+	title?: string
+	/** Optional description */
+	description?: React.ReactNode
+	/** Property definitions */
+	properties: PropDefinition[]
+	/** Additional CSS classes */
+	className?: string
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+export function APIReference({ title, description, properties, className }: APIReferenceProps) {
+	return (
+		<div className={cn('my-6', className)}>
+			{title && (
+				<h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-2">{title}</h3>
+			)}
+			{description && (
+				<p className="text-sm text-gray-600 dark:text-gray-400 mb-4">{description}</p>
+			)}
+
+			<div className="overflow-hidden rounded-lg border border-gray-200 dark:border-gray-700">
+				<table className="w-full text-sm">
+					<thead>
+						<tr className="bg-gray-50 dark:bg-gray-800/50">
+							<th className="px-4 py-3 text-left font-medium text-gray-600 dark:text-gray-300">
+								Property
+							</th>
+							<th className="px-4 py-3 text-left font-medium text-gray-600 dark:text-gray-300">
+								Type
+							</th>
+							<th className="px-4 py-3 text-left font-medium text-gray-600 dark:text-gray-300 hidden md:table-cell">
+								Default
+							</th>
+							<th className="px-4 py-3 text-left font-medium text-gray-600 dark:text-gray-300">
+								Description
+							</th>
+						</tr>
+					</thead>
+					<tbody className="divide-y divide-gray-100 dark:divide-gray-800">
+						{properties.map((prop) => (
+							<PropRow key={prop.name} {...prop} />
+						))}
+					</tbody>
+				</table>
+			</div>
+		</div>
+	)
+}
+
+function PropRow({ name, type, required, defaultValue, description, status }: PropDefinition) {
+	return (
+		<tr className="bg-white dark:bg-gray-900 hover:bg-gray-50 dark:hover:bg-gray-800/50 transition-colors">
+			{/* Property name */}
+			<td className="px-4 py-3 align-top">
+				<div className="flex items-center gap-2 flex-wrap">
+					<code className="font-mono text-sm font-medium text-indigo-600 dark:text-indigo-400">
+						{name}
+					</code>
+					{required && (
+						<Badge
+							variant="outline"
+							className="text-[10px] px-1.5 py-0 border-red-300 text-red-600 dark:border-red-800 dark:text-red-400"
+						>
+							required
+						</Badge>
+					)}
+					{status === 'experimental' && (
+						<Badge
+							variant="outline"
+							className="text-[10px] px-1.5 py-0 border-amber-300 text-amber-600 dark:border-amber-800 dark:text-amber-400"
+						>
+							experimental
+						</Badge>
+					)}
+					{status === 'deprecated' && (
+						<Badge
+							variant="outline"
+							className="text-[10px] px-1.5 py-0 border-gray-300 text-gray-500 dark:border-gray-700 dark:text-gray-500 line-through"
+						>
+							deprecated
+						</Badge>
+					)}
+				</div>
+			</td>
+
+			{/* Type */}
+			<td className="px-4 py-3 align-top">
+				<code className="font-mono text-xs text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-800 px-1.5 py-0.5 rounded whitespace-nowrap">
+					{type}
+				</code>
+			</td>
+
+			{/* Default value */}
+			<td className="px-4 py-3 align-top hidden md:table-cell">
+				{defaultValue ? (
+					<code className="font-mono text-xs text-gray-600 dark:text-gray-400">{defaultValue}</code>
+				) : (
+					<span className="text-gray-400 dark:text-gray-600">-</span>
+				)}
+			</td>
+
+			{/* Description */}
+			<td className="px-4 py-3 align-top text-gray-600 dark:text-gray-400">{description}</td>
+		</tr>
+	)
+}
+
+// ============================================================================
+// Utility Components
+// ============================================================================
+
+/** Code inline span for type references in descriptions */
+export function TypeRef({ children }: { children: React.ReactNode }) {
+	return (
+		<code className="font-mono text-xs text-indigo-600 dark:text-indigo-400 bg-indigo-50 dark:bg-indigo-950/50 px-1 py-0.5 rounded">
+			{children}
+		</code>
+	)
+}
+
+/** Section divider for grouping related APIs */
+export function APIDivider({ title }: { title: string }) {
+	return (
+		<div className="flex items-center gap-4 my-8">
+			<div className="h-px flex-1 bg-gradient-to-r from-transparent via-gray-200 dark:via-gray-700 to-transparent" />
+			<span className="text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-400">
+				{title}
+			</span>
+			<div className="h-px flex-1 bg-gradient-to-r from-transparent via-gray-200 dark:via-gray-700 to-transparent" />
+		</div>
+	)
+}

packages/website/src/constants.ts

@@ -1,3 +1,10 @@
-export const CDN_URL = 'https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js'
+// Demo build (auto-init with demo LLM, for quick testing)
-export const CDN_CN_URL =
+export const CDN_DEMO_URL = 'https://cdn.jsdelivr.net/npm/page-agent/dist/iife/page-agent.demo.js'
-	'https://registry.npmmirror.com/page-agent/latest/files/dist/umd/page-agent.js'
+export const CDN_DEMO_CN_URL =
+	'https://registry.npmmirror.com/page-agent/latest/files/dist/iife/page-agent.demo.js'
+
+// Demo LLM for website testing
+export const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+export const DEMO_BASE_URL =
+	'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
+export const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'

packages/website/src/docs/features/data-masking/page.tsx

@@ -1,48 +0,0 @@
-import BetaNotice from '@/components/BetaNotice'
-import CodeEditor from '@/components/CodeEditor'
-
-export default function DataMasking() {
-	return (
-		<div>
-			<h1 className="text-4xl font-bold mb-6">数据脱敏</h1>
-
-			<BetaNotice />
-
-			<p className="text-xl text-gray-600 dark:text-gray-300 mb-6 leading-relaxed">
-				保护敏感数据，确保 AI 处理过程中的数据安全。
-			</p>
-
-			<h2 className="text-2xl font-bold mb-3">脱敏策略</h2>
-
-			<div className="space-y-4 mb-6">
-				<div className="p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg">
-					<h3 className="text-lg font-semibold mb-2 text-blue-900 dark:text-blue-300">
-						🔒 自动脱敏
-					</h3>
-					<p className="text-gray-600 dark:text-gray-300">
-						自动识别并脱敏手机号、身份证号、银行卡号等敏感信息。
-					</p>
-				</div>
-
-				<div className="p-4 bg-purple-50 dark:bg-purple-900/20 rounded-lg">
-					<h3 className="text-lg font-semibold mb-2 text-purple-900 dark:text-purple-300">
-						⚙️ 自定义规则
-					</h3>
-					<p className="text-gray-600 dark:text-gray-300">
-						支持自定义脱敏规则，适应不同业务场景的数据保护需求。
-					</p>
-				</div>
-			</div>
-
-			<CodeEditor
-				code={`// 数据脱敏配置
-// @todo
-const rules = [
-	{ pattern: /\\d{11}/, replacement: '***-****-****' },
-	{ pattern: /\\d{4}-\\d{4}-\\d{4}-\\d{4}/, replacement: '****-****-****-****' }
-]
-pageAgent.maskData(rules)`}
-			/>
-		</div>
-	)
-}

packages/website/src/docs/features/security-permissions/page.tsx

@@ -1,81 +0,0 @@
-import BetaNotice from '@/components/BetaNotice'
-
-export default function SecurityPermissions() {
-	return (
-		<div>
-			<h1 className="text-4xl font-bold mb-6">安全与权限</h1>
-
-			<BetaNotice />
-
-			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
-				page-agent 提供四种安全机制，确保 AI 操作在可控范围内进行。
-			</p>
-
-			<div className="space-y-6">
-				<section>
-					<h2 className="text-2xl font-bold mb-3">元素操作黑白名单</h2>
-					<div className="space-y-3">
-						<div className="p-4 bg-red-50 dark:bg-red-900/20 rounded-lg">
-							<h3 className="text-lg font-semibold text-red-900 dark:text-red-300">
-								🚫 操作黑名单
-							</h3>
-							<p className="text-gray-600 dark:text-gray-300">
-								禁止 AI 操作敏感元素，如删除按钮、支付按钮等。
-							</p>
-						</div>
-						<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
-							<h3 className="text-lg font-semibold text-green-900 dark:text-green-300">
-								✅ 操作白名单
-							</h3>
-							<p className="text-gray-600 dark:text-gray-300">明确定义 AI 可以操作的元素范围。</p>
-						</div>
-					</div>
-				</section>
-
-				<section>
-					<h2 className="text-2xl font-bold mb-3">URL 黑白名单</h2>
-					<div className="space-y-3">
-						<div className="p-4 bg-red-50 dark:bg-red-900/20 rounded-lg">
-							<h3 className="text-lg font-semibold text-red-900 dark:text-red-300">
-								🚫 URL 黑名单
-							</h3>
-							<p className="text-gray-600 dark:text-gray-300">禁止 AI 访问敏感页面和危险链接。</p>
-						</div>
-						<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
-							<h3 className="text-lg font-semibold text-green-900 dark:text-green-300">
-								✅ URL 白名单
-							</h3>
-							<p className="text-gray-600 dark:text-gray-300">限制 AI 只能访问预定义的安全页面。</p>
-						</div>
-					</div>
-				</section>
-
-				<section>
-					<h2 className="text-2xl font-bold mb-3">Instruction 安全约束</h2>
-					<div className="p-4 bg-yellow-50 dark:bg-yellow-900/20 rounded-lg">
-						<h3 className="text-lg font-semibold mb-2 text-yellow-900 dark:text-yellow-300">
-							⚠️ 高危操作控制
-						</h3>
-						<p className="text-gray-600 dark:text-gray-300 mb-3">
-							在 AI 指令中明确列举高危操作，通过两种策略进行控制：
-						</p>
-						<div className="space-y-2">
-							<div className="pl-3 border-l-2 border-red-400">
-								<p className="font-medium text-red-700 dark:text-red-300">完全禁止操作</p>
-								<p className="text-sm text-gray-500 dark:text-gray-400">
-									对极高风险操作明确禁止执行
-								</p>
-							</div>
-							<div className="pl-3 border-l-2 border-orange-400">
-								<p className="font-medium text-orange-700 dark:text-orange-300">需用户确认操作</p>
-								<p className="text-sm text-gray-500 dark:text-gray-400">
-									对中等风险操作要求用户明确同意
-								</p>
-							</div>
-						</div>
-					</div>
-				</section>
-			</div>
-		</div>
-	)
-}

packages/website/src/docs/integration/cdn-setup/page.tsx

@@ -1,44 +0,0 @@
-import BetaNotice from '@/components/BetaNotice'
-import CodeEditor from '@/components/CodeEditor'
-import { CDN_CN_URL, CDN_URL } from '@/constants'
-
-export default function CdnSetup() {
-	return (
-		<div>
-			<h1 className="text-4xl font-bold mb-6">CDN 引入</h1>
-
-			<p className="text-xl text-gray-600 dark:text-gray-300 mb-6 leading-relaxed">
-				通过 CDN 快速集成 page-agent，无需复杂的构建配置。
-			</p>
-
-			<h2 className="text-2xl font-bold mb-3">快速开始</h2>
-
-			<CodeEditor
-				className="mb-8"
-				code={`
-// CDN: \t${CDN_URL}
-// Mirror: \t${CDN_CN_URL}
-<script 
-	src="${CDN_URL}" 
-	crossorigin="true" 
-	type="text/javascript"
-></script>
-
-<script>
-	// window.pageAgent
-</script>`}
-			/>
-
-			<div className="bg-yellow-50 dark:bg-yellow-900/20 p-4 rounded-lg">
-				<h3 className="text-lg font-semibold mb-2 text-yellow-900 dark:text-yellow-300">
-					⚠️ 注意事项
-				</h3>
-				<ul className="text-gray-600 dark:text-gray-300 space-y-1">
-					<li>• 生产环境建议使用固定版本号</li>
-					<li>• 确保 HTTPS 环境下使用</li>
-					<li>• 配置 CSP 策略允许脚本执行</li>
-				</ul>
-			</div>
-		</div>
-	)
-}

packages/website/src/docs/integration/configuration/page.tsx

@@ -1,115 +0,0 @@
-import CodeEditor from '@/components/CodeEditor'
-
-export default function Configuration() {
-	return (
-		<div>
-			<h1 className="text-4xl font-bold mb-6">配置选项</h1>
-
-			<CodeEditor
-				className="mb-8"
-				language="typescript"
-				code={`// config
-type PageAgentConfig = LLMConfig & AgentConfig & PageControllerConfig
-
-interface LLMConfig {
-	baseURL?: string
-	apiKey?: string
-	model?: string
-	temperature?: 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
-}
-
-interface AgentConfig {
-	language?: "en-US" | "zh-CN"
-
-	/**
-	 * Custom tools to extend PageAgent capabilities
-	 * @experimental
-	 * @note You can also override or remove internal tools by using the same name.
-	 * @see [tools](../tools/index.ts)
-	 *
-	 * @example
-	 * // override internal tool
-	 * import { tool } from 'page-agent'
-	 * const customTools = {
-	 * ask_user: tool({
-	 * 	description:
-	 * 		'Ask the user or parent model a question and wait for their answer. Use this if you need more information or clarification.',
-	 * 	inputSchema: zod.object({
-	 * 		question: zod.string(),
-	 * 	}),
-	 * 	execute: async function (this: PageAgent, input) {
-	 * 		const answer = await do_some_thing(input.question)
-	 * 		return "✅ Received user answer: " + answer
-	 * 	},
-	 * })
-	 * }
-	 *
-	 * @example
-	 * // remove internal tool
-	 * const customTools = {
-	 * 	ask_user: null // never ask user questions
-	 * }
-	 */
-	customTools?: Record<string, PageAgentTool | null>
-
-	// lifecycle hooks
-	// @todo: use event instead of hooks
-
-	onBeforeStep?: (this: PageAgent, stepCnt: number) => Promise<void> | void
-	onAfterStep?: (this: PageAgent, stepCnt: number, history: AgentHistory[]) => 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.
-	 */
-	onDispose?: (this: PageAgent, reason?: string) => void
-
-	// page behavior hooks
-
-	/**
-	 * @experimental
-	 * Enable the experimental script execution tool that allows executing generated JavaScript code on the page.
-	 * @note Can cause unpredictable side effects.
-	 * @note May bypass some safe guards and data-masking mechanisms.
-	 */
-	experimentalScriptExecutionTool?: boolean
-
-	/**
-	 * 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.
-	 */
-	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
-}
-
-interface PageControllerConfig {
-	interactiveBlacklist?: (Element | (() => Element))[]
-	interactiveWhitelist?: (Element | (() => Element))[]
-	include_attributes?: string[]
-	highlightOpacity?: number
-	highlightLabelOpacity?: number
-	viewportExpansion?: number
-}
-
-`}
-			/>
-		</div>
-	)
-}

packages/website/src/docs/introduction/quick-start/page.tsx

@@ -1,84 +0,0 @@
-import { useTranslation } from 'react-i18next'
-
-import BetaNotice from '@/components/BetaNotice'
-import CodeEditor from '@/components/CodeEditor'
-import { CDN_CN_URL, CDN_URL } from '@/constants'
-
-export default function QuickStart() {
-	const { t } = useTranslation('docs')
-
-	return (
-		<div>
-			<h1 className="text-4xl font-bold mb-6">{t('quick_start.title')}</h1>
-
-			<p className=" mb-6 leading-relaxed">{t('quick_start.subtitle')}</p>
-
-			<h2 className="text-2xl font-bold mb-3">{t('quick_start.installation')}</h2>
-
-			<div className="space-y-4 mb-6">
-				<div className="p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg">
-					<h3 className="text-lg font-semibold mb-2 text-blue-900 dark:text-blue-300">
-						{t('quick_start.step1_title')}
-					</h3>
-					<div className="space-y-3">
-						<div>
-							<p className="text-sm font-medium mb-2">{t('quick_start.step1_cdn')}</p>
-							<CodeEditor
-								code={`// CDN: \t${CDN_URL}
-// Mirror: \t${CDN_CN_URL}
-<script src="${CDN_URL}" crossorigin="true" type="text/javascript"></script>`}
-								language="html"
-							/>
-						</div>
-						<div>
-							<p className="text-sm font-medium mb-2">{t('quick_start.step1_npm')}</p>
-							<CodeEditor
-								code={`// npm install page-agent
-import PageAgent from 'page-agent'`}
-								language="bash"
-							/>
-						</div>
-					</div>
-				</div>
-
-				<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
-					<h3 className="text-lg font-semibold mb-2 text-green-900 dark:text-green-300">
-						{t('quick_start.step2_title')}
-					</h3>
-					<CodeEditor
-						code={`// 仅供测试使用，生产环境需要配置 LLM 接入点，本工具不提供 LLM 服务
-// 测试接口
-// @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({
-  model: DEMO_MODEL,
-  baseURL: DEMO_BASE_URL,
-  apiKey: DEMO_API_KEY,
-  language: 'zh-CN'
-})`}
-						language="javascript"
-					/>
-				</div>
-
-				<div className="p-4 bg-purple-50 dark:bg-purple-900/20 rounded-lg">
-					<h3 className="text-lg font-semibold mb-2 text-purple-900 dark:text-purple-300">
-						{t('quick_start.step3_title')}
-					</h3>
-					<CodeEditor
-						code={`// 程序化执行自然语言指令
-await pageAgent.execute('点击提交按钮，然后填写用户名为张三');
-
-// 或者显示对话框让用户输入指令
-pageAgent.panel.show()
-`}
-						language="javascript"
-					/>
-				</div>
-			</div>
-		</div>
-	)
-}

packages/website/src/env.d.ts

@@ -1,5 +1,9 @@
 /// <reference types="vite/client" />
 
+interface ImportMetaEnv {
+	readonly VERSION: string
+}
+
 declare module '*.module.css' {
 	const classes: Record<string, string>
 	export default classes

packages/website/src/i18n/README.md

@@ -28,9 +28,9 @@ pages/i18n/
 import { useTranslation } from 'react-i18next'
 
 function MyComponent() {
-  const { t } = useTranslation('common') // 指定命名空间
+    const { t } = useTranslation('common') // 指定命名空间
-  
+
-  return <h1>{t('header.nav_docs')}</h1>
+    return <h1>{t('header.nav_docs')}</h1>
 }
 ```
 
@@ -71,4 +71,3 @@ t('common:header.nav_docs')
 - [ ] 文档页翻译（`docs.json`）
 - [ ] DocsLayout 导航结构国际化
 - [ ] 404 页面国际化
-

packages/website/src/i18n/locales/en-US/common.ts

@@ -24,17 +24,19 @@ export default {
 		introduction: 'Introduction',
 		features: 'Features',
 		integration: 'Integration',
+		advanced: 'Advanced',
 		overview: 'Overview',
 		quick_start: 'Quick Start',
 		limitations: 'Limitations',
-		model_integration: 'Model Integration',
+		models: 'Models',
 		custom_tools: 'Custom Tools',
 		knowledge_injection: 'Instructions',
-		security_permissions: 'Security & Permissions',
 		data_masking: 'Data Masking',
 		cdn_setup: 'CDN Setup',
-		configuration: 'Configuration',
 		best_practices: 'Best Practices',
 		third_party_agent: 'Third-party Agent',
+		security_permissions: 'Security & Permissions',
+		page_agent: 'PageAgent',
+		page_agent_core: 'PageAgentCore',
 	},
 }

packages/website/src/i18n/locales/en-US/docs.ts

@@ -5,7 +5,7 @@ export default {
 			'page-agent is a purely web-based GUI Agent. Gives your website an AI operator in simple steps.',
 		what_is: 'What is page-agent?',
 		what_is_desc:
-			'page-agent is an embedded GUI Agent. Unlike traditional browser automation tools, page-agent targets web developers, not scrapers or agent clients builders. Integrate it into your site to let users interact with pages through natural language.',
+			'page-agent is an embedded GUI Agent. Unlike traditional browser automation tools, page-agent is built for web developers and web applications first. Integrate it into your site to let users interact with pages through natural language.',
 		features_title: 'Core Features',
 		feature_dom: {
 			title: '🧠 Smart DOM Analysis',
@@ -112,8 +112,8 @@ export default {
 		future_3: '• Basic visual understanding',
 		future_4: '• Smarter error recovery',
 	},
-	model_integration: {
+	models: {
-		title: 'Model Integration',
+		title: 'Models',
 		subtitle:
 			'Supports models that comply with OpenAI API specification and support tool calls, including public cloud services and private deployments.',
 		recommendation_logic: 'Recommended: Lightweight models with strong ToolCall capabilities.',

packages/website/src/i18n/locales/zh-CN/common.ts

@@ -23,17 +23,19 @@ export default {
 		introduction: '介绍',
 		features: '功能特性',
 		integration: '集成指南',
+		advanced: '高级',
 		overview: '概览',
 		quick_start: '快速开始',
 		limitations: '使用限制',
-		model_integration: '模型接入',
+		models: '模型',
 		custom_tools: '自定义工具',
 		knowledge_injection: '知识注入',
-		security_permissions: '安全与权限',
 		data_masking: '数据脱敏',
 		cdn_setup: 'CDN 引入',
-		configuration: '配置选项',
 		best_practices: '最佳实践',
 		third_party_agent: '接入第三方 Agent',
+		security_permissions: '安全与权限',
+		page_agent: 'PageAgent',
+		page_agent_core: 'PageAgentCore',
 	},
 }

packages/website/src/i18n/locales/zh-CN/docs.ts

@@ -111,8 +111,8 @@ export default {
 		future_3: '• 基础的视觉理解能力',
 		future_4: '• 更智能的错误恢复机制',
 	},
-	model_integration: {
+	models: {
-		title: '模型接入',
+		title: '模型',
 		subtitle: '当前支持符合 OpenAI 接口规范且支持 tool call 的模型,包括公有云服务和私有部署方案。',
 		recommendation_logic: '推荐使用 ToolCall 能力强的轻量级模型。',
 		recommended: '推荐模型',

packages/website/src/main.tsx

@@ -1,19 +1,15 @@
 import { createRoot } from 'react-dom/client'
-import { Route, Router, Switch } from 'wouter'
+import { Router } from 'wouter'
 import { useHashLocation } from 'wouter/use-hash-location'
 
 import './i18n/config'
 import './i18n/types'
 import { default as PagesRouter } from './router'
-import { default as TestPagesRouter } from './test-pages/router'
 
 import './index.css'
 
 createRoot(document.getElementById('root')!).render(
 	<Router hook={useHashLocation}>
-		<Switch>
+		<PagesRouter />
-			<Route path="/test-pages" component={TestPagesRouter} nest />
-			<Route path="/" component={PagesRouter} nest />
-		</Switch>
 	</Router>
 )

packages/website/src/pages/Home.tsx

@@ -1,21 +1,26 @@
 /* eslint-disable react-dom/no-dangerously-set-innerhtml */
 import { Bot, Box, MessageSquare, PlayCircle, Shield, Sparkles, Users, Zap } from 'lucide-react'
-import { PageAgent } from 'page-agent'
 import { useEffect, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import { Link, useSearchParams } from 'wouter'
 
-import Footer from './components/Footer'
+import Footer from '../components/Footer'
-import Header from './components/Header'
+import Header from '../components/Header'
-import { AnimatedGradientText } from './components/ui/animated-gradient-text'
+import { AnimatedGradientText } from '../components/ui/animated-gradient-text'
-import { Highlighter } from './components/ui/highlighter'
+import { Highlighter } from '../components/ui/highlighter'
-import { NeonGradientCard } from './components/ui/neon-gradient-card'
+import { NeonGradientCard } from '../components/ui/neon-gradient-card'
-import { Particles } from './components/ui/particles'
+import { Particles } from '../components/ui/particles'
-import { SparklesText } from './components/ui/sparkles-text'
+import { SparklesText } from '../components/ui/sparkles-text'
-import { CDN_CN_URL, CDN_URL } from './constants'
+import {
+	CDN_DEMO_CN_URL,
+	CDN_DEMO_URL,
+	DEMO_API_KEY,
+	DEMO_BASE_URL,
+	DEMO_MODEL,
+} from '../constants'
 
 function getInjection(useCN?: boolean) {
-	const cdn = useCN ? CDN_CN_URL : CDN_URL
+	const cdn = useCN ? CDN_DEMO_CN_URL : CDN_DEMO_URL
 
 	const injection = encodeURI(
 		`javascript:(function(){var s=document.createElement('script');s.src=\`${cdn}?t=\${Math.random()}\`;s.setAttribute('crossorigin', true);s.type="text/javascript";s.onload=()=>console.log('PageAgent script loaded!');document.body.appendChild(s);})();`
@@ -53,13 +58,12 @@ export default function HomePage() {
 	const handleExecute = async () => {
 		if (!task.trim()) return
 
-		let pageAgent: PageAgent
 		const win = window as any
 
-		if (win.pageAgent && !win.pageAgent.disposed) {
+		// Lazy load PageAgent only when user clicks execute
-			pageAgent = win.pageAgent
+		if (!win.pageAgent || win.pageAgent.disposed) {
-		} else {
+			const { PageAgent } = await import('page-agent')
-			pageAgent = new PageAgent({
+			win.pageAgent = new PageAgent({
 				// 把 react 根元素排除掉，挂了很多冒泡时间导致假阳
 				interactiveBlacklist: [document.getElementById('root')!],
 				language: i18n.language as any,
@@ -73,19 +77,26 @@ export default function HomePage() {
 					},
 				},
 
-				// experimentalScriptExecutionTool: true,
+				model:
+					import.meta.env.DEV && import.meta.env.LLM_MODEL_NAME
+						? import.meta.env.LLM_MODEL_NAME
+						: DEMO_MODEL,
+				baseURL:
+					import.meta.env.DEV && import.meta.env.LLM_BASE_URL
+						? import.meta.env.LLM_BASE_URL
+						: DEMO_BASE_URL,
+				apiKey:
+					import.meta.env.DEV && import.meta.env.LLM_API_KEY
+						? import.meta.env.LLM_API_KEY
+						: DEMO_API_KEY,
 
-				// testing server
+				// enableAskUser: false,
-				// @note: rate limit. prompt limit.
+				// promptForNextTask: false,
-				// model: DEMO_MODEL,
+				// enablePanel: false,
-				// baseURL: DEMO_BASE_URL,
-				// apiKey: DEMO_API_KEY,
 			})
-			win.pageAgent = pageAgent
 		}
 
-		const result = await pageAgent.execute(task)
+		const result = await win.pageAgent.execute(task)
-
 		console.log(result)
 	}
 
@@ -95,7 +106,10 @@ export default function HomePage() {
 
 			{/* Hero Section */}
 			<main id="main-content">
-				<section className="relative px-6 py-22 lg:py-28" aria-labelledby="hero-heading">
+				<section
+					className="relative px-6 py-22 pb-18 lg:py-28 overflow-hidden"
+					aria-labelledby="hero-heading"
+				>
 					<div className="max-w-7xl mx-auto text-center">
 						{/* Background Pattern + Particles */}
 						<div className="absolute inset-0 opacity-30" aria-hidden="true">

packages/website/src/pages/docs/Layout.tsx

@@ -24,38 +24,47 @@ export default function DocsLayout({ children }: DocsLayoutProps) {
 		{
 			title: t('nav.introduction'),
 			items: [
-				{ title: t('nav.overview'), path: '/docs/introduction/overview' },
+				{ title: t('nav.overview'), path: '/introduction/overview' },
-				{ title: t('nav.quick_start'), path: '/docs/introduction/quick-start' },
+				{ title: t('nav.quick_start'), path: '/introduction/quick-start' },
-				{ title: t('nav.limitations'), path: '/docs/introduction/limitations' },
+				{ title: t('nav.limitations'), path: '/introduction/limitations' },
 			],
 		},
 		{
 			title: t('nav.features'),
 			items: [
-				{ title: t('nav.model_integration'), path: '/docs/features/model-integration' },
+				{ title: t('nav.models'), path: '/features/models' },
-				{ title: t('nav.custom_tools'), path: '/docs/features/custom-tools' },
+				{ title: t('nav.custom_tools'), path: '/features/custom-tools' },
-				{ title: t('nav.knowledge_injection'), path: '/docs/features/custom-instructions' },
+				{ title: t('nav.knowledge_injection'), path: '/features/custom-instructions' },
-				{ title: t('nav.security_permissions'), path: '/docs/features/security-permissions' },
+				{ title: t('nav.data_masking'), path: '/features/data-masking' },
-				{ title: t('nav.data_masking'), path: '/docs/features/data-masking' },
 			],
 		},
 		{
 			title: t('nav.integration'),
 			items: [
-				{ title: t('nav.cdn_setup'), path: '/docs/integration/cdn-setup' },
+				{ title: t('nav.third_party_agent'), path: '/integration/third-party-agent' },
-				{ title: t('nav.configuration'), path: '/docs/integration/configuration' },
+				{ title: t('nav.cdn_setup'), path: '/integration/cdn-setup' },
-				{ title: t('nav.best_practices'), path: '/docs/integration/best-practices' },
+				{
-				{ title: t('nav.third_party_agent'), path: '/docs/integration/third-party-agent' },
+					title: '🚧 ' + t('nav.security_permissions'),
+					path: '/integration/security-permissions',
+				},
+				{ title: '🚧 ' + t('nav.best_practices'), path: '/integration/best-practices' },
+			],
+		},
+		{
+			title: t('nav.advanced'),
+			items: [
+				{ title: t('nav.page_agent'), path: '/advanced/page-agent' },
+				{ title: t('nav.page_agent_core'), path: '/advanced/page-agent-core' },
 			],
 		},
 	]
 
 	return (
 		<div className="max-w-7xl mx-auto px-6 py-8 overflow-x-auto">
-			<div className="flex gap-8 min-w-[900px]">
+			<div className="flex gap-8 min-w-225">
 				{/* Sidebar */}
 				<aside className="w-64 shrink-0" role="complementary" aria-label="文档导航">
-					<div className="sticky top-8">
+					<div className="sticky">
 						<nav className="space-y-8" role="navigation" aria-label="文档章节">
 							{navigationSections.map((section) => (
 								<section key={section.title}>

packages/website/src/pages/docs/advanced/page-agent-core/page.tsx

@@ -0,0 +1,514 @@
+import { useTranslation } from 'react-i18next'
+
+import CodeEditor from '@/components/CodeEditor'
+import { APIDivider, APIReference, TypeRef } from '@/components/ui/api-reference'
+
+export default function PageAgentCoreDocs() {
+	const { i18n } = useTranslation()
+	const isZh = i18n.language === 'zh-CN'
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">PageAgentCore</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? 'PageAgentCore 是不带 UI 的核心 Agent 类。用于需要自定义 UI 或无头运行的场景。'
+					: 'PageAgentCore is the core Agent class without UI. Use it for custom UI or headless scenarios.'}
+			</p>
+
+			{/* When to use */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">
+					{isZh ? '何时使用 PageAgentCore' : 'When to Use PageAgentCore'}
+				</h2>
+				<ul className="list-disc list-inside text-gray-600 dark:text-gray-400 space-y-2">
+					<li>{isZh ? '需要自定义 UI 界面' : 'Need a custom UI interface'}</li>
+					<li>{isZh ? '在自动化测试中无头运行' : 'Running headless in automated tests'}</li>
+					<li>
+						{isZh
+							? '在非浏览器环境运行（需自定义 PageController）'
+							: 'Running in non-browser environments (requires custom PageController)'}
+					</li>
+					<li>
+						{isZh
+							? '将 PageAgent 嵌入其他 Agent 系统'
+							: 'Embedding PageAgent in other agent systems'}
+					</li>
+				</ul>
+			</section>
+
+			{/* Basic Usage */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">{isZh ? '基本用法' : 'Basic Usage'}</h2>
+				<CodeEditor
+					language="typescript"
+					code={`import { PageAgentCore } from '@page-agent/core'
+import { PageController } from '@page-agent/page-controller'
+
+const agent = new PageAgentCore({
+  pageController: new PageController({ enableMask: true }),
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: 'your-api-key',
+  model: 'gpt-5.2',
+  language: 'en-US',
+})
+
+// Listen to events for UI display
+
+agent.addEventListener('statuschange', () => {
+  console.log('Status:', agent.status)
+})
+
+agent.addEventListener('historychange', () => {
+  console.log('History:', agent.history)
+})
+
+agent.addEventListener('activity', (e) => {
+  const activity = (e as CustomEvent).detail
+  console.log('Activity:', activity.type)
+})
+
+// Execute task
+const result = await agent.execute('Fill in the form with test data')`}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '配置' : 'Configuration'} />
+
+			{/* LLM Configuration */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">LLMConfig</h2>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '配置与大语言模型的连接参数。支持 OpenAI 兼容的 API。'
+						: 'Configure connection parameters for the language model. Supports OpenAI-compatible APIs.'}
+				</p>
+				<APIReference
+					properties={[
+						{
+							name: 'baseURL',
+							type: 'string',
+							required: true,
+							description: isZh
+								? 'LLM API 的基础 URL（如 https://api.openai.com/v1）'
+								: 'Base URL of the LLM API (e.g., https://api.openai.com/v1)',
+						},
+						{
+							name: 'apiKey',
+							type: 'string',
+							required: true,
+							description: isZh ? 'API 密钥' : 'API key for authentication',
+						},
+						{
+							name: 'model',
+							type: 'string',
+							required: true,
+							description: isZh
+								? '模型名称（如 gpt-4o, claude-3.5-sonnet）'
+								: 'Model name (e.g., gpt-4o, claude-3.5-sonnet)',
+						},
+						{
+							name: 'temperature',
+							type: 'number',
+							defaultValue: '0',
+							description: isZh
+								? '模型温度参数，控制输出随机性'
+								: 'Model temperature, controls output randomness',
+						},
+						{
+							name: 'maxRetries',
+							type: 'number',
+							defaultValue: '3',
+							description: isZh ? 'API 调用失败时的最大重试次数' : 'Maximum retries on API failure',
+						},
+						{
+							name: 'customFetch',
+							type: 'typeof fetch',
+							description: isZh
+								? '自定义 fetch 函数，用于定制 headers、credentials、代理等'
+								: 'Custom fetch function for customizing headers, credentials, proxy, etc.',
+						},
+					]}
+				/>
+			</section>
+
+			{/* Agent Configuration */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">AgentConfig</h2>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '配置 Agent 的行为、生命周期钩子和扩展能力。'
+						: 'Configure agent behavior, lifecycle hooks, and extension capabilities.'}
+				</p>
+				<APIReference
+					properties={[
+						{
+							name: 'language',
+							type: "'en-US' | 'zh-CN'",
+							defaultValue: "'en-US'",
+							description: isZh ? 'Agent 输出语言' : 'Agent output language',
+						},
+						{
+							name: 'customTools',
+							type: 'Record<string, PageAgentTool | null>',
+							status: 'experimental',
+							description: isZh
+								? '自定义工具，可扩展或覆盖内置工具。设为 null 可移除工具。'
+								: 'Custom tools to extend or override built-in tools. Set to null to remove a tool.',
+						},
+						{
+							name: 'instructions',
+							type: 'InstructionsConfig',
+							description: isZh
+								? '指导 Agent 行为的指令配置'
+								: 'Instructions to guide agent behavior',
+						},
+						{
+							name: 'transformPageContent',
+							type: '(content: string) => string | Promise<string>',
+							description: isZh
+								? '发送给 LLM 前转换页面内容，可用于数据脱敏'
+								: 'Transform page content before sending to LLM, useful for data masking',
+						},
+						{
+							name: 'experimentalScriptExecutionTool',
+							type: 'boolean',
+							defaultValue: 'false',
+							status: 'experimental',
+							description: isZh
+								? '启用实验性 JavaScript 执行工具'
+								: 'Enable experimental JavaScript execution tool',
+						},
+					]}
+				/>
+
+				<h3 className="text-lg font-semibold mt-6 mb-3">InstructionsConfig</h3>
+				<APIReference
+					properties={[
+						{
+							name: 'system',
+							type: 'string',
+							description: isZh
+								? '全局系统级指令，应用于所有任务'
+								: 'Global system-level instructions, applied to all tasks',
+						},
+						{
+							name: 'getPageInstructions',
+							type: '(url: string) => string | undefined | null',
+							description: isZh
+								? '动态页面级指令回调，在每个步骤前调用'
+								: 'Dynamic page-level instructions callback, called before each step',
+						},
+					]}
+				/>
+			</section>
+
+			{/* Lifecycle Hooks */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">{isZh ? '生命周期钩子' : 'Lifecycle Hooks'}</h2>
+				<APIReference
+					properties={[
+						{
+							name: 'onBeforeStep',
+							type: '(stepCnt: number) => void | Promise<void>',
+							description: isZh ? '每个步骤执行前调用' : 'Called before each step execution',
+							status: 'experimental',
+						},
+						{
+							name: 'onAfterStep',
+							type: '(history: HistoricalEvent[]) => void | Promise<void>',
+							description: isZh ? '每个步骤执行后调用' : 'Called after each step execution',
+							status: 'experimental',
+						},
+						{
+							name: 'onBeforeTask',
+							type: '() => void | Promise<void>',
+							description: isZh ? '任务开始前调用' : 'Called before task starts',
+							status: 'experimental',
+						},
+						{
+							name: 'onAfterTask',
+							type: '(result: ExecutionResult) => void | Promise<void>',
+							description: isZh ? '任务结束后调用' : 'Called after task ends',
+							status: 'experimental',
+						},
+						{
+							name: 'onDispose',
+							type: '(reason?: string) => void',
+							description: isZh ? 'Agent 销毁时调用' : 'Called when agent is disposed',
+							status: 'experimental',
+						},
+					]}
+				/>
+			</section>
+
+			{/* PageController Configuration */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">PageControllerConfig</h2>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '配置 DOM 提取、元素交互和视觉反馈。'
+						: 'Configure DOM extraction, element interaction, and visual feedback.'}
+				</p>
+				<APIReference
+					properties={[
+						{
+							name: 'pageController',
+							type: 'PageController',
+							status: 'experimental',
+							description: isZh
+								? '自定义 PageController 实例。如不提供，将创建默认实例。'
+								: 'Custom PageController instance. If not provided, a default one will be created.',
+						},
+						{
+							name: 'enableMask',
+							type: 'boolean',
+							defaultValue: 'true',
+							description: isZh
+								? '启用视觉遮罩覆盖层，阻止用户在自动化期间操作'
+								: 'Enable visual mask overlay that blocks user interaction during automation',
+						},
+						{
+							name: 'viewportExpansion',
+							type: 'number',
+							defaultValue: '0',
+							description: isZh
+								? '视口扩展像素数，-1 表示提取整个页面'
+								: 'Viewport expansion in pixels, -1 means extract entire page',
+						},
+						{
+							name: 'interactiveBlacklist',
+							type: '(Element | (() => Element))[]',
+							description: isZh ? '要排除的交互元素列表' : 'Elements to exclude from interaction',
+						},
+						{
+							name: 'interactiveWhitelist',
+							type: '(Element | (() => Element))[]',
+							description: isZh
+								? '要强制包含的交互元素列表'
+								: 'Elements to force include for interaction',
+						},
+						{
+							name: 'include_attributes',
+							type: 'string[]',
+							description: isZh
+								? '在 DOM 提取中包含的额外属性'
+								: 'Additional attributes to include in DOM extraction',
+						},
+					]}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '属性与方法' : 'Properties & Methods'} />
+
+			{/* Properties */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">{isZh ? '属性' : 'Properties'}</h2>
+				<APIReference
+					properties={[
+						{
+							name: 'status',
+							type: "'idle' | 'running' | 'completed' | 'error'",
+							description: isZh ? '当前 Agent 执行状态' : 'Current agent execution status',
+						},
+						{
+							name: 'history',
+							type: 'HistoricalEvent[]',
+							description: isZh
+								? '历史事件数组，构成 Agent 的记忆'
+								: 'Array of historical events, forms agent memory',
+						},
+						{
+							name: 'task',
+							type: 'string',
+							description: isZh ? '当前正在执行的任务' : 'Current task being executed',
+						},
+						{
+							name: 'pageController',
+							type: 'PageController',
+							description: isZh
+								? 'PageController 实例，用于 DOM 操作'
+								: 'PageController instance for DOM operations',
+						},
+						{
+							name: 'tools',
+							type: 'Map<string, PageAgentTool>',
+							description: isZh ? '可用工具的 Map' : 'Map of available tools',
+						},
+						{
+							name: 'onAskUser',
+							type: '(question: string) => Promise<string>',
+							description: isZh
+								? 'Agent 需要用户输入时的回调。未设置则禁用 ask_user 工具。'
+								: 'Callback when agent needs user input. If not set, ask_user tool is disabled.',
+						},
+					]}
+				/>
+			</section>
+
+			{/* Methods */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">{isZh ? '方法' : 'Methods'}</h2>
+				<APIReference
+					properties={[
+						{
+							name: 'execute(task: string)',
+							type: 'Promise<ExecutionResult>',
+							description: isZh
+								? '执行任务并返回结果。包含 success、data 和 history 字段。'
+								: 'Execute a task and return result. Contains success, data, and history fields.',
+						},
+						{
+							name: 'pushObservation(content: string)',
+							type: 'void',
+							description: isZh
+								? '向历史流推送一个观察事件，会在下一步时被 LLM 看到'
+								: 'Push an observation to history stream, will be seen by LLM in next step',
+						},
+						{
+							name: 'emitActivity(activity: AgentActivity)',
+							type: 'void',
+							description: isZh
+								? '发出活动事件用于 UI 反馈'
+								: 'Emit activity event for UI feedback',
+						},
+						{
+							name: 'dispose(reason?: string)',
+							type: 'void',
+							description: isZh
+								? '销毁 Agent 并清理资源'
+								: 'Dispose the agent and clean up resources',
+						},
+					]}
+				/>
+			</section>
+
+			{/* Events */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">{isZh ? '事件' : 'Events'}</h2>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh ? (
+						<>
+							PageAgentCore 继承自 <TypeRef>EventTarget</TypeRef>，提供以下事件：
+						</>
+					) : (
+						<>
+							PageAgentCore extends <TypeRef>EventTarget</TypeRef> and provides the following
+							events:
+						</>
+					)}
+				</p>
+				<APIReference
+					properties={[
+						{
+							name: 'statuschange',
+							type: 'Event',
+							description: isZh
+								? 'Agent 状态变化时触发 (idle → running → completed/error)'
+								: 'Fired when agent status changes (idle → running → completed/error)',
+						},
+						{
+							name: 'historychange',
+							type: 'Event',
+							description: isZh
+								? '历史事件更新时触发（持久化事件，构成 Agent 记忆）'
+								: 'Fired when history events are updated (persistent, part of agent memory)',
+						},
+						{
+							name: 'activity',
+							type: 'CustomEvent<AgentActivity>',
+							description: isZh
+								? '实时活动反馈（短暂状态，仅用于 UI）。类型包括：thinking, executing, executed, retrying, error'
+								: 'Real-time activity feedback (transient, UI only). Types: thinking, executing, executed, retrying, error',
+						},
+						{
+							name: 'dispose',
+							type: 'Event',
+							description: isZh ? 'Agent 被销毁时触发' : 'Fired when agent is disposed',
+						},
+					]}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '类型定义' : 'Type Definitions'} />
+
+			{/* ExecutionResult */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">ExecutionResult</h2>
+				<CodeEditor
+					language="typescript"
+					code={`interface ExecutionResult {
+  /** Whether the task completed successfully */
+  success: boolean
+  /** Result description from the agent */
+  data: string
+  /** Full execution history */
+  history: HistoricalEvent[]
+}`}
+				/>
+			</section>
+
+			{/* AgentActivity */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">AgentActivity</h2>
+				<CodeEditor
+					language="typescript"
+					code={`type AgentActivity =
+  | { type: 'thinking' }
+  | { type: 'executing'; tool: string; input: unknown }
+  | { type: 'executed'; tool: string; input: unknown; output: string; duration: number }
+  | { type: 'retrying'; attempt: number; maxAttempts: number }
+  | { type: 'error'; message: string }`}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '无头模式' : 'Headless Mode'} />
+
+			{/* Headless Usage */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">{isZh ? '无头模式' : 'Headless Mode'}</h2>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '在非 DOM 环境中，你必须实现自定义的 PageController（例如远程操作页面或 Puppeteer）。'
+						: 'In non-DOM environments, you must implement a custom PageController (e.g., remote page control or Puppeteer).'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`import { PageAgentCore } from '@page-agent/core'
+import type { PageController } from '@page-agent/page-controller'
+
+class MyRemotePageController implements PageController {
+  // Implement required methods for DOM extraction and interaction
+}
+
+const agent = new PageAgentCore({
+  pageController: new MyRemotePageController(),
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: 'your-api-key',
+  model: 'gpt-5.2',
+  language: 'en-US',
+})
+
+// Listen to events for UI display
+
+agent.addEventListener('statuschange', () => {
+  console.log('Status:', agent.status)
+})
+
+agent.addEventListener('historychange', () => {
+  console.log('History:', agent.history)
+})
+
+agent.addEventListener('activity', (e) => {
+  const activity = (e as CustomEvent).detail
+  console.log('Activity:', activity.type)
+})
+
+// Execute task
+const result = await agent.execute('Fill in the form with test data')`}
+				/>
+			</section>
+		</div>
+	)
+}

packages/website/src/pages/docs/advanced/page-agent/page.tsx

@@ -0,0 +1,246 @@
+import { useTranslation } from 'react-i18next'
+import { Link } from 'wouter'
+
+import CodeEditor from '@/components/CodeEditor'
+import { APIReference, TypeRef } from '@/components/ui/api-reference'
+
+export default function PageAgentDocs() {
+	const { i18n } = useTranslation()
+	const isZh = i18n.language === 'zh-CN'
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">PageAgent</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? 'PageAgent 是带有内置 UI 面板的完整 Agent 类。它继承自 PageAgentCore，并自动创建交互面板。'
+					: 'PageAgent is the complete Agent class with built-in UI panel. It extends PageAgentCore and automatically creates an interactive panel.'}
+			</p>
+
+			{/* When to use */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">
+					{isZh ? '何时使用 PageAgent' : 'When to Use PageAgent'}
+				</h2>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '在大多数场景下，你应该使用 PageAgent。它提供了开箱即用的完整体验：'
+						: 'In most cases, you should use PageAgent. It provides a complete out-of-the-box experience:'}
+				</p>
+				<ul className="list-disc list-inside text-gray-600 dark:text-gray-400 space-y-2 mb-6">
+					<li>
+						{isZh
+							? '内置 UI 面板，显示任务进度、Agent 思考过程和操作结果'
+							: 'Built-in UI panel showing task progress, agent thinking, and action results'}
+					</li>
+					<li>
+						{isZh
+							? '支持 ask_user 工具，Agent 可以向用户提问'
+							: 'Supports ask_user tool for agent to ask questions to users'}
+					</li>
+				</ul>
+			</section>
+
+			{/* Basic Usage */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">{isZh ? '基本用法' : 'Basic Usage'}</h2>
+				<CodeEditor
+					language="typescript"
+					code={`import { PageAgent } from 'page-agent'
+
+const agent = new PageAgent({
+  // LLM Configuration (required)
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: 'your-api-key',
+  model: 'gpt-4o',
+  
+  // Optional settings
+  language: 'en-US',
+})
+
+// Execute a task
+const result = await agent.execute('Click the login button')
+
+console.log(result.success) // true or false
+console.log(result.data)    // Task result description
+console.log(result.history) // Full execution history`}
+				/>
+			</section>
+
+			{/* Class Definition */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">{isZh ? '类定义' : 'Class Definition'}</h2>
+				<CodeEditor
+					language="typescript"
+					code={`class PageAgent extends PageAgentCore {
+  /** The UI panel instance */
+  panel: Panel
+
+  constructor(config: PageAgentConfig)
+}`}
+				/>
+				<p className="text-gray-600 dark:text-gray-400 mt-4">
+					{isZh ? (
+						<>
+							PageAgent 继承自{' '}
+							<Link
+								href="/advanced/page-agent-core"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								PageAgentCore
+							</Link>
+							，所有核心方法和事件都可用。详细的 API 参考请查看 PageAgentCore 文档。
+						</>
+					) : (
+						<>
+							PageAgent extends{' '}
+							<Link
+								href="/advanced/page-agent-core"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								PageAgentCore
+							</Link>
+							. All core methods and events are available. See PageAgentCore docs for detailed API
+							reference.
+						</>
+					)}
+				</p>
+			</section>
+
+			{/* Configuration */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">{isZh ? '配置' : 'Configuration'}</h2>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? 'PageAgent 使用与 PageAgentCore 相同的配置接口。'
+						: 'PageAgent uses the same configuration interface as PageAgentCore.'}
+				</p>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh ? (
+						<>
+							完整配置请参考{' '}
+							<Link
+								href="/advanced/page-agent-core"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								PageAgentCore 配置文档
+							</Link>
+							。
+						</>
+					) : (
+						<>
+							See{' '}
+							<Link
+								href="/advanced/page-agent-core"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								PageAgentCore configuration docs
+							</Link>{' '}
+							for complete reference.
+						</>
+					)}
+				</p>
+			</section>
+
+			{/* Panel Property */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">{isZh ? 'Panel 属性' : 'Panel Property'}</h2>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? 'PageAgent 自动创建一个 Panel 实例。你可以通过 panel 属性访问它来控制 UI：'
+						: 'PageAgent automatically creates a Panel instance. You can access it via the panel property to control the UI:'}
+				</p>
+
+				<APIReference
+					properties={[
+						{
+							name: 'panel',
+							type: 'Panel',
+							required: true,
+							description: isZh
+								? '内置的 UI 面板实例，用于显示任务进度和接收用户输入。'
+								: 'The built-in UI panel instance for displaying task progress and receiving user input.',
+						},
+					]}
+				/>
+
+				<h3 className="text-lg font-semibold mt-6 mb-3">{isZh ? 'Panel 方法' : 'Panel Methods'}</h3>
+				<CodeEditor
+					language="typescript"
+					code={`// Show/hide the panel
+agent.panel.show()
+agent.panel.hide()
+
+// Expand/collapse history view
+agent.panel.expand()
+agent.panel.collapse()
+
+// Reset panel state
+agent.panel.reset()
+
+// Dispose panel (called automatically when agent disposes)
+agent.panel.dispose()`}
+				/>
+			</section>
+
+			{/* Comparison with PageAgentCore */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">
+					{isZh ? 'PageAgent vs PageAgentCore' : 'PageAgent vs PageAgentCore'}
+				</h2>
+				<div className="overflow-hidden rounded-lg border border-gray-200 dark:border-gray-700">
+					<table className="w-full text-sm">
+						<thead>
+							<tr className="bg-gray-50 dark:bg-gray-800/50">
+								<th className="px-4 py-3 text-left font-medium text-gray-600 dark:text-gray-300">
+									{isZh ? '特性' : 'Feature'}
+								</th>
+								<th className="px-4 py-3 text-center font-medium text-gray-600 dark:text-gray-300">
+									PageAgent
+								</th>
+								<th className="px-4 py-3 text-center font-medium text-gray-600 dark:text-gray-300">
+									PageAgentCore
+								</th>
+							</tr>
+						</thead>
+						<tbody className="divide-y divide-gray-100 dark:divide-gray-800">
+							<tr className="bg-white dark:bg-gray-900">
+								<td className="px-4 py-3 text-gray-600 dark:text-gray-400">
+									{isZh ? 'UI 面板' : 'UI Panel'}
+								</td>
+								<td className="px-4 py-3 text-center text-green-600 dark:text-green-400">✓</td>
+								<td className="px-4 py-3 text-center text-gray-400 dark:text-gray-600">-</td>
+							</tr>
+							<tr className="bg-white dark:bg-gray-900">
+								<td className="px-4 py-3 text-gray-600 dark:text-gray-400">
+									{isZh ? 'Headless 模式' : 'Headless Mode'}
+								</td>
+								<td className="px-4 py-3 text-center text-gray-400 dark:text-gray-600">-</td>
+								<td className="px-4 py-3 text-center text-green-600 dark:text-green-400">✓</td>
+							</tr>
+							<tr className="bg-white dark:bg-gray-900">
+								<td className="px-4 py-3 text-gray-600 dark:text-gray-400">
+									{isZh ? '自定义 PageController' : 'Custom PageController'}
+								</td>
+								<td className="px-4 py-3 text-center text-green-600 dark:text-green-400">✓</td>
+								<td className="px-4 py-3 text-center text-green-600 dark:text-green-400">✓</td>
+							</tr>
+							<tr className="bg-white dark:bg-gray-900">
+								<td className="px-4 py-3 text-gray-600 dark:text-gray-400">
+									{isZh ? '适用场景' : 'Use Case'}
+								</td>
+								<td className="px-4 py-3 text-center text-gray-600 dark:text-gray-400">
+									{isZh ? '网页集成' : 'Web integration'}
+								</td>
+								<td className="px-4 py-3 text-center text-gray-600 dark:text-gray-400">
+									{isZh ? '自定义 UI / 无头' : 'Custom UI / Headless'}
+								</td>
+							</tr>
+						</tbody>
+					</table>
+				</div>
+			</section>
+		</div>
+	)
+}

packages/website/src/pages/docs/features/data-masking/page.tsx

@@ -0,0 +1,73 @@
+import { useTranslation } from 'react-i18next'
+
+import CodeEditor from '@/components/CodeEditor'
+
+export default function DataMasking() {
+	const { i18n } = useTranslation()
+	const isZh = i18n.language === 'zh-CN'
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">{isZh ? '数据脱敏' : 'Data Masking'}</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? '使用 transformPageContent 钩子在页面内容发送给 LLM 之前进行处理，可用于检查清洗效果、修改页面信息、隐藏敏感数据等。'
+					: 'Use the transformPageContent hook to process page content before sending to LLM. Useful for inspecting extraction results, modifying page info, and masking sensitive data.'}
+			</p>
+
+			<section className="mb-12">
+				<h2 className="text-3xl font-bold mb-6">{isZh ? '接口定义' : 'API Definition'}</h2>
+
+				<CodeEditor
+					className="mb-6"
+					code={`interface PageAgentConfig {
+  /**
+   * Transform page content before sending to LLM.
+   * Called after DOM extraction and simplification.
+   */
+  transformPageContent?: (content: string) => Promise<string> | string
+}`}
+				/>
+			</section>
+
+			<section className="mb-12">
+				<h2 className="text-3xl font-bold mb-6">
+					{isZh ? '常用脱敏规则' : 'Common Masking Patterns'}
+				</h2>
+
+				<p className="text-gray-600 dark:text-gray-300 mb-6">
+					{isZh
+						? '以下示例展示了如何脱敏常见的敏感信息：'
+						: 'The following example shows how to mask common sensitive data:'}
+				</p>
+
+				<CodeEditor
+					code={`const agent = new PageAgent({
+  transformPageContent: async (content) => {
+    // China phone number (11 digits starting with 1)
+    content = content.replace(/\\b(1[3-9]\\d)(\\d{4})(\\d{4})\\b/g, '$1****$3')
+
+    // Email address
+    content = content.replace(
+      /\\b([a-zA-Z0-9._%+-])[^@]*(@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,})\\b/g,
+      '$1***$2'
+    )
+
+    // China ID card number (18 digits)
+    content = content.replace(
+      /\\b(\\d{6})(19|20\\d{2})(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])(\\d{3}[\\dXx])\\b/g,
+      '$1********$5'
+    )
+
+    // Bank card number (16-19 digits)
+    content = content.replace(/\\b(\\d{4})\\d{8,11}(\\d{4})\\b/g, '$1********$2')
+
+    return content
+  }
+})`}
+				/>
+			</section>
+		</div>
+	)
+}

packages/website/src/pages/docs/features/models/page.tsx

@@ -4,13 +4,19 @@ import CodeEditor from '@/components/CodeEditor'
 
 // Recommended models: lightweight with excellent tool call capabilities
 const MODELS = {
-	recommended: ['gpt-4.1-mini', 'claude-haiku-4.5', 'gemini-3-flash', 'deepseek-3.2', 'gpt-5.2'],
+	recommended: [
-	verified: [
+		'gpt-4.1-mini',
+		'claude-haiku-4.5',
+		'gemini-3-flash',
+		'deepseek-3.2',
+		'gpt-5.2',
 		'qwen-3-max',
+	],
+	verified: [
+		'qwen-3-plus',
 		'gpt-4.1',
 		'gpt-5',
 		'gpt-5-mini',
-		'gpt-5.1',
 		'grok-4',
 		'grok-code-fast',
 		'claude-sonnet-3.5',
@@ -21,22 +27,20 @@ const MODELS = {
 	],
 }
 
-export default function ModelIntegration() {
+export default function Models() {
 	const { t } = useTranslation('docs')
 	const allModels = [...MODELS.recommended, ...MODELS.verified]
 
 	return (
 		<div className="max-w-4xl">
-			<h1 className="text-4xl font-bold mb-4">{t('model_integration.title')}</h1>
+			<h1 className="text-4xl font-bold mb-4">{t('models.title')}</h1>
-			<p className="text-lg text-gray-600 dark:text-gray-400 mb-8">
+			<p className="text-lg text-gray-600 dark:text-gray-400 mb-8">{t('models.subtitle')}</p>
-				{t('model_integration.subtitle')}
-			</p>
 
 			{/* Models Section */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-3">{t('model_integration.available')}</h2>
+				<h2 className="text-2xl font-semibold mb-3">{t('models.available')}</h2>
 				<p className="text-sm text-gray-600 dark:text-gray-400 mb-4">
-					{t('model_integration.recommendation_logic')}
+					{t('models.recommendation_logic')}
 				</p>
 				<div className="bg-linear-to-br from-emerald-50 to-cyan-50 dark:from-emerald-950/30 dark:to-cyan-950/30 rounded-xl p-6 border border-emerald-200/50 dark:border-emerald-800/50">
 					<div className="flex flex-wrap gap-2">
@@ -63,41 +67,41 @@ export default function ModelIntegration() {
 
 			{/* Tips Section */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{t('model_integration.tips')}</h2>
+				<h2 className="text-2xl font-semibold mb-4">{t('models.tips')}</h2>
 				<div className="p-4 bg-blue-50 dark:bg-blue-950/20 rounded-lg border border-blue-200 dark:border-blue-800">
 					<ul className="text-sm text-gray-700 dark:text-gray-300 space-y-2 list-disc pl-5">
-						<li>{t('model_integration.tip_2')}</li>
+						<li>{t('models.tip_2')}</li>
-						<li>{t('model_integration.tip_3')}</li>
+						<li>{t('models.tip_3')}</li>
 					</ul>
 				</div>
 			</section>
 
 			{/* Security Section */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{t('model_integration.security')}</h2>
+				<h2 className="text-2xl font-semibold mb-4">{t('models.security')}</h2>
 				<div className="bg-yellow-50 dark:bg-yellow-950/20 border-l-4 border-yellow-500 p-5 rounded-r-lg mb-4">
 					<p className="text-sm font-semibold text-yellow-900 dark:text-yellow-200">
-						{t('model_integration.security_warning')}
+						{t('models.security_warning')}
 					</p>
 				</div>
 				<div className="bg-gray-50 dark:bg-gray-900/30 rounded-lg p-5 border border-gray-200 dark:border-gray-800">
 					<h3 className="font-semibold text-gray-900 dark:text-gray-100 mb-2">
-						{t('model_integration.security_backend_proxy')}
+						{t('models.security_backend_proxy')}
 					</h3>
 					<p className="text-sm text-gray-600 dark:text-gray-400 mb-3">
-						{t('model_integration.security_backend_desc')}
+						{t('models.security_backend_desc')}
 					</p>
 					<ul className="text-sm text-gray-600 dark:text-gray-400 space-y-1">
-						<li>{t('model_integration.security_method_1')}</li>
+						<li>{t('models.security_method_1')}</li>
-						<li>{t('model_integration.security_method_2')}</li>
+						<li>{t('models.security_method_2')}</li>
-						<li>{t('model_integration.security_method_3')}</li>
+						<li>{t('models.security_method_3')}</li>
 					</ul>
 				</div>
 			</section>
 
 			{/* Configuration Section */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{t('model_integration.configuration')}</h2>
+				<h2 className="text-2xl font-semibold mb-4">{t('models.configuration')}</h2>
 				<CodeEditor
 					code={`// OpenAI-compatible services (e.g., Alibaba Bailian)
 const pageAgent = new PageAgent({