chore(version): bump version to 1.4.3

* feat(core): experimental support for llms.txt

* docs: experimentalLlmsTxt

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -9,7 +9,7 @@ body:
         Thanks for your interest in improving the project! Before submitting, please read our guidelines.
         感谢您对改进项目的兴趣！提交前请阅读我们的指南。
 
-        - [Code of Conduct](https://github.com/alibaba/page-agent/blob/main/CODE_OF_CONDUCT.md)
+        - [Code of Conduct](https://github.com/alibaba/page-agent/blob/main/docs/CODE_OF_CONDUCT.md)
         - [Contributing Guide](https://github.com/alibaba/page-agent/blob/main/CONTRIBUTING.md)
 
   - type: textarea

.github/ISSUE_TEMPLATE/config.yml

@@ -10,5 +10,5 @@ contact_links:
     url: https://github.com/alibaba/page-agent/blob/main/CONTRIBUTING.md
     about: How to contribute code and ideas. 如何进行贡献与提交代码。
   - name: Code of Conduct / 行为准则
-    url: https://github.com/alibaba/page-agent/blob/main/CODE_OF_CONDUCT.md
+    url: https://github.com/alibaba/page-agent/blob/main/docs/CODE_OF_CONDUCT.md
     about: Community expectations and standards. 社区行为期望与标准。

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -9,7 +9,7 @@ body:
         Thanks for your interest in improving the project! Before submitting, please read our guidelines.
         感谢您对改进项目的兴趣！提交前请阅读我们的指南。
 
-        - [Code of Conduct](https://github.com/alibaba/page-agent/blob/main/CODE_OF_CONDUCT.md)
+        - [Code of Conduct](https://github.com/alibaba/page-agent/blob/main/docs/CODE_OF_CONDUCT.md)
         - [Contributing Guide](https://github.com/alibaba/page-agent/blob/main/CONTRIBUTING.md)
 
   - type: textarea

.github/PULL_REQUEST_TEMPLATE.md

@@ -22,4 +22,4 @@ Closes #(issue)
 
 ## Requirements / 要求
 
-- [ ] I have read and follow the [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing Guide](CONTRIBUTING.md) . / 我已阅读并遵守行为准则。
+- [ ] I have read and follow the [Code of Conduct](../docs/CODE_OF_CONDUCT.md) and [Contributing Guide](../CONTRIBUTING.md) . / 我已阅读并遵守行为准则。

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20, 24, 25]
+        node-version: [24]
 
     steps:
       - uses: actions/checkout@v6

.gitignore

@@ -29,11 +29,6 @@ dist-ssr
 .env
 .env.*
 
-# Copied files for npm publish (generated by prepublishOnly)
-packages/page-agent/README.md
-packages/page-agent/README-zh.md
-packages/page-agent/LICENSE
-
 # extension
 .output
 .wxt

.vscode/settings.json

@@ -18,7 +18,7 @@
         "wouter"
     ],
     "files.exclude": {
-        "packages/*/node_modules": true,
+        "packages/*/node_modules": true
     },
     "markdownlint.config": {
         // "comment": "Relaxed rules",
@@ -32,6 +32,7 @@
         "first-line-h1": false,
         "block-spacing": false,
         "blanks-around-lists": false,
-        "ol-prefix": false
+        "ol-prefix": false,
+        "no-duplicate-heading": false
     }
 }

AGENTS.md

@@ -22,6 +22,7 @@ npm start                    # Start website dev server
 npm run build                # Build all packages
 npm run build:libs           # Build all libraries
 npm run lint                 # ESLint with TypeScript strict rules
+npm run zip -w @page-agent/ext # Zip the extension package
 ```
 
 ## Architecture
@@ -36,7 +37,7 @@ packages/
 ├── page-agent/              # npm: "page-agent" entry class (with UI + controller + demo builds)
 ├── website/                 # @page-agent/website (private)
 ├── llms/                    # @page-agent/llms
-├── extension/               # 🚧 WIP: Browser extension (WXT + React)
+├── extension/               # Browser extension (WXT + React)
 ├── page-controller/         # @page-agent/page-controller
 └── ui/                      # @page-agent/ui
 ```

CHANGELOG.md

@@ -1,94 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.0.0] - 2026-01-19
-
-### 🎉 First Stable Release
-
-PageAgent is now ready for production use. The API is stable and breaking changes will follow semantic versioning.
-
-### Features
-
-#### Core
-
-- **PageAgent** - Main entry class with built-in UI Panel
-- **PageAgentCore** - Headless agent class for custom UI or programmatic use
-- **DOM Analysis** - Text-based DOM extraction with high-intensity dehydration
-- **LLM Support** - Works with OpenAI, Claude, DeepSeek, Qwen, and other OpenAI-compatible APIs
-- **Tool System** - Built-in tools for click, input, scroll, select, and more
-- **Custom Tools** - Extend agent capabilities with your own tools (experimental)
-- **Lifecycle Hooks** - Hook into agent execution (experimental)
-- **Instructions System** - System-level and page-level instructions to guide agent behavior
-- **Data Masking** - Transform page content before sending to LLM
-
-#### Page Controller
-
-- **Element Interactions** - Click, input text, select options, scroll
-- **Visual Mask** - Blocks user interaction during automation
-- **DOM Tree Extraction** - Efficient page structure extraction for LLM consumption
-
-#### UI
-
-- **Interactive Panel** - Real-time task progress and agent thinking display
-- **Ask User Tool** - Agent can ask users for clarification
-- **i18n Support** - English and Chinese localization
-
-### Configuration
-
-```typescript
-interface PageAgentConfig {
-    // LLM Configuration (required)
-    baseURL: string
-    apiKey: string
-    model: string
-    temperature?: number
-    maxRetries?: number
-    customFetch?: typeof fetch
-
-    // Agent Configuration
-    language?: 'en-US' | 'zh-CN'
-    maxSteps?: number // default: 20
-    customTools?: Record<string, PageAgentTool> // experimental
-    instructions?: InstructionsConfig
-    transformPageContent?: (content: string) => string | Promise<string>
-    experimentalScriptExecutionTool?: boolean // default: false
-
-    // Lifecycle Hooks (experimental)
-    onBeforeTask?: (agent, result) => void
-    onAfterTask?: (agent, result) => void
-    onBeforeStep?: (agent, stepCount) => void
-    onAfterStep?: (agent, history) => void
-    onDispose?: (agent, reason?) => void
-
-    // Page Controller Configuration
-    enableMask?: boolean // default: true
-    viewportExpansion?: number
-    interactiveBlacklist?: Element[]
-    interactiveWhitelist?: Element[]
-}
-```
-
-### Packages
-
-| Package                       | Description                        |
-| ----------------------------- | ---------------------------------- |
-| `page-agent`                  | Main entry with UI Panel           |
-| `@page-agent/core`            | Core agent logic without UI        |
-| `@page-agent/llms`            | LLM client with retry logic        |
-| `@page-agent/page-controller` | DOM operations and visual feedback |
-| `@page-agent/ui`              | Panel and i18n                     |
-
-### Known Limitations
-
-- Single-page application only (cannot navigate across pages)
-- No visual recognition (relies on DOM structure)
-- Limited interaction support (no hover, drag-drop, canvas operations)
-- See [Limitations](https://alibaba.github.io/page-agent/#/docs/introduction/limitations) for details
-
-### Acknowledgments
-
-This project builds upon the excellent work of [browser-use](https://github.com/browser-use/browser-use). DOM processing components and prompts are adapted from browser-use (MIT License).

CONTRIBUTING.md

@@ -20,10 +20,11 @@ Thank you for your interest in contributing to Page-Agent! We welcome contributi
 
 ### Project Structure
 
-This is a **monorepo** with npm workspaces containing **3 main packages**:
+This is a **monorepo** with npm workspaces containing **4 main packages**:
 
 - **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel, published as `page-agent` on npm
 - **Core** (`packages/core/`) - Core agent logic without UI (npm: `@page-agent/core`)
+- **Extension** (`packages/extension/`) - Chrome extension for multi-page tasks and browser-level automation
 - **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.
@@ -145,6 +146,16 @@ If your lame AI assistant does not support [AGENTS.md](https://agents.md/). Add
 npm start
 ```
 
+### Extension Development
+
+```bash
+npm run dev -w @page-agent/ext
+npm run zip -w @page-agent/ext
+```
+
+- Load extension in Chrome via `chrome://extensions` -> **Load unpacked**
+- Use `packages/extension/docs/extension_api.md` (EN) or `packages/extension/docs/extension_api_zh.md` (ZH) for API integration details
+
 ### Testing on Other Websites
 
 - Start and serve a local `iife` script
@@ -193,14 +204,6 @@ By contributing to this project, you agree that your contributions will be licen
 
 > You may need to sign a github CLA before you create a PR.
 
-### Browser-Use Attribution
-
-Parts of this project are derived from the [browser-use](https://github.com/browser-use/browser-use) project (MIT License). When contributing to DOM-related functionality:
-
-- Maintain existing attribution comments
-- Follow similar patterns for consistency
-- Credit browser-use for derived concepts
-
 ## 💬 Questions?
 
 - Open a GitHub issue for technical questions

README.md

@@ -1,4 +1,4 @@
-# PageAgent 🤖🪄
+# Page Agent
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://img.alicdn.com/imgextra/i4/O1CN01qKig1P1FnhpFKNdi6_!!6000000000532-2-tps-1280-256.png">
@@ -9,28 +9,33 @@
 
 The GUI Agent Living in Your Webpage. Control web interfaces with natural language.
 
-🌐 **English** | [中文](./README-zh.md)
+🌐 **English** | [中文](./docs/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/34d8444d-cbfb-44a3-a24e-fd5c167bb0bf" controls crossorigin muted></video>
+<video id="demo-video" src="https://github.com/user-attachments/assets/11aed429-b69c-49d5-8982-fa99b4a0e9a8" controls crossorigin muted></video>
 
 ---
 
 ## ✨ Features
 
-- **🎯 Easy Integration**
+- **🎯 Easy integration**
-    - No python. No headless browser. No browser extension. Just in-page scripts.
+    - No need for `browser extension` / `python` / `headless browser`.
-- **🔐 Client-Side Processing**
+    - Just in-page javascript. Everything happens in your web page.
-- **🧠 DOM Extraction**
+    - The best tool for your agent to control web pages.
-- **💬 Natural Language Interface**
+- **📖 Text-based DOM manipulation**
-- **🎨 UI with Human in the loop**
+    - No screenshots. No OCR or multi-modal LLMs needed.
+    - No special permissions required.
+- **🧠 Bring your own LLMs**
+- **🎨 Pretty UI with human-in-the-loop**
+- **🐙 Optional [chrome extension](https://alibaba.github.io/page-agent/docs/features/chrome-extension) for multi-page tasks.**
 
-And 😉
+## 💡 Use Cases
 
-- **🧪 `cross-page` control with an experimental chrome extension** - `packages/extension`
+- **SaaS AI Copilot** — Ship an AI copilot in your product in lines of code. No backend rewrite needed.
-
+- **Smart Form Filling** — Turn 20-click workflows into one sentence. Perfect for ERP, CRM, and admin systems.
-👉 [**🗺️ Roadmap**](https://github.com/alibaba/page-agent/issues/96)
+- **Accessibility** — Make any web app accessible through natural language. Voice commands, screen readers, zero barrier.
+- **Multi-page Agent** — Extend your agent's reach across browser tabs with the optional [chrome extension](https://alibaba.github.io/page-agent/docs/features/chrome-extension).
 
 ## 🚀 Quick Start
 
@@ -39,19 +44,15 @@ And 😉
 Fastest way to try PageAgent with our free Demo LLM:
 
 ```html
-<script
+<script src="{URL}" crossorigin="true"></script>
-    src="https://cdn.jsdelivr.net/npm/page-agent@1.1.1/dist/iife/page-agent.demo.js"
-    crossorigin="true"
-></script>
 ```
 
-> - **⚠️ For technical evaluation only.** Demo LLM has rate limits and usage restrictions. May change without notice.
-> - **🌷 Bring your own LLM API.**
-
 | Mirrors | URL                                                                                |
 | ------- | ---------------------------------------------------------------------------------- |
-| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.1.1/dist/iife/page-agent.demo.js         |
+| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.4.3/dist/iife/page-agent.demo.js         |
-| China   | https://registry.npmmirror.com/page-agent/1.1.1/files/dist/iife/page-agent.demo.js |
+| China   | https://registry.npmmirror.com/page-agent/1.4.3/files/dist/iife/page-agent.demo.js |
+
+> **⚠️ For technical evaluation only.** This demo CDN uses our free [testing LLM API](https://alibaba.github.io/page-agent/docs/features/models#free-testing-api). By using it, you agree to its [terms](https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md).
 
 ### NPM Installation
 
@@ -63,8 +64,8 @@ npm install page-agent
 import { PageAgent } from 'page-agent'
 
 const agent = new PageAgent({
-    model: 'deepseek-chat',
+    model: 'qwen3.5-plus',
-    baseURL: 'https://api.deepseek.com',
+    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
     apiKey: 'YOUR_API_KEY',
     language: 'en-US',
 })
@@ -72,25 +73,13 @@ const agent = new PageAgent({
 await agent.execute('Click the login button')
 ```
 
-## 🏗️ Structure
+For more programmatic usage, see [📖 Documentations](https://alibaba.github.io/page-agent/docs/introduction/overview).
-
-PageAgent adopts a simplified monorepo structure:
-
-```
-packages/
-├── core/                # ** Core agent logic without UI(npm: @page-agent/core) **
-├── page-agent/          # Exported agent and demo(npm: page-agent)
-├── llms/                # LLM client (npm: @page-agent/llms)
-├── page-controller/     # DOM operations & Visual Mask (npm: @page-agent/page-controller)
-├── ui/                  # Panel & i18n (npm: @page-agent/ui)
-└── website/             # Demo & Documentation site
-```
 
 ## 🤝 Contributing
 
 We welcome contributions from the community! Follow our instructions in [CONTRIBUTING.md](CONTRIBUTING.md) for environment setup and local development.
 
-Please read [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
+Please read [Code of Conduct](docs/CODE_OF_CONDUCT.md) before contributing.
 
 ## 👏 Acknowledgments
 

docs/CHANGELOG.md

@@ -0,0 +1,180 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.0] - 2026-02-27
+
+### Features
+
+- Update Terms of Use and Privacy Policy
+- **Robust tool-call validation** - Action inputs are now validated against tool schemas individually, producing clear error messages (e.g. `Invalid input for action "click_element_by_index"`) instead of unreadable union parse errors
+- **Primitive action input coercion** - Small models that output `{"click_element_by_index": 2}` instead of `{"click_element_by_index": {"index": 2}}` are now auto-corrected using tool schemas
+- **Qwen model updates** - Added `qwen3.5-plus` as the default free testing model; disabled `enable_thinking` for Qwen models to avoid incompatible responses
+- **Updated default LLM endpoint** - Migrated demo and extension to a new testing endpoint with legacy endpoint auto-migration
+
+### Improvements
+
+- Unified zod imports (`* as z`) across all packages for consistency
+- Better Zod error formatting with `z.prettifyError()` in LLM client
+- Exported `InvokeError` and `InvokeErrorType` as values (not just types) from `@page-agent/llms`
+- Exported `SupportedLanguage` type from `@page-agent/core`
+
+### Extension v0.1.8
+
+- **Language setting** - Added language selector (System / English / 中文) in config panel
+- **UI makeover** - New empty state with breathing glow and typing animation; ai-motion glow overlay while running; refined focus styles
+- **Testing endpoint notice** - Shows terms of use notice when using the free testing API
+- **Legacy endpoint migration** - Auto-migrates old Supabase testing endpoint to new endpoint on startup
+
+---
+
+## [1.3.0] - 2026-02-13
+
+### Breaking Changes
+
+- **Lifecycle: `stop()` vs `dispose()`** - New `stop()` method to cancel the current task while keeping the agent reusable. `dispose()` is now terminal — a disposed agent cannot be reused. This affects both `PageAgentCore` and `PanelAgentAdapter`.
+
+### Features
+
+- **Panel action button** - The panel button now morphs between Stop (■) and Close (X) based on agent status
+- **Error history** - Errors and max-step failures are now recorded in `history` as `AgentErrorEvent`, making post-task analysis more complete
+
+### Bug Fixes
+
+- **AbortError handling** - `AbortError` is no longer retried by the LLM client, and shows a clean "Task stopped" message instead of a raw error stack
+
+---
+
+## [1.2.0] - 2026-02-11
+
+### Features
+
+- **Observe Phase** - Agent now observes the page before each action, improving decision accuracy on dynamic pages
+- **Better Abort Handling** - Improved `abortSignal` support for cleaner task cancellation
+
+### Improvements
+
+- Pruned system prompts for lower token usage and faster responses
+- Improved error handling during agent steps with better error messages
+- Zod tree-shaking for smaller bundle size
+
+### Bug Fixes
+
+- Fixed indentation lost in DOM extraction caused by `trimLines`
+- Fixed `gpt-5-mini` temperature configuration
+
+---
+
+## [1.1.0] - 2026-02-02
+
+### Features
+
+- **Custom System Prompt** - New `systemPrompt` config option to customize or extend the default system prompt
+- **Chrome Extension** - Extension with multi-tab control, main-world API with token auth, and tab lifecycle management
+
+### Improvements
+
+- Renamed `include_attributes` to `includeAttributes` in PageController config (camelCase consistency)
+- Lazy-loaded mask module for faster initialization
+- Better date formatting and error messages from LLM client
+- Added `rawRequest` to step history for easier debugging
+
+### Bug Fixes
+
+- Fixed CSP errors by using local SVGs for cursor mask instead of inline styles
+- Fixed `AbortError` being incorrectly retried and shown to users
+- Fixed mask not working correctly when starting a new task after stopping a previous one
+
+---
+
+## [1.0.0] - 2026-01-19
+
+### 🎉 First Stable Release
+
+PageAgent is now ready for production use. The API is stable and breaking changes will follow semantic versioning.
+
+### Features
+
+#### Core
+
+- **PageAgent** - Main entry class with built-in UI Panel
+- **PageAgentCore** - Headless agent class for custom UI or programmatic use
+- **DOM Analysis** - Text-based DOM extraction with high-intensity dehydration
+- **LLM Support** - Works with OpenAI, Claude, DeepSeek, Qwen, and other OpenAI-compatible APIs
+- **Tool System** - Built-in tools for click, input, scroll, select, and more
+- **Custom Tools** - Extend agent capabilities with your own tools (experimental)
+- **Lifecycle Hooks** - Hook into agent execution (experimental)
+- **Instructions System** - System-level and page-level instructions to guide agent behavior
+- **Data Masking** - Transform page content before sending to LLM
+
+#### Page Controller
+
+- **Element Interactions** - Click, input text, select options, scroll
+- **Visual Mask** - Blocks user interaction during automation
+- **DOM Tree Extraction** - Efficient page structure extraction for LLM consumption
+
+#### UI
+
+- **Interactive Panel** - Real-time task progress and agent thinking display
+- **Ask User Tool** - Agent can ask users for clarification
+- **i18n Support** - English and Chinese localization
+
+### Configuration 
+
+```typescript
+// Version 1.0.0
+interface PageAgentConfig {
+    // LLM Configuration (required)
+    baseURL: string
+    apiKey: string
+    model: string
+    temperature?: number
+    maxRetries?: number
+    customFetch?: typeof fetch
+
+    // Agent Configuration
+    language?: 'en-US' | 'zh-CN'
+    maxSteps?: number // default: 20
+    customTools?: Record<string, PageAgentTool> // experimental
+    instructions?: InstructionsConfig
+    transformPageContent?: (content: string) => string | Promise<string>
+    experimentalScriptExecutionTool?: boolean // default: false
+
+    // Lifecycle Hooks (experimental)
+    onBeforeTask?: (agent, result) => void
+    onAfterTask?: (agent, result) => void
+    onBeforeStep?: (agent, stepCount) => void
+    onAfterStep?: (agent, history) => void
+    onDispose?: (agent, reason?) => void
+
+    // Page Controller Configuration
+    enableMask?: boolean // default: true
+    viewportExpansion?: number
+    interactiveBlacklist?: Element[]
+    interactiveWhitelist?: Element[]
+}
+```
+
+### Packages
+
+| Package                       | Description                        |
+| ----------------------------- | ---------------------------------- |
+| `page-agent`                  | Main entry with UI Panel           |
+| `@page-agent/core`            | Core agent logic without UI        |
+| `@page-agent/llms`            | LLM client with retry logic        |
+| `@page-agent/page-controller` | DOM operations and visual feedback |
+| `@page-agent/ui`              | Panel and i18n                     |
+
+### Known Limitations
+
+- Single-page application only (cannot navigate across pages)
+- No visual recognition (relies on DOM structure)
+- Limited interaction support (no hover, drag-drop, canvas operations)
+- See [Limitations](https://alibaba.github.io/page-agent/docs/introduction/limitations) for details
+
+### Acknowledgments
+
+This project builds upon the excellent work of [browser-use](https://github.com/browser-use/browser-use). DOM processing components and prompts are adapted from browser-use (MIT License).

docs/README-zh.md

@@ -1,4 +1,4 @@
-# PageAgent 🤖🪄
+# Page Agent
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://img.alicdn.com/imgextra/i4/O1CN01qKig1P1FnhpFKNdi6_!!6000000000532-2-tps-1280-256.png">
@@ -9,28 +9,33 @@
 
 纯 JS 实现的 GUI agent。使用自然语言操作你的 Web 应用。无须后端、客户端、浏览器插件。
 
-🌐 [English](./README.md) | **中文**
+🌐 [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/34d8444d-cbfb-44a3-a24e-fd5c167bb0bf" controls crossorigin muted></video>
+<video id="demo-video" src="https://github.com/user-attachments/assets/11aed429-b69c-49d5-8982-fa99b4a0e9a8" controls crossorigin muted></video>
 
 ---
 
 ## ✨ Features
 
 - **🎯 轻松集成**
-    - 无需 Python，无需无头浏览器，无需浏览器插件。纯页面内脚本。
+    - 无需 `浏览器插件` / `Python` / `无头浏览器`。
-- **🔐 端侧运行**
+    - 纯页面内 JavaScript，一切都在你的网页中完成。
-- **🧠 HTML 脱水**
+    - The best tool for your agent to control web pages.
-- **💬 自然语言接口**
+- **📖 基于文本的 DOM 操作**
-- **🎨 HITL 交互界面**
+    - 无需截图，无需 OCR 或多模态模型。
+    - 无需特殊权限。
+- **🧠 用你自己的 LLM**
+- **🎨 精美 UI，支持人机协同**
+- **🐙 可选的 [Chrome 扩展](https://alibaba.github.io/page-agent/docs/features/chrome-extension)，支持跨页面任务。**
 
-以及 😉
+## 💡 应用场景
 
-- **🧪 实验性的 Chrome 扩展，支持跨页面控制** - `packages/extension`
+- **SaaS AI 副驾驶** — 几行代码为你的产品加上 AI 副驾驶，不需要重写后端。
-
+- **智能表单填写** — 把 20 次点击变成一句话。ERP、CRM、管理后台的最佳拍档。
-👉 [**🗺️ Roadmap**](https://github.com/alibaba/page-agent/issues/96)
+- **无障碍增强** — 用自然语言让任何网页无障碍。语音指令、屏幕阅读器，零门槛。
+- **跨页面 Agent** — 通过可选的 [Chrome 扩展](https://alibaba.github.io/page-agent/docs/features/chrome-extension)，让你的 Agent 跨标签页工作。
 
 ## 🚀 快速开始
 
@@ -39,19 +44,15 @@
 通过我们免费的 Demo LLM 快速体验 PageAgent：
 
 ```html
-<script
+<script src="{URL}" crossorigin="true"></script>
-    src="https://registry.npmmirror.com/page-agent/1.1.1/files/dist/iife/page-agent.demo.js"
-    crossorigin="true"
-></script>
 ```
 
-> - **⚠️ 仅用于技术评估。** Demo LLM 有速率和使用限制，可能随时变更。
-> - **🌷 建议使用自己的 LLM API。**
-
 | Mirrors | URL                                                                                |
 | ------- | ---------------------------------------------------------------------------------- |
-| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.1.1/dist/iife/page-agent.demo.js         |
+| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.4.3/dist/iife/page-agent.demo.js         |
-| China   | https://registry.npmmirror.com/page-agent/1.1.1/files/dist/iife/page-agent.demo.js |
+| China   | https://registry.npmmirror.com/page-agent/1.4.3/files/dist/iife/page-agent.demo.js |
+
+> **⚠️ 仅用于技术评估。** 该 Demo CDN 使用了免费的[测试 LLM API](https://alibaba.github.io/page-agent/docs/features/models#free-testing-api)，使用即表示您同意其[条款](https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md)。
 
 ### NPM 安装
 
@@ -63,8 +64,8 @@ npm install page-agent
 import { PageAgent } from 'page-agent'
 
 const agent = new PageAgent({
-    model: 'deepseek-chat',
+    model: 'qwen3.5-plus',
-    baseURL: 'https://api.deepseek.com',
+    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
     apiKey: 'YOUR_API_KEY',
     language: 'zh-CN',
 })
@@ -72,25 +73,11 @@ const agent = new PageAgent({
 await agent.execute('点击登录按钮')
 ```
 
-适用于无法使用 NPM 的环境，我们也提供了 IIFE 构建的 CDN 方式。[@see CDN Usage](https://alibaba.github.io/page-agent/#/docs/integration/cdn-setup)
+更多编程用法，请参阅 [📖 文档](https://alibaba.github.io/page-agent/docs/introduction/overview)。
-
-## 🏗️ 架构设计
-
-PageAgent adopts a simplified monorepo structure:
-
-```
-packages/
-├── core/                # ** Core agent logic without UI(npm: @page-agent/core) **
-├── page-agent/          # Exported agent and demo(npm: page-agent)
-├── llms/                # LLM 客户端 (npm: @page-agent/llms)
-├── page-controller/     # DOM 操作 & 蒙层 & 模拟鼠标 (npm: @page-agent/page-controller)
-├── ui/                  # 面板 & i18n (npm: @page-agent/ui)
-└── website/             # 文档站点
-```
 
 ## 🤝 贡献
 
-欢迎社区贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解环境配置和本地开发说明。
+欢迎社区贡献！请参阅 [CONTRIBUTING.md](../CONTRIBUTING.md) 了解环境配置和本地开发说明。
 
 请在贡献前阅读[行为准则](CODE_OF_CONDUCT.md)。
 
@@ -119,7 +106,7 @@ file and in the node_modules directory after installation.
 
 ## 📄 许可证
 
-[MIT License](LICENSE)
+[MIT License](../LICENSE)
 
 ---
 

docs/terms-and-privacy.md

@@ -0,0 +1,83 @@
+# Terms of Use & Privacy
+
+**Last updated:** February 2026
+
+"We" in this document refers to the maintainers of the open-source Page Agent project (https://github.com/alibaba/page-agent). This document covers the Page Agent software itself and the testing services we provide — **not** any third-party product or service built with it.
+
+---
+
+## 1. Open Source Software Privacy
+
+Page Agent (PageAgent.js and Page Agent Extension) is a **client-side only** tool with a "Bring Your Own Key" (BYOK) architecture. The software itself does **not** include any backend service. The software does **not** collect or transmit any user data on its own, and the maintainers do **not** have access to your browsing activity, page content, or task instructions through the software.
+
+All data transmission occurs **only** between your browser and the LLM provider you configure. You are in full control of which provider receives your data.
+
+- You choose which LLM provider to use
+- You may configure your own API endpoint at any time
+- The project is open source and can be audited: https://github.com/alibaba/page-agent
+
+---
+
+## 2. Testing API and Demo Disclaimer & Terms of Use
+
+To facilitate easy testing and technical evaluation, we provide a free testing LLM API. This API is used in the project homepage's live demo, the pre-built demo CDN bundles, and the browser extension's default configuration. Users may also use it independently for their own technical evaluation of page-agent.
+
+This free testing API is provided **strictly for technical evaluation and R&D purposes only**. It must not be used in any production environment. By using this service, you agree to the following terms:
+
+**No Sensitive Data**: You are strictly prohibited from inputting any Personal Identifiable Information (PII), confidential business data, financial/medical records, or using this agent on web pages containing such sensitive information.
+
+**Zero Data Retention**: We do not store, log, or use your prompts or webpage data (DOM) for model training. All data is processed in-transit and immediately discarded. However, we do temporarily process necessary, identity-agnostic network data (such as IP addresses) solely for rate-limiting and anti-abuse purposes.
+
+**Independent Infrastructure**: The `page-agent` open-source software is completely frontend-based with a "Bring Your Own Key" (BYOK) architecture and no built-in backend. To facilitate easy testing, the maintainers have independently purchased public cloud services from Alibaba Cloud China ([aliyun.com](https://www.aliyun.com) FC and BaiLian Qwen models). This project is not affiliated with, nor endorsed by, Alibaba Cloud.
+
+**No Guaranteed Availability**: This testing API may be rate-limited, degraded, or discontinued at any time without prior notice.
+
+**"AS IS" & Limitation of Liability**: This service is provided strictly on an "AS IS" and "AS AVAILABLE" basis, without any warranties. The maintainers bear no liability for any data loss, service interruption, or legal consequences arising from your use of this demo.
+
+**Recommendation for Real Usage**: For secure and continuous usage, we strongly advise using the default BYOK mode with your own legally compliant commercial LLM API keys, or connecting to local, offline models (e.g., Ollama).
+
+**Note**: This service processes data via servers located in Mainland China. If you are located in a region with strict data localization laws (such as the EU/EEA), please do not use this demo.
+
+---
+
+## 3. Browser Extension (Page Agent Ext)
+
+### Data Processing
+
+The extension performs DOM analysis and automation actions **locally in your browser**. Your browsing history, passwords, and form data are not accessed or collected by the extension developer.
+
+Data is transmitted to external servers **only when you initiate an automation task**. When this occurs:
+
+- Your task instructions (natural language commands)
+- Simplified page structure (cleaned DOM) of all pages under the extension's control
+
+are sent to the LLM API endpoint configured in **your settings**.
+
+> **Note:** The DOM cleaning process simplifies page structure for AI readability but **does not guarantee removal of sensitive information** (e.g., visible text, form values, or personal data on the page). Please be mindful of the page content when initiating tasks.
+
+**If you configure a third-party LLM provider** (e.g., OpenAI, Anthropic, or others), data is sent directly to that provider. Their privacy policies apply.
+
+**If you use the built-in testing API**, the terms in [Section 2](#2-testing-api-and-demo-disclaimer--terms-of-use) apply. By using the extension with the default testing API, you agree to those terms.
+
+### Data Storage
+
+- **Local storage only**: Your configuration (API endpoint, API key, model selection) is stored in your browser via `chrome.storage.local`
+- **No cloud sync**: Configuration is not synced to any external server
+- **No analytics**: The extension does not include any analytics or tracking code
+
+### Your Control
+
+- The extension is open source and can be audited by anyone
+- You choose which LLM provider to use
+- You may configure your own API endpoint at any time
+- You can clear all stored data by removing the extension
+
+---
+
+## Changes
+
+We may update these terms as the project evolves.
+
+## Contact
+
+https://github.com/alibaba/page-agent/issues

package.json

@@ -1,7 +1,7 @@
 {
     "name": "root",
     "private": true,
-    "version": "1.1.1",
+    "version": "1.4.3",
     "type": "module",
     "workspaces": [
         "packages/page-controller",
@@ -21,8 +21,7 @@
     },
     "homepage": "https://alibaba.github.io/page-agent/",
     "engines": {
-        "node": ">=20.0.0",
+        "node": "^20.19.0 || ^22.13.0 || >=24"
-        "npm": ">=10.0.0"
     },
     "scripts": {
         "cleanup": "rm -rf packages/*/dist",
@@ -36,30 +35,33 @@
         "prepare": "husky"
     },
     "devDependencies": {
-        "@commitlint/cli": "^20.3.1",
+        "@commitlint/cli": "^20.4.2",
-        "@commitlint/config-conventional": "^20.3.1",
+        "@commitlint/config-conventional": "^20.4.2",
         "@eslint/js": "^9.39.2",
-        "@microsoft/api-extractor": "^7.55.2",
+        "@microsoft/api-extractor": "^7.57.6",
+        "@tailwindcss/vite": "^4.2.1",
         "@trivago/prettier-plugin-sort-imports": "^6.0.2",
-        "@types/node": "^25.0.9",
+        "@types/node": "^25.3.3",
+        "@vitejs/plugin-react-swc": "^4.1.0",
         "chalk": "^5.6.2",
         "concurrently": "^9.2.1",
-        "dotenv": "^17.2.3",
+        "dotenv": "^17.3.1",
         "eslint": "^9.39.2",
         "eslint-config-prettier": "^10.1.8",
-        "eslint-plugin-react-dom": "^2.7.2",
+        "eslint-plugin-react-dom": "^2.13.0",
         "eslint-plugin-react-hooks": "^7.0.1",
-        "eslint-plugin-react-refresh": "^0.5.0",
+        "eslint-plugin-react-refresh": "^0.5.2",
-        "eslint-plugin-react-x": "^2.7.2",
+        "eslint-plugin-react-x": "^2.13.0",
-        "globals": "^17.0.0",
+        "globals": "^17.4.0",
         "husky": "^9.1.7",
-        "lint-staged": "^16.2.4",
+        "lint-staged": "^16.3.1",
         "prettier": "^3.8.0",
         "typescript": "^5.9.3",
-        "typescript-eslint": "^8.54.0",
+        "typescript-eslint": "^8.56.1",
         "unplugin-dts": "^1.0.0-beta.6",
         "vite": "^7.3.1",
-        "vite-plugin-css-injected-by-js": "^3.5.2"
+        "vite-plugin-css-injected-by-js": "^4.0.1",
+        "vite-bundle-analyzer": "^1.3.6"
     },
     "overrides": {
         "typescript": "^5.9.3"

packages/core/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@page-agent/core",
     "private": false,
-    "version": "1.1.1",
+    "version": "1.4.3",
     "type": "module",
     "main": "./dist/esm/page-agent-core.js",
     "module": "./dist/esm/page-agent-core.js",
@@ -45,7 +45,7 @@
     "dependencies": {
         "chalk": "^5.6.2",
         "zod": "^4.3.5",
-        "@page-agent/llms": "1.1.1",
+        "@page-agent/llms": "1.4.3",
-        "@page-agent/page-controller": "1.1.1"
+        "@page-agent/page-controller": "1.4.3"
     }
 }

packages/core/src/PageAgentCore.ts

@@ -3,16 +3,15 @@
  * All rights reserved.
  */
 import { InvokeError, LLM, type Tool } from '@page-agent/llms'
-import type { PageController } from '@page-agent/page-controller'
+import type { BrowserState, PageController } from '@page-agent/page-controller'
 import chalk from 'chalk'
-import zod from 'zod'
+import * as z from 'zod'
 
-import { type PageAgentConfig } from './config'
-import { DEFAULT_MAX_STEPS } from './config/constants'
 import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
 import { tools } from './tools'
-import {
+import type {
 	AgentActivity,
+	AgentConfig,
 	AgentReflection,
 	AgentStatus,
 	AgentStepEvent,
@@ -21,17 +20,26 @@ import {
 	MacroToolInput,
 	MacroToolResult,
 } from './types'
-import { normalizeResponse, trimLines, uid, waitFor } from './utils'
+import { assert, fetchLlmsTxt, normalizeResponse, uid, waitFor } from './utils'
-import { assert } from './utils/assert'
 
-export { type PageAgentConfig }
 export { tool, type PageAgentTool } from './tools'
 export type * from './types'
 
+export type PageAgentCoreConfig = AgentConfig & { pageController: PageController }
+
 /**
- * AI agent for browser DOM automation.
+ * AI agent for browser automation.
  *
  * @remarks
+ * ## Re-act Agent Loop
+ * - step
+ *    - observe (gather information about current environment and context)
+ *    - think (LLM calling)
+ *      - reflection (evaluate history, generate memory, short-term planning)
+ *      - action (give the action to approach the next goal)
+ *    - act (execute the action)
+ * - loop
+ *
  * ## Event System
  * - `statuschange` - Agent status transitions (idle → running → completed/error)
  * - `historychange` - History events updated (persistent, part of agent memory)
@@ -50,14 +58,18 @@ export type * from './types'
  *    - Types: thinking, executing, executed, retrying, error
  */
 export class PageAgentCore extends EventTarget {
-	config: PageAgentConfig & { maxSteps: number }
+	readonly id = uid()
-	id = uid()
+	readonly config: PageAgentCoreConfig & { maxSteps: number }
-	tools: typeof tools
+	readonly tools: typeof tools
+	/** PageController for DOM operations */
+	readonly pageController: PageController
+
 	task = ''
 	taskId = ''
-
+	/** History events */
-	/** Agent execution status */
+	history: HistoricalEvent[] = []
-	#status: AgentStatus = 'idle'
+	/** Whether this agent has been disposed */
+	disposed = false
 
 	/**
 	 * Callback for when agent needs user input (ask_user tool)
@@ -66,27 +78,25 @@ export class PageAgentCore extends EventTarget {
 	 */
 	onAskUser?: (question: string) => Promise<string>
 
+	#status: AgentStatus = 'idle'
 	#llm: LLM
 	#abortController = new AbortController()
+	#observations: string[] = []
 
-	/** PageController for DOM operations */
+	/** internal states during a single task execution */
-	pageController: PageController
+	#states = {
-
+		/** Accumulated wait time in seconds */
-	/** Runtime states for tracking across steps */
-	states = {
-		/** Accumulated wait time in seconds, used by wait tool */
 		totalWaitTime: 0,
-		/** Last known URL for detecting navigation */
+		/** For detecting navigation */
 		lastURL: '',
+		/** Browser state */
+		browserState: null as BrowserState | null,
 	}
 
-	/** History events */
+	constructor(config: PageAgentCoreConfig) {
-	history: HistoricalEvent[] = []
-
-	constructor(config: PageAgentConfig & { pageController: PageController }) {
 		super()
 
-		this.config = { ...config, maxSteps: config.maxSteps || DEFAULT_MAX_STEPS }
+		this.config = { ...config, maxSteps: config.maxSteps || 20 }
 
 		this.#llm = new LLM(this.config)
 		this.tools = new Map(tools)
@@ -166,15 +176,24 @@ export class PageAgentCore extends EventTarget {
 	}
 
 	/**
-	 * Push a persistent observation to the history event stream.
+	 * Push a observation message to the history event stream.
-	 * This will be visible in <agent_history> and remain in memory across steps.
+	 * This will be visible in <agent_history> and remain persistent in memory across steps.
+	 * @experimental @internal
+	 * @note history change will be emitted before next step starts
 	 */
 	pushObservation(content: string): void {
-		this.history.push({ type: 'observation', content })
+		this.#observations.push(content)
-		this.#emitHistoryChange()
+	}
+
+	/** Stop the current task. Agent remains reusable. */
+	stop() {
+		this.pageController.cleanUpHighlights()
+		this.pageController.hideMask()
+		this.#abortController.abort()
 	}
 
 	async execute(task: string): Promise<ExecutionResult> {
+		if (this.disposed) throw new Error('PageAgent has been disposed. Create a new instance.')
 		if (!task) throw new Error('Task is required')
 		this.task = task
 		this.taskId = uid()
@@ -202,45 +221,46 @@ export class PageAgentCore extends EventTarget {
 		this.history = []
 		this.#setStatus('running')
 		this.#emitHistoryChange()
+		this.#observations = []
 
-		// Reset states
+		// Reset internal states
-		this.states = {
+		this.#states = { totalWaitTime: 0, lastURL: '', browserState: null }
-			totalWaitTime: 0,
-			lastURL: '',
-		}
 
-		try {
+		let step = 0
-			let step = 0
 
-			while (true) {
+		while (true) {
-				await this.#generateObservations(step)
+			try {
+				console.group(`step: ${step}`)
 
 				await onBeforeStep?.(this, step)
 
-				console.group(`step: ${step}`)
+				// observe
 
-				// abort
+				console.log(chalk.blue.bold('👀 Observing...'))
-				if (this.#abortController.signal.aborted) throw new Error('AbortError')
 
-				// Thinking
+				this.#states.browserState = await this.pageController.getBrowserState()
-				console.log(chalk.blue('Thinking...'))
+				await this.#handleObservations(step)
-				this.#emitActivity({ type: 'thinking' })
 
-				// invoke LLM
+				// assemble prompts
 
 				const messages = [
 					{ role: 'system' as const, content: this.#getSystemPrompt() },
 					{ role: 'user' as const, content: await this.#assembleUserPrompt() },
 				]
 
-				const tools = { AgentOutput: this.#packMacroTool() }
+				const macroTool = { AgentOutput: this.#packMacroTool() }
 
-				const result = await this.#llm.invoke(messages, tools, this.#abortController.signal, {
+				// invoke LLM
+
+				console.log(chalk.blue.bold('🧠 Thinking...'))
+				this.#emitActivity({ type: 'thinking' })
+
+				const result = await this.#llm.invoke(messages, macroTool, this.#abortController.signal, {
 					toolChoiceName: 'AgentOutput',
-					normalizeResponse,
+					normalizeResponse: (res) => normalizeResponse(res, this.tools),
 				})
 
-				// assemble history event
+				// assemble history
 
 				const macroResult = result.toolResult as MacroToolResult
 				const input = macroResult.input
@@ -270,22 +290,12 @@ export class PageAgentCore extends EventTarget {
 
 				//
 
-				console.log(chalk.green('Step finished:'), actionName)
-				console.groupEnd()
-
 				await onAfterStep?.(this, this.history)
 
-				step++
+				console.groupEnd()
-				if (step > this.config.maxSteps) {
+
-					this.#onDone(false)
+				// finish task if done
-					const result: ExecutionResult = {
+
-						success: false,
-						data: 'Step count exceeded maximum limit',
-						history: this.history,
-					}
-					await onAfterTask?.(this, result)
-					return result
-				}
 				if (actionName === 'done') {
 					const success = action.input?.success ?? false
 					const text = action.input?.text || 'no text provided'
@@ -299,19 +309,41 @@ export class PageAgentCore extends EventTarget {
 					await onAfterTask?.(this, result)
 					return result
 				}
+			} catch (error: unknown) {
+				console.groupEnd() // to prevent nested groups
+				const isAbortError = (error as any)?.rawError?.name === 'AbortError'
+
+				console.error('Task failed', error)
+				const errorMessage = isAbortError ? 'Task stopped' : String(error)
+				this.#emitActivity({ type: 'error', message: errorMessage })
+				this.history.push({ type: 'error', message: errorMessage, rawResponse: error })
+				this.#emitHistoryChange()
+				this.#onDone(false)
+				const result: ExecutionResult = {
+					success: false,
+					data: errorMessage,
+					history: this.history,
+				}
+				await onAfterTask?.(this, result)
+				return result
 			}
-		} catch (error: unknown) {
+
-			console.error('Task failed', error)
+			step++
-			const errorMessage = String(error)
+			if (step > this.config.maxSteps) {
-			this.#emitActivity({ type: 'error', message: errorMessage })
+				const errorMessage = 'Step count exceeded maximum limit'
-			this.#onDone(false)
+				this.history.push({ type: 'error', message: errorMessage })
-			const result: ExecutionResult = {
+				this.#emitHistoryChange()
-				success: false,
+				this.#onDone(false)
-				data: errorMessage,
+				const result: ExecutionResult = {
-				history: this.history,
+					success: false,
+					data: errorMessage,
+					history: this.history,
+				}
+				await onAfterTask?.(this, result)
+				return result
 			}
-			await onAfterTask?.(this, result)
+
-			return result
+			await waitFor(0.4) // @TODO: configurable
 		}
 	}
 
@@ -328,29 +360,27 @@ export class PageAgentCore extends EventTarget {
 		const tools = this.tools
 
 		const actionSchemas = Array.from(tools.entries()).map(([toolName, tool]) => {
-			return zod.object({ [toolName]: tool.inputSchema }).describe(tool.description)
+			return z.object({ [toolName]: tool.inputSchema }).describe(tool.description)
 		})
 
-		const actionSchema = zod.union(
+		const actionSchema = z.union(actionSchemas as unknown as [z.ZodType, z.ZodType, ...z.ZodType[]])
-			actionSchemas as unknown as [zod.ZodType, zod.ZodType, ...zod.ZodType[]]
-		)
 
-		const macroToolSchema = zod.object({
+		const macroToolSchema = z.object({
-			// thinking: zod.string().optional(),
+			// thinking: z.string().optional(),
-			evaluation_previous_goal: zod.string().optional(),
+			evaluation_previous_goal: z.string().optional(),
-			memory: zod.string().optional(),
+			memory: z.string().optional(),
-			next_goal: zod.string().optional(),
+			next_goal: z.string().optional(),
 			action: actionSchema,
 		})
 
 		return {
-			description: 'You MUST call this tool every step. Outputs your reflections and next action.',
+			description: 'You MUST call this tool every step!',
-			inputSchema: macroToolSchema as zod.ZodType<MacroToolInput>,
+			inputSchema: macroToolSchema as z.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)
+				console.log(chalk.blue.bold('MacroTool input'), input)
 				const action = input.action
 
 				const toolName = Object.keys(action)[0]
@@ -371,7 +401,7 @@ export class PageAgentCore extends EventTarget {
 
 				// Find the corresponding tool
 				const tool = tools.get(toolName)
-				assert(tool, `Tool ${toolName} not found. (@note should have been caught before this!!!)`)
+				assert(tool, `Tool ${toolName} not found`)
 
 				console.log(chalk.blue.bold(`Executing tool: ${toolName}`), toolInput)
 
@@ -395,9 +425,11 @@ export class PageAgentCore extends EventTarget {
 					duration,
 				})
 
-				// Reset wait time for non-wait tools
+				// counting wait time
-				if (toolName !== 'wait') {
+				if (toolName === 'wait') {
-					this.states.totalWaitTime = 0
+					this.#states.totalWaitTime += toolInput?.seconds || 0
+				} else {
+					this.#states.totalWaitTime = 0
 				}
 
 				// Return structured result
@@ -427,17 +459,16 @@ export class PageAgentCore extends EventTarget {
 	}
 
 	/**
-	 * Get instructions from config and format as XML block
+	 * Get instructions from config
 	 */
 	async #getInstructions(): Promise<string> {
-		const { instructions } = this.config
+		const { instructions, experimentalLlmsTxt } = this.config
-		if (!instructions) return ''
 
-		const systemInstructions = instructions.system?.trim()
+		const systemInstructions = instructions?.system?.trim()
-		const url = await this.pageController.getCurrentUrl()
 		let pageInstructions: string | undefined
 
-		if (instructions.getPageInstructions) {
+		const url = this.#states.browserState?.url || ''
+		if (instructions?.getPageInstructions && url) {
 			try {
 				pageInstructions = instructions.getPageInstructions(url)?.trim()
 			} catch (error) {
@@ -447,7 +478,10 @@ export class PageAgentCore extends EventTarget {
 				)
 			}
 		}
-		if (!systemInstructions && !pageInstructions) return ''
+
+		const llmsTxt = experimentalLlmsTxt && url ? await fetchLlmsTxt(url) : undefined
+
+		if (!systemInstructions && !pageInstructions && !llmsTxt) return ''
 
 		let result = '<instructions>\n'
 
@@ -459,29 +493,38 @@ export class PageAgentCore extends EventTarget {
 			result += `<page_instructions>\n${pageInstructions}\n</page_instructions>\n`
 		}
 
+		if (llmsTxt) {
+			result += `<llms_txt>\n${llmsTxt}\n</llms_txt>\n`
+		}
+
 		result += '</instructions>\n\n'
 
 		return result
 	}
 
 	/**
-	 * Generate observations before each step
+	 * Generate system observations before each step
-	 * - URL change detection
-	 * - Too many steps warning
 	 * @todo loop detection
 	 * @todo console error
 	 */
-	async #generateObservations(stepCount: number): Promise<void> {
+	async #handleObservations(step: number): Promise<void> {
+		// Accumulated wait time warning
+		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.`
+			)
+		}
+
 		// Detect URL change
-		const currentURL = await this.pageController.getCurrentUrl()
+		const currentURL = this.#states.browserState?.url || ''
-		if (currentURL !== this.states.lastURL) {
+		if (currentURL !== this.#states.lastURL) {
 			this.pushObservation(`Page navigated to → ${currentURL}`)
-			this.states.lastURL = currentURL
+			this.#states.lastURL = currentURL
 			await waitFor(0.5) // wait for page to stabilize
 		}
 
-		// Warn about remaining steps
+		// Remaining steps warning
-		const remaining = this.config.maxSteps - stepCount
+		const remaining = this.config.maxSteps - step
 		if (remaining === 5) {
 			this.pushObservation(
 				`⚠️ Only ${remaining} steps remaining. Consider wrapping up or calling done with partial results.`
@@ -491,12 +534,25 @@ export class PageAgentCore extends EventTarget {
 				`⚠️ Critical: Only ${remaining} steps left! You must finish the task or call done immediately.`
 			)
 		}
+
+		// Push observations to history and emit
+		if (this.#observations.length > 0) {
+			for (const content of this.#observations) {
+				this.history.push({ type: 'observation', content })
+				console.log(chalk.cyan('Observation:'), content)
+			}
+			this.#observations = []
+			this.#emitHistoryChange()
+		}
 	}
 
 	async #assembleUserPrompt(): Promise<string> {
+		const browserState = this.#states.browserState!
+
 		let prompt = ''
 
 		// <instructions> (optional)
+
 		prompt += await this.#getInstructions()
 
 		// <agent_state>
@@ -506,38 +562,36 @@ export class PageAgentCore extends EventTarget {
 
 		const stepCount = this.history.filter((e) => e.type === 'step').length
 
-		prompt += `<agent_state>
+		prompt += '<agent_state>\n'
-			<user_request>
+		prompt += '<user_request>\n'
-			${this.task}
+		prompt += `${this.task}\n`
-			</user_request>
+		prompt += '</user_request>\n'
-			<step_info>
+		prompt += '<step_info>\n'
-			Step ${stepCount + 1} of ${this.config.maxSteps} max possible steps
+		prompt += `Step ${stepCount + 1} of ${this.config.maxSteps} max possible steps\n`
-			Current date and time: ${new Date().toLocaleString()}
+		prompt += `Current time: ${new Date().toLocaleString()}\n`
-			</step_info>
+		prompt += '</step_info>\n'
-			</agent_state>
+		prompt += '</agent_state>\n\n'
-		`
 
 		// <agent_history>
 		//  - <step_N> for steps
 		//  - <sys> for observations and system messages
 
-		prompt += '\n<agent_history>\n'
+		prompt += '<agent_history>\n'
 
 		let stepIndex = 0
 		for (const event of this.history) {
 			if (event.type === 'step') {
 				stepIndex++
-				prompt += `<step_${stepIndex}>
+				prompt += `<step_${stepIndex}>\n`
-				Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}
+				prompt += `Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}\n`
-				Memory: ${event.reflection.memory}
+				prompt += `Memory: ${event.reflection.memory}\n`
-				Next Goal: ${event.reflection.next_goal}
+				prompt += `Next Goal: ${event.reflection.next_goal}\n`
-				Action Results: ${event.action.output}
+				prompt += `Action Results: ${event.action.output}\n`
-				</step_${stepIndex}>
+				prompt += `</step_${stepIndex}>\n`
-			`
 			} else if (event.type === 'observation') {
 				prompt += `<sys>${event.content}</sys>\n`
 			} else if (event.type === 'user_takeover') {
-				prompt += `<sys>User took over control and made changes to the page.</sys>\n`
+				prompt += `<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
@@ -548,9 +602,18 @@ export class PageAgentCore extends EventTarget {
 
 		// <browser_state>
 
-		prompt += await this.#getBrowserState()
+		let pageContent = browserState.content
+		if (this.config.transformPageContent) {
+			pageContent = await this.config.transformPageContent(pageContent)
+		}
 
-		return trimLines(prompt)
+		prompt += '<browser_state>\n'
+		prompt += browserState.header + '\n'
+		prompt += pageContent + '\n'
+		prompt += browserState.footer + '\n\n'
+		prompt += '</browser_state>\n\n'
+
+		return prompt
 	}
 
 	#onDone(success = true) {
@@ -560,25 +623,9 @@ export class PageAgentCore extends EventTarget {
 		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>
-			${state.header}
-			${content}
-			${state.footer}
-			
-			</browser_state>
-		`)
-	}
-
 	dispose() {
 		console.log('Disposing PageAgent...')
+		this.disposed = true
 		this.pageController.dispose()
 		// this.history = []
 		this.#abortController.abort()

packages/core/src/config/constants.ts

@@ -1 +0,0 @@
-export const DEFAULT_MAX_STEPS = 20

packages/core/src/config/index.ts

@@ -1,152 +0,0 @@
-import type { LLMConfig } from '@page-agent/llms'
-import type { PageControllerConfig } from '@page-agent/page-controller'
-
-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
-
-	/**
-	 * Maximum number of steps the agent can take per task.
-	 * @default 20
-	 */
-	maxSteps?: number
-
-	/**
-	 * Custom tools to extend PageAgent capabilities
-	 * @experimental
-	 * @note You can also override or remove internal tools by using the same name.
-	 * @see PageAgentTool
-	 *
-	 * @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>
-
-	/**
-	 * Instructions to guide the agent's behavior
-	 */
-	instructions?: {
-		/**
-		 * Global system-level instructions, applied to all tasks
-		 */
-		system?: string
-
-		/**
-		 * Dynamic page-level instructions callback
-		 * Called before each step to get instructions for the current page
-		 * @param url - Current page URL (window.location.href)
-		 * @returns Instructions string, or undefined/null to skip
-		 */
-		getPageInstructions?: (url: string) => string | undefined | null
-	}
-
-	/**
-	 * Lifecycle hooks for task execution.
-	 * @experimental API may change in future versions.
-	 *
-	 * All hooks receive the agent instance as first parameter.
-	 */
-
-	/**
-	 * Called before each step execution.
-	 * @experimental
-	 * @param agent - The PageAgentCore instance
-	 * @param stepCount - Current step number (0-indexed)
-	 */
-	onBeforeStep?: (agent: PageAgentCore, stepCount: number) => Promise<void> | void
-
-	/**
-	 * Called after each step execution.
-	 * @experimental
-	 * @param agent - The PageAgentCore instance
-	 * @param history - Current history of events
-	 */
-	onAfterStep?: (agent: PageAgentCore, history: HistoricalEvent[]) => Promise<void> | void
-
-	/**
-	 * Called before task execution starts.
-	 * @experimental
-	 * @param agent - The PageAgentCore instance
-	 */
-	onBeforeTask?: (agent: PageAgentCore) => Promise<void> | void
-
-	/**
-	 * Called after task execution completes (success or failure).
-	 * @experimental
-	 * @param agent - The PageAgentCore instance
-	 * @param result - The execution result
-	 */
-	onAfterTask?: (agent: PageAgentCore, result: ExecutionResult) => Promise<void> | void
-
-	/**
-	 * Called when the agent is disposed.
-	 * @experimental
-	 * @note This hook can block the disposal process if it's async.
-	 * @param agent - The PageAgentCore instance
-	 * @param reason - Optional reason for disposal
-	 */
-	onDispose?: (agent: PageAgentCore, 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
-
-	/**
-	 * 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
-
-	/**
-	 * Completely override the default system prompt.
-	 * @experimental Use with caution - incorrect prompts may break agent behavior.
-	 */
-	customSystemPrompt?: string
-}
-
-export type PageAgentConfig = LLMConfig & AgentConfig & PageControllerConfig

packages/core/src/prompts/system_prompt.md

@@ -128,7 +128,6 @@ Exhibit the following reasoning patterns to successfully achieve the <user_reque
 Here are examples of good output patterns. Use them as reference but never copy them directly.
 
 <evaluation_examples>
-- Positive Examples:
 "evaluation_previous_goal": "Successfully navigated to the product page and found the target information. Verdict: Success"
 "evaluation_previous_goal": "Clicked the login button and user authentication form appeared. Verdict: Success"
 </evaluation_examples>
@@ -139,7 +138,6 @@ Here are examples of good output patterns. Use them as reference but never copy
 
 <next_goal_examples>
 "next_goal": "Click on the 'Add to Cart' button to proceed with the purchase flow."
-"next_goal": "Extract details from the first item on the page."
 </next_goal_examples>
 </examples>
 

packages/core/src/tools/index.ts

@@ -2,7 +2,7 @@
  * Internal tools for PageAgent.
  * @note Adapted from browser-use
  */
-import zod, { type z } from 'zod'
+import * as z from 'zod'
 
 import type { PageAgentCore } from '../PageAgentCore'
 import { waitFor } from '../utils'
@@ -31,14 +31,13 @@ tools.set(
 	'done',
 	tool({
 		description:
-			'Complete task - provide a summary of results for the user. Set success=True if task completed successfully, false otherwise. Text should be your response to the user summarizing results.',
+			'Complete task. Text is your final response to the user — keep it concise unless the user explicitly asks for detail.',
-		inputSchema: zod.object({
+		inputSchema: z.object({
-			text: zod.string(),
+			text: z.string(),
-			success: zod.boolean().default(true),
+			success: z.boolean().default(true),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			// @note main loop will handle this one
-			// this.onDone(input.text, input.success)
 			return Promise.resolve('Task completed')
 		},
 	})
@@ -47,25 +46,17 @@ tools.set(
 tools.set(
 	'wait',
 	tool({
-		description:
+		description: 'Wait for x seconds. Can be used to wait until the page or data is fully loaded.',
-			'Wait for x seconds. default 1s (max 10 seconds, min 1 second). This can be used to wait until the page or data is fully loaded.',
+		inputSchema: z.object({
-		inputSchema: zod.object({
+			seconds: z.number().min(1).max(10).default(1),
-			seconds: zod.number().min(1).max(10).default(1),
 		}),
 		execute: async function (this: PageAgentCore, input) {
+			// try to subtract LLM calling time from the actual wait time
 			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.`
 		},
 	})
@@ -76,8 +67,8 @@ tools.set(
 	tool({
 		description:
 			'Ask the user a question and wait for their answer. Use this if you need more information or clarification.',
-		inputSchema: zod.object({
+		inputSchema: z.object({
-			question: zod.string(),
+			question: z.string(),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			if (!this.onAskUser) {
@@ -93,8 +84,8 @@ tools.set(
 	'click_element_by_index',
 	tool({
 		description: 'Click element by index',
-		inputSchema: zod.object({
+		inputSchema: z.object({
-			index: zod.int().min(0),
+			index: z.int().min(0),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.clickElement(input.index)
@@ -106,10 +97,10 @@ tools.set(
 tools.set(
 	'input_text',
 	tool({
-		description: 'Click and input text into a input interactive element',
+		description: 'Click and type text into an interactive input element',
-		inputSchema: zod.object({
+		inputSchema: z.object({
-			index: zod.int().min(0),
+			index: z.int().min(0),
-			text: zod.string(),
+			text: z.string(),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.inputText(input.index, input.text)
@@ -123,9 +114,9 @@ tools.set(
 	tool({
 		description:
 			'Select dropdown option for interactive element index by the text of the option you want to select',
-		inputSchema: zod.object({
+		inputSchema: z.object({
-			index: zod.int().min(0),
+			index: z.int().min(0),
-			text: zod.string(),
+			text: z.string(),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.selectOption(input.index, input.text)
@@ -140,13 +131,12 @@ tools.set(
 tools.set(
 	'scroll',
 	tool({
-		description:
+		description: 'Scroll the page vertically. Use index for scroll elements (dropdowns/custom UI).',
-			'Scroll the page by specified number of pages (set down=True to scroll down, down=False to scroll up, num_pages=number of pages to scroll like 0.5 for half page, 1.0 for one page, etc.). Optional index parameter to scroll within a specific element or its scroll container (works well for dropdowns and custom UI components). Optional pixels parameter to scroll by a specific number of pixels instead of pages.',
+		inputSchema: z.object({
-		inputSchema: zod.object({
+			down: z.boolean().default(true),
-			down: zod.boolean().default(true),
+			num_pages: z.number().min(0).max(10).optional().default(0.1),
-			num_pages: zod.number().min(0).max(10).optional().default(0.1),
+			pixels: z.number().int().min(0).optional(),
-			pixels: zod.number().int().min(0).optional(),
+			index: z.number().int().min(0).optional(),
-			index: zod.number().int().min(0).optional(),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.scroll({
@@ -158,15 +148,18 @@ tools.set(
 	})
 )
 
+/**
+ * @todo Tables need a dedicated parser to extract structured data. This tool is useless.
+ */
 tools.set(
 	'scroll_horizontally',
 	tool({
 		description:
-			'Scroll the page or element horizontally (set right=True to scroll right, right=False to scroll left, pixels=number of pixels to scroll). Optional index parameter to scroll within a specific element or its scroll container (works well for wide tables).',
+			'Scroll the page horizontally, or within a specific element by index. Useful for wide tables.',
-		inputSchema: zod.object({
+		inputSchema: z.object({
-			right: zod.boolean().default(true),
+			right: z.boolean().default(true),
-			pixels: zod.number().int().min(0),
+			pixels: z.number().int().min(0),
-			index: zod.number().int().min(0).optional(),
+			index: z.number().int().min(0).optional(),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.scrollHorizontally(input)
@@ -180,8 +173,8 @@ tools.set(
 	tool({
 		description:
 			'Execute JavaScript code on the current page. Supports async/await syntax. Use with caution!',
-		inputSchema: zod.object({
+		inputSchema: z.object({
-			script: zod.string(),
+			script: z.string(),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.executeJavascript(input.script)
@@ -190,8 +183,6 @@ tools.set(
 	})
 )
 
-// @todo get_dropdown_options
-// @todo select_dropdown_option
 // @todo send_keys
 // @todo upload_file
 // @todo go_back

packages/core/src/types.ts

@@ -1,3 +1,158 @@
+import type { LLMConfig } from '@page-agent/llms'
+
+// @note circular dependency but okay
+import type { PageAgentCore } from './PageAgentCore'
+import type { PageAgentTool } from './tools'
+
+/** Supported UI languages */
+export type SupportedLanguage = 'en-US' | 'zh-CN'
+
+export interface AgentConfig extends LLMConfig {
+	language?: SupportedLanguage
+
+	/**
+	 * Maximum number of steps the agent can take per task.
+	 * @default 20
+	 */
+	maxSteps?: number
+
+	/**
+	 * Custom tools to extend PageAgent capabilities
+	 * @experimental
+	 * @note You can also override or remove internal tools by using the same name.
+	 * @see PageAgentTool
+	 *
+	 * @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>
+
+	/**
+	 * Instructions to guide the agent's behavior
+	 */
+	instructions?: {
+		/**
+		 * Global system-level instructions, applied to all tasks
+		 */
+		system?: string
+
+		/**
+		 * Dynamic page-level instructions callback
+		 * Called before each step to get instructions for the current page
+		 * @param url - Current page URL (window.location.href)
+		 * @returns Instructions string, or undefined/null to skip
+		 */
+		getPageInstructions?: (url: string) => string | undefined | null
+	}
+
+	/**
+	 * Lifecycle hooks for task execution.
+	 * @experimental API may change in future versions.
+	 *
+	 * All hooks receive the agent instance as first parameter.
+	 */
+
+	/**
+	 * Called before each step execution.
+	 * @experimental
+	 * @param agent - The PageAgentCore instance
+	 * @param stepCount - Current step number (0-indexed)
+	 */
+	onBeforeStep?: (agent: PageAgentCore, stepCount: number) => Promise<void> | void
+
+	/**
+	 * Called after each step execution.
+	 * @experimental
+	 * @param agent - The PageAgentCore instance
+	 * @param history - Current history of events
+	 */
+	onAfterStep?: (agent: PageAgentCore, history: HistoricalEvent[]) => Promise<void> | void
+
+	/**
+	 * Called before task execution starts.
+	 * @experimental
+	 * @param agent - The PageAgentCore instance
+	 */
+	onBeforeTask?: (agent: PageAgentCore) => Promise<void> | void
+
+	/**
+	 * Called after task execution completes (success or failure).
+	 * @experimental
+	 * @param agent - The PageAgentCore instance
+	 * @param result - The execution result
+	 */
+	onAfterTask?: (agent: PageAgentCore, result: ExecutionResult) => Promise<void> | void
+
+	/**
+	 * Called when the agent is disposed.
+	 * @experimental
+	 * @note This hook can block the disposal process if it's async.
+	 * @param agent - The PageAgentCore instance
+	 * @param reason - Optional reason for disposal
+	 */
+	onDispose?: (agent: PageAgentCore, 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
+
+	/**
+	 * @experimental
+	 * Fetch /llms.txt from current site origin and include as context.
+	 * Only fetched once per origin per task.
+	 * @default false
+	 */
+	experimentalLlmsTxt?: 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
+
+	/**
+	 * Completely override the default system prompt.
+	 * @experimental Use with caution - incorrect prompts may break agent behavior.
+	 */
+	customSystemPrompt?: string
+}
+
 /**
  * Agent reflection state - the reflection-before-action model
  *

packages/core/src/utils/assert.ts

@@ -1,17 +0,0 @@
-import chalk from 'chalk'
-
-/**
- * Simple assertion function that throws an error if the condition is falsy
- * @param condition - The condition to assert
- * @param message - Optional error message
- * @throws Error if condition is falsy
- */
-export function assert(condition: unknown, message?: string, silent?: boolean): asserts condition {
-	if (!condition) {
-		const errorMessage = message ?? 'Assertion failed'
-
-		if (!silent) console.error(chalk.red(`❌ assert: ${errorMessage}`))
-
-		throw new Error(errorMessage)
-	}
-}

packages/core/src/utils/autoFixer.ts

@@ -1,4 +1,8 @@
+import { InvokeError, InvokeErrorType } from '@page-agent/llms'
 import chalk from 'chalk'
+import * as z from 'zod'
+
+import type { PageAgentTool } from '../tools'
 
 /**
  * Normalize LLM response and fix common format issues.
@@ -9,9 +13,10 @@ import chalk from 'chalk'
  * - Arguments wrapped as double JSON string
  * - Nested function call format
  * - Missing action field (fallback to wait)
+ * - Primitive action input for single-field tools (e.g. `{"click_element_by_index": 2}`)
  * - etc.
  */
-export function normalizeResponse(response: any): any {
+export function normalizeResponse(response: any, tools?: Map<string, PageAgentTool>): any {
 	let resolvedArguments = null as any
 
 	const choice = (response as { choices?: Choice[] }).choices?.[0]
@@ -78,6 +83,11 @@ export function normalizeResponse(response: any): any {
 		resolvedArguments.action = safeJsonParse(resolvedArguments.action)
 	}
 
+	// validate and fix action input using tool schemas
+	if (resolvedArguments.action && tools) {
+		resolvedArguments.action = validateAction(resolvedArguments.action, tools)
+	}
+
 	// fix incomplete formats
 	if (!resolvedArguments.action) {
 		console.log(chalk.yellow(`[normalizeResponse] #5: fixing tool_call`))
@@ -108,6 +118,55 @@ export function normalizeResponse(response: any): any {
 	}
 }
 
+/**
+ * Validate action against tool schemas. Provides clear error messages
+ * instead of letting the union schema produce unreadable errors.
+ *
+ * Also coerces primitive inputs for single-field tools:
+ * e.g. `{"click_element_by_index": 2}` → `{"click_element_by_index": {"index": 2}}`
+ */
+function validateAction(action: any, tools: Map<string, PageAgentTool>): any {
+	if (typeof action !== 'object' || action === null) return action
+
+	const toolName = Object.keys(action)[0]
+	if (!toolName) return action
+
+	const tool = tools.get(toolName)
+	if (!tool) {
+		const available = Array.from(tools.keys()).join(', ')
+		throw new InvokeError(
+			InvokeErrorType.INVALID_TOOL_ARGS,
+			`Unknown action "${toolName}". Available: ${available}`
+		)
+	}
+
+	let value = action[toolName]
+	const schema = tool.inputSchema
+
+	// coerce primitive input for single-field tools
+	if (schema instanceof z.ZodObject && value !== null && typeof value !== 'object') {
+		const requiredKey = Object.keys(schema.shape).find(
+			(k) => !(schema.shape as Record<string, z.ZodType>)[k].safeParse(undefined).success
+		)
+		if (requiredKey) {
+			console.log(
+				chalk.yellow(`[normalizeResponse] coercing primitive action input for "${toolName}"`)
+			)
+			value = { [requiredKey]: value }
+		}
+	}
+
+	const result = schema.safeParse(value)
+	if (!result.success) {
+		throw new InvokeError(
+			InvokeErrorType.INVALID_TOOL_ARGS,
+			`Invalid input for action "${toolName}": ${z.prettifyError(result.error)}`
+		)
+	}
+
+	return { [toolName]: result.data }
+}
+
 /**
  * Safely parse JSON, return original input if not json.
  */

packages/core/src/utils/index.ts

@@ -1,27 +1,7 @@
+import chalk from 'chalk'
+
 export { normalizeResponse } from './autoFixer'
 
-/**
- * Wait until condition becomes true
- * @returns Returns when condition becomes true, throws otherwise
- * @param timeout Timeout in milliseconds, default 0 means no timeout, throws error on timeout
- */
-export async function waitUntil(check: () => boolean, timeout = 60 * 60_1000): Promise<boolean> {
-	if (check()) return true
-
-	return new Promise((resolve, reject) => {
-		const start = Date.now()
-		const interval = setInterval(() => {
-			if (check()) {
-				clearInterval(interval)
-				resolve(true)
-			} else if (Date.now() - start > timeout) {
-				clearInterval(interval)
-				reject(new Error('Timeout waiting for condition to become true'))
-			}
-		}, 100)
-	})
-}
-
 export async function waitFor(seconds: number): Promise<void> {
 	await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
 }
@@ -37,15 +17,6 @@ export function truncate(text: string, maxLength: number): string {
 
 //
 
-export function trimLines(text: string): string {
-	return text
-		.split('\n')
-		.map((line) => line.trim())
-		.join('\n')
-}
-
-//
-
 export function randomID(existingIDs?: string[]): string {
 	let id = Math.random().toString(36).substring(2, 11)
 
@@ -85,3 +56,44 @@ export function uid() {
 	ids.push(id)
 	return id
 }
+
+const llmsTxtCache = new Map<string, string | null>()
+
+/** Fetch /llms.txt for a URL's origin. Cached per origin, `null` = tried and not found. */
+export async function fetchLlmsTxt(url: string): Promise<string | null> {
+	const origin = new URL(url).origin
+	if (llmsTxtCache.has(origin)) return llmsTxtCache.get(origin)!
+
+	const endpoint = `${origin}/llms.txt`
+	let result: string | null = null
+	try {
+		console.log(chalk.gray(`[llms.txt] Fetching ${endpoint}`))
+		const res = await fetch(endpoint, { signal: AbortSignal.timeout(3000) })
+		if (res.ok) {
+			result = await res.text()
+			console.log(chalk.green(`[llms.txt] Found (${result.length} chars)`))
+		} else {
+			console.log(chalk.gray(`[llms.txt] ${res.status} for ${endpoint}`))
+		}
+	} catch (e) {
+		console.log(chalk.gray(`[llms.txt] Failed for ${endpoint}`), e)
+	}
+	llmsTxtCache.set(origin, result)
+	return result
+}
+
+/**
+ * Simple assertion function that throws an error if the condition is falsy
+ * @param condition - The condition to assert
+ * @param message - Optional error message
+ * @throws Error if condition is falsy
+ */
+export function assert(condition: unknown, message?: string, silent?: boolean): asserts condition {
+	if (!condition) {
+		const errorMessage = message ?? 'Assertion failed'
+
+		if (!silent) console.error(chalk.red(`❌ assert: ${errorMessage}`))
+
+		throw new Error(errorMessage)
+	}
+}

packages/extension/PRIVACY.md

@@ -1,57 +1,5 @@
 # Privacy Policy for Page Agent Extension
 
-**Last updated:** January 2026
+This document has moved. Please see our full **[Terms of Use & Privacy](../../docs/terms-and-privacy.md)**.
 
-## Overview
+Online: https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md
-
-Page Agent Extension is a browser automation tool that uses AI to help you interact with web pages. This policy explains what data is processed and under what circumstances.
-
-## Data Processing
-
-### Local Processing
-
-The extension performs DOM analysis and automation actions **locally in your browser**. Your browsing history, passwords, and form data are not accessed or collected by the extension itself.
-
-### Data Transmission
-
-Data is transmitted to external servers **only when you initiate an automation task**. When this occurs:
-
-- Your task instructions (natural language commands)
-- Sanitized page structure (simplified DOM, excluding sensitive form values)
-
-are sent to the LLM API endpoint configured in **your settings**.
-
-**If you configure a third-party LLM provider** (e.g., OpenAI, Anthropic, or others), data is sent directly to that provider. Their privacy policies apply.
-
-**If you use our testing endpoint**, your requests are proxied to [DeepSeek](https://deepseek.com) for AI processing. Regarding this test endpoint:
-
-- This endpoint is provided for evaluation purposes only and is not recommended for production or daily use
-- We do **not** store your task content, page content, or visited URLs
-- Minimal logging (timestamps, request metadata, IP addresses) may occur for abuse prevention and service stability
-- DeepSeek's [Privacy Policy](https://cdn.deepseek.com/policies/en-US/deepseek-privacy-policy.html) applies to their processing of your requests
-
-## Data Storage
-
-- **Local storage only**: Your configuration (API endpoint, API key, model selection) is stored in your browser via `chrome.storage.local`
-- **No cloud sync**: Configuration is not synced to any external server
-- **No analytics**: The extension does not include any analytics or tracking code
-
-## Your Control
-
-- The extension is open source and can be audited by anyone
-- You choose which LLM provider to use
-- You may configure your own API endpoint at any time
-- You can clear all stored data by removing the extension
-
-## Changes to This Policy
-
-We may update this policy as the extension evolves. Significant changes will be noted in the extension's release notes.
-
-## Contact
-
-For questions about this privacy policy:
-https://github.com/alibaba/page-agent/issues
-
----
-
-Source code: https://github.com/alibaba/page-agent

packages/extension/components.json

@@ -5,7 +5,7 @@
     "tsx": true,
     "tailwind": {
         "config": "",
-        "css": "src/index.css",
+        "css": "src/assets/index.css",
         "baseColor": "neutral",
         "cssVariables": true,
         "prefix": ""
@@ -16,7 +16,7 @@
         "utils": "@/lib/utils",
         "ui": "@/components/ui",
         "lib": "@/lib",
-        "hooks": "@/hooks"
+        "hooks": "@/lib/hooks"
     },
     "registries": {
         "@magicui": "https://magicui.design/r/{name}.json"

packages/extension/docs/extension_api.md

@@ -1,12 +1,18 @@
 # Page Agent Extension API
 
-This document describes how to integrate the Page Agent browser extension into your web application.
+Integrate the Page Agent extension into your web app and trigger multi-page browser tasks from page JavaScript.
 
 ## Installation
 
 ### 1. Install the browser extension
 
-Install the Page Agent extension from the Chrome Web Store.
+Primary channel:
+
+- Chrome Web Store: https://chromewebstore.google.com/detail/page-agent-ext/akldabonmimlicnjlflnapfeklbfemhj
+
+Latest updates are often published earlier on:
+
+- GitHub Releases: https://github.com/alibaba/page-agent/releases
 
 ### 2. Install type definitions (recommended)
 
@@ -14,11 +20,19 @@ Install the Page Agent extension from the Chrome Web Store.
 npm install @page-agent/core --save-dev
 ```
 
-### 3. Set up authentication
+### 3. Authorization (Token)
 
-The extension only injects APIs when it detects a valid token in `localStorage`.
+The token allows your page JS to call the extension API (`window.PAGE_AGENT_EXT`) and execute multi-page tasks.
 
-1. Open the extension's side panel to get your authorization token
+Why token-based access is required:
+
+- The extension has broad browser permissions (page access, navigation, multi-tab control).
+- If abused, it can harm user privacy and security.
+- Users must explicitly provide the token only to applications they trust.
+
+Setup:
+
+1. Open the extension side panel and copy your auth token.
 2. Set the token in your page:
 
 ```typescript
@@ -60,36 +74,36 @@ if (await waitForExtension()) {
 
 ## Global API
 
-The extension injects the following APIs into the `window` object:
+After token match, the extension injects APIs into `window`.
 
 ### `window.PAGE_AGENT_EXT_VERSION`
 
-Extension version string (e.g., `"1.0.0"`). This is exposed separately to allow version checking before accessing the main API object.
+Extension version string (for capability checks before using the main API).
 
 ### `window.PAGE_AGENT_EXT`
 
-Main API namespace object containing:
+Main namespace object.
 
 #### `PAGE_AGENT_EXT.execute(task, config)`
 
-Execute an agent task.
+Execute one agent task.
 
-**Parameters:**
+Parameters:
 
 | Name | Type | Required | Description |
-|------|------|----------|-------------|
+| ---- | ---- | -------- | ----------- |
 | `task` | `string` | Yes | Task description |
-| `config` | `ExecuteConfig` | Yes | Execution configuration (LLM settings, options, and event callbacks) |
+| `config` | `ExecuteConfig` | Yes | LLM settings, options, and callbacks |
 
-**Returns:** `Promise<ExecutionResult>`
+Returns: `Promise<ExecutionResult>`
 
-#### `PAGE_AGENT_EXT.dispose()`
+#### `PAGE_AGENT_EXT.stop()`
 
-Stop and destroy the current running agent.
+Stop the current task.
 
 ## Types
 
-Install `@page-agent/core` for full type definitions:
+Install `@page-agent/core` for complete types:
 
 ```typescript
 import type {
@@ -104,35 +118,24 @@ export interface ExecuteConfig {
   apiKey: string
   model: string
 
-  /**
+  // Include the initial tab where page JS starts. Default: true.
-   * Whether to include the initial tab (that holds this main world script) in the task.
-   * @default true
-   */
   includeInitialTab?: boolean
 
   onStatusChange?: (status: AgentStatus) => void
   onActivity?: (activity: AgentActivity) => void
   onHistoryUpdate?: (history: HistoricalEvent[]) => void
-  onDispose?: () => void
 }
 
 export type Execute = (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
 ```
 
-### AgentStatus
+`AgentStatus`
 
 ```typescript
 type AgentStatus = 'idle' | 'running' | 'completed' | 'error'
 ```
 
-| Status | Description |
+`AgentActivity`
-|--------|-------------|
-| `idle` | Agent is idle, ready to execute |
-| `running` | Agent is executing a task |
-| `completed` | Task completed successfully |
-| `error` | Task failed with an error |
-
-### AgentActivity
 
 ```typescript
 type AgentActivity =
@@ -143,15 +146,7 @@ type AgentActivity =
   | { type: 'error'; message: string }
 ```
 
-| Type | Description |
+`HistoricalEvent`
-|------|-------------|
-| `thinking` | Agent is analyzing the page and planning |
-| `executing` | Agent is executing a tool action |
-| `executed` | Tool execution completed |
-| `retrying` | Retrying after a failure |
-| `error` | An error occurred |
-
-### HistoricalEvent
 
 ```typescript
 type HistoricalEvent =
@@ -162,7 +157,7 @@ type HistoricalEvent =
   | { type: 'error'; message: string; rawResponse?: unknown }
 ```
 
-### ExecutionResult
+`ExecutionResult`
 
 ```typescript
 interface ExecutionResult {
@@ -183,81 +178,22 @@ const result = await window.PAGE_AGENT_EXT!.execute(
     baseURL: 'https://api.openai.com/v1',
     apiKey: process.env.OPENAI_API_KEY!,
     model: 'gpt-5.2',
-  }
+    includeInitialTab: false, // Optional: exclude current tab
-)
+    onStatusChange: (status) => console.log(status),
-
+    onActivity: (activity) => console.log(activity),
-if (result.success) {
-  console.log('Task completed:', result.data)
-} else {
-  console.error('Task failed')
-}
-```
-
-### Exclude Initial Tab
-
-By default, the agent includes the initial tab (where the script runs) in the task. Set `includeInitialTab: false` to exclude it:
-
-```typescript
-const result = await window.PAGE_AGENT_EXT!.execute(
-  'Open a new tab and search for page-agent on GitHub',
-  {
-    baseURL: 'https://api.openai.com/v1',
-    apiKey: process.env.OPENAI_API_KEY!,
-    model: 'gpt-5.2',
-    includeInitialTab: false,  // Agent will open new tabs only
   }
 )
 ```
 
-### With Event Callbacks
+### Stop the Current Task
 
 ```typescript
-await window.PAGE_AGENT_EXT!.execute('Navigate to the settings page', {
+window.PAGE_AGENT_EXT!.stop()
-  baseURL: 'https://api.openai.com/v1',
-  apiKey: process.env.OPENAI_API_KEY!,
-  model: 'gpt-5.2',
-  onStatusChange: (status) => {
-    updateUI({ agentStatus: status })
-  },
-  onActivity: (activity) => {
-    switch (activity.type) {
-      case 'thinking':
-        showSpinner('Agent is thinking...')
-        break
-      case 'executing':
-        showSpinner(`Executing: ${activity.tool}`)
-        break
-      case 'executed':
-        log(`${activity.tool} completed in ${activity.duration}ms`)
-        break
-      case 'error':
-        showError(activity.message)
-        break
-    }
-  },
-  onHistoryUpdate: (history) => {
-    renderHistory(history)
-  },
-})
-```
-
-### Stop Execution
-
-```typescript
-// Start a task
-window.PAGE_AGENT_EXT!.execute('Scroll through all pages', {
-  baseURL: 'https://api.openai.com/v1',
-  apiKey: process.env.OPENAI_API_KEY!,
-  model: 'gpt-5.2',
-})
-
-// Later, stop it
-window.PAGE_AGENT_EXT!.dispose()
 ```
 
 ## Window Type Declaration
 
-If not using `@page-agent/core`, add this to your project:
+If you are not importing `@page-agent/core`, add:
 
 ```typescript
 import type {
@@ -275,7 +211,6 @@ interface ExecuteConfig {
   onStatusChange?: (status: AgentStatus) => void
   onActivity?: (activity: AgentActivity) => void
   onHistoryUpdate?: (history: HistoricalEvent[]) => void
-  onDispose?: () => void
 }
 
 declare global {
@@ -283,8 +218,8 @@ declare global {
     PAGE_AGENT_EXT_VERSION?: string
     PAGE_AGENT_EXT?: {
       version: string
-      execute: (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
+      execute: Execute
-      dispose: () => void
+      stop: () => void
     }
   }
 }

packages/extension/docs/extension_api_zh.md

@@ -1,291 +0,0 @@
-# Page Agent 浏览器插件 API
-
-本文档介绍如何在网页应用中接入 Page Agent 浏览器插件。
-
-## 安装
-
-### 1. 安装浏览器插件
-
-从 Chrome 应用商店安装 Page Agent 插件。
-
-### 2. 安装类型定义（推荐）
-
-```bash
-npm install @page-agent/core --save-dev
-```
-
-### 3. 配置认证
-
-插件在页面加载后检测 `localStorage` 中的 token，匹配时才会注入 API。
-
-1. 打开插件的侧边栏面板，获取授权 token
-2. 在页面中设置 token：
-
-```typescript
-localStorage.setItem('PageAgentExtUserAuthToken', 'your-token')
-```
-
-## 快速开始
-
-```typescript
-import type {
-  AgentActivity,
-  AgentStatus,
-  ExecutionResult,
-  HistoricalEvent,
-} from '@page-agent/core'
-
-// 等待插件注入（最多 1 秒）
-async function waitForExtension(timeout = 1000): Promise<boolean> {
-  const start = Date.now()
-  while (Date.now() - start < timeout) {
-    if (window.PAGE_AGENT_EXT) return true
-    await new Promise((r) => setTimeout(r, 100))
-  }
-  return false
-}
-
-// 使用
-if (await waitForExtension()) {
-  const result = await window.PAGE_AGENT_EXT!.execute('点击登录按钮', {
-    baseURL: 'https://api.openai.com/v1',
-    apiKey: 'your-api-key',
-    model: 'gpt-5.2',
-    onStatusChange: (status) => console.log('状态:', status),
-    onActivity: (activity) => console.log('活动:', activity),
-  })
-  console.log('结果:', result)
-}
-```
-
-## 全局 API
-
-插件在 `window` 对象上注入以下 API：
-
-### `window.PAGE_AGENT_EXT_VERSION`
-
-插件版本号字符串（例如 `"1.0.0"`）。单独暴露版本号，方便在访问主 API 对象前进行版本检查。
-
-### `window.PAGE_AGENT_EXT`
-
-主 API 命名空间对象，包含：
-
-#### `PAGE_AGENT_EXT.execute(task, config)`
-
-执行 Agent 任务。
-
-**参数：**
-
-| 名称 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `task` | `string` | 是 | 任务描述 |
-| `config` | `ExecuteConfig` | 是 | 执行配置（LLM 设置、选项和事件回调） |
-
-**返回：** `Promise<ExecutionResult>`
-
-#### `PAGE_AGENT_EXT.dispose()`
-
-停止并销毁当前运行的 Agent。
-
-## 类型定义
-
-安装 `@page-agent/core` 获取完整类型：
-
-```typescript
-import type {
-  AgentActivity,
-  AgentStatus,
-  ExecutionResult,
-  HistoricalEvent,
-} from '@page-agent/core'
-
-export interface ExecuteConfig {
-  baseURL: string
-  apiKey: string
-  model: string
-
-  /**
-   * 是否将初始标签页（运行此脚本的页面）包含在任务中。
-   * @default true
-   */
-  includeInitialTab?: boolean
-
-  onStatusChange?: (status: AgentStatus) => void
-  onActivity?: (activity: AgentActivity) => void
-  onHistoryUpdate?: (history: HistoricalEvent[]) => void
-  onDispose?: () => void
-}
-
-export type Execute = (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
-```
-
-### AgentStatus
-
-```typescript
-type AgentStatus = 'idle' | 'running' | 'completed' | 'error'
-```
-
-| 状态 | 说明 |
-|------|------|
-| `idle` | 空闲，准备执行 |
-| `running` | 正在执行任务 |
-| `completed` | 任务成功完成 |
-| `error` | 任务执行失败 |
-
-### AgentActivity
-
-```typescript
-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 }
-```
-
-| 类型 | 说明 |
-|------|------|
-| `thinking` | Agent 正在分析页面并规划 |
-| `executing` | 正在执行工具操作 |
-| `executed` | 工具执行完成 |
-| `retrying` | 失败后重试 |
-| `error` | 发生错误 |
-
-### HistoricalEvent
-
-```typescript
-type HistoricalEvent =
-  | { type: 'step'; stepIndex: number; reflection: AgentReflection; action: Action }
-  | { type: 'observation'; content: string }
-  | { type: 'user_takeover' }
-  | { type: 'retry'; message: string; attempt: number; maxAttempts: number }
-  | { type: 'error'; message: string; rawResponse?: unknown }
-```
-
-### ExecutionResult
-
-```typescript
-interface ExecutionResult {
-  success: boolean
-  data: string
-  history: HistoricalEvent[]
-}
-```
-
-## 使用示例
-
-### 基础执行
-
-```typescript
-const result = await window.PAGE_AGENT_EXT!.execute(
-  '在邮箱输入框填入 test@example.com 然后点击提交',
-  {
-    baseURL: 'https://api.openai.com/v1',
-    apiKey: process.env.OPENAI_API_KEY!,
-    model: 'gpt-5.2',
-  }
-)
-
-if (result.success) {
-  console.log('任务完成:', result.data)
-} else {
-  console.error('任务失败')
-}
-```
-
-### 排除初始标签页
-
-默认情况下，Agent 会将初始标签页（运行脚本的页面）包含在任务中。设置 `includeInitialTab: false` 可以排除它：
-
-```typescript
-const result = await window.PAGE_AGENT_EXT!.execute(
-  '打开新标签页并在 GitHub 上搜索 page-agent',
-  {
-    baseURL: 'https://api.openai.com/v1',
-    apiKey: process.env.OPENAI_API_KEY!,
-    model: 'gpt-5.2',
-    includeInitialTab: false,  // Agent 只会打开新标签页
-  }
-)
-```
-
-### 使用事件回调
-
-```typescript
-await window.PAGE_AGENT_EXT!.execute('导航到设置页面', {
-  baseURL: 'https://api.openai.com/v1',
-  apiKey: process.env.OPENAI_API_KEY!,
-  model: 'gpt-5.2',
-  onStatusChange: (status) => {
-    updateUI({ agentStatus: status })
-  },
-  onActivity: (activity) => {
-    switch (activity.type) {
-      case 'thinking':
-        showSpinner('Agent 正在思考...')
-        break
-      case 'executing':
-        showSpinner(`正在执行: ${activity.tool}`)
-        break
-      case 'executed':
-        log(`${activity.tool} 完成，耗时 ${activity.duration}ms`)
-        break
-      case 'error':
-        showError(activity.message)
-        break
-    }
-  },
-  onHistoryUpdate: (history) => {
-    renderHistory(history)
-  },
-})
-```
-
-### 停止执行
-
-```typescript
-// 启动任务
-window.PAGE_AGENT_EXT!.execute('滚动浏览所有页面', {
-  baseURL: 'https://api.openai.com/v1',
-  apiKey: process.env.OPENAI_API_KEY!,
-  model: 'gpt-5.2',
-})
-
-// 稍后停止
-window.PAGE_AGENT_EXT!.dispose()
-```
-
-## Window 类型声明
-
-如果不使用 `@page-agent/core`，可以添加以下声明：
-
-```typescript
-import type {
-  AgentActivity,
-  AgentStatus,
-  ExecutionResult,
-  HistoricalEvent,
-} from '@page-agent/core'
-
-interface ExecuteConfig {
-  baseURL: string
-  apiKey: string
-  model: string
-  includeInitialTab?: boolean
-  onStatusChange?: (status: AgentStatus) => void
-  onActivity?: (activity: AgentActivity) => void
-  onHistoryUpdate?: (history: HistoricalEvent[]) => void
-  onDispose?: () => void
-}
-
-declare global {
-  interface Window {
-    PAGE_AGENT_EXT_VERSION?: string
-    PAGE_AGENT_EXT?: {
-      version: string
-      execute: (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
-      dispose: () => void
-    }
-  }
-}
-```

packages/extension/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@page-agent/ext",
     "private": true,
-    "version": "0.1.3",
+    "version": "0.1.8",
     "type": "module",
     "scripts": {
         "dev": "wxt",
@@ -10,23 +10,6 @@
         "postinstall": "wxt prepare"
     },
     "devDependencies": {
-        "@tailwindcss/vite": "^4.1.18",
-        "@types/chrome": "^0.1.34",
-        "@types/react": "^19.2.8",
-        "@types/react-dom": "^19.2.1",
-        "@vitejs/plugin-react-swc": "^4.1.0",
-        "@wxt-dev/module-react": "^1.1.5",
-        "react": "^19.2.4",
-        "react-dom": "^19.2.4",
-        "tailwindcss": "^4.1.14",
-        "tw-animate-css": "^1.4.0",
-        "wxt": "^0.20.13"
-    },
-    "dependencies": {
-        "@page-agent/core": "1.1.1",
-        "@page-agent/llms": "1.1.1",
-        "@page-agent/page-controller": "1.1.1",
-        "@page-agent/ui": "1.1.1",
         "@radix-ui/react-hover-card": "^1.1.15",
         "@radix-ui/react-icons": "^1.3.2",
         "@radix-ui/react-label": "^2.1.8",
@@ -34,14 +17,33 @@
         "@radix-ui/react-slot": "^1.2.4",
         "@radix-ui/react-switch": "^1.2.6",
         "@radix-ui/react-tooltip": "^1.2.8",
+        "@types/chrome": "^0.1.37",
+        "@types/react": "^19.2.14",
+        "@types/react-dom": "^19.2.1",
+        "@wxt-dev/module-react": "^1.1.5",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
-        "lucide-react": "^0.563.0",
+        "idb": "^8.0.3",
-        "motion": "^12.30.0",
+        "lucide-react": "^0.576.0",
+        "motion": "^12.34.5",
         "next-themes": "^0.4.6",
+        "react": "^19.2.4",
+        "react-dom": "^19.2.4",
         "rough-notation": "^0.5.1",
-        "simple-icons": "^16.7.0",
+        "simple-icons": "^16.10.0",
         "sonner": "^2.0.7",
-        "tailwind-merge": "^3.4.0"
+        "tailwind-merge": "^3.5.0",
+        "tailwindcss": "^4.1.14",
+        "tw-animate-css": "^1.4.0",
+        "wxt": "^0.20.18"
+    },
+    "dependencies": {
+        "@page-agent/core": "1.4.3",
+        "@page-agent/llms": "1.4.3",
+        "@page-agent/page-controller": "1.4.3",
+        "@page-agent/ui": "1.4.3",
+        "ai-motion": "^0.4.8",
+        "chalk": "^5.6.2",
+        "zod": "^4.3.5"
     }
 }

packages/extension/public/_locales/en/messages.json

@@ -0,0 +1,11 @@
+{
+	"extName": {
+		"message": "Page Agent Ext"
+	},
+	"extDescription": {
+		"message": "AI-powered browser automation assistant. Control web pages with natural language."
+	},
+	"extActionTitle": {
+		"message": "Open Page Agent"
+	}
+}

packages/extension/public/_locales/zh_CN/messages.json

@@ -0,0 +1,11 @@
+{
+	"extName": {
+		"message": "Page Agent Ext"
+	},
+	"extDescription": {
+		"message": "AI 驱动的浏览器自动化助手，用自然语言控制网页。"
+	},
+	"extActionTitle": {
+		"message": "打开 Page Agent"
+	}
+}

packages/extension/src/agent/MultiPageAgent.ts

@@ -74,6 +74,11 @@ export class MultiPageAgent extends PageAgentCore {
 				})
 			},
 
+			onBeforeStep: async (agent) => {
+				// make sure the current tab is loaded before the step starts
+				await tabsController.waitUntilTabLoaded(tabsController.currentTabId!)
+			},
+
 			onDispose: () => {
 				if (heartBeatInterval) {
 					window.clearInterval(heartBeatInterval)
@@ -84,8 +89,7 @@ export class MultiPageAgent extends PageAgentCore {
 					isAgentRunning: false,
 				})
 
-				// no need to dispose tabsController and pageController
+				tabsController.dispose()
-				// as they do not keep references
 			},
 		})
 	}

packages/extension/src/agent/RemotePageController.background.ts

@@ -8,13 +8,21 @@ export function handlePageControlMessage(
 	sender: chrome.runtime.MessageSender,
 	sendResponse: (response: unknown) => void
 ): true | undefined {
+	const PREFIX = '[RemotePageController.background]'
+
+	function debug(...messages: any[]) {
+		console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
+	}
+
 	const { action, payload, targetTabId } = message
 
 	if (action === 'get_my_tab_id') {
+		debug('get_my_tab_id', sender.tab?.id)
 		sendResponse({ tabId: sender.tab?.id || null })
 		return
 	}
 
+	// proxy to content script
 	chrome.tabs
 		.sendMessage(targetTabId, {
 			type: 'PAGE_CONTROL',
@@ -25,6 +33,7 @@ export function handlePageControlMessage(
 			sendResponse(result)
 		})
 		.catch((error) => {
+			console.error(PREFIX, error)
 			sendResponse({
 				success: false,
 				error: error instanceof Error ? error.message : String(error),

packages/extension/src/agent/RemotePageController.content.ts

@@ -12,10 +12,14 @@ export function initPageController() {
 		.then((response) => {
 			return (response as { tabId: number | null }).tabId
 		})
+		.catch((error) => {
+			console.error('[RemotePageController.ContentScript]: Failed to get my tab id', error)
+			return null
+		})
 
 	function getPC(): PageController {
 		if (!pageController) {
-			pageController = new PageController({ enableMask: false })
+			pageController = new PageController({ enableMask: false, viewportExpansion: 400 })
 		}
 		return pageController
 	}

packages/extension/src/agent/RemotePageController.ts

@@ -2,13 +2,31 @@ import type { BrowserState } from '@page-agent/page-controller'
 
 import type { TabsController } from './TabsController'
 
+const PREFIX = '[RemotePageController]'
+
+function debug(...messages: any[]) {
+	console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
+}
+
+function sendMessage(message: {
+	type: 'PAGE_CONTROL'
+	action: string
+	targetTabId: number
+	payload?: any
+}): Promise<any> {
+	return chrome.runtime.sendMessage(message).catch((error) => {
+		console.error(PREFIX, message.action, error)
+		return null
+	})
+}
+
 /**
  * Agent side page controller.
  * - live in the agent env (extension page or content script)
  * - communicates with remote PageController via sw
  */
 export class RemotePageController {
-	private tabsController: TabsController
+	tabsController: TabsController
 
 	constructor(tabsController: TabsController) {
 		this.tabsController = tabsController
@@ -18,46 +36,46 @@ export class RemotePageController {
 		return this.tabsController.currentTabId
 	}
 
-	async getCurrentUrl(): Promise<string> {
+	private async getCurrentUrl(): Promise<string> {
 		if (!this.currentTabId) return ''
 		const { url } = await this.tabsController.getTabInfo(this.currentTabId)
 		return url || ''
 	}
 
-	async getCurrentTitle(): Promise<string> {
+	private async getCurrentTitle(): Promise<string> {
 		if (!this.currentTabId) return ''
 		const { title } = await this.tabsController.getTabInfo(this.currentTabId)
 		return title || ''
 	}
 
-	get currentTabTitle(): Promise<string> {
-		return this.getCurrentTitle()
-	}
-
 	async getLastUpdateTime(): Promise<number> {
 		if (!this.currentTabId) throw new Error('tabsController not initialized.')
-
+		return sendMessage({
-		return await chrome.runtime.sendMessage({
 			type: 'PAGE_CONTROL',
 			action: 'get_last_update_time',
 			targetTabId: this.currentTabId,
 		})
 	}
 
-	// getBrowserState
 	async getBrowserState(): Promise<BrowserState> {
-		let browserState = {} as BrowserState
+		if (!this.currentTabId) throw new Error('tabsController not initialized.')
 
-		if (!this.currentTabId || !isContentScriptAllowed(await this.currentTabUrl)) {
+		let browserState = {} as BrowserState
+		debug('getBrowserState', this.currentTabId)
+
+		const currentUrl = await this.getCurrentUrl()
+		const currentTitle = await this.getCurrentTitle()
+
+		if (!this.currentTabId || !isContentScriptAllowed(currentUrl)) {
 			browserState = {
-				url: await this.currentTabUrl,
+				url: currentUrl,
-				title: await this.currentTabTitle,
+				title: currentTitle,
 				header: '',
-				content: '(empty page)',
+				content: '(empty page. either current page is not readable or not loaded yet.)',
 				footer: '',
 			}
 		} else {
-			browserState = await chrome.runtime.sendMessage({
+			browserState = await sendMessage({
 				type: 'PAGE_CONTROL',
 				action: 'get_browser_state',
 				targetTabId: this.currentTabId,
@@ -67,61 +85,58 @@ export class RemotePageController {
 		const sum = await this.tabsController.summarizeTabs()
 		browserState.header = sum + '\n\n' + (browserState.header || '')
 
+		debug('getBrowserState: success', this.currentTabId, browserState)
+
 		return browserState
 	}
 
-	// updateTree
 	async updateTree(): Promise<void> {
-		if (!this.currentTabId || !isContentScriptAllowed(await this.currentTabUrl)) {
+		if (!this.currentTabId || !isContentScriptAllowed(await this.getCurrentUrl())) {
 			return
 		}
 
-		await chrome.runtime.sendMessage({
+		await sendMessage({
 			type: 'PAGE_CONTROL',
 			action: 'update_tree',
 			targetTabId: this.currentTabId,
 		})
 	}
 
-	// cleanUpHighlights
 	async cleanUpHighlights(): Promise<void> {
-		if (!this.currentTabId || !isContentScriptAllowed(await this.currentTabUrl)) {
+		if (!this.currentTabId || !isContentScriptAllowed(await this.getCurrentUrl())) {
 			return
 		}
 
-		await chrome.runtime.sendMessage({
+		await sendMessage({
 			type: 'PAGE_CONTROL',
 			action: 'clean_up_highlights',
 			targetTabId: this.currentTabId,
 		})
 	}
 
-	// clickElement
 	async clickElement(...args: any[]): Promise<DomActionReturn> {
-		return this.remoteCallDomAction('click_element', args)
+		const res = await this.remoteCallDomAction('click_element', args)
+		// @note may cause page navigation, wait for 1 second to ensure the page loading started
+		await new Promise((resolve) => setTimeout(resolve, 1000))
+		return res
 	}
 
-	// inputText
 	async inputText(...args: any[]): Promise<DomActionReturn> {
 		return this.remoteCallDomAction('input_text', args)
 	}
 
-	// selectOption
 	async selectOption(...args: any[]): Promise<DomActionReturn> {
 		return this.remoteCallDomAction('select_option', args)
 	}
 
-	// scroll
 	async scroll(...args: any[]): Promise<DomActionReturn> {
 		return this.remoteCallDomAction('scroll', args)
 	}
 
-	// scrollHorizontally
 	async scrollHorizontally(...args: any[]): Promise<DomActionReturn> {
 		return this.remoteCallDomAction('scroll_horizontally', args)
 	}
 
-	// executeJavascript
 	async executeJavascript(...args: any[]): Promise<DomActionReturn> {
 		return this.remoteCallDomAction('execute_javascript', args)
 	}
@@ -133,35 +148,26 @@ export class RemotePageController {
 	/** @note Managed by content script via storage polling. */
 	dispose(): void {}
 
-	private async preCheck() {
-		if (!this.currentTabId) {
-			return 'RemotePageController not initialized.'
-		}
-
-		if (!isContentScriptAllowed(await this.currentTabUrl)) {
-			return 'Operation not allowed on this page. Use open_new_tab to navigate to a web page first.'
-		}
-
-		return null
-	}
-
 	private async remoteCallDomAction(action: string, payload: any[]): Promise<DomActionReturn> {
-		const preCheckError = await this.preCheck()
+		if (!this.currentTabId) {
-		if (preCheckError) {
+			return { success: false, message: 'RemotePageController not initialized.' }
-			return { success: false, message: preCheckError }
 		}
 
-		return await chrome.runtime.sendMessage({
+		if (!isContentScriptAllowed(await this.getCurrentUrl())) {
+			return {
+				success: false,
+				message:
+					'Operation not allowed on this page. Use open_new_tab to navigate to a web page first.',
+			}
+		}
+
+		return sendMessage({
 			type: 'PAGE_CONTROL',
 			action: action,
 			targetTabId: this.currentTabId!,
 			payload,
 		})
 	}
-
-	private get currentTabUrl(): Promise<string> {
-		return this.getCurrentUrl()
-	}
 }
 
 interface DomActionReturn {

packages/extension/src/agent/TabsController.background.ts

@@ -3,6 +3,12 @@
  */
 import type { TabAction } from './TabsController'
 
+const PREFIX = '[TabsController.background]'
+
+function debug(...messages: any[]) {
+	console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
+}
+
 export function handleTabControlMessage(
 	message: { type: 'TAB_CONTROL'; action: TabAction; payload: any },
 	sender: chrome.runtime.MessageSender,
@@ -12,10 +18,12 @@ export function handleTabControlMessage(
 
 	switch (action as TabAction) {
 		case 'get_active_tab': {
+			debug('get_active_tab')
 			chrome.tabs
 				.query({ active: true, currentWindow: true })
 				.then((tabs) => {
 					const tabId = tabs.length > 0 ? tabs[0].id || null : null
+					debug('get_active_tab: success', tabId)
 					sendResponse({ success: true, tabId })
 				})
 				.catch((error) => {
@@ -25,11 +33,12 @@ export function handleTabControlMessage(
 		}
 
 		case 'get_tab_info': {
+			debug('get_tab_info', payload)
 			chrome.tabs
 				.get(payload.tabId)
 				.then((tab) => {
-					const result = { title: tab.title || '', url: tab.url || '' }
+					debug('get_tab_info: success', tab)
-					sendResponse(result)
+					sendResponse(tab)
 				})
 				.catch((error) => {
 					sendResponse({ error: error instanceof Error ? error.message : String(error) })
@@ -38,10 +47,11 @@ export function handleTabControlMessage(
 		}
 
 		case 'open_new_tab': {
+			debug('open_new_tab', payload)
 			chrome.tabs
 				.create({ url: payload.url, active: false })
 				.then((newTab) => {
-					// @todo: wait for tab to be fully loaded
+					debug('open_new_tab: success', newTab)
 					sendResponse({ success: true, tabId: newTab.id, windowId: newTab.windowId })
 				})
 				.catch((error) => {
@@ -51,20 +61,22 @@ export function handleTabControlMessage(
 		}
 
 		case 'create_tab_group': {
+			debug('create_tab_group', payload)
 			chrome.tabs
 				.group({ tabIds: payload.tabIds, createProperties: { windowId: payload.windowId } })
 				.then((groupId) => {
-					console.log('Created tab group', groupId)
+					debug('create_tab_group: success', groupId)
 					sendResponse({ success: true, groupId })
 				})
 				.catch((error) => {
-					console.error('Failed to create tab group', error)
+					console.error(PREFIX, 'Failed to create tab group', error)
 					sendResponse({ error: error instanceof Error ? error.message : String(error) })
 				})
 			return true // async response
 		}
 
 		case 'update_tab_group': {
+			debug('update_tab_group', payload)
 			chrome.tabGroups
 				.update(payload.groupId, payload.properties)
 				.then(() => {
@@ -77,6 +89,7 @@ export function handleTabControlMessage(
 		}
 
 		case 'add_tab_to_group': {
+			debug('add_tab_to_group', payload)
 			chrome.tabs
 				.group({ tabIds: payload.tabId, groupId: payload.groupId })
 				.then(() => {
@@ -89,6 +102,7 @@ export function handleTabControlMessage(
 		}
 
 		case 'close_tab': {
+			debug('close_tab', payload)
 			chrome.tabs
 				.remove(payload.tabId)
 				.then(() => {
@@ -105,3 +119,42 @@ export function handleTabControlMessage(
 			return
 	}
 }
+
+export function setupTabChangeEvents() {
+	console.log('[TabsController.background] setupTabChangeEvents')
+
+	chrome.tabs.onCreated.addListener((tab) => {
+		debug('onCreated', tab)
+		chrome.runtime
+			.sendMessage({ type: 'TAB_CHANGE', action: 'created', payload: { tab } })
+			.catch((error) => {
+				debug('onCreated error:', error)
+			})
+	})
+
+	chrome.tabs.onRemoved.addListener((tabId, removeInfo) => {
+		debug('onRemoved', tabId, removeInfo)
+		chrome.runtime
+			.sendMessage({
+				type: 'TAB_CHANGE',
+				action: 'removed',
+				payload: { tabId, removeInfo },
+			})
+			.catch((error) => {
+				debug('onRemoved error:', error)
+			})
+	})
+
+	chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
+		debug('onUpdated', tabId, changeInfo)
+		chrome.runtime
+			.sendMessage({
+				type: 'TAB_CHANGE',
+				action: 'updated',
+				payload: { tabId, changeInfo, tab },
+			})
+			.catch((error) => {
+				debug('onUpdated error:', error)
+			})
+	})
+}

packages/extension/src/agent/TabsController.ts

@@ -1,3 +1,20 @@
+const PREFIX = '[TabsController]'
+
+function debug(...messages: any[]) {
+	console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
+}
+
+function sendMessage(message: {
+	type: 'TAB_CONTROL'
+	action: TabAction
+	payload?: any
+}): Promise<any> {
+	return chrome.runtime.sendMessage(message).catch((error) => {
+		console.error(PREFIX, message.action, error)
+		return null
+	})
+}
+
 /**
  * Controller for managing browser tabs.
  * - live in the agent env (extension page or content script)
@@ -13,6 +30,8 @@ export class TabsController extends EventTarget {
 	private windowId: number | null = null
 
 	async init(task: string, includeInitialTab: boolean = true) {
+		debug('init', task, includeInitialTab)
+
 		this.task = task
 		this.tabs = []
 		this.currentTabId = null
@@ -20,7 +39,7 @@ export class TabsController extends EventTarget {
 		this.initialTabId = null
 		this.windowId = null
 
-		const result = await chrome.runtime.sendMessage({
+		const result = await sendMessage({
 			type: 'TAB_CONTROL',
 			action: 'get_active_tab',
 		})
@@ -33,9 +52,20 @@ export class TabsController extends EventTarget {
 
 		if (includeInitialTab) {
 			this.currentTabId = this.initialTabId
+
+			// update tab status immediately
+			const info = await sendMessage({
+				type: 'TAB_CONTROL',
+				action: 'get_tab_info',
+				payload: { tabId: this.initialTabId },
+			})
+
 			this.tabs.push({
 				id: result.tabId,
 				isInitial: true,
+				url: info.url,
+				title: info.title,
+				status: info.status,
 			})
 		}
 
@@ -70,6 +100,14 @@ export class TabsController extends EventTarget {
 						}
 					}
 				}
+			} else if (message.action === 'updated') {
+				const { tabId, tab } = message.payload as { tabId: number; tab: chrome.tabs.Tab }
+				const targetTab = this.tabs.find((t) => t.id === tabId)
+				if (targetTab) {
+					targetTab.url = tab.url
+					targetTab.title = tab.title
+					targetTab.status = tab.status
+				}
 			}
 		}
 
@@ -80,8 +118,10 @@ export class TabsController extends EventTarget {
 		})
 	}
 
-	async openNewTab(url: string): Promise<{ success: boolean; tabId: number; message: string }> {
+	async openNewTab(url: string): Promise<string> {
-		const result = await chrome.runtime.sendMessage({
+		debug('openNewTab', url)
+
+		const result = await sendMessage({
 			type: 'TAB_CONTROL',
 			action: 'open_new_tab',
 			payload: { url },
@@ -104,7 +144,7 @@ export class TabsController extends EventTarget {
 		await this.switchToTab(tabId)
 
 		if (!this.tabGroupId) {
-			const result = await chrome.runtime.sendMessage({
+			const result = await sendMessage({
 				type: 'TAB_CONTROL',
 				action: 'create_tab_group',
 				payload: { tabIds: [tabId], windowId: this.windowId },
@@ -118,7 +158,7 @@ export class TabsController extends EventTarget {
 
 			this.tabGroupId = groupId
 
-			await chrome.runtime.sendMessage({
+			await sendMessage({
 				type: 'TAB_CONTROL',
 				action: 'update_tab_group',
 				payload: {
@@ -131,57 +171,43 @@ export class TabsController extends EventTarget {
 				},
 			})
 		} else {
-			await chrome.runtime.sendMessage({
+			await sendMessage({
 				type: 'TAB_CONTROL',
 				action: 'add_tab_to_group',
 				payload: { tabId: result.tabId, groupId: this.tabGroupId },
 			})
 		}
 
-		// wait for the new tab to be fully loaded
+		await this.waitUntilTabLoaded(tabId)
-		// @todo
-		await new Promise((resolve) => setTimeout(resolve, 500))
 
-		return {
+		return `✅ Opened new tab ID ${tabId} with URL ${url}`
-			success: true,
-			tabId,
-			message: `Opened new tab ID ${tabId} with URL ${url}`,
-		}
 	}
 
-	async switchToTab(tabId: number): Promise<{ success: boolean; message: string }> {
+	async switchToTab(tabId: number): Promise<string> {
+		debug('switchToTab', tabId)
+
 		const targetTab = this.tabs.find((t) => t.id === tabId)
 		if (!targetTab) {
-			return {
+			throw new Error(`Tab ID ${tabId} not found in tab list.`)
-				success: false,
-				message: `Tab ID ${tabId} not found in tab list.`,
-			}
 		}
 
 		await this.updateCurrentTabId(tabId)
 
-		return {
+		return `✅ Switched to tab ID ${tabId}.`
-			success: true,
-			message: `Switched to tab ID ${tabId}.`,
-		}
 	}
 
-	async closeTab(tabId: number): Promise<{ success: boolean; message: string }> {
+	async closeTab(tabId: number): Promise<string> {
+		debug('closeTab', tabId)
+
 		const targetTab = this.tabs.find((t) => t.id === tabId)
 		if (!targetTab) {
-			return {
+			throw new Error(`Tab ID ${tabId} not found in tab list.`)
-				success: false,
-				message: `Tab ID ${tabId} not found in tab list.`,
-			}
 		}
 		if (targetTab.isInitial) {
-			return {
+			throw new Error(`Cannot close the initial tab ID ${tabId}.`)
-				success: false,
-				message: `Cannot close the initial tab ID ${tabId}.`,
-			}
 		}
 
-		const result = await chrome.runtime.sendMessage({
+		const result = await sendMessage({
 			type: 'TAB_CONTROL',
 			action: 'close_tab',
 			payload: { tabId },
@@ -198,29 +224,39 @@ export class TabsController extends EventTarget {
 				}
 			}
 
-			return {
+			return `✅ Closed tab ID ${tabId}.`
-				success: true,
-				message: `Closed tab ID ${tabId}.`,
-			}
 		} else {
-			return {
+			throw new Error(`Failed to close tab ID ${tabId}: ${result.error}`)
-				success: false,
-				message: `Failed to close tab ID ${tabId}: ${result.error}`,
-			}
 		}
 	}
 
 	async updateCurrentTabId(tabId: number | null) {
+		debug('updateCurrentTabId', tabId)
+
 		this.currentTabId = tabId
 		await chrome.storage.local.set({ currentTabId: tabId })
 	}
 
 	async getTabInfo(tabId: number): Promise<{ title: string; url: string }> {
-		const result = await chrome.runtime.sendMessage({
+		// use cached tab info if available
+		const tabMeta = this.tabs.find((t) => t.id === tabId)
+		if (tabMeta && tabMeta.url && tabMeta.title) {
+			return { title: tabMeta.title, url: tabMeta.url }
+		}
+
+		// otherwise, pull the latest tab info from the background script
+		debug('getTabInfo: pulling from background script', tabId)
+		const result = await sendMessage({
 			type: 'TAB_CONTROL',
 			action: 'get_tab_info',
 			payload: { tabId },
 		})
+
+		if (tabMeta) {
+			tabMeta.url = result.url
+			tabMeta.title = result.title
+		}
+
 		return result
 	}
 
@@ -239,6 +275,17 @@ export class TabsController extends EventTarget {
 		return summaries.join('\n')
 	}
 
+	async waitUntilTabLoaded(tabId: number): Promise<void> {
+		const tab = this.tabs.find((t) => t.id === tabId)
+		if (!tab) throw new Error(`Tab ID ${tabId} not found in tab list.`)
+
+		if (tab.status === 'unloaded') throw new Error(`Tab ID ${tabId} is unloaded.`)
+		if (tab.status === 'complete') return
+
+		debug('waitUntilTabLoaded', tabId)
+		await waitUntil(() => tab.status === 'complete', 4_000)
+	}
+
 	dispose() {
 		this.dispatchEvent(new Event('dispose'))
 	}
@@ -257,6 +304,9 @@ export type TabAction =
 interface TabMeta {
 	id: number
 	isInitial: boolean
+	url?: string
+	title?: string
+	status?: 'loading' | 'unloaded' | 'complete'
 }
 
 const TAB_GROUP_COLORS = [
@@ -275,3 +325,33 @@ type TabGroupColor = (typeof TAB_GROUP_COLORS)[number]
 function randomColor(): TabGroupColor {
 	return TAB_GROUP_COLORS[Math.floor(Math.random() * TAB_GROUP_COLORS.length)]
 }
+
+/**
+ * Wait until condition becomes true
+ * @returns Returns when condition becomes true, throws otherwise
+ * @param timeoutMS Timeout in milliseconds, default 1 minutes, throws error on timeout
+ * @param error Error object to reject on timeout. If not provided, will resolve with false
+ */
+export async function waitUntil(
+	check: () => boolean | Promise<boolean>,
+	timeoutMS = 60_000,
+	error?: string
+): Promise<boolean> {
+	if (await check()) return true
+
+	return new Promise((resolve, reject) => {
+		const start = Date.now()
+		const poll = async () => {
+			if (await check()) return resolve(true)
+			if (Date.now() - start > timeoutMS) {
+				if (error) {
+					return reject(new Error(error))
+				} else {
+					return resolve(false)
+				}
+			}
+			setTimeout(poll, 100)
+		}
+		setTimeout(poll, 100)
+	})
+}

packages/extension/src/agent/constants.ts

@@ -1,13 +1,30 @@
 import type { LLMConfig } from '@page-agent/llms'
 
 // Demo LLM for testing
-export const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+export const DEMO_MODEL = 'qwen3.5-plus'
-export const DEMO_BASE_URL =
+export const DEMO_BASE_URL = 'https://page-ag-testing-ohftxirgbn.cn-shanghai.fcapp.run'
-	'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
+export const DEMO_API_KEY = 'NA'
-export const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
 
 export const DEMO_CONFIG: LLMConfig = {
 	apiKey: DEMO_API_KEY,
 	baseURL: DEMO_BASE_URL,
 	model: DEMO_MODEL,
 }
+
+/** Legacy testing endpoints that should be auto-migrated to DEMO_BASE_URL */
+export const LEGACY_TESTING_ENDPOINTS = [
+	'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy',
+]
+
+export function isTestingEndpoint(url: string): boolean {
+	const normalized = url.replace(/\/+$/, '')
+	return normalized === DEMO_BASE_URL || LEGACY_TESTING_ENDPOINTS.some((ep) => normalized === ep)
+}
+
+export function migrateLegacyEndpoint(config: LLMConfig): LLMConfig {
+	const normalized = config.baseURL.replace(/\/+$/, '')
+	if (LEGACY_TESTING_ENDPOINTS.some((ep) => normalized === ep)) {
+		return { ...DEMO_CONFIG }
+	}
+	return config
+}

packages/extension/src/agent/system_prompt.md

@@ -120,7 +120,6 @@ Exhibit the following reasoning patterns to successfully achieve the <user_reque
 Here are examples of good output patterns. Use them as reference but never copy them directly.
 
 <evaluation_examples>
-- Positive Examples:
 "evaluation_previous_goal": "Successfully navigated to the product page and found the target information. Verdict: Success"
 "evaluation_previous_goal": "Clicked the login button and user authentication form appeared. Verdict: Success"
 </evaluation_examples>
@@ -131,7 +130,6 @@ Here are examples of good output patterns. Use them as reference but never copy
 
 <next_goal_examples>
 "next_goal": "Click on the 'Add to Cart' button to proceed with the purchase flow."
-"next_goal": "Extract details from the first item on the page."
 </next_goal_examples>
 </examples>
 

packages/extension/src/agent/tabTools.ts

@@ -6,14 +6,14 @@
  * - switch_to_tab: Switch to an existing tab
  * - close_tab: Close a tab (optionally switch to another)
  */
-import zod from 'zod'
+import * as z from 'zod'
 
 import type { TabsController } from './TabsController'
 
 /** Tool definition compatible with PageAgentCore customTools */
 interface TabTool {
 	description: string
-	inputSchema: zod.ZodType
+	inputSchema: z.ZodType
 	execute: (input: unknown) => Promise<string>
 }
 
@@ -26,37 +26,48 @@ export function createTabTools(tabsController: TabsController): Record<string, T
 		open_new_tab: {
 			description:
 				'Open a new browser tab with the specified URL. The new tab becomes the current tab for all subsequent page operations.',
-			inputSchema: zod.object({
+			inputSchema: z.object({
-				url: zod.string().describe('The URL to open in the new tab'),
+				url: z.string().describe('The URL to open in the new tab'),
 			}),
 			execute: async (input: unknown) => {
 				const { url } = input as { url: string }
-				const result = await tabsController.openNewTab(url)
+				try {
-				return result.message
+					return await tabsController.openNewTab(url)
+				} catch (error) {
+					return `❌ Failed: ${error instanceof Error ? error.message : String(error)}`
+				}
 			},
 		},
 
 		switch_to_tab: {
 			description:
 				'Switch to an existing tab by its ID. After switching, all page operations will target the new current tab. You can only switch to tabs in the tab list shown in browser state.',
-			inputSchema: zod.object({
+			inputSchema: z.object({
-				tab_id: zod.number().int().describe('The tab ID to switch to'),
+				tab_id: z.number().int().describe('The tab ID to switch to'),
 			}),
 			execute: async (input: unknown) => {
 				const { tab_id } = input as { tab_id: number }
-				return (await tabsController.switchToTab(tab_id)).message
+				try {
+					return await tabsController.switchToTab(tab_id)
+				} catch (error) {
+					return `❌ Failed: ${error instanceof Error ? error.message : String(error)}`
+				}
 			},
 		},
 
 		close_tab: {
 			description:
 				'Close a tab by its ID. Cannot close the initial tab. Optionally specify which tab to switch to after closing.',
-			inputSchema: zod.object({
+			inputSchema: z.object({
-				tab_id: zod.number().int().describe('The tab ID to close'),
+				tab_id: z.number().int().describe('The tab ID to close'),
 			}),
 			execute: async (input: unknown) => {
 				const { tab_id } = input as { tab_id: number }
-				return (await tabsController.closeTab(tab_id)).message
+				try {
+					return await tabsController.closeTab(tab_id)
+				} catch (error) {
+					return `❌ Failed: ${error instanceof Error ? error.message : String(error)}`
+				}
 			},
 		},
 	}

packages/extension/src/agent/useAgent.ts

@@ -1,22 +1,34 @@
 /**
  * React hook for using AgentController
  */
-import type { AgentActivity, AgentStatus, HistoricalEvent } from '@page-agent/core'
+import type {
+	AgentActivity,
+	AgentStatus,
+	HistoricalEvent,
+	SupportedLanguage,
+} from '@page-agent/core'
 import type { LLMConfig } from '@page-agent/llms'
 import { useCallback, useEffect, useRef, useState } from 'react'
 
 import { MultiPageAgent } from './MultiPageAgent'
-import { DEMO_CONFIG } from './constants'
+import { DEMO_CONFIG, migrateLegacyEndpoint } from './constants'
+
+/** Language preference: undefined means follow system */
+export type LanguagePreference = SupportedLanguage | undefined
+
+export interface ExtConfig extends LLMConfig {
+	language?: LanguagePreference
+}
 
 export interface UseAgentResult {
 	status: AgentStatus
 	history: HistoricalEvent[]
 	activity: AgentActivity | null
 	currentTask: string
-	config: LLMConfig | null
+	config: ExtConfig | null
 	execute: (task: string) => Promise<void>
 	stop: () => void
-	configure: (config: LLMConfig) => Promise<void>
+	configure: (config: ExtConfig) => Promise<void>
 }
 
 export function useAgent(): UseAgentResult {
@@ -25,16 +37,23 @@ export function useAgent(): UseAgentResult {
 	const [history, setHistory] = useState<HistoricalEvent[]>([])
 	const [activity, setActivity] = useState<AgentActivity | null>(null)
 	const [currentTask, setCurrentTask] = useState('')
-	const [config, setConfig] = useState<LLMConfig | null>(null)
+	const [config, setConfig] = useState<ExtConfig | null>(null)
 
 	useEffect(() => {
-		chrome.storage.local.get('llmConfig').then((result) => {
+		chrome.storage.local.get(['llmConfig', 'language']).then((result) => {
-			if (result.llmConfig) {
+			let llmConfig = (result.llmConfig as LLMConfig) ?? DEMO_CONFIG
-				setConfig(result.llmConfig as LLMConfig)
+			const language = (result.language as SupportedLanguage) || undefined
-			} else {
+
+			// Auto-migrate legacy testing endpoints
+			const migrated = migrateLegacyEndpoint(llmConfig)
+			if (migrated !== llmConfig) {
+				llmConfig = migrated
+				chrome.storage.local.set({ llmConfig: migrated })
+			} else if (!result.llmConfig) {
 				chrome.storage.local.set({ llmConfig: DEMO_CONFIG })
-				setConfig(DEMO_CONFIG)
 			}
+
+			setConfig({ ...llmConfig, language })
 		})
 	}, [])
 
@@ -75,7 +94,7 @@ export function useAgent(): UseAgentResult {
 
 	const execute = useCallback(async (task: string) => {
 		const agent = agentRef.current
-		console.log('Fire task:', task, agent)
+		console.log('🚀 [useAgent] start executing task:', task)
 		if (!agent) throw new Error('Agent not initialized')
 
 		setCurrentTask(task)
@@ -84,12 +103,17 @@ export function useAgent(): UseAgentResult {
 	}, [])
 
 	const stop = useCallback(() => {
-		agentRef.current?.dispose()
+		agentRef.current?.stop()
 	}, [])
 
-	const configure = useCallback(async (newConfig: LLMConfig) => {
+	const configure = useCallback(async ({ language, ...llmConfig }: ExtConfig) => {
-		await chrome.storage.local.set({ llmConfig: newConfig })
+		await chrome.storage.local.set({ llmConfig })
-		setConfig(newConfig)
+		if (language) {
+			await chrome.storage.local.set({ language })
+		} else {
+			await chrome.storage.local.remove('language')
+		}
+		setConfig({ ...llmConfig, language })
 	}, [])
 
 	return {

packages/extension/src/assets/index.css

@@ -111,6 +111,41 @@
 	--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
 	--color-sidebar-border: var(--sidebar-border);
 	--color-sidebar-ring: var(--sidebar-ring);
+	--animate-blink-cursor: blink-cursor 1.2s step-end infinite;
+	@keyframes blink-cursor {
+		0%,
+		49% {
+			opacity: 1;
+		}
+		50%,
+		100% {
+			opacity: 0;
+		}
+	}
+}
+
+@keyframes glow-a {
+	0%,
+	100% {
+		opacity: 0.45;
+		transform: scale(1);
+	}
+	50% {
+		opacity: 0;
+		transform: scale(1.1);
+	}
+}
+
+@keyframes glow-b {
+	0%,
+	100% {
+		opacity: 0;
+		transform: scale(1.1);
+	}
+	50% {
+		opacity: 0.45;
+		transform: scale(1);
+	}
 }
 
 @layer base {

packages/extension/src/components/ui/input-group.tsx

@@ -21,8 +21,9 @@ function InputGroup({ className, ...props }: React.ComponentProps<'div'>) {
 				'has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>[data-align=block-start]]:[&>input]:pb-3',
 				'has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-end]]:[&>input]:pt-3',
 
-				// Focus state.
+				// Focus state — soft multi-color glow matching ai-motion palette
-				'has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-ring/50 has-[[data-slot=input-group-control]:focus-visible]:ring-[3px]',
+				'has-[[data-slot=input-group-control]:focus-visible]:border-blue-400/60',
+				'has-[[data-slot=input-group-control]:focus-visible]:shadow-[0_0_0_1px_rgba(57,182,255,0.2),0_0_8px_rgba(57,182,255,0.15),0_0_16px_rgba(189,69,251,0.1)]',
 
 				// Error state.
 				'has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[[data-slot][aria-invalid=true]]:border-destructive dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40',

packages/extension/src/components/ui/typing-animation.tsx

@@ -0,0 +1,164 @@
+import { MotionProps, motion, useInView } from 'motion/react'
+import { useEffect, useMemo, useRef, useState } from 'react'
+
+import { cn } from '@/lib/utils'
+
+interface TypingAnimationProps extends MotionProps {
+	children?: string
+	words?: string[]
+	className?: string
+	duration?: number
+	typeSpeed?: number
+	deleteSpeed?: number
+	delay?: number
+	pauseDelay?: number
+	loop?: boolean
+	as?: React.ElementType
+	startOnView?: boolean
+	showCursor?: boolean
+	blinkCursor?: boolean
+	cursorStyle?: 'line' | 'block' | 'underscore'
+}
+
+export function TypingAnimation({
+	children,
+	words,
+	className,
+	duration = 100,
+	typeSpeed,
+	deleteSpeed,
+	delay = 0,
+	pauseDelay = 1000,
+	loop = false,
+	as: Component = 'span',
+	startOnView = true,
+	showCursor = true,
+	blinkCursor = true,
+	cursorStyle = 'line',
+	...props
+}: TypingAnimationProps) {
+	const MotionComponent = motion.create(Component, {
+		forwardMotionProps: true,
+	})
+
+	const [displayedText, setDisplayedText] = useState<string>('')
+	const [currentWordIndex, setCurrentWordIndex] = useState(0)
+	const [currentCharIndex, setCurrentCharIndex] = useState(0)
+	const [phase, setPhase] = useState<'typing' | 'pause' | 'deleting'>('typing')
+	const elementRef = useRef<HTMLElement | null>(null)
+	const isInView = useInView(elementRef as React.RefObject<Element>, {
+		amount: 0.3,
+		once: true,
+	})
+
+	const wordsToAnimate = useMemo(() => words || (children ? [children] : []), [words, children])
+	const hasMultipleWords = wordsToAnimate.length > 1
+
+	const typingSpeed = typeSpeed || duration
+	const deletingSpeed = deleteSpeed || typingSpeed / 2
+
+	const shouldStart = startOnView ? isInView : true
+
+	useEffect(() => {
+		if (!shouldStart || wordsToAnimate.length === 0) return
+
+		const timeoutDelay =
+			delay > 0 && displayedText === ''
+				? delay
+				: phase === 'typing'
+					? typingSpeed
+					: phase === 'deleting'
+						? deletingSpeed
+						: pauseDelay
+
+		const timeout = setTimeout(() => {
+			const currentWord = wordsToAnimate[currentWordIndex] || ''
+			const graphemes = Array.from(currentWord)
+
+			switch (phase) {
+				case 'typing':
+					if (currentCharIndex < graphemes.length) {
+						setDisplayedText(graphemes.slice(0, currentCharIndex + 1).join(''))
+						setCurrentCharIndex(currentCharIndex + 1)
+					} else {
+						if (hasMultipleWords || loop) {
+							const isLastWord = currentWordIndex === wordsToAnimate.length - 1
+							if (!isLastWord || loop) {
+								setPhase('pause')
+							}
+						}
+					}
+					break
+
+				case 'pause':
+					setPhase('deleting')
+					break
+
+				case 'deleting':
+					if (currentCharIndex > 0) {
+						setDisplayedText(graphemes.slice(0, currentCharIndex - 1).join(''))
+						setCurrentCharIndex(currentCharIndex - 1)
+					} else {
+						const nextIndex = (currentWordIndex + 1) % wordsToAnimate.length
+						setCurrentWordIndex(nextIndex)
+						setPhase('typing')
+					}
+					break
+			}
+		}, timeoutDelay)
+
+		return () => clearTimeout(timeout)
+	}, [
+		shouldStart,
+		phase,
+		currentCharIndex,
+		currentWordIndex,
+		displayedText,
+		wordsToAnimate,
+		hasMultipleWords,
+		loop,
+		typingSpeed,
+		deletingSpeed,
+		pauseDelay,
+		delay,
+	])
+
+	const currentWordGraphemes = Array.from(wordsToAnimate[currentWordIndex] || '')
+	const isComplete =
+		!loop &&
+		currentWordIndex === wordsToAnimate.length - 1 &&
+		currentCharIndex >= currentWordGraphemes.length &&
+		phase !== 'deleting'
+
+	const shouldShowCursor =
+		showCursor &&
+		!isComplete &&
+		(hasMultipleWords || loop || currentCharIndex < currentWordGraphemes.length)
+
+	const getCursorChar = () => {
+		switch (cursorStyle) {
+			case 'block':
+				return '▌'
+			case 'underscore':
+				return '_'
+			case 'line':
+			default:
+				return '|'
+		}
+	}
+
+	return (
+		<MotionComponent
+			ref={elementRef}
+			className={cn('leading-[5rem] tracking-[-0.02em]', className)}
+			{...props}
+		>
+			{displayedText}
+			{shouldShowCursor && (
+				<span className={cn('inline-block', blinkCursor && 'animate-blink-cursor')}>
+					{getCursorChar()}
+				</span>
+			)}
+		</MotionComponent>
+	)
+}

packages/extension/src/entrypoints/background.ts

@@ -1,24 +1,13 @@
 import { handlePageControlMessage } from '@/agent/RemotePageController.background'
-import { handleTabControlMessage } from '@/agent/TabsController.background'
+import { handleTabControlMessage, setupTabChangeEvents } from '@/agent/TabsController.background'
-
-chrome.runtime.onMessage.addListener((message, sender, sendResponse): true | undefined => {
-	if (message.type === 'TAB_CONTROL') {
-		return handleTabControlMessage(message, sender, sendResponse)
-	} else if (message.type === 'PAGE_CONTROL') {
-		return handlePageControlMessage(message, sender, sendResponse)
-	} else {
-		sendResponse({ error: 'Unknown message type' })
-		return
-	}
-})
-
-// ============================================================================
-// Extension Setup
-// ============================================================================
 
 export default defineBackground(() => {
 	console.log('[Background] Service Worker started')
 
+	// tab change events
+
+	setupTabChangeEvents()
+
 	// generate user auth token
 
 	chrome.storage.local.get('PageAgentExtUserAuthToken').then((result) => {
@@ -28,21 +17,20 @@ export default defineBackground(() => {
 		chrome.storage.local.set({ PageAgentExtUserAuthToken: userAuthToken })
 	})
 
+	// message proxy
+
+	chrome.runtime.onMessage.addListener((message, sender, sendResponse): true | undefined => {
+		if (message.type === 'TAB_CONTROL') {
+			return handleTabControlMessage(message, sender, sendResponse)
+		} else if (message.type === 'PAGE_CONTROL') {
+			return handlePageControlMessage(message, sender, sendResponse)
+		} else {
+			sendResponse({ error: 'Unknown message type' })
+			return
+		}
+	})
+
 	// setup
 
 	chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true }).catch(() => {})
-
-	// Tab change events
-
-	chrome.tabs.onCreated.addListener((tab) => {
-		chrome.runtime.sendMessage({ type: 'TAB_CHANGE', action: 'created', payload: { tab } })
-	})
-
-	chrome.tabs.onRemoved.addListener((tabId, removeInfo) => {
-		chrome.runtime.sendMessage({
-			type: 'TAB_CHANGE',
-			action: 'removed',
-			payload: { tabId, removeInfo },
-		})
-	})
 })

packages/extension/src/entrypoints/content.ts

@@ -6,7 +6,7 @@ const DEBUG_PREFIX = '[Content]'
 
 export default defineContentScript({
 	matches: ['<all_urls>'],
-	runAt: 'document_idle',
+	runAt: 'document_end',
 
 	main() {
 		console.debug(`${DEBUG_PREFIX} Loaded on ${window.location.href}`)
@@ -71,7 +71,8 @@ async function exposeAgentToPage() {
 				try {
 					const { task, config } = payload
 
-					// create when used
+					// Dispose old instance before creating new one
+					multiPageAgent?.dispose()
 
 					multiPageAgent = new MultiPageAgent(config)
 
@@ -116,17 +117,6 @@ async function exposeAgentToPage() {
 						)
 					})
 
-					multiPageAgent.addEventListener('dispose', () => {
-						window.postMessage(
-							{
-								channel: 'PAGE_AGENT_EXT_RESPONSE',
-								id,
-								action: 'dispose_event',
-							},
-							'*'
-						)
-					})
-
 					// result
 
 					const result = await multiPageAgent.execute(task)
@@ -155,9 +145,8 @@ async function exposeAgentToPage() {
 				break
 			}
 
-			case 'dispose': {
+			case 'stop': {
-				// @note stop ongoing processes but can still be re-used later
+				multiPageAgent?.stop()
-				multiPageAgent?.dispose()
 				break
 			}
 

packages/extension/src/entrypoints/main-world.ts

@@ -16,7 +16,6 @@ export interface ExecuteConfig {
 	onStatusChange?: (status: AgentStatus) => void
 	onActivity?: (activity: AgentActivity) => void
 	onHistoryUpdate?: (history: HistoricalEvent[]) => void
-	onDispose?: () => void
 }
 
 export default defineUnlistedScript(() => {
@@ -60,12 +59,6 @@ export default defineUnlistedScript(() => {
 					return
 				}
 
-				if (data.action === 'dispose_event' && config.onDispose) {
-					config.onDispose()
-					window.removeEventListener('message', handleMessage)
-					return
-				}
-
 				if (data.action !== 'execute_result') return
 
 				// execute_result
@@ -104,14 +97,14 @@ export default defineUnlistedScript(() => {
 		return promise
 	}
 
-	const dispose = () => {
+	const stop = () => {
 		const id = getId()
 
 		window.postMessage(
 			{
 				channel: 'PAGE_AGENT_EXT_REQUEST',
 				id,
-				action: 'dispose',
+				action: 'stop',
 			},
 			'*'
 		)
@@ -121,6 +114,6 @@ export default defineUnlistedScript(() => {
 	;(window as any).PAGE_AGENT_EXT = {
 		version: __EXT_VERSION__,
 		execute,
-		dispose,
+		stop,
 	}
 })

packages/extension/src/entrypoints/sidepanel/App.tsx

@@ -1,4 +1,4 @@
-import { Send, Settings, Square } from 'lucide-react'
+import { History, Send, Settings, Square } from 'lucide-react'
 import { useCallback, useEffect, useRef, useState } from 'react'
 
 import { Button } from '@/components/ui/button'
@@ -8,20 +8,47 @@ import {
 	InputGroupButton,
 	InputGroupTextarea,
 } from '@/components/ui/input-group'
+import { saveSession } from '@/lib/db'
 
 import { useAgent } from '../../agent/useAgent'
 import { ConfigPanel } from './components/ConfigPanel'
+import { HistoryDetail } from './components/HistoryDetail'
+import { HistoryList } from './components/HistoryList'
 import { ActivityCard, EventCard } from './components/cards'
-import { EmptyState, Logo, StatusDot } from './components/misc'
+import { EmptyState, Logo, MotionOverlay, StatusDot } from './components/misc'
+
+type View =
+	| { name: 'chat' }
+	| { name: 'config' }
+	| { name: 'history' }
+	| { name: 'history-detail'; sessionId: string }
 
 export default function App() {
-	const [showConfig, setShowConfig] = useState(false)
+	const [view, setView] = useState<View>({ name: 'chat' })
 	const [inputValue, setInputValue] = useState('')
 	const historyRef = useRef<HTMLDivElement>(null)
 	const textareaRef = useRef<HTMLTextAreaElement>(null)
 
 	const { status, history, activity, currentTask, config, execute, stop, configure } = useAgent()
 
+	// Persist session when task finishes
+	const prevStatusRef = useRef(status)
+	useEffect(() => {
+		const prev = prevStatusRef.current
+		prevStatusRef.current = status
+
+		if (
+			prev === 'running' &&
+			(status === 'completed' || status === 'error') &&
+			history.length > 0 &&
+			currentTask
+		) {
+			saveSession({ task: currentTask, history, status }).catch((err) =>
+				console.error('[SidePanel] Failed to save session:', err)
+			)
+		}
+	}, [status, history, currentTask])
+
 	// Auto-scroll to bottom on new events
 	useEffect(() => {
 		if (historyRef.current) {
@@ -56,36 +83,62 @@ export default function App() {
 		}
 	}
 
-	if (showConfig) {
+	// --- View routing ---
+
+	if (view.name === 'config') {
 		return (
 			<ConfigPanel
 				config={config}
 				onSave={async (newConfig) => {
 					await configure(newConfig)
-					setShowConfig(false)
+					setView({ name: 'chat' })
 				}}
-				onClose={() => setShowConfig(false)}
+				onClose={() => setView({ name: 'chat' })}
 			/>
 		)
 	}
 
+	if (view.name === 'history') {
+		return (
+			<HistoryList
+				onSelect={(id) => setView({ name: 'history-detail', sessionId: id })}
+				onBack={() => setView({ name: 'chat' })}
+			/>
+		)
+	}
+
+	if (view.name === 'history-detail') {
+		return <HistoryDetail sessionId={view.sessionId} onBack={() => setView({ name: 'history' })} />
+	}
+
+	// --- Chat view ---
+
 	const isRunning = status === 'running'
 	const showEmptyState = !currentTask && history.length === 0 && !isRunning
 
 	return (
-		<div className="flex flex-col h-screen bg-background">
+		<div className="relative flex flex-col h-screen bg-background">
+			<MotionOverlay active={isRunning} />
 			{/* Header */}
 			<header className="flex items-center justify-between border-b px-3 py-2">
 				<div className="flex items-center gap-2">
 					<Logo className="size-5" />
 					<span className="text-sm font-medium">Page Agent Ext</span>
 				</div>
-				<div className="flex items-center gap-3">
+				<div className="flex items-center gap-1">
 					<StatusDot status={status} />
 					<Button
 						variant="ghost"
 						size="icon-sm"
-						onClick={() => setShowConfig(true)}
+						onClick={() => setView({ name: 'history' })}
+						className="cursor-pointer"
+					>
+						<History className="size-3.5" />
+					</Button>
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						onClick={() => setView({ name: 'config' })}
 						className="cursor-pointer"
 					>
 						<Settings className="size-3.5" />

packages/extension/src/entrypoints/sidepanel/components/ConfigPanel.tsx

@@ -1,15 +1,15 @@
-import type { LLMConfig } from '@page-agent/llms'
 import { Copy, CornerUpLeft, Eye, EyeOff, HatGlasses, Home, Loader2, Scale } from 'lucide-react'
 import { useEffect, useState } from 'react'
 import { siGithub } from 'simple-icons'
 
-import { DEMO_API_KEY, DEMO_BASE_URL, DEMO_MODEL } from '@/agent/constants'
+import { DEMO_API_KEY, DEMO_BASE_URL, DEMO_MODEL, isTestingEndpoint } from '@/agent/constants'
+import type { ExtConfig, LanguagePreference } from '@/agent/useAgent'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 
 interface ConfigPanelProps {
-	config: LLMConfig | null
+	config: ExtConfig | null
-	onSave: (config: LLMConfig) => Promise<void>
+	onSave: (config: ExtConfig) => Promise<void>
 	onClose: () => void
 }
 
@@ -17,6 +17,7 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 	const [apiKey, setApiKey] = useState(config?.apiKey || DEMO_API_KEY)
 	const [baseURL, setBaseURL] = useState(config?.baseURL || DEMO_BASE_URL)
 	const [model, setModel] = useState(config?.model || DEMO_MODEL)
+	const [language, setLanguage] = useState<LanguagePreference>(config?.language)
 	const [saving, setSaving] = useState(false)
 	const [userAuthToken, setUserAuthToken] = useState<string>('')
 	const [copied, setCopied] = useState(false)
@@ -28,6 +29,7 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 		setApiKey(config?.apiKey || DEMO_API_KEY)
 		setBaseURL(config?.baseURL || DEMO_BASE_URL)
 		setModel(config?.model || DEMO_MODEL)
+		setLanguage(config?.language)
 	}, [config])
 
 	// Poll for user auth token every second until found
@@ -65,7 +67,7 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 	const handleSave = async () => {
 		setSaving(true)
 		try {
-			await onSave({ apiKey, baseURL, model })
+			await onSave({ apiKey, baseURL, model, language })
 		} finally {
 			setSaving(false)
 		}
@@ -85,6 +87,23 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 				</Button>
 			</div>
 
+			{/* Testing API notice */}
+			{isTestingEndpoint(baseURL) && (
+				<div className="p-2.5 rounded-md border border-amber-500/30 bg-amber-500/5 text-[10px] text-muted-foreground leading-relaxed">
+					<Scale className="size-3 inline-block mr-1 -mt-0.5 text-amber-600" />
+					You are using the free testing API. By using this service you agree to the{' '}
+					<a
+						href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="underline hover:text-foreground"
+					>
+						Terms of Use & Privacy Policy
+					</a>
+					. No sensitive data. No guaranteed availability.
+				</div>
+			)}
+
 			{/* User Auth Token Section */}
 			<div className="flex flex-col gap-1.5 p-3 bg-muted/50 rounded-md border">
 				<label className="text-xs font-medium text-muted-foreground">User Auth Token</label>
@@ -165,6 +184,19 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 				</div>
 			</div>
 
+			<div className="flex flex-col gap-1.5">
+				<label className="text-xs text-muted-foreground">Language</label>
+				<select
+					value={language ?? ''}
+					onChange={(e) => setLanguage((e.target.value || undefined) as LanguagePreference)}
+					className="h-8 text-xs rounded-md border border-input bg-background px-2 cursor-pointer"
+				>
+					<option value="">System</option>
+					<option value="en-US">English</option>
+					<option value="zh-CN">中文</option>
+				</select>
+			</div>
+
 			<div className="flex gap-2 mt-2">
 				<Button variant="outline" onClick={onClose} className="flex-1 h-8 text-xs cursor-pointer">
 					Cancel
@@ -204,7 +236,7 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 					</a>
 
 					<a
-						href="https://github.com/alibaba/page-agent/blob/main/packages/extension/PRIVACY.md"
+						href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md"
 						target="_blank"
 						rel="noopener noreferrer"
 						className="flex items-center gap-1 hover:text-foreground"

packages/extension/src/entrypoints/sidepanel/components/HistoryDetail.tsx

@@ -0,0 +1,51 @@
+import { ArrowLeft } from 'lucide-react'
+import { useEffect, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { type SessionRecord, getSession } from '@/lib/db'
+
+import { EventCard } from './cards'
+
+export function HistoryDetail({ sessionId, onBack }: { sessionId: string; onBack: () => void }) {
+	const [session, setSession] = useState<SessionRecord | null>(null)
+
+	useEffect(() => {
+		getSession(sessionId).then((s) => setSession(s ?? null))
+	}, [sessionId])
+
+	if (!session) {
+		return (
+			<div className="flex items-center justify-center h-screen text-xs text-muted-foreground">
+				Loading...
+			</div>
+		)
+	}
+
+	return (
+		<div className="flex flex-col h-screen bg-background">
+			{/* Header */}
+			<header className="flex items-center gap-2 border-b px-3 py-2">
+				<Button variant="ghost" size="icon-sm" onClick={onBack} className="cursor-pointer">
+					<ArrowLeft className="size-3.5" />
+				</Button>
+				<span className="text-sm font-medium truncate">History</span>
+			</header>
+
+			{/* Task */}
+			<div className="border-b px-3 py-2 bg-muted/30">
+				<div className="text-[10px] text-muted-foreground uppercase tracking-wide">Task</div>
+				<div className="text-xs font-medium" title={session.task}>
+					{session.task}
+				</div>
+			</div>
+
+			{/* Events (read-only) */}
+			<div className="flex-1 overflow-y-auto p-3 space-y-2">
+				{session.history.map((event, index) => (
+					// eslint-disable-next-line react-x/no-array-index-key
+					<EventCard key={index} event={event} />
+				))}
+			</div>
+		</div>
+	)
+}

packages/extension/src/entrypoints/sidepanel/components/HistoryList.tsx

@@ -0,0 +1,119 @@
+import { ArrowLeft, CheckCircle, Trash2, XCircle } from 'lucide-react'
+import { useCallback, useEffect, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { type SessionRecord, clearSessions, deleteSession, listSessions } from '@/lib/db'
+
+function timeAgo(ts: number): string {
+	const seconds = Math.floor((Date.now() - ts) / 1000)
+	if (seconds < 60) return 'just now'
+	const minutes = Math.floor(seconds / 60)
+	if (minutes < 60) return `${minutes}m ago`
+	const hours = Math.floor(minutes / 60)
+	if (hours < 24) return `${hours}h ago`
+	const days = Math.floor(hours / 24)
+	return `${days}d ago`
+}
+
+export function HistoryList({
+	onSelect,
+	onBack,
+}: {
+	onSelect: (id: string) => void
+	onBack: () => void
+}) {
+	const [sessions, setSessions] = useState<SessionRecord[]>([])
+	const [loading, setLoading] = useState(true)
+
+	const load = useCallback(async () => {
+		setSessions(await listSessions())
+		setLoading(false)
+	}, [])
+
+	useEffect(() => {
+		// eslint-disable-next-line react-hooks/set-state-in-effect
+		load()
+	}, [load])
+
+	const handleDelete = async (e: React.MouseEvent, id: string) => {
+		e.stopPropagation()
+		await deleteSession(id)
+		setSessions((prev) => prev.filter((s) => s.id !== id))
+	}
+
+	return (
+		<div className="flex flex-col h-screen bg-background">
+			{/* Header */}
+			<header className="flex items-center gap-2 border-b px-3 py-2">
+				<Button variant="ghost" size="icon-sm" onClick={onBack} className="cursor-pointer">
+					<ArrowLeft className="size-3.5" />
+				</Button>
+				<span className="text-sm font-medium flex-1">History</span>
+				{sessions.length > 0 && (
+					<Button
+						variant="ghost"
+						size="sm"
+						onClick={async () => {
+							await clearSessions()
+							setSessions([])
+						}}
+						className="text-[10px] text-muted-foreground hover:text-destructive cursor-pointer h-6 px-2"
+					>
+						<Trash2 className="size-3 mr-1" />
+						Clear All
+					</Button>
+				)}
+			</header>
+
+			{/* List */}
+			<div className="flex-1 overflow-y-auto">
+				{loading && (
+					<div className="flex items-center justify-center h-32 text-xs text-muted-foreground">
+						Loading...
+					</div>
+				)}
+
+				{!loading && sessions.length === 0 && (
+					<div className="flex items-center justify-center h-32 text-xs text-muted-foreground">
+						No history yet
+					</div>
+				)}
+
+				{sessions.map((session) => (
+					<div
+						key={session.id}
+						role="button"
+						tabIndex={0}
+						onClick={() => onSelect(session.id)}
+						onKeyDown={(e) => e.key === 'Enter' && onSelect(session.id)}
+						className="w-full text-left px-3 py-2.5 border-b hover:bg-muted/50 transition-colors cursor-pointer flex items-start gap-2 group"
+					>
+						{/* Status icon */}
+						{session.status === 'completed' ? (
+							<CheckCircle className="size-3.5 text-green-500 shrink-0 mt-0.5" />
+						) : (
+							<XCircle className="size-3.5 text-destructive shrink-0 mt-0.5" />
+						)}
+
+						{/* Content */}
+						<div className="flex-1 min-w-0">
+							<p className="text-xs font-medium truncate">{session.task}</p>
+							<p className="text-[10px] text-muted-foreground mt-0.5">
+								{timeAgo(session.createdAt)} · {session.history.length} steps
+							</p>
+						</div>
+
+						{/* Delete */}
+						<button
+							type="button"
+							onClick={(e) => handleDelete(e, session.id)}
+							className="opacity-0 group-hover:opacity-100 transition-opacity p-1 hover:text-destructive cursor-pointer shrink-0"
+						>
+							<Trash2 className="size-3" />
+						</button>
+					</div>
+				))}
+			</div>
+		</div>
+	)
+}

packages/extension/src/entrypoints/sidepanel/components/misc.tsx

@@ -1,5 +1,10 @@
 import type { AgentStatus } from '@page-agent/core'
+import { Motion } from 'ai-motion'
+import { BookOpen, Globe } from 'lucide-react'
+import { useEffect, useRef } from 'react'
+import { siGithub } from 'simple-icons'
 
+import { TypingAnimation } from '@/components/ui/typing-animation'
 import { cn } from '@/lib/utils'
 
 // Status dot indicator
@@ -19,7 +24,7 @@ export function StatusDot({ status }: { status: AgentStatus }) {
 	}[status]
 
 	return (
-		<div className="flex items-center gap-1.5">
+		<div className="flex items-center gap-1.5 mr-2">
 			<span
 				className={cn('size-2 rounded-full', colorClass, status === 'running' && 'animate-pulse')}
 			/>
@@ -32,14 +37,111 @@ export function Logo({ className }: { className?: string }) {
 	return <img src="/assets/page-agent-256.webp" alt="Page Agent" className={cn('', className)} />
 }
 
-// Empty state with logo
+// Full-screen ai-motion glow overlay, shown only while running
+export function MotionOverlay({ active }: { active: boolean }) {
+	const containerRef = useRef<HTMLDivElement>(null)
+	const motionRef = useRef<Motion | null>(null)
+
+	useEffect(() => {
+		const mode = document.documentElement.classList.contains('dark') ? 'dark' : 'light'
+		const motion = new Motion({
+			mode,
+			borderWidth: 4,
+			borderRadius: 14,
+			glowWidth: mode === 'dark' ? 120 : 60,
+			styles: { position: 'absolute', inset: '0' },
+		})
+		motionRef.current = motion
+		containerRef.current!.appendChild(motion.element)
+		motion.autoResize(containerRef.current!)
+
+		return () => {
+			motion.dispose()
+			motionRef.current = null
+		}
+	}, [])
+
+	useEffect(() => {
+		const motion = motionRef.current
+		if (!motion) return
+
+		let disposed = false
+		if (active) {
+			motion.start()
+			motion.fadeIn()
+		} else {
+			motion.fadeOut().then(() => !disposed && motion.pause())
+		}
+		return () => {
+			disposed = true
+		}
+	}, [active])
+
+	return (
+		<div
+			ref={containerRef}
+			className="pointer-events-none absolute inset-0 z-10 opacity-60"
+			style={{ display: active ? undefined : 'none' }}
+		/>
+	)
+}
+
+// Empty state with logo and breathing glow
 export function EmptyState() {
 	return (
-		<div className="flex flex-col items-center justify-center h-full gap-3 text-center px-6">
+		<div className="flex flex-col items-center justify-center h-full gap-4 text-center px-6">
-			<Logo className="size-20 opacity-80" />
+			<div className="relative select-none pointer-events-none">
+				<div className="absolute inset-0 -m-6 rounded-full bg-[conic-gradient(from_180deg,oklch(0.55_0.2_280),oklch(0.5_0.15_230),oklch(0.6_0.18_310),oklch(0.55_0.2_280))] blur-2xl animate-[glow-a_5s_ease-in-out_infinite]" />
+				<div className="absolute inset-0 -m-6 rounded-full bg-[conic-gradient(from_0deg,oklch(0.55_0.18_160),oklch(0.5_0.2_200),oklch(0.6_0.15_120),oklch(0.55_0.18_160))] blur-2xl animate-[glow-b_5s_ease-in-out_infinite]" />
+				<Logo className="relative size-20 opacity-80" />
+			</div>
 			<div>
-				<h2 className="text-sm font-medium text-foreground">Page Agent Ext</h2>
+				<h2 className="text-base font-medium text-foreground mb-1">Page Agent Ext</h2>
-				<p className="text-xs text-muted-foreground mt-1">Enter a task to automate this page</p>
+				<TypingAnimation
+					className="text-sm text-muted-foreground"
+					words={[
+						'Enter a task to automate this page',
+						'Execute multi-page tasks',
+						'Call this extension from your web page',
+						'Use this extension in your own agents',
+					]}
+					cursorStyle="underscore"
+					loop
+					typeSpeed={20}
+					deleteSpeed={10}
+					pauseDelay={3000}
+				/>
+			</div>
+			<div className="flex items-center gap-3 mt-1 text-muted-foreground">
+				<a
+					href="https://github.com/alibaba/page-agent"
+					target="_blank"
+					rel="noopener noreferrer"
+					className="hover:text-foreground transition-colors"
+					title="GitHub"
+				>
+					<svg role="img" viewBox="0 0 24 24" className="size-4 fill-current">
+						<path d={siGithub.path} />
+					</svg>
+				</a>
+				<a
+					href="https://alibaba.github.io/page-agent/docs/features/chrome-extension"
+					target="_blank"
+					rel="noopener noreferrer"
+					className="hover:text-foreground transition-colors"
+					title="Documentation"
+				>
+					<BookOpen className="size-4" />
+				</a>
+				<a
+					href="https://alibaba.github.io/page-agent"
+					target="_blank"
+					rel="noopener noreferrer"
+					className="hover:text-foreground transition-colors"
+					title="Website"
+				>
+					<Globe className="size-4" />
+				</a>
 			</div>
 		</div>
 	)

packages/extension/src/lib/db.ts

@@ -0,0 +1,70 @@
+import type { HistoricalEvent } from '@page-agent/core'
+import { type DBSchema, type IDBPDatabase, openDB } from 'idb'
+
+const DB_NAME = 'page-agent-ext'
+const DB_VERSION = 1
+
+export interface SessionRecord {
+	id: string
+	task: string
+	history: HistoricalEvent[]
+	status: 'completed' | 'error'
+	createdAt: number
+}
+
+interface PageAgentDB extends DBSchema {
+	sessions: {
+		key: string
+		value: SessionRecord
+		indexes: { 'by-created': number }
+	}
+}
+
+let dbPromise: Promise<IDBPDatabase<PageAgentDB>> | null = null
+
+function getDB() {
+	if (!dbPromise) {
+		dbPromise = openDB<PageAgentDB>(DB_NAME, DB_VERSION, {
+			upgrade(db) {
+				const store = db.createObjectStore('sessions', { keyPath: 'id' })
+				store.createIndex('by-created', 'createdAt')
+			},
+		})
+	}
+	return dbPromise
+}
+
+export async function saveSession(
+	session: Omit<SessionRecord, 'id' | 'createdAt'>
+): Promise<SessionRecord> {
+	const db = await getDB()
+	const record: SessionRecord = {
+		...session,
+		id: crypto.randomUUID(),
+		createdAt: Date.now(),
+	}
+	await db.put('sessions', record)
+	return record
+}
+
+/** List sessions, newest first */
+export async function listSessions(): Promise<SessionRecord[]> {
+	const db = await getDB()
+	const all = await db.getAllFromIndex('sessions', 'by-created')
+	return all.reverse()
+}
+
+export async function getSession(id: string): Promise<SessionRecord | undefined> {
+	const db = await getDB()
+	return db.get('sessions', id)
+}
+
+export async function deleteSession(id: string): Promise<void> {
+	const db = await getDB()
+	await db.delete('sessions', id)
+}
+
+export async function clearSessions(): Promise<void> {
+	const db = await getDB()
+	await db.clear('sessions')
+}

packages/extension/wxt.config.js

@@ -38,9 +38,9 @@ export default defineConfig({
 		},
 	}),
 	manifest: {
-		name: 'Page Agent Ext',
+		default_locale: 'en',
-		description:
+		name: '__MSG_extName__',
-			'AI-powered browser automation assistant. Control web pages with natural language.',
+		description: '__MSG_extDescription__',
 		homepage_url: 'https://alibaba.github.io/page-agent/',
 		permissions: ['tabs', 'tabGroups', 'sidePanel', 'storage'],
 		host_permissions: ['<all_urls>'],
@@ -48,7 +48,7 @@ export default defineConfig({
 			64: 'assets/page-agent-64.png',
 		},
 		action: {
-			default_title: 'Open Page Agent',
+			default_title: '__MSG_extActionTitle__',
 		},
 		web_accessible_resources: [
 			{

packages/llms/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@page-agent/llms",
-    "version": "1.1.1",
+    "version": "1.4.3",
     "type": "module",
     "main": "./dist/lib/page-agent-llms.js",
     "module": "./dist/lib/page-agent-llms.js",

packages/llms/src/OpenAIClient.ts

@@ -1,6 +1,8 @@
 /**
  * OpenAI Client implementation
  */
+import * as z from 'zod'
+
 import { InvokeError, InvokeErrorType } from './errors'
 import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
 import { modelPatch, zodToOpenAITool } from './utils'
@@ -54,8 +56,10 @@ export class OpenAIClient implements LLMClient {
 				signal: abortSignal,
 			})
 		} catch (error: unknown) {
-			console.error(error)
+			const isAbortError = (error as any)?.name === 'AbortError'
-			throw new InvokeError(InvokeErrorType.NETWORK_ERROR, 'Network request failed', error)
+			const errorMessage = isAbortError ? 'Network request aborted' : 'Network request failed'
+			if (!isAbortError) console.error(error)
+			throw new InvokeError(InvokeErrorType.NETWORK_ERROR, errorMessage, error)
 		}
 
 		// 3. Handle HTTP errors
@@ -180,7 +184,7 @@ export class OpenAIClient implements LLMClient {
 		// Validate with schema
 		const validation = tool.inputSchema.safeParse(parsedArgs)
 		if (!validation.success) {
-			console.error(validation.error)
+			console.error(z.prettifyError(validation.error))
 			throw new InvokeError(
 				InvokeErrorType.INVALID_TOOL_ARGS,
 				'Tool arguments validation failed',

packages/llms/src/env.d.ts

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

packages/llms/src/errors.ts

@@ -34,12 +34,15 @@ export class InvokeError extends Error {
 		super(message)
 		this.name = 'InvokeError'
 		this.type = type
-		this.retryable = this.isRetryable(type)
+		this.retryable = this.isRetryable(type, rawError)
 		this.rawError = rawError
 		this.rawResponse = rawResponse
 	}
 
-	private isRetryable(type: InvokeErrorType): boolean {
+	private isRetryable(type: InvokeErrorType, rawError?: unknown): boolean {
+		const isAbortError = (rawError as any)?.name === 'AbortError'
+		if (isAbortError) return false
+
 		const retryableTypes: InvokeErrorType[] = [
 			InvokeErrorType.NETWORK_ERROR,
 			InvokeErrorType.RATE_LIMIT,

packages/llms/src/index.ts

@@ -1,16 +1,17 @@
 import { OpenAIClient } from './OpenAIClient'
 import { DEFAULT_TEMPERATURE, LLM_MAX_RETRIES } from './constants'
-import { InvokeError } from './errors'
+import { InvokeError, InvokeErrorType } from './errors'
 import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
 
-export type { InvokeError, InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool }
+export { InvokeError, InvokeErrorType }
+export type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool }
 
 export function parseLLMConfig(config: LLMConfig): Required<LLMConfig> {
 	// Runtime validation as defensive programming (types already guarantee these)
 	if (!config.baseURL || !config.apiKey || !config.model) {
 		throw new Error(
 			'[PageAgent] LLM configuration required. Please provide: baseURL, apiKey, model. ' +
-				'See: https://alibaba.github.io/page-agent/#/docs/features/models'
+				'See: https://alibaba.github.io/page-agent/docs/features/models'
 		)
 	}
 
@@ -49,6 +50,9 @@ export class LLM extends EventTarget {
 	): Promise<InvokeResult> {
 		return await withRetry(
 			async () => {
+				// in case user aborted before invoking
+				if (abortSignal.aborted) throw new Error('AbortError')
+
 				const result = await this.client.invoke(messages, tools, abortSignal, options)
 
 				return result

packages/llms/src/types.ts

@@ -1,7 +1,7 @@
 /**
  * Core types for LLM integration
  */
-import type { z } from 'zod'
+import type * as z from 'zod'
 
 /**
  * Message format - OpenAI standard (industry standard)

packages/llms/src/utils.ts

@@ -2,7 +2,7 @@
  * Utility functions for LLM integration
  */
 import chalk from 'chalk'
-import { z } from 'zod'
+import * as z from 'zod'
 
 import type { Tool } from './types'
 
@@ -38,6 +38,7 @@ export function modelPatch(body: Record<string, any>) {
 	if (modelName.startsWith('qwen')) {
 		debug('Applying Qwen patch: use higher temperature for auto fixing')
 		body.temperature = Math.max(body.temperature || 0, 1.0)
+		body.enable_thinking = false
 	}
 
 	if (modelName.startsWith('claude')) {

packages/page-agent/package.json

@@ -1,7 +1,7 @@
 {
     "name": "page-agent",
     "private": false,
-    "version": "1.1.1",
+    "version": "1.4.3",
     "type": "module",
     "main": "./dist/esm/page-agent.js",
     "module": "./dist/esm/page-agent.js",
@@ -44,11 +44,11 @@
         "postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
     },
     "dependencies": {
+        "@page-agent/core": "1.4.3",
+        "@page-agent/llms": "1.4.3",
+        "@page-agent/page-controller": "1.4.3",
+        "@page-agent/ui": "1.4.3",
         "chalk": "^5.6.2",
-        "zod": "^4.3.5",
+        "zod": "^4.3.5"
-        "@page-agent/llms": "1.1.1",
-        "@page-agent/page-controller": "1.1.1",
-        "@page-agent/core": "1.1.1",
-        "@page-agent/ui": "1.1.1"
     }
 }

packages/page-agent/src/PageAgent.ts

@@ -2,12 +2,13 @@
  * Copyright (C) 2025 Alibaba Group Holding Limited
  * All rights reserved.
  */
-import { type PageAgentConfig, PageAgentCore, type PageAgentTool, tool } from '@page-agent/core'
+import { type AgentConfig, PageAgentCore } from '@page-agent/core'
-import { PageController } from '@page-agent/page-controller'
+import { PageController, type PageControllerConfig } from '@page-agent/page-controller'
 import { Panel } from '@page-agent/ui'
 
-export type { PageAgentConfig, PageAgentTool }
+export * from '@page-agent/core'
-export { tool }
+
+export type PageAgentConfig = AgentConfig & PageControllerConfig
 
 export class PageAgent extends PageAgentCore {
 	panel: Panel

packages/page-agent/src/demo.ts

@@ -13,9 +13,9 @@ window.PageAgent = PageAgent
 
 console.log('🚀 page-agent.js loaded!')
 
-const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+const DEMO_MODEL = 'qwen3.5-plus'
-const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
+const DEMO_BASE_URL = 'https://page-ag-testing-ohftxirgbn.cn-shanghai.fcapp.run'
-const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+const DEMO_API_KEY = 'NA'
 
 // in case document.x is not ready yet
 setTimeout(() => {

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

@@ -3,6 +3,7 @@ import { config as dotenvConfig } from 'dotenv'
 import { dirname, resolve } from 'path'
 import { fileURLToPath } from 'url'
 import { defineConfig } from 'vite'
+// import { analyzer } from 'vite-bundle-analyzer'
 import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -14,8 +15,11 @@ dotenvConfig({ path: resolve(__dirname, '../../.env') })
 // - alias all local packages so that they can be build in
 // - no external
 // - no d.ts. dts does not work with monorepo aliasing
-export default defineConfig(({ mode }) => ({
+export default defineConfig(() => ({
-	plugins: [cssInjectedByJsPlugin({ relativeCSSInjection: true })],
+	plugins: [
+		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
+		// analyzer()
+	],
 	publicDir: false,
 	esbuild: {
 		keepNames: true,

packages/page-controller/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@page-agent/page-controller",
-    "version": "1.1.1",
+    "version": "1.4.3",
     "type": "module",
     "main": "./dist/lib/page-controller.js",
     "module": "./dist/lib/page-controller.js",

packages/page-controller/src/PageController.ts

@@ -248,7 +248,7 @@ export class PageController extends EventTarget {
 			if (element instanceof HTMLAnchorElement && element.target === '_blank') {
 				return {
 					success: true,
-					message: `✅ Clicked element (${elemText ?? index}). ⚠️ Link opens in a new tab. You are not capable of reading new tabs.`,
+					message: `✅ Clicked element (${elemText ?? index}). ⚠️ Link opened in a new tab.`,
 				}
 			}
 

packages/page-controller/src/actions.ts

@@ -86,7 +86,7 @@ export async function clickElement(element: HTMLElement) {
 	// dispatch a click event
 	// element.click()
 
-	await waitFor(0.1) // Wait to ensure click event processing completes
+	await waitFor(0.2) // Wait to ensure click event processing completes
 }
 
 // eslint-disable-next-line @typescript-eslint/unbound-method
@@ -181,11 +181,6 @@ export async function scrollVertically(
 	// Element-specific scrolling if element is provided
 	if (element) {
 		const targetElement = element
-		console.log(
-			'[SCROLL DEBUG] Starting direct container scroll for element:',
-			targetElement.tagName
-		)
-
 		let currentElement = targetElement as HTMLElement | null
 		let scrollSuccess = false
 		let scrolledElement: HTMLElement | null = null
@@ -198,19 +193,6 @@ export async function scrollVertically(
 			const hasScrollableY = /(auto|scroll|overlay)/.test(computedStyle.overflowY)
 			const canScrollVertically = currentElement.scrollHeight > currentElement.clientHeight
 
-			console.log(
-				'[SCROLL DEBUG] Checking element:',
-				currentElement.tagName,
-				'hasScrollableY:',
-				hasScrollableY,
-				'canScrollVertically:',
-				canScrollVertically,
-				'scrollHeight:',
-				currentElement.scrollHeight,
-				'clientHeight:',
-				currentElement.clientHeight
-			)
-
 			if (hasScrollableY && canScrollVertically) {
 				const beforeScroll = currentElement.scrollTop
 				const maxScroll = currentElement.scrollHeight - currentElement.clientHeight
@@ -228,27 +210,10 @@ export async function scrollVertically(
 				const afterScroll = currentElement.scrollTop
 				const actualScrollDelta = afterScroll - beforeScroll
 
-				console.log(
-					'[SCROLL DEBUG] Scroll attempt:',
-					currentElement.tagName,
-					'before:',
-					beforeScroll,
-					'after:',
-					afterScroll,
-					'delta:',
-					actualScrollDelta
-				)
-
 				if (Math.abs(actualScrollDelta) > 0.5) {
 					scrollSuccess = true
 					scrolledElement = currentElement
 					scrollDelta = actualScrollDelta
-					console.log(
-						'[SCROLL DEBUG] Successfully scrolled container:',
-						currentElement.tagName,
-						'delta:',
-						actualScrollDelta
-					)
 					break
 				}
 			}
@@ -344,11 +309,6 @@ export async function scrollHorizontally(
 	// Element-specific scrolling if element is provided
 	if (element) {
 		const targetElement = element
-		console.log(
-			'[SCROLL DEBUG] Starting direct container scroll for element:',
-			targetElement.tagName
-		)
-
 		let currentElement = targetElement as HTMLElement | null
 		let scrollSuccess = false
 		let scrolledElement: HTMLElement | null = null
@@ -361,19 +321,6 @@ export async function scrollHorizontally(
 			const hasScrollableX = /(auto|scroll|overlay)/.test(computedStyle.overflowX)
 			const canScrollHorizontally = currentElement.scrollWidth > currentElement.clientWidth
 
-			console.log(
-				'[SCROLL DEBUG] Checking element:',
-				currentElement.tagName,
-				'hasScrollableX:',
-				hasScrollableX,
-				'canScrollHorizontally:',
-				canScrollHorizontally,
-				'scrollWidth:',
-				currentElement.scrollWidth,
-				'clientWidth:',
-				currentElement.clientWidth
-			)
-
 			if (hasScrollableX && canScrollHorizontally) {
 				const beforeScroll = currentElement.scrollLeft
 				const maxScroll = currentElement.scrollWidth - currentElement.clientWidth
@@ -391,27 +338,10 @@ export async function scrollHorizontally(
 				const afterScroll = currentElement.scrollLeft
 				const actualScrollDelta = afterScroll - beforeScroll
 
-				console.log(
-					'[SCROLL DEBUG] Scroll attempt:',
-					currentElement.tagName,
-					'before:',
-					beforeScroll,
-					'after:',
-					afterScroll,
-					'delta:',
-					actualScrollDelta
-				)
-
 				if (Math.abs(actualScrollDelta) > 0.5) {
 					scrollSuccess = true
 					scrolledElement = currentElement
 					scrollDelta = actualScrollDelta
-					console.log(
-						'[SCROLL DEBUG] Successfully scrolled container:',
-						currentElement.tagName,
-						'delta:',
-						actualScrollDelta
-					)
 					break
 				}
 			}

packages/ui/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@page-agent/ui",
-    "version": "1.1.1",
+    "version": "1.4.3",
     "type": "module",
     "main": "./dist/lib/page-agent-ui.js",
     "module": "./dist/lib/page-agent-ui.js",

packages/ui/src/i18n/locales.ts

@@ -12,9 +12,10 @@ const enUS = {
 			question: 'Question: {{question}}',
 			waitingPlaceholder: 'Waiting for task to start...',
 			stop: 'Stop',
+			close: 'Close',
 			expand: 'Expand history',
 			collapse: 'Collapse history',
-			step: 'Step {{number}} · {{time}}{{duration}}',
+			step: 'Step {{number}}',
 		},
 		tools: {
 			clicking: 'Clicking element [{{index}}]...',
@@ -59,9 +60,10 @@ const zhCN = {
 			question: '询问: {{question}}',
 			waitingPlaceholder: '等待任务开始...',
 			stop: '终止',
+			close: '关闭',
 			expand: '展开历史',
 			collapse: '收起历史',
-			step: '步骤 {{number}} · {{time}}{{duration}}',
+			step: '步骤 {{number}}',
 		},
 		tools: {
 			clicking: '正在点击元素 [{{index}}]...',

packages/ui/src/index.ts

@@ -1,3 +1,2 @@
 export { Panel, type PanelConfig } from './panel/Panel'
-export type { AgentActivity, PanelAgentAdapter } from './panel/types'
 export { I18n, type SupportedLanguage, type TranslationKey } from './i18n'

packages/ui/src/panel/Panel.ts

@@ -1,6 +1,6 @@
 import { I18n, type SupportedLanguage } from '../i18n'
 import { truncate } from '../utils'
-import { createCard, createReflectionLines, formatTime } from './cards'
+import { createCard, createReflectionLines } from './cards'
 import type { AgentActivity, PanelAgentAdapter } from './types'
 
 import styles from './Panel.module.css'
@@ -33,7 +33,7 @@ export class Panel {
 	#statusText: HTMLElement
 	#historySection: HTMLElement
 	#expandButton: HTMLElement
-	#stopButton: HTMLElement
+	#actionButton: HTMLElement
 	#inputSection: HTMLElement
 	#taskInput: HTMLInputElement
 
@@ -76,7 +76,7 @@ export class Panel {
 		this.#statusText = this.#wrapper.querySelector(`.${styles.statusText}`)!
 		this.#historySection = this.#wrapper.querySelector(`.${styles.historySection}`)!
 		this.#expandButton = this.#wrapper.querySelector(`.${styles.expandButton}`)!
-		this.#stopButton = this.#wrapper.querySelector(`.${styles.stopButton}`)!
+		this.#actionButton = this.#wrapper.querySelector(`.${styles.stopButton}`)!
 		this.#inputSection = this.#wrapper.querySelector(`.${styles.inputSectionWrapper}`)!
 		this.#taskInput = this.#wrapper.querySelector(`.${styles.taskInput}`)!
 
@@ -105,6 +105,15 @@ export class Panel {
 			status === 'running' ? 'thinking' : status === 'idle' ? 'thinking' : status
 		this.#updateStatusIndicator(indicatorType)
 
+		// Morph action button: running = stop (■), not running = close (X)
+		if (status === 'running') {
+			this.#actionButton.textContent = '■'
+			this.#actionButton.title = this.#i18n.t('ui.panel.stop')
+		} else {
+			this.#actionButton.textContent = 'X'
+			this.#actionButton.title = this.#i18n.t('ui.panel.close')
+		}
+
 		// Show/hide based on status
 		if (status === 'running') {
 			this.show()
@@ -178,7 +187,6 @@ export class Panel {
 			tempCard.innerHTML = createCard({
 				icon: '❓',
 				content: `Question: ${question}`,
-				meta: formatTime(this.#config.language ?? 'en-US'),
 				type: 'question',
 			})
 			const cardElement = tempCard.firstElementChild as HTMLElement
@@ -266,10 +274,14 @@ export class Panel {
 	}
 
 	/**
-	 * Stop Agent
+	 * Action button handler: stop when running, close (dispose) when idle
 	 */
-	#stopAgent(): void {
+	#handleActionButton(): void {
-		this.#agent.dispose()
+		if (this.#agent.status === 'running') {
+			this.#agent.stop()
+		} else {
+			this.#agent.dispose()
+		}
 	}
 
 	/**
@@ -383,7 +395,7 @@ export class Panel {
 					<button class="${styles.controlButton} ${styles.expandButton}" title="${this.#i18n.t('ui.panel.expand')}">
 						▼
 					</button>
-					<button class="${styles.controlButton} ${styles.stopButton}" title="${this.#i18n.t('ui.panel.stop')}">
+					<button class="${styles.controlButton} ${styles.stopButton}" title="${this.#i18n.t('ui.panel.close')}">
 						X
 					</button>
 				</div>
@@ -420,10 +432,10 @@ export class Panel {
 			this.#toggle()
 		})
 
-		// Stop button
+		// Action button (stop / close)
-		this.#stopButton.addEventListener('click', (e) => {
+		this.#actionButton.addEventListener('click', (e) => {
 			e.stopPropagation()
-			this.#stopAgent()
+			this.#handleActionButton()
 		})
 
 		// Submit on Enter key in input field
@@ -578,15 +590,12 @@ export class Panel {
 	/** Create cards for a history event */
 	#createHistoryCards(event: PanelAgentAdapter['history'][number]): string[] {
 		const cards: string[] = []
-		const time = formatTime(this.#config.language ?? 'en-US')
 		const meta =
 			event.type === 'step' && event.stepIndex !== undefined
 				? this.#i18n.t('ui.panel.step', {
 						number: (event.stepIndex + 1).toString(),
-						time,
-						duration: '',
 					})
-				: time
+				: undefined
 
 		if (event.type === 'step') {
 			// Reflection card
@@ -623,7 +632,7 @@ export class Panel {
 	/** Create cards for an action */
 	#createActionCards(
 		action: { name: string; input: unknown; output: string },
-		meta: string
+		meta?: string
 	): string[] {
 		const cards: string[] = []
 

packages/ui/src/panel/cards.ts

@@ -32,16 +32,6 @@ export function createCard({ icon, content, meta, type }: CardOptions): string {
 	`
 }
 
-/** 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

packages/ui/src/panel/types.ts

@@ -68,6 +68,9 @@ export interface PanelAgentAdapter extends EventTarget {
 	/** Execute a task */
 	execute(task: string): Promise<unknown>
 
-	/** Dispose the agent */
+	/** Stop the current task (agent remains reusable) */
+	stop(): void
+
+	/** Dispose the agent (terminal, cannot be reused) */
 	dispose(): void
 }

packages/website/AGENTS.md

@@ -5,9 +5,9 @@
 - **React** with TypeScript
 - **Vite** for dev server and build
 - **Tailwind CSS** for styling
-- **shadcn/ui** (new-york style) for UI components
+- **shadcn/ui** (new-york style) for UI components — **do NOT hand-edit `src/components/ui/` files**
 - **Magic UI** for animations and effects
-- **wouter** with hash routing for static hosting
+- **wouter** with browser routing (`base: "/page-agent"`)
 - **lucide-react** for icons
 
 ## Component Guidelines
@@ -53,58 +53,74 @@ Located in `src/components/ui/`:
 ### Styling Rules
 
 1. **Prefer Tailwind classes** over custom CSS
-2. Use CSS modules only for complex component-specific styles
+2. Support dark mode via `dark:` classes
-3. Support dark mode via `dark:` classes
+3. Use CSS variables from `src/index.css` for theme colors
-4. Use CSS variables from `src/index.css` for theme colors
 
 ## Project Structure
 
 ```
 src/
 ├── pages/
-│   ├── Home.tsx         # Homepage
+│   ├── home/
+│   │   ├── HomeContent.tsx  # Homepage sections
+│   │   └── ...Section.tsx
 │   └── docs/
-│       ├── Layout.tsx   # Documentation sidebar
+│       ├── index.tsx    # Docs route switch
+│       ├── Layout.tsx   # Sidebar navigation
 │       └── [section]/[topic]/page.tsx
 ├── components/
-│   ├── ui/              # shadcn/ui + Magic UI components
+│   ├── ui/              # shadcn/ui + Magic UI (DO NOT hand-edit)
+│   ├── Heading.tsx      # Anchor heading for doc pages
 │   ├── Header.tsx       # Site header
 │   └── Footer.tsx       # Site footer
 ├── i18n/                # Internationalization
-├── router.tsx           # Central routing
+├── router.tsx           # Root layout + routing
 └── main.tsx             # App entry
 ```
 
+## Routing
+
+Uses wouter browser routing with base path for GitHub Pages deployment at `https://alibaba.github.io/page-agent/`.
+
+```tsx
+// main.tsx
+<Router base="/page-agent">
+  <PagesRouter />
+</Router>
+```
+
+**Key rules:**
+
+- Header and Footer live in `router.tsx` **outside** `<Switch>`, so they always see the root router context (`base="/page-agent"`)
+- Docs pages are nested via `<Route path="/docs" nest>`, which creates a child context (`base="/page-agent/docs"`)
+- Inside the docs nest, Link hrefs are relative to `/docs` (e.g. `href="/features/models"`, NOT `href="/docs/features/models"`)
+- **Never use `~` prefix** in Link hrefs — it bypasses the base path entirely
+- Doc page headings use `<Heading id="slug" level={2}>` for anchor links
+
+### SPA on GitHub Pages
+
+Instead of `404.html` redirects, the build copies `index.html` into every route directory. Add new routes to the `SPA_ROUTES` array in `vite.config.js`.
+
 ## Adding New Pages
 
 ### Documentation Page
 
 1. Create `src/pages/docs/<section>/<slug>/page.tsx`
-2. Add route to `src/router.tsx` with `<Header /> + <DocsLayout>` wrapper
+2. Add route in `src/pages/docs/index.tsx`
-3. Add navigation item to `pages/docs/Layout.tsx`
+3. Add navigation item in `src/pages/docs/Layout.tsx`
-
+4. Add path to `SPA_ROUTES` in `vite.config.js`
-## Routing
-
-Uses hash-based routing for static hosting:
-
-```tsx
-import { Router } from 'wouter'
-import { useHashLocation } from 'wouter/use-hash-location'
-
-;<Router hook={useHashLocation}>{/* routes */}</Router>
-```
 
 ## Configuration Files
 
 | File              | Purpose                 |
 | ----------------- | ----------------------- |
 | `components.json` | shadcn/ui configuration |
-| `vite.config.js`  | Vite build settings     |
+| `vite.config.js`  | Vite build + SPA routes |
 | `tsconfig.json`   | TypeScript config       |
 
 ## Commands
 
 ```bash
-npm start        # Dev server (from root)
+npm start            # Dev server (from root)
 npm run build:website    # Build website (from root)
 ```

packages/website/index.html

@@ -45,13 +45,24 @@
 		</script>
 	</head>
 	<body>
-		<div id="root"></div>
+		<div id="root">
+			<div id="sk">
+				<p class="sk-text" id="sk-text">Loading...</p>
+				<style>
+					#sk{display:flex;align-items:center;justify-content:center;min-height:100vh;background:linear-gradient(135deg,#eff6ff,#f5f3ff)}
+					@media(prefers-color-scheme:dark){#sk{background:linear-gradient(135deg,#111827,#1f2937)}}
+					.sk-text{font:400 14px/1 system-ui,sans-serif;color:#94a3b8;animation:skf 2s ease-in-out infinite}
+					@keyframes skf{0%,100%{opacity:.6}50%{opacity:.3}}
+				</style>
+			</div>
+		</div>
 		<script type="module" src="./src/main.tsx"></script>
 		<script>
-			// Dynamically update html lang attribute based on i18n detection
 			const updateHtmlLang = () => {
 				const lang = localStorage.getItem('i18nextLng') || navigator.language || 'zh-CN'
 				document.documentElement.lang = lang
+				const el = document.getElementById('sk-text')
+				if (el) el.textContent = lang.startsWith('zh') ? '加载中...' : 'Loading...'
 			}
 			updateHtmlLang()
 			window.addEventListener('storage', updateHtmlLang)

packages/website/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@page-agent/website",
     "private": true,
-    "version": "1.1.1",
+    "version": "1.4.3",
     "type": "module",
     "scripts": {
         "dev": "vite --host 0.0.0.0",
@@ -10,30 +10,26 @@
         "typecheck": "tsc --noEmit"
     },
     "devDependencies": {
-        "@tailwindcss/vite": "^4.1.18",
-        "@types/react": "^19.2.8",
-        "@types/react-dom": "^19.2.1",
-        "@vitejs/plugin-react-swc": "^4.1.0",
-        "react": "^19.2.4",
-        "react-dom": "^19.2.4",
-        "tailwindcss": "^4.1.14",
-        "tw-animate-css": "^1.4.0",
-        "wouter": "^3.9.0"
-    },
-    "dependencies": {
         "@radix-ui/react-icons": "^1.3.2",
         "@radix-ui/react-separator": "^1.1.8",
         "@radix-ui/react-slot": "^1.2.4",
         "@radix-ui/react-switch": "^1.2.6",
         "@radix-ui/react-tooltip": "^1.2.8",
+        "@types/react": "^19.2.14",
+        "@types/react-dom": "^19.2.1",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
-        "lucide-react": "^0.563.0",
+        "lucide-react": "^0.576.0",
-        "motion": "^12.30.0",
+        "motion": "^12.34.5",
         "next-themes": "^0.4.6",
+        "react": "^19.2.4",
+        "react-dom": "^19.2.4",
         "rough-notation": "^0.5.1",
-        "simple-icons": "^16.7.0",
+        "simple-icons": "^16.10.0",
         "sonner": "^2.0.7",
-        "tailwind-merge": "^3.4.0"
+        "tailwind-merge": "^3.5.0",
+        "tailwindcss": "^4.1.14",
+        "tw-animate-css": "^1.4.0",
+        "wouter": "^3.9.0"
     }
 }

packages/website/src/components/APIReference.tsx

@@ -5,10 +5,9 @@
  */
 import * as React from 'react'
 
+import { Badge } from '@/components/ui/badge'
 import { cn } from '@/lib/utils'
 
-import { Badge } from './badge'
-
 // ============================================================================
 // Types
 // ============================================================================
@@ -35,6 +34,8 @@ export interface APIReferenceProps {
 	description?: React.ReactNode
 	/** Property definitions */
 	properties: PropDefinition[]
+	/** Display variant: 'properties' for fields, 'methods' for methods */
+	variant?: 'properties' | 'methods'
 	/** Additional CSS classes */
 	className?: string
 }
@@ -43,7 +44,14 @@ export interface APIReferenceProps {
 // Component
 // ============================================================================
 
-export function APIReference({ title, description, properties, className }: APIReferenceProps) {
+export function APIReference({
+	title,
+	description,
+	properties,
+	variant = 'properties',
+	className,
+}: APIReferenceProps) {
+	const isMethodsVariant = variant === 'methods'
 	return (
 		<div className={cn('my-6', className)}>
 			{title && (
@@ -58,10 +66,10 @@ export function APIReference({ title, description, properties, className }: APIR
 					<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
+								{isMethodsVariant ? 'Method' : 'Property'}
 							</th>
 							<th className="px-4 py-3 text-left font-medium text-gray-600 dark:text-gray-300">
-								Type
+								{isMethodsVariant ? 'Return Type' : 'Type'}
 							</th>
 							<th className="px-4 py-3 text-left font-medium text-gray-600 dark:text-gray-300 hidden md:table-cell">
 								Default
@@ -120,7 +128,7 @@ function PropRow({ name, type, required, defaultValue, description, status }: Pr
 
 			{/* 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">
+				<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 wrap-break-word">
 					{type}
 				</code>
 			</td>

packages/website/src/components/CodeEditor.tsx

@@ -42,7 +42,7 @@ const CodeEditor: React.FC<CodeEditorProps> = ({
 
 	return (
 		<div
-			className={`group relative ${containerClasses} rounded-xl border shadow-2xl overflow-hidden ${className}`}
+			className={`group relative ${containerClasses} rounded-xl border shadow-2xl my-4 overflow-hidden ${className}`}
 		>
 			{/* 编辑器顶部栏 */}
 			{showHeader && (

packages/website/src/components/Footer.tsx

@@ -16,6 +16,14 @@ export default function Footer() {
 						© 2026 page-agent. All rights reserved.
 					</p>
 					<div className="flex items-center space-x-6">
+						<a
+							href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md"
+							target="_blank"
+							rel="noopener noreferrer"
+							className="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-white transition-colors duration-200 text-sm"
+						>
+							{isZh ? '使用条款与隐私' : 'Terms & Privacy'}
+						</a>
 						<a
 							href="https://github.com/alibaba/page-agent"
 							target="_blank"

packages/website/src/components/Header.tsx

@@ -23,7 +23,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={isZh ? 'page-agent 首页' : 'page-agent home'}
 							onClick={() => setMobileMenuOpen(false)}
@@ -44,7 +44,7 @@ export default function Header() {
 									animateOnHover={true}
 									aria-hidden="true"
 								>
-									GUI Agent in your webpage
+									AI Agent In Your Webpage
 								</HyperText>
 							</div>
 						</Link>
@@ -56,7 +56,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={isZh ? '文档' : 'Docs'}
 							>
@@ -90,7 +90,7 @@ export default function Header() {
 								{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" />
@@ -138,7 +138,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/Heading.tsx

@@ -0,0 +1,45 @@
+import { ComponentPropsWithoutRef, useEffect, useRef } from 'react'
+
+import { cn } from '@/lib/utils'
+
+type Level = 2 | 3
+
+interface HeadingProps extends Omit<ComponentPropsWithoutRef<'h2'>, 'children'> {
+	id: string
+	level?: Level
+	children: React.ReactNode
+}
+
+const levelStyles = {
+	2: { tag: 'h2', className: 'text-2xl font-semibold mb-4' },
+	3: { tag: 'h3', className: 'text-xl font-semibold mb-3' },
+} as const
+
+export function Heading({ id, level = 2, className, children, ...props }: HeadingProps) {
+	const ref = useRef<HTMLHeadingElement>(null)
+	const { tag: Tag, className: defaultClassName } = levelStyles[level]
+
+	useEffect(() => {
+		if (window.location.hash === `#${id}`) {
+			ref.current?.scrollIntoView({ behavior: 'smooth' })
+		}
+	}, [id])
+
+	return (
+		<Tag
+			ref={ref}
+			id={id}
+			className={cn('group relative scroll-mt-20', defaultClassName, className)}
+			{...props}
+		>
+			<a
+				href={`#${id}`}
+				className="absolute -left-5 top-1/2 -translate-y-1/2 opacity-0 group-hover:opacity-100 text-gray-400 hover:text-blue-500 transition-opacity no-underline"
+				aria-label={`Link to ${id}`}
+			>
+				#
+			</a>
+			{children}
+		</Tag>
+	)
+}

packages/website/src/components/ui/magic-card.tsx

@@ -85,7 +85,7 @@ export function MagicCard({
           `,
 				}}
 			/>
-			<div className="bg-background absolute inset-px rounded-[inherit]" />
+			<div className="absolute inset-px rounded-[inherit] bg-white dark:bg-neutral-900" />
 			<motion.div
 				className="pointer-events-none absolute inset-px rounded-[inherit] opacity-0 transition-opacity duration-300 group-hover:opacity-100"
 				style={{

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

@@ -0,0 +1,74 @@
+import { ComponentPropsWithoutRef } from 'react'
+
+import { cn } from '@/lib/utils'
+
+interface MarqueeProps extends ComponentPropsWithoutRef<'div'> {
+	/**
+	 * Optional CSS class name to apply custom styles
+	 */
+	className?: string
+	/**
+	 * Whether to reverse the animation direction
+	 * @default false
+	 */
+	reverse?: boolean
+	/**
+	 * Whether to pause the animation on hover
+	 * @default false
+	 */
+	pauseOnHover?: boolean
+	/**
+	 * Content to be displayed in the marquee
+	 */
+	children: React.ReactNode
+	/**
+	 * Whether to animate vertically instead of horizontally
+	 * @default false
+	 */
+	vertical?: boolean
+	/**
+	 * Number of times to repeat the content
+	 * @default 4
+	 */
+	repeat?: number
+}
+
+export function Marquee({
+	className,
+	reverse = false,
+	pauseOnHover = false,
+	children,
+	vertical = false,
+	repeat = 4,
+	...props
+}: MarqueeProps) {
+	return (
+		<div
+			{...props}
+			className={cn(
+				'group flex [gap:var(--gap)] overflow-hidden p-2 [--duration:40s] [--gap:1rem]',
+				{
+					'flex-row': !vertical,
+					'flex-col': vertical,
+				},
+				className
+			)}
+		>
+			{Array(repeat)
+				.fill(0)
+				.map((_, i) => (
+					<div
+						key={i}
+						className={cn('flex shrink-0 justify-around [gap:var(--gap)]', {
+							'animate-marquee flex-row': !vertical,
+							'animate-marquee-vertical flex-col': vertical,
+							'group-hover:[animation-play-state:paused]': pauseOnHover,
+							'[animation-direction:reverse]': reverse,
+						})}
+					>
+						{children}
+					</div>
+				))}
+		</div>
+	)
+}

packages/website/src/constants.ts

@@ -1,11 +1,10 @@
 // Demo build (auto-init with demo LLM, for quick testing)
 export const CDN_DEMO_URL =
-	'https://cdn.jsdelivr.net/npm/page-agent@1.1.1/dist/iife/page-agent.demo.js'
+	'https://cdn.jsdelivr.net/npm/page-agent@1.4.3/dist/iife/page-agent.demo.js'
 export const CDN_DEMO_CN_URL =
-	'https://registry.npmmirror.com/page-agent/1.1.1/files/dist/iife/page-agent.demo.js'
+	'https://registry.npmmirror.com/page-agent/1.4.3/files/dist/iife/page-agent.demo.js'
 
-// Demo LLM for website testing
+// Demo LLM for website testing (homepage quick trial uses flash)
-export const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+export const DEMO_MODEL = 'qwen3.5-flash'
-export const DEMO_BASE_URL =
+export const DEMO_BASE_URL = 'https://page-ag-testing-ohftxirgbn.cn-shanghai.fcapp.run'
-	'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
+export const DEMO_API_KEY = 'NA'
-export const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'

packages/website/src/index.css

@@ -377,6 +377,24 @@ td {
 			background-position: bottom center;
 		}
 	}
+	--animate-marquee: marquee var(--duration) infinite linear;
+	--animate-marquee-vertical: marquee-vertical var(--duration) linear infinite;
+	@keyframes marquee {
+		from {
+			transform: translateX(0);
+		}
+		to {
+			transform: translateX(calc(-100% - var(--gap)));
+		}
+	}
+	@keyframes marquee-vertical {
+		from {
+			transform: translateY(0);
+		}
+		to {
+			transform: translateY(calc(-100% - var(--gap)));
+		}
+	}
 }
 
 /* shadcn dark mode */

packages/website/src/main.tsx

@@ -1,15 +1,21 @@
 import { createRoot } from 'react-dom/client'
 import { Router } from 'wouter'
-import { useHashLocation } from 'wouter/use-hash-location'
 
 import { LanguageProvider } from './i18n/context'
 import { default as PagesRouter } from './router'
 
 import './index.css'
 
+// Redirect legacy hash routes (e.g. /#/docs/foo) to clean paths
+const { hash } = window.location
+if (hash.length > 1 && hash.includes('/')) {
+	const path = hash.replace(/^#\/?/, '/')
+	history.replaceState(null, '', '/page-agent' + path)
+}
+
 createRoot(document.getElementById('root')!).render(
 	<LanguageProvider>
-		<Router hook={useHashLocation}>
+		<Router base="/page-agent">
 			<PagesRouter />
 		</Router>
 	</LanguageProvider>

packages/website/src/pages/Home.tsx

@@ -1,586 +1,27 @@
-/* eslint-disable react-dom/no-dangerously-set-innerhtml */
+import { Suspense, lazy } from 'react'
-import { Bot, Box, MessageSquare, PlayCircle, Shield, Sparkles, Users, Zap } from 'lucide-react'
-import { useEffect, useState } from 'react'
-import { Link, useSearchParams } from 'wouter'
 
-import Footer from '../components/Footer'
+import HeroSection from './home/HeroSection'
-import Header from '../components/Header'
-import { AnimatedGradientText } from '../components/ui/animated-gradient-text'
-import { Highlighter } from '../components/ui/highlighter'
-import { NeonGradientCard } from '../components/ui/neon-gradient-card'
-import { Particles } from '../components/ui/particles'
-import { SparklesText } from '../components/ui/sparkles-text'
-import {
-	CDN_DEMO_CN_URL,
-	CDN_DEMO_URL,
-	DEMO_API_KEY,
-	DEMO_BASE_URL,
-	DEMO_MODEL,
-} from '../constants'
-import { useLanguage } from '../i18n/context'
 
-function getInjection(useCN?: boolean) {
+const FeaturesSection = lazy(() => import('./home/FeaturesSection'))
-	const cdn = useCN ? CDN_DEMO_CN_URL : CDN_DEMO_URL
+const ScenariosSection = lazy(() => import('./home/ScenariosSection'))
-
+const OneMoreThingSection = lazy(() => import('./home/OneMoreThingSection'))
-	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);})();`
-	)
-
-	return `
-	<a
-		href=${injection}
-		class="inline-flex items-center text-xs px-3 py-2 bg-blue-500 text-white font-medium rounded-lg hover:shadow-md transform hover:scale-105 transition-all duration-200 cursor-move border-2 border-dashed border-green-300"
-		draggable="true"
-		onclick="return false;"
-		title="Drag me to your bookmarks bar!"
-	>
-		✨PageAgent
-	</a>
-	`
-}
 
 export default function HomePage() {
-	const { language, isZh } = useLanguage()
-
-	const defaultTask = isZh
-		? '从导航栏中进入文档页，打开"快速开始"相关的文档，帮我总结成 markdown'
-		: 'Goto docs in navigation bar, find Quick-Start section, and summarize in markdown'
-
-	const [task, setTask] = useState(() => defaultTask)
-
-	// Update task when language changes
-	useEffect(() => {
-		setTask(defaultTask)
-	}, [defaultTask])
-
-	const [params, setParams] = useSearchParams()
-	const isOther = params.has('try_other')
-
-	const [activeTab, setActiveTab] = useState<'try' | 'other'>(isOther ? 'other' : 'try')
-	const [cdnSource, setCdnSource] = useState<'international' | 'china'>('international')
-
-	const handleExecute = async () => {
-		if (!task.trim()) return
-
-		const win = window as any
-
-		// Lazy load PageAgent only when user clicks execute
-		if (!win.pageAgent || win.pageAgent.disposed) {
-			const { PageAgent } = await import('page-agent')
-			win.pageAgent = new PageAgent({
-				// 把 react 根元素排除掉，挂了很多冒泡时间导致假阳
-				interactiveBlacklist: [document.getElementById('root')!],
-				language: language,
-
-				instructions: {
-					system: 'You are a helpful assistant on PageAgent website.',
-					getPageInstructions: (url) => {
-						const hint = url.includes('page-agent') ? 'This is PageAgent demo page.' : undefined
-						console.log('[instructions] getPageInstructions:', url, '->', hint)
-						return hint
-					},
-				},
-
-				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,
-
-				// enableAskUser: false,
-				// promptForNextTask: false,
-				// enablePanel: false,
-			})
-		}
-
-		const result = await win.pageAgent.execute(task)
-		console.log(result)
-	}
-
 	return (
-		<div className="min-h-screen bg-linear-to-br from-blue-50 to-purple-50 dark:from-gray-900 dark:to-gray-800">
+		<>
-			<Header />
+			<HeroSection />
-
+			<Suspense
-			{/* Hero Section */}
+				fallback={
-			<main id="main-content">
+					<div className="flex items-center justify-center gap-3 py-20 text-gray-400">
-				<section
+						<div className="w-4 h-4 border-2 border-blue-500 border-t-transparent rounded-full animate-spin" />
-					className="relative px-6 py-22 pb-18 lg:py-28 overflow-hidden"
+						Loading...
-					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">
-							<div className="absolute inset-0 bg-linear-to-r from-blue-400/20 to-purple-400/20 rounded-3xl transform rotate-1"></div>
-							<div className="absolute inset-0 bg-linear-to-l from-purple-400/20 to-blue-400/20 rounded-3xl transform -rotate-1"></div>
-						</div>
-						<Particles
-							className="absolute inset-0"
-							quantity={80}
-							staticity={30}
-							ease={80}
-							color="#6366f1"
-						/>
-
-						<div className="relative z-10">
-							<div className="inline-flex items-center px-4 py-2 mb-8 text-sm font-medium bg-white/90 dark:bg-gray-800/90 rounded-full shadow-lg border border-gray-200 dark:border-gray-700">
-								<span
-									className="w-2 h-2 bg-blue-500 rounded-full mr-2 animate-pulse"
-									aria-hidden="true"
-								></span>
-								<AnimatedGradientText colorFrom="#3b82f6" colorTo="#8b5cf6">
-									GUI Agent in your webpage
-								</AnimatedGradientText>
-							</div>
-
-							<h1
-								id="hero-heading"
-								className="text-5xl lg:text-7xl font-bold mb-8 bg-linear-to-r from-blue-600 to-purple-600 bg-clip-text text-transparent pb-1"
-							>
-								{isZh ? '让你的 Web 应用' : 'The AI Operator'}
-								<br />
-								{isZh ? '拥有 AI 操作员' : 'Living in Your Web App'}
-							</h1>
-
-							<p className="text-xl lg:text-2xl text-gray-600 dark:text-gray-300 mb-12 max-w-4xl mx-auto leading-relaxed">
-								<Highlighter action="underline" color="#8b5cf6" strokeWidth={2}>
-									<span className="bg-linear-to-r from-blue-500 to-purple-500 bg-clip-text text-transparent font-bold">
-										{isZh ? '🪄一行代码' : '🪄One line of code'}
-									</span>
-								</Highlighter>
-								{isZh
-									? '，为你的网站添加 GUI Agent。'
-									: ' adds intelligent GUI Agents to your website.'}
-								<br />
-								{isZh
-									? '用户/答疑机器人给出文字指示，AI 帮你操作页面。'
-									: 'Users give natural language commands, AI handles the rest.'}
-							</p>
-
-							{/* Try It Now Section - Tab Card */}
-							<div className="mb-12">
-								<div className="max-w-3xl mx-auto">
-									<NeonGradientCard
-										borderSize={2}
-										borderRadius={20}
-										neonColors={{ firstColor: '#ff00aa', secondColor: '#00FFF1' }}
-									>
-										{/* Tab Headers */}
-										<div className="flex border-b border-gray-200 dark:border-gray-700">
-											<button
-												onClick={() => setActiveTab('try')}
-												className={`flex-1 px-4 py-4 text-lg font-medium transition-colors duration-200 rounded-tl-2xl ${
-													activeTab === 'try'
-														? 'bg-linear-to-r from-blue-50 to-purple-50 dark:from-blue-900/30 dark:to-purple-900/30 text-blue-700 dark:text-blue-300 border-b-2 border-blue-500'
-														: 'text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-white hover:bg-gray-50 dark:hover:bg-gray-700'
-												}`}
-											>
-												{isZh ? '🚀 立即尝试' : '🚀 Try It Now'}
-											</button>
-											<button
-												onClick={() => setActiveTab('other')}
-												className={`flex-1 px-4 py-4 text-lg font-medium transition-colors duration-200 rounded-tr-2xl ${
-													activeTab === 'other'
-														? 'bg-linear-to-r from-green-50 to-blue-50 dark:from-green-900/30 dark:to-blue-900/30 text-green-700 dark:text-green-300 border-b-2 border-green-500'
-														: 'text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-white hover:bg-gray-50 dark:hover:bg-gray-700'
-												}`}
-											>
-												{isZh ? '🌐 其他网页尝试' : '🌐 Try on Other Sites'}
-											</button>
-										</div>
-
-										{/* Tab Content */}
-										<div className="p-4">
-											{activeTab === 'try' && (
-												<div className="space-y-4">
-													<div className="relative">
-														<input
-															value={task}
-															onChange={(e) => setTask(e.target.value)}
-															placeholder={
-																isZh
-																	? '输入您想要 AI 执行的任务...'
-																	: 'Describe what you want AI to do...'
-															}
-															className="w-full px-4 py-3 pr-20 border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-700 text-gray-900 dark:text-white placeholder-gray-500 dark:placeholder-gray-400 focus:ring-2 focus:ring-blue-500 focus:border-transparent resize-none text-sm mb-0"
-															data-page-agent-not-interactive
-														/>
-														<button
-															onClick={handleExecute}
-															// disabled
-															// disabled={!task.trim()}
-															className="absolute right-2 top-2 px-5 py-1.5 bg-linear-to-r from-blue-600 to-purple-600 text-white font-medium rounded-md hover:shadow-md transform hover:scale-105 transition-all duration-200 disabled:opacity-50 disabled:cursor-not-allowed disabled:transform-none text-sm"
-															data-page-agent-not-interactive
-														>
-															{isZh ? '执行' : 'Run'}
-														</button>
-													</div>
-												</div>
-											)}
-
-											{activeTab === 'other' && (
-												<div className="grid md:grid-cols-2 gap-6">
-													{/* 左侧：操作步骤 */}
-													<div className="space-y-4">
-														{/* Keyboard Shortcut Hint */}
-														<div className="bg-blue-50 dark:bg-gray-700 p-4 rounded-lg">
-															<p className="text-gray-700 dark:text-gray-300 text-sm mb-3">
-																<span className="font-semibold">
-																	{isZh ? '步骤 1:' : 'Step 1:'}
-																</span>{' '}
-																{isZh ? '显示收藏夹栏' : 'Show your bookmarks bar'}
-															</p>
-															<div className="flex items-center justify-center gap-2">
-																<kbd className="px-2 py-1 bg-white dark:bg-gray-600 border border-gray-300 dark:border-gray-500 rounded text-xs font-mono">
-																	Ctrl + Shift + B
-																</kbd>
-																<span className="text-gray-500 dark:text-gray-400">
-																	{isZh ? '或' : 'or'}
-																</span>
-																<kbd className="px-2 py-1 bg-white dark:bg-gray-600 border border-gray-300 dark:border-gray-500 rounded text-xs font-mono">
-																	⌘ + Shift + B
-																</kbd>
-															</div>
-														</div>
-
-														{/* Draggable Bookmarklet */}
-														<div className="bg-green-50 dark:bg-gray-700 p-4 rounded-lg">
-															<p className="text-gray-700 dark:text-gray-300 text-sm mb-3">
-																<span className="font-semibold">
-																	{isZh ? '步骤 2:' : 'Step 2:'}
-																</span>{' '}
-																{isZh
-																	? '拖拽下面按钮到收藏夹栏'
-																	: 'Drag this button to your bookmarks'}
-															</p>
-															<div className="flex items-center justify-center gap-3">
-																<select
-																	value={cdnSource}
-																	onChange={(e) =>
-																		setCdnSource(e.target.value as 'international' | 'china')
-																	}
-																	className="px-2 py-1.5 text-xs border border-gray-300 dark:border-gray-500 rounded bg-white dark:bg-gray-600 text-gray-700 dark:text-gray-200"
-																>
-																	<option value="international">
-																		{isZh ? '国际' : 'International'}
-																	</option>
-																	<option value="china">
-																		{isZh ? '国内镜像' : 'China Mirror'}
-																	</option>
-																</select>
-																<div
-																	dangerouslySetInnerHTML={{
-																		__html: getInjection(cdnSource === 'china'),
-																	}}
-																></div>
-															</div>
-														</div>
-
-														{/* Usage Instructions */}
-														<div className="bg-purple-50 dark:bg-gray-700 p-4 rounded-lg">
-															<p className="text-gray-700 dark:text-gray-300 text-sm">
-																<span className="font-semibold">
-																	{isZh ? '步骤 3:' : 'Step 3:'}
-																</span>{' '}
-																{isZh
-																	? '在其他网站点击收藏夹中的按钮即可使用'
-																	: 'Click the bookmark on any site to activate'}
-															</p>
-														</div>
-													</div>
-
-													{/* 右侧：注意事项 */}
-													<div className="bg-yellow-50 dark:bg-gray-700 p-4 rounded-lg">
-														<h4 className="font-semibold text-gray-900 dark:text-white mb-3 text-sm">
-															{isZh ? '⚠️ 注意' : '⚠️ Heads Up'}
-														</h4>
-														<ul className="space-y-2 text-sm text-gray-700 dark:text-gray-300">
-															<li className="flex items-start text-left">
-																<span className="w-1.5 h-1.5 bg-yellow-500 rounded-full mt-2 mr-2 shrink-0 "></span>
-																{isZh
-																	? '仅做技术评估，链接定期失效'
-																	: 'Demo only—link may expire without notice'}
-															</li>
-															<li className="flex items-start text-left">
-																<span className="w-1.5 h-1.5 bg-yellow-500 rounded-full mt-2 mr-2 shrink-0 "></span>
-																{isZh
-																	? '使用 DeepSeek 模型，参考 DeepSeek 用户协议和隐私政策'
-																	: 'This free demo uses DeepSeek API (see their terms and privacy policy)'}
-															</li>
-															<li className="flex items-start text-left">
-																<span className="w-1.5 h-1.5 bg-yellow-500 rounded-full mt-2 mr-2 shrink-0 "></span>
-																{isZh
-																	? '部分网站屏蔽了链接嵌入，将无反应'
-																	: 'Some sites block script injection (CSP policies)'}
-															</li>
-															<li className="flex items-start text-left">
-																<span className="w-1.5 h-1.5 bg-yellow-500 rounded-full mt-2 mr-2 shrink-0 "></span>
-																{isZh
-																	? '仅支持单页应用，页面跳转后需要重新注入'
-																	: 'Works on single-page apps only—reload required after navigation'}
-															</li>
-															<li className="flex items-start text-left">
-																<span className="w-1.5 h-1.5 bg-yellow-500 rounded-full mt-2 mr-2 shrink-0 "></span>
-																{isZh
-																	? '仅识别文本，不识别图像，不支持拖拽等复杂交互'
-																	: 'Text-only understanding—no image recognition or drag-and-drop'}
-															</li>
-															<li className="flex items-start text-left">
-																<span className="w-1.5 h-1.5 bg-yellow-500 rounded-full mt-2 mr-2 shrink-0 "></span>
-																{isZh ? '详细使用限制参照' : 'Full limitations in'}{' '}
-																<Link
-																	href="/docs/introduction/limitations"
-																	className="text-blue-600 dark:text-blue-400 hover:underline"
-																>
-																	{isZh ? '《文档》' : 'Docs'}
-																</Link>
-															</li>
-														</ul>
-													</div>
-												</div>
-											)}
-										</div>
-									</NeonGradientCard>
-								</div>
-							</div>
-
-							<ul
-								className="flex flex-wrap justify-center gap-6 text-sm text-gray-500 dark:text-gray-400"
-								role="list"
-							>
-								<li className="flex items-center">
-									<span
-										className="w-2 h-2 bg-green-500 rounded-full mr-2"
-										aria-hidden="true"
-									></span>
-									{isZh ? '纯前端方案' : 'Pure Front-end Solution'}
-								</li>
-								<li className="flex items-center">
-									<span
-										className="w-2 h-2 bg-green-500 rounded-full mr-2"
-										aria-hidden="true"
-									></span>
-									{isZh ? '支持私有模型' : 'Your Own Models'}
-								</li>
-								<li className="flex items-center">
-									<span
-										className="w-2 h-2 bg-green-500 rounded-full mr-2"
-										aria-hidden="true"
-									></span>
-									{isZh ? '无痛脱敏' : 'Built-in Privacy'}
-								</li>
-								<li className="flex items-center">
-									<span
-										className="w-2 h-2 bg-green-500 rounded-full mr-2"
-										aria-hidden="true"
-									></span>
-									{isZh ? 'MIT 开源' : 'MIT Open Source'}
-								</li>
-							</ul>
-						</div>
 					</div>
-				</section>
+				}
-
+			>
-				{/* Features Section */}
+				<FeaturesSection />
-				<section
+				<ScenariosSection />
-					className="px-6 py-20 bg-white/50 dark:bg-gray-800/50 backdrop-blur-sm"
+				<OneMoreThingSection />
-					aria-labelledby="features-heading"
+			</Suspense>
-				>
+		</>
-					<div className="max-w-7xl mx-auto">
-						<div className="grid md:grid-cols-2 lg:grid-cols-4 gap-8" role="list">
-							{/* Feature 1 */}
-							<article
-								className="group p-8 bg-linear-to-br from-blue-100 to-purple-100 dark:from-gray-700 dark:to-gray-800 rounded-2xl shadow-lg hover:shadow-xl transition-all duration-300 border border-gray-100 dark:border-gray-700"
-								role="listitem"
-							>
-								<div
-									className="w-14 h-14 bg-linear-to-br from-blue-500 to-blue-600 rounded-xl flex items-center justify-center mb-6 group-hover:scale-110 group-hover:rotate-3 transition-all duration-300 shadow-lg"
-									aria-hidden="true"
-								>
-									<Box className="w-7 h-7 text-white" strokeWidth={2.5} />
-								</div>
-								<h3 className="text-xl font-bold mb-4 text-gray-900 dark:text-white">
-									{isZh ? '纯页面内方案' : 'In-page Solution'}
-								</h3>
-								<p className="text-gray-600 dark:text-gray-300 leading-relaxed">
-									{isZh
-										? '完全运行在你的页面内。不需要浏览器插件、不需要无头浏览器，不需要后端。'
-										: 'Runs entirely within your page. No browser extensions, no headless browsers, and no backend required.'}
-								</p>
-							</article>
-
-							{/* Feature 2 */}
-							<article
-								className="group p-8 bg-linear-to-br from-purple-100 to-pink-100 dark:from-gray-700 dark:to-gray-800 rounded-2xl shadow-lg hover:shadow-xl transition-all duration-300 border border-gray-100 dark:border-gray-700"
-								role="listitem"
-							>
-								<div
-									className="w-14 h-14 bg-linear-to-br from-green-500 to-green-600 rounded-xl flex items-center justify-center mb-6 group-hover:scale-110 group-hover:rotate-3 transition-all duration-300 shadow-lg"
-									aria-hidden="true"
-								>
-									<Zap className="w-7 h-7 text-white fill-white" strokeWidth={2.5} />
-								</div>
-								<h3 className="text-xl font-bold mb-4 text-gray-900 dark:text-white">
-									{isZh ? '零后端部署' : 'Zero Backend Setup'}
-								</h3>
-								<p className="text-gray-600 dark:text-gray-300 leading-relaxed">
-									{isZh
-										? '前端脚本引入，自定义 LLM 接入点。从 OpenAI 到 qwen3，完全由你掌控。'
-										: 'Just drop in a script. Works with any LLM provider—OpenAI, Anthropic, or your own models.'}
-								</p>
-							</article>
-
-							{/* Feature 3 */}
-							<article
-								className="group p-8 bg-linear-to-br from-orange-100 to-red-100 dark:from-gray-700 dark:to-gray-800 rounded-2xl shadow-lg hover:shadow-xl transition-all duration-300 border border-gray-100 dark:border-gray-700"
-								role="listitem"
-							>
-								<div
-									className="w-14 h-14 bg-linear-to-br from-purple-500 to-purple-600 rounded-xl flex items-center justify-center mb-6 group-hover:scale-110 group-hover:rotate-3 transition-all duration-300 shadow-lg"
-									aria-hidden="true"
-								>
-									<MessageSquare className="w-7 h-7 text-white" strokeWidth={2.5} />
-								</div>
-								<h3 className="text-xl font-bold mb-4 text-gray-900 dark:text-white">
-									{isZh ? '普惠智能交互' : 'Natural Language UI'}
-								</h3>
-								<p className="text-gray-600 dark:text-gray-300 leading-relaxed">
-									{isZh
-										? '为复杂 B端系统、管理后台提供自然语言入口。让每个用户都能轻松上手。'
-										: 'Transform complex admin panels into chat interfaces. Make powerful tools accessible to everyone, not just experts.'}
-								</p>
-							</article>
-
-							{/* Feature 4 */}
-							<article
-								className="group p-8 bg-linear-to-br from-green-100 to-blue-100 dark:from-gray-700 dark:to-gray-800 rounded-2xl shadow-lg hover:shadow-xl transition-all duration-300 border border-gray-100 dark:border-gray-700"
-								role="listitem"
-							>
-								<div
-									className="w-14 h-14 bg-linear-to-br from-orange-500 to-orange-600 rounded-xl flex items-center justify-center mb-6 group-hover:scale-110 group-hover:rotate-3 transition-all duration-300 shadow-lg"
-									aria-hidden="true"
-								>
-									<Shield className="w-7 h-7 text-white" strokeWidth={2.5} />
-								</div>
-								<h3 className="text-xl font-bold mb-4 text-gray-900 dark:text-white">
-									{isZh ? '安全可控集成' : 'Secure by Design'}
-								</h3>
-								<p className="text-gray-600 dark:text-gray-300 leading-relaxed">
-									{isZh
-										? '支持操作黑白名单、数据脱敏保护。注入自定义知识库，让 AI 按你的规则工作。'
-										: 'Control what AI can access with allowlists, data masking, and custom knowledge injection. Your rules, your data.'}
-								</p>
-							</article>
-						</div>
-					</div>
-				</section>
-
-				{/* Use Cases Section */}
-				<section className="px-6 py-20" aria-labelledby="use-cases-heading">
-					<div className="max-w-7xl mx-auto">
-						<div className="text-center mb-16">
-							<SparklesText
-								className="text-4xl lg:text-5xl mb-6"
-								colors={{ first: '#3b82f6', second: '#8b5cf6' }}
-							>
-								{isZh ? '应用场景' : 'Where It Shines'}
-							</SparklesText>
-							<p className="text-xl text-gray-600 dark:text-gray-300 max-w-3xl mx-auto">
-								{isZh
-									? '从简单的表单填写到复杂的业务流程，AI 都能理解并执行'
-									: 'From simple forms to complex workflows, AI understands and executes'}
-							</p>
-						</div>
-
-						<div className="grid lg:grid-cols-2 gap-12" role="list">
-							{/* Use Case 1 */}
-							<div className="group bg-linear-to-br from-blue-100 to-purple-100 dark:from-gray-700 dark:to-gray-800 p-8 rounded-2xl hover:shadow-xl transition-all duration-300">
-								<div className="flex items-start space-x-4">
-									<div className="w-12 h-12 bg-linear-to-br from-blue-500 to-purple-500 rounded-xl flex items-center justify-center shrink-0 group-hover:scale-110 transition-transform duration-300 shadow-md">
-										<Bot className="w-6 h-6 text-white" strokeWidth={2.5} />
-									</div>
-
-									<div>
-										<h3 className="text-xl font-bold mb-2 text-gray-900 dark:text-white">
-											{isZh ? '对接答疑机器人' : 'Supercharge Support Bots'}
-										</h3>
-										<p className="text-gray-600 dark:text-gray-300">
-											{isZh
-												? '把你的答疑助手变成全能Agent。客服机器人不再只说「请先点击设置按钮然后点击...」，而是直接帮用户现场操作。'
-												: 'Stop telling users where to click—let AI do it for them. Turn your chatbot from a guide into an operator that actually completes tasks.'}
-										</p>
-									</div>
-								</div>
-							</div>
-
-							{/* Use Case 2 */}
-							<div className="group bg-linear-to-br from-green-100 to-blue-100 dark:from-gray-700 dark:to-gray-800 p-8 rounded-2xl hover:shadow-xl transition-all duration-300">
-								<div className="flex items-start space-x-4">
-									<div className="w-12 h-12 bg-linear-to-br from-green-500 to-blue-500 rounded-xl flex items-center justify-center shrink-0 group-hover:scale-110 transition-transform duration-300 shadow-md">
-										<Sparkles className="w-6 h-6 text-white" strokeWidth={2.5} />
-									</div>
-									<div>
-										<h3 className="text-xl font-bold mb-2 text-gray-900 dark:text-white">
-											{isZh ? '交互升级/智能化改造' : 'Modernize Legacy Apps'}
-										</h3>
-										<p className="text-gray-600 dark:text-gray-300">
-											{isZh
-												? '一行代码，老应用变身Agent，产品专家帮用户操作复杂 B 端软件。降低人工支持成本，提高用户满意度。'
-												: 'Add AI superpowers to old software without rebuilding. One script tag transforms complex enterprise tools into chat-driven interfaces.'}
-										</p>
-									</div>
-								</div>
-							</div>
-
-							{/* Use Case 3 */}
-							<div className="group bg-linear-to-br from-purple-100 to-pink-100 dark:from-gray-700 dark:to-gray-800 p-8 rounded-2xl hover:shadow-xl transition-all duration-300">
-								<div className="flex items-start space-x-4">
-									<div className="w-12 h-12 bg-linear-to-br from-purple-500 to-pink-500 rounded-xl flex items-center justify-center shrink-0 group-hover:scale-110 transition-transform duration-300 shadow-md">
-										<PlayCircle className="w-6 h-6 text-white fill-white/30" strokeWidth={2.5} />
-									</div>
-									<div>
-										<h3 className="text-xl font-bold mb-2 text-gray-900 dark:text-white">
-											{isZh ? '产品教学' : 'Interactive Walkthroughs'}
-										</h3>
-										<p className="text-gray-600 dark:text-gray-300">
-											{isZh
-												? '向用户演示交互过程，边做边教。例如让AI演示「如何提交报销申请」的完整操作流程。'
-												: "Show, don't tell. Let AI demonstrate workflows in real-time—perfect for onboarding or training new users on complex systems."}
-										</p>
-									</div>
-								</div>
-							</div>
-
-							{/* Use Case 4 */}
-							<div className="group bg-linear-to-br from-orange-100 to-red-100 dark:from-gray-700 dark:to-gray-800 p-8 rounded-2xl hover:shadow-xl transition-all duration-300">
-								<div className="flex items-start space-x-4">
-									<div className="w-12 h-12 bg-linear-to-br from-orange-500 to-red-500 rounded-xl flex items-center justify-center shrink-0 group-hover:scale-110 transition-transform duration-300 shadow-md">
-										<Users className="w-6 h-6 text-white" strokeWidth={2.5} />
-									</div>
-									<div>
-										<h3 className="text-xl font-bold mb-2 text-gray-900 dark:text-white">
-											{isZh ? '无障碍支持' : 'Accessibility First'}
-										</h3>
-										<p className="text-gray-600 dark:text-gray-300">
-											{isZh
-												? '为视障用户、老年用户提供自然语言交互，对接屏幕阅读器或语音助理，让软件人人可用。'
-												: 'Make web apps accessible through natural language. Perfect for screen readers, voice control, or users who find traditional interfaces challenging.'}
-										</p>
-									</div>
-								</div>
-							</div>
-						</div>
-					</div>
-				</section>
-			</main>
-
-			<Footer />
-		</div>
 	)
 }

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

@@ -31,8 +31,8 @@ export default function DocsLayout({ children }: DocsLayoutProps) {
 				{ title: isZh ? '快速开始' : 'Quick Start', path: '/introduction/quick-start' },
 				{ title: isZh ? '使用限制' : 'Limitations', path: '/introduction/limitations' },
 				{
-					title: '🚧 ' + (isZh ? '最佳实践' : 'Best Practices'),
+					title: isZh ? '故障排查' : 'Troubleshooting',
-					path: '/integration/best-practices',
+					path: '/introduction/troubleshooting',
 				},
 			],
 		},
@@ -46,7 +46,7 @@ export default function DocsLayout({ children }: DocsLayoutProps) {
 				{ title: isZh ? 'Chrome 扩展' : 'Chrome Extension', path: '/features/chrome-extension' },
 				{
 					title: isZh ? '接入第三方 Agent' : 'Third-party Agent',
-					path: '/integration/third-party-agent',
+					path: '/features/third-party-agent',
 				},
 			],
 		},
@@ -55,10 +55,11 @@ export default function DocsLayout({ children }: DocsLayoutProps) {
 			items: [
 				{ title: 'PageAgent', path: '/advanced/page-agent' },
 				{ title: 'PageAgentCore', path: '/advanced/page-agent-core' },
+				{ title: 'PageController', path: '/advanced/page-controller' },
 				{ title: isZh ? '自定义 UI' : 'Custom UI', path: '/advanced/custom-ui' },
 				{
 					title: '🚧 ' + (isZh ? '安全与权限' : 'Security & Permissions'),
-					path: '/integration/security-permissions',
+					path: '/advanced/security-permissions',
 				},
 			],
 		},

packages/website/src/pages/docs/advanced/custom-ui/page.tsx

@@ -1,5 +1,6 @@
+import { APIDivider, APIReference } from '@/components/APIReference'
 import CodeEditor from '@/components/CodeEditor'
-import { APIDivider, APIReference } from '@/components/ui/api-reference'
+import { Heading } from '@/components/Heading'
 import { useLanguage } from '@/i18n/context'
 
 export default function CustomUIDocs() {
@@ -17,7 +18,7 @@ export default function CustomUIDocs() {
 
 			{/* Architecture */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{isZh ? '架构' : 'Architecture'}</h2>
+				<Heading id="architecture">{isZh ? '架构' : 'Architecture'}</Heading>
 				<p className="text-gray-600 dark:text-gray-400 mb-4">
 					{isZh
 						? 'PageAgent 由三个独立模块组成，可自由组合：'
@@ -45,7 +46,7 @@ export default function CustomUIDocs() {
 
 			{/* Two Event Streams */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{isZh ? '两个事件流' : 'Two Event Streams'}</h2>
+				<Heading id="two-event-streams">{isZh ? '两个事件流' : 'Two Event Streams'}</Heading>
 				<p className="text-gray-600 dark:text-gray-400 mb-4">
 					{isZh
 						? 'PageAgentCore 提供两种不同性质的事件流，方便 UI 渲染：'
@@ -120,7 +121,7 @@ export default function CustomUIDocs() {
 
 			{/* All Events */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{isZh ? '所有事件' : 'All Events'}</h2>
+				<Heading id="all-events">{isZh ? '所有事件' : 'All Events'}</Heading>
 				<APIReference
 					properties={[
 						{
@@ -155,7 +156,7 @@ export default function CustomUIDocs() {
 
 			{/* HistoricalEvent Types */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">HistoricalEvent</h2>
+				<Heading id="historicalevent">HistoricalEvent</Heading>
 				<p className="text-gray-600 dark:text-gray-400 mb-4">
 					{isZh ? 'agent.history 数组中的事件类型：' : 'Event types in agent.history array:'}
 				</p>
@@ -172,7 +173,7 @@ export default function CustomUIDocs() {
 
 			{/* AgentActivity Types */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">AgentActivity</h2>
+				<Heading id="agentactivity">AgentActivity</Heading>
 				<p className="text-gray-600 dark:text-gray-400 mb-4">
 					{isZh ? 'activity 事件的 detail 类型：' : 'The detail type of activity events:'}
 				</p>
@@ -191,9 +192,7 @@ export default function CustomUIDocs() {
 
 			{/* React Hooks Example */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">
+				<Heading id="using-react-hooks">{isZh ? '使用 React Hooks' : 'Using React Hooks'}</Heading>
-					{isZh ? '使用 React Hooks' : 'Using React Hooks'}
-				</h2>
 				<p className="text-gray-600 dark:text-gray-400 mb-4">
 					{isZh ? '监听事件并更新 React 状态：' : 'Listen to events and update React state:'}
 				</p>
@@ -229,9 +228,9 @@ export default function CustomUIDocs() {
 
 			{/* Assembly Example */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">
+				<Heading id="assembling-core-controller-custom-ui">
 					{isZh ? '组装 Core + Controller + 自定义 UI' : 'Assembling Core + Controller + Custom UI'}
-				</h2>
+				</Heading>
 				<p className="text-gray-600 dark:text-gray-400 mb-4">
 					{isZh
 						? '参考内置 PageAgent 的实现方式，用自定义 UI 替换 Panel：'

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

@@ -1,5 +1,8 @@
+import { Link } from 'wouter'
+
+import { APIDivider, APIReference, TypeRef } from '@/components/APIReference'
 import CodeEditor from '@/components/CodeEditor'
-import { APIDivider, APIReference, TypeRef } from '@/components/ui/api-reference'
+import { Heading } from '@/components/Heading'
 import { useLanguage } from '@/i18n/context'
 
 export default function PageAgentCoreDocs() {
@@ -17,9 +20,9 @@ export default function PageAgentCoreDocs() {
 
 			{/* When to use */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">
+				<Heading id="when-to-use-pageagentcore">
 					{isZh ? '何时使用 PageAgentCore' : 'When to Use PageAgentCore'}
-				</h2>
+				</Heading>
 				<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>
@@ -38,7 +41,7 @@ export default function PageAgentCoreDocs() {
 
 			{/* Basic Usage */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{isZh ? '基本用法' : 'Basic Usage'}</h2>
+				<Heading id="basic-usage">{isZh ? '基本用法' : 'Basic Usage'}</Heading>
 				<CodeEditor
 					language="typescript"
 					code={`import { PageAgentCore } from '@page-agent/core'
@@ -49,19 +52,13 @@ const agent = new PageAgentCore({
   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)
@@ -74,14 +71,54 @@ const result = await agent.execute('Fill in the form with test data')`}
 
 			<APIDivider title={isZh ? '配置' : 'Configuration'} />
 
-			{/* LLM Configuration */}
+			{/* Configuration */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">LLMConfig</h2>
+				<Heading id="configuration">PageAgentCoreConfig</Heading>
 				<p className="text-gray-600 dark:text-gray-400 mb-4">
 					{isZh
-						? '配置与大语言模型的连接参数。支持 OpenAI 兼容的 API。'
+						? 'PageAgentCoreConfig = AgentConfig & { pageController: PageController }。AgentConfig 包含以下配置项：'
-						: 'Configure connection parameters for the language model. Supports OpenAI-compatible APIs.'}
+						: 'PageAgentCoreConfig = AgentConfig & { pageController: PageController }. AgentConfig contains the following options:'}
 				</p>
+
+				{/* PageController */}
+				<h3 className="text-lg font-semibold mt-6 mb-3 text-gray-800 dark:text-gray-200">
+					PageController
+				</h3>
+				<APIReference
+					properties={[
+						{
+							name: 'pageController',
+							type: 'PageController',
+							required: true,
+							description: isZh ? (
+								<>
+									<Link
+										href="/advanced/page-controller"
+										className="text-blue-600 dark:text-blue-400 hover:underline"
+									>
+										PageController
+									</Link>{' '}
+									实例，用于 DOM 操作和元素交互。
+								</>
+							) : (
+								<>
+									<Link
+										href="/advanced/page-controller"
+										className="text-blue-600 dark:text-blue-400 hover:underline"
+									>
+										PageController
+									</Link>{' '}
+									instance for DOM operations and element interaction.
+								</>
+							),
+						},
+					]}
+				/>
+
+				{/* LLM Config */}
+				<h3 className="text-lg font-semibold mt-6 mb-3 text-gray-800 dark:text-gray-200">
+					{isZh ? 'LLM 配置' : 'LLM Config'}
+				</h3>
 				<APIReference
 					properties={[
 						{
@@ -109,7 +146,6 @@ const result = await agent.execute('Fill in the form with test data')`}
 						{
 							name: 'temperature',
 							type: 'number',
-							defaultValue: '0',
 							description: isZh
 								? '模型温度参数，控制输出随机性'
 								: 'Model temperature, controls output randomness',
@@ -129,16 +165,11 @@ const result = await agent.execute('Fill in the form with test data')`}
 						},
 					]}
 				/>
-			</section>
 
-			{/* Agent Configuration */}
+				{/* Agent Config */}
-			<section className="mb-10">
+				<h3 className="text-lg font-semibold mt-6 mb-3 text-gray-800 dark:text-gray-200">
-				<h2 className="text-2xl font-semibold mb-4">AgentConfig</h2>
+					{isZh ? 'Agent 配置' : 'Agent Config'}
-				<p className="text-gray-600 dark:text-gray-400 mb-4">
+				</h3>
-					{isZh
-						? '配置 Agent 的行为、生命周期钩子和扩展能力。'
-						: 'Configure agent behavior, lifecycle hooks, and extension capabilities.'}
-				</p>
 				<APIReference
 					properties={[
 						{
@@ -165,8 +196,8 @@ const result = await agent.execute('Fill in the form with test data')`}
 							name: 'instructions',
 							type: 'InstructionsConfig',
 							description: isZh
-								? '指导 Agent 行为的指令配置'
+								? '指导 Agent 行为的指令配置，见下方类型定义'
-								: 'Instructions to guide agent behavior',
+								: 'Instructions to guide agent behavior, see type definition below',
 						},
 						{
 							name: 'transformPageContent',
@@ -176,7 +207,15 @@ const result = await agent.execute('Fill in the form with test data')`}
 								: 'Transform page content before sending to LLM, useful for data masking',
 						},
 						{
-							name: 'experimentalScriptExecutionTool',
+							name: 'customSystemPrompt',
+							type: 'string',
+							status: 'experimental',
+							description: isZh
+								? '完全覆盖默认系统提示词。谨慎使用。'
+								: 'Completely override the default system prompt. Use with caution.',
+						},
+						{
+							name: 'experimentalScript\nExecutionTool',
 							type: 'boolean',
 							defaultValue: 'false',
 							status: 'experimental',
@@ -184,134 +223,58 @@ const result = await agent.execute('Fill in the form with test data')`}
 								? '启用实验性 JavaScript 执行工具'
 								: 'Enable experimental JavaScript execution tool',
 						},
-					]}
-				/>
-
-				<h3 className="text-lg font-semibold mt-6 mb-3">InstructionsConfig</h3>
-				<APIReference
-					properties={[
 						{
-							name: 'system',
+							name: 'experimentalLlmsTxt',
-							type: 'string',
+							type: 'boolean',
+							defaultValue: 'false',
+							status: 'experimental',
 							description: isZh
-								? '全局系统级指令，应用于所有任务'
+								? '从当前站点根目录获取 /llms.txt 并作为上下文提供给 LLM'
-								: 'Global system-level instructions, applied to all tasks',
+								: 'Fetch /llms.txt from site origin and include as LLM context',
-						},
-						{
-							name: 'getPageInstructions',
-							type: '(url: string) => string | undefined | null',
-							description: isZh
-								? '动态页面级指令回调，在每个步骤前调用'
-								: 'Dynamic page-level instructions callback, called before each step',
 						},
 					]}
 				/>
-			</section>
 
-			{/* Lifecycle Hooks */}
+				{/* Lifecycle Hooks */}
-			<section className="mb-10">
+				<h3 className="text-lg font-semibold mt-6 mb-3 text-gray-800 dark:text-gray-200">
-				<h2 className="text-2xl font-semibold mb-4">{isZh ? '生命周期钩子' : 'Lifecycle Hooks'}</h2>
+					{isZh ? '生命周期钩子' : 'Lifecycle Hooks'}
+					<span className="ml-2 text-xs font-normal text-amber-600 dark:text-amber-400">
+						experimental
+					</span>
+				</h3>
 				<div className="bg-amber-50 dark:bg-amber-900/20 border border-amber-200 dark:border-amber-800 rounded-lg p-4 mb-4">
 					<p className="text-amber-800 dark:text-amber-200 text-sm">
-						<strong>⚠️ {isZh ? '警告' : 'Warning'}:</strong>{' '}
 						{isZh
-							? '这些接口高度实验性，可能在未来版本中发生变化。建议优先使用事件系统（Events）来监听 Agent 状态。'
+							? '这些接口高度实验性，可能在未来版本中发生变化。'
-							: 'These APIs are highly experimental and may change in future versions. Prefer using the Events system for monitoring agent state.'}
+							: 'These APIs are highly experimental and may change in future versions. '}
 					</p>
 				</div>
-				<p className="text-gray-600 dark:text-gray-400 mb-4">
-					{isZh
-						? '所有生命周期钩子都接收 agent 实例作为第一个参数，便于在回调中访问 Agent 状态和方法。'
-						: 'All lifecycle hooks receive the agent instance as first parameter, making it easy to access agent state and methods in callbacks.'}
-				</p>
 				<APIReference
 					properties={[
 						{
 							name: 'onBeforeStep',
-							type: '(agent: PageAgentCore, stepCount: number) => void | Promise<void>',
+							type: '(agent, stepCount) => void | Promise<void>',
 							description: isZh ? '每个步骤执行前调用' : 'Called before each step execution',
-							status: 'experimental',
 						},
 						{
 							name: 'onAfterStep',
-							type: '(agent: PageAgentCore, history: HistoricalEvent[]) => void | Promise<void>',
+							type: '(agent, history) => void | Promise<void>',
 							description: isZh ? '每个步骤执行后调用' : 'Called after each step execution',
-							status: 'experimental',
 						},
 						{
 							name: 'onBeforeTask',
-							type: '(agent: PageAgentCore) => void | Promise<void>',
+							type: '(agent) => void | Promise<void>',
 							description: isZh ? '任务开始前调用' : 'Called before task starts',
-							status: 'experimental',
 						},
 						{
 							name: 'onAfterTask',
-							type: '(agent: PageAgentCore, result: ExecutionResult) => void | Promise<void>',
+							type: '(agent, result) => void | Promise<void>',
 							description: isZh ? '任务结束后调用' : 'Called after task ends',
-							status: 'experimental',
 						},
 						{
 							name: 'onDispose',
-							type: '(agent: PageAgentCore, reason?: string) => void',
+							type: '(agent, reason?) => 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: 'includeAttributes',
-							type: 'string[]',
-							description: isZh
-								? '在 DOM 提取中包含的额外属性'
-								: 'Additional attributes to include in DOM extraction',
 						},
 					]}
 				/>
@@ -321,7 +284,7 @@ const result = await agent.execute('Fill in the form with test data')`}
 
 			{/* Properties */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{isZh ? '属性' : 'Properties'}</h2>
+				<Heading id="properties">{isZh ? '属性' : 'Properties'}</Heading>
 				<APIReference
 					properties={[
 						{
@@ -366,25 +329,26 @@ const result = await agent.execute('Fill in the form with test data')`}
 
 			{/* Methods */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{isZh ? '方法' : 'Methods'}</h2>
+				<Heading id="methods">{isZh ? '方法' : 'Methods'}</Heading>
 				<APIReference
+					variant="methods"
 					properties={[
 						{
-							name: 'execute(task: string)',
+							name: 'execute(task)',
 							type: 'Promise<ExecutionResult>',
 							description: isZh
 								? '执行任务并返回结果。包含 success、data 和 history 字段。'
 								: 'Execute a task and return result. Contains success, data, and history fields.',
 						},
 						{
-							name: 'pushObservation(content: string)',
+							name: 'stop()',
 							type: 'void',
 							description: isZh
-								? '向历史流推送一个观察事件，会在下一步时被 LLM 看到'
+								? '停止当前任务。Agent 仍可复用。'
-								: 'Push an observation to history stream, will be seen by LLM in next step',
+								: 'Stop the current task. Agent remains reusable.',
 						},
 						{
-							name: 'dispose(reason?: string)',
+							name: 'dispose()',
 							type: 'void',
 							description: isZh
 								? '销毁 Agent 并清理资源'
@@ -396,7 +360,7 @@ const result = await agent.execute('Fill in the form with test data')`}
 
 			{/* Events */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{isZh ? '事件' : 'Events'}</h2>
+				<Heading id="events">{isZh ? '事件' : 'Events'}</Heading>
 				<p className="text-gray-600 dark:text-gray-400 mb-4">
 					{isZh ? (
 						<>
@@ -445,15 +409,12 @@ const result = await agent.execute('Fill in the form with test data')`}
 
 			{/* ExecutionResult */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">ExecutionResult</h2>
+				<Heading id="executionresult">ExecutionResult</Heading>
 				<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[]
 }`}
 				/>
@@ -461,7 +422,7 @@ const result = await agent.execute('Fill in the form with test data')`}
 
 			{/* AgentActivity */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">AgentActivity</h2>
+				<Heading id="agentactivity">AgentActivity</Heading>
 				<CodeEditor
 					language="typescript"
 					code={`type AgentActivity =
@@ -473,50 +434,21 @@ const result = await agent.execute('Fill in the form with test data')`}
 				/>
 			</section>
 
-			<APIDivider title={isZh ? '无头模式' : 'Headless Mode'} />
+			{/* InstructionsConfig */}
-
-			{/* Headless Usage */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{isZh ? '无头模式' : 'Headless Mode'}</h2>
+				<Heading id="instructionsconfig">InstructionsConfig</Heading>
-				<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'
+					code={`interface InstructionsConfig {
-import type { PageController } from '@page-agent/page-controller'
+  /** Global system-level instructions, applied to all tasks */
+  system?: string
 
-class MyRemotePageController implements PageController {
+  /**
-  // Implement required methods for DOM extraction and interaction
+   * Dynamic page-level instructions callback.
-}
+   * Called before each step to get instructions for the current page.
-
+   */
-const agent = new PageAgentCore({
+  getPageInstructions?: (url: string) => string | undefined
-  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

@@ -1,7 +1,7 @@
 import { Link } from 'wouter'
 
 import CodeEditor from '@/components/CodeEditor'
-import { APIReference, TypeRef } from '@/components/ui/api-reference'
+import { Heading } from '@/components/Heading'
 import { useLanguage } from '@/i18n/context'
 
 export default function PageAgentDocs() {
@@ -13,21 +13,26 @@ export default function PageAgentDocs() {
 
 			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
 				{isZh
-					? 'PageAgent 是带有内置 UI 面板的完整 Agent 类。它继承自 PageAgentCore，并自动创建交互面板。'
+					? 'PageAgent 是带有内置 UI 面板的完整 Agent 类。它继承自 PageAgentCore，并自动创建交互面板和 PageController。'
-					: 'PageAgent is the complete Agent class with built-in UI panel. It extends PageAgentCore and automatically creates an interactive panel.'}
+					: 'PageAgent is the complete Agent class with built-in UI panel. It extends PageAgentCore and automatically creates an interactive panel and PageController.'}
 			</p>
 
 			{/* When to use */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">
+				<Heading id="when-to-use-pageagent">
 					{isZh ? '何时使用 PageAgent' : 'When to Use PageAgent'}
-				</h2>
+				</Heading>
 				<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
+							? '自动创建 PageController，处理 DOM 提取和元素操作'
+							: 'Automatically creates PageController for DOM extraction and element actions'}
+					</li>
 					<li>
 						{isZh
 							? '内置 UI 面板，显示任务进度、Agent 思考过程和操作结果'
@@ -43,7 +48,7 @@ export default function PageAgentDocs() {
 
 			{/* Basic Usage */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{isZh ? '基本用法' : 'Basic Usage'}</h2>
+				<Heading id="basic-usage">{isZh ? '基本用法' : 'Basic Usage'}</Heading>
 				<CodeEditor
 					language="typescript"
 					code={`import { PageAgent } from 'page-agent'
@@ -69,13 +74,12 @@ console.log(result.history) // Full execution history`}
 
 			{/* Class Definition */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{isZh ? '类定义' : 'Class Definition'}</h2>
+				<Heading id="class-definition">{isZh ? '类定义' : 'Class Definition'}</Heading>
 				<CodeEditor
 					language="typescript"
 					code={`class PageAgent extends PageAgentCore {
-  /** The UI panel instance */
   panel: Panel
-
+  pageController: PageController
   constructor(config: PageAgentConfig)
 }`}
 				/>
@@ -89,7 +93,21 @@ console.log(result.history) // Full execution history`}
 							>
 								PageAgentCore
 							</Link>
-							，所有核心方法和事件都可用。详细的 API 参考请查看 PageAgentCore 文档。
+							，所有核心方法和事件都可用。配置项合并了{' '}
+							<Link
+								href="/advanced/page-agent-core#configuration"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								AgentConfig
+							</Link>{' '}
+							和{' '}
+							<Link
+								href="/advanced/page-controller#configuration"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								PageControllerConfig
+							</Link>
+							。
 						</>
 					) : (
 						<>
@@ -100,71 +118,34 @@ console.log(result.history) // Full execution history`}
 							>
 								PageAgentCore
 							</Link>
-							. All core methods and events are available. See PageAgentCore docs for detailed API
+							. All core methods and events are available. Config merges{' '}
-							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"
+								href="/advanced/page-agent-core#configuration"
 								className="text-blue-600 dark:text-blue-400 hover:underline"
 							>
-								PageAgentCore 配置文档
+								AgentConfig
-							</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.
+							and{' '}
+							<Link
+								href="/advanced/page-controller#configuration"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								PageControllerConfig
+							</Link>
+							.
 						</>
 					)}
 				</p>
 			</section>
 
-			{/* Panel Property */}
+			{/* Panel */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">{isZh ? 'Panel 属性' : 'Panel Property'}</h2>
+				<Heading id="panel">{isZh ? 'UI 面板' : 'UI Panel'}</Heading>
 				<p className="text-gray-600 dark:text-gray-400 mb-4">
 					{isZh
-						? 'PageAgent 自动创建一个 Panel 实例。你可以通过 panel 属性访问它来控制 UI：'
+						? 'PageAgent 自动创建一个 Panel 实例。你可以通过 panel 属性控制 UI：'
-						: 'PageAgent automatically creates a Panel instance. You can access it via the panel property to control the UI:'}
+						: 'PageAgent automatically creates a Panel instance. You can control the UI via the panel property:'}
 				</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
@@ -185,9 +166,9 @@ agent.panel.dispose()`}
 
 			{/* Comparison with PageAgentCore */}
 			<section className="mb-10">
-				<h2 className="text-2xl font-semibold mb-4">
+				<Heading id="pageagent-vs-pageagentcore">
 					{isZh ? 'PageAgent vs PageAgentCore' : 'PageAgent vs PageAgentCore'}
-				</h2>
+				</Heading>
 				<div className="overflow-hidden rounded-lg border border-gray-200 dark:border-gray-700">
 					<table className="w-full text-sm">
 						<thead>
@@ -211,16 +192,16 @@ agent.panel.dispose()`}
 							</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'}
+									{isZh ? '自动创建 PageController' : 'Auto-creates PageController'}
 								</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>
+								<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 ? '自定义 PageController' : 'Custom PageController'}
+									{isZh ? 'Headless 模式' : 'Headless Mode'}
 								</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>
 								<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">

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

@@ -0,0 +1,286 @@
+import { Link } from 'wouter'
+
+import { APIDivider, APIReference } from '@/components/APIReference'
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+export default function PageControllerDocs() {
+	const { isZh } = useLanguage()
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">PageController</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? 'PageController 负责 DOM 提取和元素交互，独立于 LLM。它将页面状态结构化为 LLM 可消费的格式，并执行元素级操作。'
+					: 'PageController handles DOM extraction and element interaction, independent of LLM. It structures page state into LLM-consumable format and executes element-level actions.'}
+			</p>
+
+			{/* Basic Usage */}
+			<section className="mb-10">
+				<Heading id="basic-usage">{isZh ? '基本用法' : 'Basic Usage'}</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? 'PageAgent 接受 PageController 配置项：'
+						: 'PageAgent accepts PageController options:'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`import { PageAgent } from 'page-agent'
+
+const agent = new PageAgent({
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: 'your-api-key',
+  model: 'gpt-5.2',
+
+  // PageController options
+  enableMask: true,
+  viewportExpansion: 0,
+})`}
+				/>
+				<p className="text-gray-600 dark:text-gray-400 mt-4">
+					{isZh
+						? 'PageAgentCore 接受 PageController 实例：'
+						: 'PageAgentCore accepts a PageController instance:'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`import { PageAgentCore } from '@page-agent/core'
+import { PageController } from '@page-agent/page-controller'
+
+const pageController = new PageController({
+  enableMask: true,
+  viewportExpansion: -1,  // extract full page
+})
+
+const agent = new PageAgentCore({
+  pageController,
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: 'your-api-key',
+  model: 'gpt-5.2',
+})`}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '配置' : 'Configuration'} />
+
+			{/* Configuration */}
+			<section className="mb-10">
+				<Heading id="configuration">PageControllerConfig</Heading>
+				<APIReference
+					properties={[
+						{
+							name: 'enableMask',
+							type: 'boolean',
+							defaultValue: 'false',
+							description: isZh
+								? '启用视觉遮罩覆盖层，在自动化期间阻止用户操作页面。通过 PageAgent 创建时默认为 true。'
+								: 'Enable visual mask overlay that blocks user interaction during automation. Defaults to true when created via PageAgent.',
+						},
+						{
+							name: 'viewportExpansion',
+							type: 'number',
+							defaultValue: '0',
+							description: isZh
+								? '向视口外扩展提取的像素数。设为 -1 表示提取整个页面。'
+								: 'Pixels to expand extraction beyond viewport. Set to -1 to extract the entire page.',
+						},
+						{
+							name: 'interactiveBlacklist',
+							type: '(Element | (() => Element))[]',
+							description: isZh
+								? '要排除的交互元素列表。支持元素引用或返回元素的函数（延迟求值）。'
+								: 'Elements to exclude from interaction. Supports element references or functions returning elements (lazy evaluation).',
+						},
+						{
+							name: 'interactiveWhitelist',
+							type: '(Element | (() => Element))[]',
+							description: isZh
+								? '要强制包含的交互元素列表。支持元素引用或返回元素的函数。'
+								: 'Elements to force include for interaction. Supports element references or functions returning elements.',
+						},
+						{
+							name: 'includeAttributes',
+							type: 'string[]',
+							description: isZh
+								? '在 DOM 提取中包含的额外 HTML 属性（如 data-testid）。默认已包含常见属性如 role, aria-label 等。'
+								: 'Additional HTML attributes to include in DOM extraction (e.g. data-testid). Common attributes like role, aria-label are included by default.',
+						},
+					]}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '方法' : 'Methods'} />
+
+			{/* Methods */}
+			<section className="mb-10">
+				<Heading id="methods">{isZh ? '方法' : 'Methods'}</Heading>
+
+				<h3 className="text-lg font-semibold mt-6 mb-3">{isZh ? '状态查询' : 'State Queries'}</h3>
+				<APIReference
+					variant="methods"
+					properties={[
+						{
+							name: 'getBrowserState()',
+							type: 'Promise<BrowserState>',
+							description: isZh
+								? '获取结构化的浏览器状态（URL、标题、简化 HTML 等），自动调用 updateTree() 刷新 DOM。这是 Agent 在每步使用的主要方法。'
+								: 'Get structured browser state (URL, title, simplified HTML, etc.), automatically calls updateTree() to refresh DOM. This is the primary method the agent uses each step.',
+						},
+						{
+							name: 'updateTree()',
+							type: 'Promise<string>',
+							description: isZh
+								? '刷新 DOM 树并返回简化 HTML。通常不需要手动调用 —— getBrowserState() 会自动调用。'
+								: 'Refresh DOM tree and return simplified HTML. Usually not needed manually — getBrowserState() calls it automatically.',
+						},
+						{
+							name: 'getCurrentUrl()',
+							type: 'Promise<string>',
+							description: isZh ? '获取当前页面 URL。' : 'Get current page URL.',
+						},
+					]}
+				/>
+
+				<h3 className="text-lg font-semibold mt-6 mb-3">{isZh ? '元素操作' : 'Element Actions'}</h3>
+				<APIReference
+					variant="methods"
+					properties={[
+						{
+							name: 'clickElement(index)',
+							type: 'Promise<ActionResult>',
+							description: isZh
+								? '按索引点击元素。索引来自简化 HTML 中的 [N] 标记。'
+								: 'Click element by index. Index comes from [N] markers in simplified HTML.',
+						},
+						{
+							name: 'inputText(index, text)',
+							type: 'Promise<ActionResult>',
+							description: isZh ? '向输入框元素填入文本。' : 'Input text into a form element.',
+						},
+						{
+							name: 'selectOption(index, optionText)',
+							type: 'Promise<ActionResult>',
+							description: isZh ? '在下拉框中选择选项。' : 'Select option in a dropdown element.',
+						},
+						{
+							name: 'scroll(options)',
+							type: 'Promise<ActionResult>',
+							description: isZh
+								? '垂直滚动页面或指定元素。'
+								: 'Scroll page or specific element vertically.',
+						},
+						{
+							name: 'scrollHorizontally(options)',
+							type: 'Promise<ActionResult>',
+							description: isZh
+								? '水平滚动页面或指定元素。'
+								: 'Scroll page or specific element horizontally.',
+						},
+					]}
+				/>
+
+				<h3 className="text-lg font-semibold mt-6 mb-3">{isZh ? '遮罩控制' : 'Mask Control'}</h3>
+				<APIReference
+					variant="methods"
+					properties={[
+						{
+							name: 'showMask()',
+							type: 'Promise<void>',
+							description: isZh
+								? '显示视觉遮罩。需要 enableMask: true。'
+								: 'Show visual mask overlay. Requires enableMask: true.',
+						},
+						{
+							name: 'hideMask()',
+							type: 'Promise<void>',
+							description: isZh ? '隐藏视觉遮罩。' : 'Hide visual mask overlay.',
+						},
+					]}
+				/>
+
+				<h3 className="text-lg font-semibold mt-6 mb-3">{isZh ? '生命周期' : 'Lifecycle'}</h3>
+				<APIReference
+					variant="methods"
+					properties={[
+						{
+							name: 'dispose()',
+							type: 'void',
+							description: isZh
+								? '清理所有资源（DOM 高亮、遮罩等）。Agent 销毁时自动调用。'
+								: 'Clean up all resources (DOM highlights, mask, etc.). Called automatically when agent disposes.',
+						},
+					]}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '类型定义' : 'Type Definitions'} />
+
+			{/* BrowserState */}
+			<section className="mb-10">
+				<Heading id="browser-state">BrowserState</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? 'getBrowserState() 返回的结构化浏览器状态，直接用于构建 LLM prompt。'
+						: 'Structured browser state returned by getBrowserState(), used directly to build LLM prompts.'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`interface BrowserState {
+  url: string
+  title: string
+  header: string   // page info + scroll position
+  content: string  // simplified HTML of interactive elements
+  footer: string   // scroll hint
+}`}
+				/>
+			</section>
+
+			{/* ActionResult */}
+			<section className="mb-10">
+				<Heading id="action-result">ActionResult</Heading>
+				<CodeEditor
+					language="typescript"
+					code={`interface ActionResult {
+  success: boolean
+  message: string
+}`}
+				/>
+			</section>
+
+			{/* Custom PageController */}
+			<section className="mb-10">
+				<Heading id="custom-implementation">
+					{isZh ? '自定义实现' : 'Custom Implementation'}
+				</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '在非浏览器环境（如 Puppeteer、Playwright），你可以实现自定义 PageController。需要实现 Agent 使用的核心方法：'
+						: 'In non-browser environments (e.g. Puppeteer, Playwright), you can implement a custom PageController. Implement the core methods used by the agent:'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`import { PageAgentCore } from '@page-agent/core'
+import type { PageController } from '@page-agent/page-controller'
+
+class PuppeteerPageController implements PageController {
+  async getBrowserState() { /* ... */ }
+  async clickElement(index: number) { /* ... */ }
+  async inputText(index: number, text: string) { /* ... */ }
+  async scroll(options: { down: boolean; numPages: number }) { /* ... */ }
+  // ... other methods
+}
+
+const agent = new PageAgentCore({
+  pageController: new PuppeteerPageController(),
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: 'your-api-key',
+  model: 'gpt-5.2',
+})`}
+				/>
+			</section>
+		</div>
+	)
+}

packages/website/src/pages/docs/advanced/security-permissions/page.tsx

@@ -1,4 +1,5 @@
 import BetaNotice from '@/components/BetaNotice'
+import { Heading } from '@/components/Heading'
 import { useLanguage } from '@/i18n/context'
 
 export default function SecurityPermissions() {
@@ -18,9 +19,9 @@ export default function SecurityPermissions() {
 
 			<div className="space-y-6">
 				<section>
-					<h2 className="text-2xl font-bold mb-3">
+					<Heading id="element-interaction-allowlist-blocklist" className="text-2xl font-bold mb-3">
 						{isZh ? '元素操作黑白名单' : 'Element Interaction Allowlist/Blocklist'}
-					</h2>
+					</Heading>
 					<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">
@@ -46,9 +47,9 @@ export default function SecurityPermissions() {
 				</section>
 
 				<section>
-					<h2 className="text-2xl font-bold mb-3">
+					<Heading id="instruction-safety-constraints" className="text-2xl font-bold mb-3">
 						{isZh ? 'Instruction 安全约束' : 'Instruction Safety Constraints'}
-					</h2>
+					</Heading>
 					<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">
 							⚠️ {isZh ? '高危操作控制' : 'High-Risk Operation Control'}

packages/website/src/pages/docs/features/chrome-extension/page.tsx

@@ -1,11 +1,14 @@
-import { siGithub } from 'simple-icons'
+import { siChromewebstore, siGithub } from 'simple-icons'
 
-import BetaNotice from '@/components/BetaNotice'
 import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
 import { useLanguage } from '@/i18n/context'
 
 export default function ChromeExtension() {
 	const { isZh } = useLanguage()
+	const chromeWebStoreUrl =
+		'https://chromewebstore.google.com/detail/page-agent-ext/akldabonmimlicnjlflnapfeklbfemhj'
+	const githubReleasesUrl = 'https://github.com/alibaba/page-agent/releases'
 
 	return (
 		<div>
@@ -13,105 +16,132 @@ export default function ChromeExtension() {
 
 			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
 				{isZh
-					? '可选的 Chrome 扩展，解锁多页任务和第三方 API 集成。'
+					? '可选的 Chrome 扩展。PageAgent.js 继续负责页面内自动化；扩展 API 额外提供多页面任务、浏览器级控制，以及从浏览器外部发起任务的能力。'
-					: 'Optional Chrome extension that unlocks multi-page tasks and third-party API integration.'}
+					: 'An optional Chrome extension. PageAgent.js keeps handling in-page automation, while the extension API adds multi-page tasks, browser-level control, and tasks initiated from outside the browser.'}
 			</p>
 
-			<BetaNotice />
-
 			<div className="space-y-8 mt-8">
-				{/* Hero Section */}
-				<section className="p-6 bg-linear-to-r from-blue-50 to-purple-50 dark:from-blue-900/20 dark:to-purple-900/20 rounded-xl">
-					<div className="flex items-start gap-4">
-						<div>
-							<p className="text-gray-600 dark:text-gray-300">
-								{isZh
-									? '解锁多页任务！借助 Chrome 扩展，Agent 可以跨标签页和页面导航，突破单页限制。'
-									: 'Unlock multi-page tasks! With the Chrome extension, your agent can navigate across tabs and pages, breaking the single-page limitation.'}
-							</p>
-						</div>
-					</div>
-				</section>
-
 				{/* Features */}
 				<section>
-					<h2 className="text-2xl font-bold mb-4">{isZh ? '核心特性' : 'Key Features'}</h2>
+					<Heading id="key-features" className="text-2xl font-bold mb-4">
-					<div className="grid md:grid-cols-2 gap-4">
+						{isZh ? '核心特性' : 'Key Features'}
+					</Heading>
+					<div className="grid md:grid-cols-3 gap-4">
 						<div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg">
 							<h3 className="font-semibold mb-2">🔓 {isZh ? '多页任务' : 'Multi-Page Tasks'}</h3>
 							<p className="text-gray-600 dark:text-gray-300 text-sm">
 								{isZh
-									? '跨多个页面和标签页执行任务，不再局限于单页操作。'
+									? '跨多个页面和标签页连续执行任务，不再受限于单页上下文。'
-									: 'Execute tasks across multiple pages and tabs. No longer limited to single-page operations.'}
+									: 'Run tasks across multiple pages and tabs without being limited to a single page context.'}
 							</p>
 						</div>
 						<div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg">
 							<h3 className="font-semibold mb-2">
-								🔌 {isZh ? '开放第三方接口' : 'Third-Party API'}
+								🧭 {isZh ? '浏览器级控制' : 'Browser-Level Control'}
 							</h3>
 							<p className="text-gray-600 dark:text-gray-300 text-sm">
 								{isZh
-									? '用户授权后，你的网页、本地 Agent 或云端 Agent 都能通过扩展操作用户浏览器！'
+									? '支持跨标签导航、页面切换和更完整的浏览器自动化能力。'
-									: 'After user authorization, your webpage, local agent, or cloud agent can control the browser through the extension.'}
+									: 'Enable richer browser automation, including cross-tab navigation and page switching.'}
+							</p>
+						</div>
+						<div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg">
+							<h3 className="font-semibold mb-2">
+								🔌 {isZh ? '开放集成接口' : 'Open Integration API'}
+							</h3>
+							<p className="text-gray-600 dark:text-gray-300 text-sm">
+								{isZh
+									? '用户主动授权后，页面 JS、本地 Agent 或云端 Agent 可通过扩展发起多页面任务。'
+									: 'With explicit user authorization, page JS, local agents, or cloud agents can trigger multi-page tasks through the extension.'}
 							</p>
 						</div>
 					</div>
 				</section>
 
-				{/* Download */}
+				{/* Install */}
 				<section>
-					<h2 className="text-2xl font-bold mb-4">{isZh ? '下载测试版' : 'Download Beta'}</h2>
+					<Heading id="get-the-extension" className="text-2xl font-bold mb-4">
-					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh ? '获取扩展' : 'Get the Extension'}
-						{isZh
+					</Heading>
-							? '扩展目前处于 Beta 阶段，请从 GitHub Releases 下载最新版本。'
+					<div className="flex flex-wrap gap-3">
-							: 'The extension is currently in beta. Download the latest version from GitHub Releases.'}
+						<a
-					</p>
+							href={chromeWebStoreUrl}
-					<a
+							target="_blank"
-						href="https://github.com/alibaba/page-agent/releases"
+							rel="noopener noreferrer"
-						target="_blank"
+							className="inline-flex items-center gap-2 px-6 py-3 bg-blue-600 hover:bg-blue-700 text-white! font-medium rounded-lg transition-colors"
-						rel="noopener noreferrer"
+						>
-						className="inline-flex items-center gap-2 px-6 py-3 bg-blue-600 hover:bg-blue-700 text-white font-medium rounded-lg transition-colors"
+							<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
-					>
+								<path d={siChromewebstore.path} />
-						<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+							</svg>
-							<path d={siGithub.path} />
+							{isZh ? '从 Chrome 应用商店安装' : 'Install from Chrome Web Store'}
-						</svg>
+						</a>
-						{isZh ? '前往 GitHub Releases 下载' : 'Download from GitHub Releases'}
+						<a
-					</a>
+							href={githubReleasesUrl}
+							target="_blank"
+							rel="noopener noreferrer"
+							className="inline-flex items-center gap-2 px-6 py-3 bg-gray-900 hover:bg-gray-800 dark:bg-gray-700 dark:hover:bg-gray-600 text-white! font-medium rounded-lg transition-colors"
+						>
+							<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+								<path d={siGithub.path} />
+							</svg>
+							{isZh ? 'GitHub Releases（更新版本）' : 'GitHub Releases (faster updates)'}
+						</a>
+					</div>
+				</section>
+
+				{/* Relationship with PageAgent.js */}
+				<section>
+					<Heading id="how-it-relates-to-page-agent-js" className="text-2xl font-bold mb-4">
+						{isZh ? '与 PageAgent.js 的关系' : 'How It Relates to PageAgent.js'}
+					</Heading>
+					<div className="p-5 bg-gray-50 dark:bg-gray-800 rounded-lg space-y-3 text-gray-600 dark:text-gray-300">
+						<p>
+							{isZh
+								? 'PageAgent.js 本身即可在页面内完成自动化。Chrome 扩展是可选的能力扩展。'
+								: 'PageAgent.js already works for in-page automation. The Chrome extension is optional, not a dependency.'}
+						</p>
+						<p>
+							{isZh
+								? '通过扩展，你可以执行多页面任务、控制浏览器，以及从浏览器外部（本地服务或云端服务）发起任务。'
+								: 'With the extension, you can perform multi-page tasks, browser-level control, and tasks triggered outside the browser (local or cloud services).'}
+						</p>
+					</div>
 				</section>
 
 				{/* Third-party Integration */}
 				<section>
-					<h2 className="text-2xl font-bold mb-4">
+					<Heading id="third-party-integration" className="text-2xl font-bold mb-4">
 						{isZh ? '第三方接入' : 'Third-Party Integration'}
-					</h2>
+					</Heading>
 					<p className="text-gray-600 dark:text-gray-300 mb-4">
 						{isZh
-							? '用户授权后，外部应用可以调用扩展 API 来控制浏览器。'
+							? '通过页面 JavaScript 调用 `window.PAGE_AGENT_EXT`，你的应用可以发起跨页面任务并控制浏览器行为。'
-							: 'After user authorization, external applications can call the extension API to control the browser.'}
+							: 'By calling `window.PAGE_AGENT_EXT` from page JavaScript, your app can trigger multi-page tasks and control browser behavior.'}
 					</p>
 
-					{/* Auth Flow */}
+					<h3 className="text-xl font-semibold mb-3">
-					<h3 className="text-xl font-semibold mb-3">{isZh ? '授权流程' : 'Authorization Flow'}</h3>
+						{isZh ? '授权与安全' : 'Authorization and Security'}
+					</h3>
 					<p className="text-gray-600 dark:text-gray-300 mb-4">
 						{isZh
-							? '扩展使用基于 Token 的授权机制，扩展端和页面端必须持有匹配的 Token。'
+							? '扩展权限范围较广（例如页面访问、导航、多标签控制）。若被滥用，可能危害用户隐私。为此，调用能力由 Token 保护，用户必须主动将 Token 提供给其信任的应用。'
-							: 'The extension uses a token-based authorization mechanism. Both extension and page must have matching tokens.'}
+							: 'The extension has broad permissions (such as page access, navigation, and multi-tab control). If abused, it can harm user privacy. That is why access is protected by a token, and users must actively share the token only with applications they trust.'}
 					</p>
 
 					<CodeEditor
 						code={
 							isZh
-								? `// 1. 用户安装扩展并在扩展设置中配置 auth token
+								? `// 1) 用户在扩展侧边栏获取 auth token
-// 2. 你的页面读取相同的 token 并存入 localStorage
+// 2) 仅在可信应用中设置该 token
-// 3. Token 匹配后，扩展会暴露 window.PAGE_AGENT_EXT 对象
+// 3) token 匹配后，扩展会暴露 window.PAGE_AGENT_EXT
 
-// ⚠️ 请在扩展弹窗中查看你的 auth token，然后填入下方
+// ⚠️ 不要把 token 提供给不可信页面或脚本
 localStorage.setItem('PageAgentExtUserAuthToken', '<从扩展中获取的-token>')`
-								: `// 1. User installs extension and sets an auth token in extension settings
+								: `// 1) Get auth token from the extension side panel
-// 2. Your page reads the same token and stores it in localStorage
+// 2) Set it only in trusted applications
-// 3. After token match, extension exposes window.PAGE_AGENT_EXT object
+// 3) After token match, extension exposes window.PAGE_AGENT_EXT
 
-// ⚠️ Check your extension popup for the auth token
+// ⚠️ Never provide the token to untrusted pages or scripts
 localStorage.setItem('PageAgentExtUserAuthToken', '<your-token-from-extension>')`
 						}
 						language="javascript"
@@ -120,7 +150,9 @@ localStorage.setItem('PageAgentExtUserAuthToken', '<your-token-from-extension>')
 
 				{/* API Reference */}
 				<section>
-					<h2 className="text-2xl font-bold mb-4">{isZh ? 'API 参考' : 'API Reference'}</h2>
+					<Heading id="api-reference" className="text-2xl font-bold mb-4">
+						{isZh ? 'API 参考' : 'API Reference'}
+					</Heading>
 
 					{/* AI Assistant Instructions */}
 					<section className="p-4 bg-purple-50 dark:bg-purple-900/20 rounded-lg">
@@ -139,26 +171,90 @@ localStorage.setItem('PageAgentExtUserAuthToken', '<your-token-from-extension>')
 								rel="noopener noreferrer"
 								className="block text-sm text-blue-600 hover:text-blue-700 dark:text-blue-400 dark:hover:text-blue-300 hover:underline"
 							>
-								📄 {isZh ? '英文版 API 文档' : 'API Documentation (English)'}
+								📄 {isZh ? 'API 文档' : 'API Documentation'}
-							</a>
-							<a
-								href="https://github.com/alibaba/page-agent/blob/main/packages/extension/docs/extension_api_zh.md"
-								target="_blank"
-								rel="noopener noreferrer"
-								className="block text-sm text-blue-600 hover:text-blue-700 dark:text-blue-400 dark:hover:text-blue-300 hover:underline"
-							>
-								📄 {isZh ? '中文版 API 文档' : 'API Documentation (Chinese)'}
 							</a>
 						</div>
 					</section>
 
-					<h3 className="text-xl font-semibold my-3">PAGE_AGENT_EXT.execute(task, config)</h3>
+					{/* TypeScript Declaration */}
+					<Heading id="typescript-declaration" className="text-2xl font-bold mb-4">
+						{isZh ? 'TypeScript 类型声明' : 'TypeScript Declaration'}
+					</Heading>
 					<p className="text-gray-600 dark:text-gray-300 mb-4">
 						{isZh
-							? '使用配置执行任务。返回一个 Promise，在任务完成时 resolve。config 参数包含 LLM 设置、选项和事件回调。'
+							? '推荐把 `execute` 的类型声明加入你的项目，获得完整类型提示。'
-							: 'Execute a task with configuration. Returns a Promise that resolves when the task completes. Config includes LLM settings, options, and event callbacks.'}
+							: 'Add this `execute` declaration to your project for full type support.'}
 					</p>
 
+					<CodeEditor
+						code={
+							isZh
+								? `import type {
+	AgentActivity,
+	AgentStatus,
+	ExecutionResult,
+	HistoricalEvent
+} from '@page-agent/core'
+
+interface ExecuteConfig {
+	baseURL: string   // LLM API 端点
+	apiKey: string    // API 密钥
+	model: string     // 模型名称
+
+	includeInitialTab?: boolean
+	onStatusChange?: (status: AgentStatus) => void
+	onActivity?: (activity: AgentActivity) => void
+	onHistoryUpdate?: (history: HistoricalEvent[]) => void
+}
+
+type Execute = (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
+
+declare global {
+	interface Window {
+		PAGE_AGENT_EXT_VERSION?: string
+		PAGE_AGENT_EXT?: {
+			version: string
+			execute: Execute
+			stop: () => void
+		}
+	}
+}`
+								: `import type {
+	AgentActivity,
+	AgentStatus,
+	ExecutionResult,
+	HistoricalEvent
+} from '@page-agent/core'
+
+interface ExecuteConfig {
+	baseURL: string   // LLM API endpoint
+	apiKey: string    // API key
+	model: string     // Model name
+
+	includeInitialTab?: boolean
+	onStatusChange?: (status: AgentStatus) => void
+	onActivity?: (activity: AgentActivity) => void
+	onHistoryUpdate?: (history: HistoricalEvent[]) => void
+}
+
+type Execute = (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
+
+declare global {
+	interface Window {
+		PAGE_AGENT_EXT_VERSION?: string
+		PAGE_AGENT_EXT?: {
+			version: string
+			execute: Execute
+			stop: () => void
+		}
+	}
+}`
+						}
+						language="typescript"
+					/>
+
+					<h3 className="text-xl font-semibold mt-6 mb-3">PAGE_AGENT_EXT.execute(task, config)</h3>
+
 					<CodeEditor
 						code={
 							isZh
@@ -168,12 +264,11 @@ const result = await window.PAGE_AGENT_EXT.execute(
 	{
 		baseURL: 'https://api.openai.com/v1',
 		apiKey: 'your-api-key',
-		model: 'gpt-5-2',
+		model: 'gpt-5.2',
 		// includeInitialTab: false, // 设为 false 排除初始标签页
 		onStatusChange: status => console.log('状态变化:', status),
 		onActivity: activity => console.log('活动:', activity),
-		onHistoryUpdate: history => console.log('历史更新:', history),
+		onHistoryUpdate: history => console.log('历史更新:', history)
-		onDispose: () => console.log('已停止')
 	}
 )
 
@@ -184,12 +279,11 @@ const result = await window.PAGE_AGENT_EXT.execute(
 	{
 		baseURL: 'https://api.openai.com/v1',
 		apiKey: 'your-api-key',
-		model: 'gpt-5-2',
+		model: 'gpt-5.2',
 		// includeInitialTab: false, // Set to false to exclude initial tab
 		onStatusChange: status => console.log('Status change:', status),
 		onActivity: activity => console.log('Activity:', activity),
-		onHistoryUpdate: history => console.log('History update:', history),
+		onHistoryUpdate: history => console.log('History update:', history)
-		onDispose: () => console.log('Disposed')
 	}
 )
 
@@ -198,130 +292,50 @@ console.log(result) // Task execution result`
 						language="javascript"
 					/>
 
-					<h3 className="text-xl font-semibold mt-6 mb-3">PAGE_AGENT_EXT.dispose()</h3>
+					<h3 className="text-xl font-semibold mt-6 mb-3">PAGE_AGENT_EXT.stop()</h3>
 					<p className="text-gray-600 dark:text-gray-300 mb-4">
-						{isZh
+						{isZh ? '停止当前正在运行的任务。' : 'Stop the current running task.'}
-							? '停止当前正在运行的任务。停止后 Agent 可以重新使用。'
-							: 'Stop the current running task. The agent can be reused after disposal.'}
 					</p>
 
 					<CodeEditor
 						code={
 							isZh
 								? `// 停止当前任务
-window.PAGE_AGENT_EXT.dispose()`
+window.PAGE_AGENT_EXT.stop()`
 								: `// Stop current task execution
-window.PAGE_AGENT_EXT.dispose()`
+window.PAGE_AGENT_EXT.stop()`
 						}
 						language="javascript"
 					/>
 				</section>
 
-				{/* ExecuteConfig */}
-				<section>
-					<h2 className="text-2xl font-bold mb-4">{isZh ? '执行配置' : 'Execute Configuration'}</h2>
-					<p className="text-gray-600 dark:text-gray-300 mb-4">
-						{isZh
-							? 'config 参数包含 LLM 设置、选项和事件回调，用于控制任务执行行为。'
-							: 'The config parameter includes LLM settings, options, and event callbacks to control task execution behavior.'}
-					</p>
-
-					<CodeEditor
-						code={
-							isZh
-								? `interface ExecuteConfig {
-	baseURL: string   // LLM API 端点
-	apiKey: string    // API 密钥
-	model: string     // 模型名称
-
-	// 是否将初始标签页包含在任务中，默认 true
-	includeInitialTab?: boolean
-
-	// Agent 状态变化时调用（idle, running, error, completed 等）
-	onStatusChange?: (status: AgentStatus) => void
-
-	// Agent 执行活动时调用（如点击、输入、导航等操作）
-	onActivity?: (activity: AgentActivity) => void
-
-	// 历史记录更新时调用（包含完整的事件历史）
-	onHistoryUpdate?: (history: HistoricalEvent[]) => void
-
-	// Agent 被停止时调用
-	onDispose?: () => void
-}`
-								: `interface ExecuteConfig {
-	baseURL: string   // LLM API endpoint
-	apiKey: string    // API key
-	model: string     // Model name
-
-	// Whether to include the initial tab in the task, default true
-	includeInitialTab?: boolean
-
-	// Called when agent status changes (idle, running, error, completed, etc.)
-	onStatusChange?: (status: AgentStatus) => void
-
-	// Called when agent performs an activity (click, input, navigation, etc.)
-	onActivity?: (activity: AgentActivity) => void
-
-	// Called when history is updated (contains full event history)
-	onHistoryUpdate?: (history: HistoricalEvent[]) => void
-
-	// Called when agent is disposed
-	onDispose?: () => void
-}`
-						}
-						language="typescript"
-					/>
-				</section>
-
-				{/* Security Notice */}
-				<section className="p-4 bg-yellow-50 dark:bg-yellow-900/20 rounded-lg">
-					<h3 className="text-lg font-semibold text-yellow-900 dark:text-yellow-300 mb-2">
-						⚠️ {isZh ? '安全须知' : 'Security Notes'}
-					</h3>
-					<ul className="text-gray-600 dark:text-gray-300 space-y-1 text-sm">
-						<li>
-							•{' '}
-							{isZh
-								? '用户必须在扩展设置中显式授权每个域名'
-								: 'Users must explicitly authorize each domain in extension settings'}
-						</li>
-						<li>
-							•{' '}
-							{isZh
-								? '生产环境建议使用后端代理 LLM API Key'
-								: 'Consider using backend proxy for LLM API keys in production'}
-						</li>
-					</ul>
-				</section>
-
 				{/* Integration Guide */}
 				<section>
-					<h2 className="text-2xl font-bold mb-4">
+					<Heading
-						{isZh
+						id="integrate-multipageagent-into-your-extension"
-							? '将 MultiPageAgent 融入你自己的插件'
+						className="text-2xl font-bold mb-4"
-							: 'Integrate MultiPageAgent into Your Extension'}
-					</h2>
-					<p className="text-gray-600 dark:text-gray-300 mb-4">
-						{isZh
-							? '你可以将 MultiPageAgent 集成到自己的浏览器扩展中，实现跨页面的 AI 自动化能力。'
-							: 'You can integrate MultiPageAgent into your own browser extension for cross-page AI automation capabilities.'}
-					</p>
-					<p className="text-gray-600 dark:text-gray-300 mb-4">TODO</p>
-					<p className="text-gray-600 dark:text-gray-300 mb-4">
-						{isZh ? '参考源码实现：' : 'Reference implementation:'}
-					</p>
-					<a
-						href="https://github.com/alibaba/page-agent/blob/main/packages/extension/src/entrypoints/background.ts"
-						target="_blank"
-						rel="noopener noreferrer"
-						className="inline-flex items-center gap-2 text-blue-600 hover:text-blue-700 dark:text-blue-400 dark:hover:text-blue-300"
 					>
-						<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+						{isZh
-							<path d={siGithub.path} />
+							? '将 MultiPageAgent 集成你自己的插件'
-						</svg>
+							: 'Integrate MultiPageAgent into Your Extension'}
-						packages/extension/src/entrypoints/background.ts
+					</Heading>
-					</a>
+					<p>@TODO</p>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '建议先阅读扩展 API 文档，再参考 background entry implementation。'
+							: 'Start with the extension API docs, then use the background entry implementation as a reference.'}
+						<a
+							href="https://github.com/alibaba/page-agent/blob/main/packages/extension/src/entrypoints/background.ts"
+							target="_blank"
+							rel="noopener noreferrer"
+							className="inline-flex items-center gap-2 text-blue-600 hover:text-blue-700 dark:text-blue-400 dark:hover:text-blue-300"
+						>
+							<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+								<path d={siGithub.path} />
+							</svg>
+							packages/extension/src/entrypoints/background.ts
+						</a>
+					</p>
 				</section>
 			</div>
 		</div>

packages/website/src/pages/docs/features/custom-instructions/page.tsx

@@ -1,4 +1,5 @@
 import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
 import { useLanguage } from '@/i18n/context'
 
 export default function Instructions() {
@@ -16,9 +17,9 @@ export default function Instructions() {
 
 			{/* System Instructions */}
 			<section className="mb-12">
-				<h2 className="text-3xl font-bold mb-6">
+				<Heading id="system-instructions" className="text-3xl font-bold mb-6">
 					{isZh ? '系统级指导 (System Instructions)' : 'System Instructions'}
-				</h2>
+				</Heading>
 
 				<p className="text-gray-600 dark:text-gray-300 mb-6">
 					{isZh
@@ -46,9 +47,9 @@ Guidelines:
 
 			{/* Page Instructions */}
 			<section className="mb-12">
-				<h2 className="text-3xl font-bold mb-6">
+				<Heading id="page-instructions" className="text-3xl font-bold mb-6">
 					{isZh ? '页面级指导 (Page Instructions)' : 'Page Instructions'}
-				</h2>
+				</Heading>
 
 				<p className="text-gray-600 dark:text-gray-300 mb-6">
 					{isZh
@@ -90,7 +91,9 @@ This is the product listing page.
 
 			{/* How It Works */}
 			<section className="mb-12">
-				<h2 className="text-3xl font-bold mb-6">{isZh ? '工作原理' : 'How It Works'}</h2>
+				<Heading id="how-it-works" className="text-3xl font-bold mb-6">
+					{isZh ? '工作原理' : 'How It Works'}
+				</Heading>
 
 				<p className="text-gray-600 dark:text-gray-300 mb-4">
 					{isZh

packages/website/src/pages/docs/features/custom-tools/page.tsx

@@ -1,5 +1,5 @@
-import BetaNotice from '@/components/BetaNotice'
 import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
 import { useLanguage } from '@/i18n/context'
 
 export default function CustomTools() {
@@ -11,109 +11,84 @@ export default function CustomTools() {
 
 			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
 				{isZh
-					? '通过注册自定义工具，扩展 AI Agent 的能力边界。使用 Zod 定义严格的输入接口，让 AI 安全调用你的业务逻辑。'
+					? '通过注册自定义工具，扩展 AI Agent 的能力边界。使用 Zod 定义输入接口，让 AI 安全调用你的业务逻辑。'
-					: 'Extend AI Agent capabilities by registering custom tools. Use Zod to define strict input schemas for safe business logic calls.'}
+					: 'Extend AI Agent capabilities by registering custom tools. Define input schemas with Zod for safe business logic invocation.'}
 			</p>
 
 			<div className="space-y-8">
 				<section>
-					<h2 className="text-2xl font-bold mb-4">{isZh ? '工具注册' : 'Tool Registration'}</h2>
+					<Heading id="define-tools" className="text-2xl font-bold mb-4">
+						{isZh ? '定义工具' : 'Define Tools'}
+					</Heading>
 					<p className="text-gray-600 dark:text-gray-300 mb-4">
 						{isZh
-							? '每个自定义工具需要定义四个核心属性：name、description、input schema 和 execute 函数。'
+							? '使用 tool() 辅助函数定义自定义工具，每个工具包含 description、inputSchema 和 execute 三个属性。'
-							: 'Each custom tool requires four core properties: name, description, input schema, and execute function.'}
+							: 'Use the tool() helper to define custom tools with description, inputSchema, and execute.'}
 					</p>
 
 					<CodeEditor
-						code={`import zod from 'zod'
+						code={`import { z } from 'zod'
 import { PageAgent, tool } from 'page-agent'
 
-// override internal tool
+const pageAgent = new PageAgent({
-const customTools = {
+  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.',
+    add_to_cart: tool({
-    inputSchema: zod.object({
+      description: 'Add a product to the shopping cart by its product ID.',
-      question: zod.string(),
+      inputSchema: z.object({
+        productId: z.string(),
+        quantity: z.number().min(1).default(1),
+      }),
+      execute: async function (input) {
+        await fetch('/api/cart', {
+          method: 'POST',
+          body: JSON.stringify(input),
+        })
+        return \`Added \${input.quantity}x \${input.productId} to cart.\`
+      },
     }),
-    execute: async function (this: PageAgent, input) {
-      const answer = await do_some_thing(input.question)
-      return "✅ Received user answer: " + answer
-    },
-  })
-}
 
-// remove internal tool
+	// 
-const customTools = {
+    search_knowledge_base: tool({
-  scroll: null, // never scroll
+      description: 'Search the internal knowledge base and return relevant articles.',
-}
+      inputSchema: z.object({
-	
+        query: z.string(),
-const pageAgent = new PageAgent({customTools})
+        limit: z.number().max(10).default(3),
-`}
+      }),
-						language="javascript"
+      execute: async function (input) {
-					/>
+        const res = await fetch(
-				</section>
+          \`/api/kb?q=\${encodeURIComponent(input.query)}&limit=\${input.limit}\`
-
+        )
-				<section>
+        const articles = await res.json()
-					<h2 className="text-2xl font-bold mb-4">{isZh ? '页面过滤器' : 'Page Filter'}</h2>
+        return JSON.stringify(articles)
-
+      },
-					<BetaNotice />
+    }),
-
-					<p className="text-gray-600 dark:text-gray-300 mb-4">
-						{isZh
-							? '通过 pageFilter 属性控制工具在哪些页面可见，提升安全性和用户体验。'
-							: 'Control tool visibility on specific pages via the pageFilter property to enhance security and UX.'}
-					</p>
-
-					<CodeEditor
-						code={`pageAgent.registerTool({
-  name: 'approveOrder',
-  description: '审批订单',
-  input: z.object({
-    orderId: z.string(),
-    approved: z.boolean()
-  }),
-  execute: async (params) => {
-    // 审批逻辑
   },
-  // 可选：页面过滤器
-  pageFilter: {
-    // 只在订单管理页面显示
-    include: ['/admin/orders', '/admin/orders/*'],
-    // 排除特定页面
-    exclude: ['/admin/orders/archived']
-  }
 })`}
 						language="javascript"
 					/>
 				</section>
 
 				<section>
-					<h2 className="text-2xl font-bold mb-4">{isZh ? '最佳实践' : 'Best Practices'}</h2>
+					<Heading id="override-remove" className="text-2xl font-bold mb-4">
-					<div className="space-y-4">
+						{isZh ? '覆盖与移除内置工具' : 'Override & Remove Built-in Tools'}
-						<div className="p-4 bg-yellow-50 dark:bg-yellow-900/20 rounded-lg">
+					</Heading>
-							<h3 className="text-lg font-semibold text-yellow-900 dark:text-yellow-300 mb-2">
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
-								{isZh ? '⚡ 性能优化' : '⚡ Performance Optimization'}
+						{isZh
-							</h3>
+							? '使用相同的名称可以覆盖内置工具的行为，设置为 null 则完全移除该工具。'
-							<ul className="text-gray-600 dark:text-gray-300 space-y-1 text-sm">
+							: 'Use the same name to override a built-in tool, or set it to null to remove it entirely.'}
-								<li>
+					</p>
-									{isZh
+
-										? '• 使用 pageFilter 减少不必要的工具加载'
+					<CodeEditor
-										: '• Use pageFilter to reduce unnecessary tool loading'}
+						code={`const pageAgent = new PageAgent({
-								</li>
+  customTools: {
-								<li>
+    scroll: null, // remove scroll tool
-									{isZh
+    execute_javascript: null, // remove script execution
-										? '• 在 execute 函数中实现适当的缓存机制'
+  },
-										: '• Implement appropriate caching in execute functions'}
+})`}
-								</li>
+						language="javascript"
-								<li>
+					/>
-									{isZh
-										? '• 避免在工具中执行耗时的同步操作'
-										: '• Avoid long-running sync operations in tools'}
-								</li>
-							</ul>
-						</div>
-					</div>
 				</section>
 			</div>
 		</div>