chore(version): bump version to 0.2.5

feat: make all ui optional

.github/ISSUE_TEMPLATE/bug_report.yml

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

.github/ISSUE_TEMPLATE/feature_request.yml

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

.github/workflows/release.yml

@@ -6,7 +6,7 @@ on:
       - 'v*'
 
 permissions:
-  id-token: write  # Required for OIDC
+  id-token: write # Required for OIDC
   contents: read
 
 jobs:
@@ -24,7 +24,7 @@ jobs:
       # Ensure npm 11.5.1 or later is installed
       - name: Update npm
         run: npm install -g npm@latest
-        
+
       - name: Install dependencies
         run: npm ci
 
@@ -32,4 +32,4 @@ jobs:
         run: npm run build:libs
 
       - name: Publish all public packages
-        run: npm publish --workspaces --access public
+        run: npm publish --workspaces --access public

.vscode/extensions.json

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

.vscode/settings.json

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

AGENTS.md

@@ -9,9 +9,10 @@ This is a **monorepo** with npm workspaces:
 
 Internal packages:
 
+- **CDN** (`packages/cdn/`) - IIFE builds for script tag usage (npm: `@page-agent/cdn`)
 - **LLMs** (`packages/llms/`) - LLM client with reflection-before-action mental model
-- **Page Controller** (`packages/page-controller/`) - DOM operations, independent of LLM
-- **UI** (`packages/ui/`) - Panel, SimulatorMask, i18n. Decoupled from PageAgent
+- **Page Controller** (`packages/page-controller/`) - DOM operations and visual feedback (SimulatorMask), independent of LLM
+- **UI** (`packages/ui/`) - Panel and i18n. Decoupled from PageAgent
 
 ## Development Commands
 
@@ -31,6 +32,7 @@ Simple monorepo solution: TypeScript references + Vite aliases. Update tsconfig
 ```
 packages/
 ├── page-agent/              # npm: "page-agent" ⭐ MAIN
+├── cdn/                     # npm: "@page-agent/cdn" (IIFE builds)
 ├── website/                 # @page-agent/website (private)
 ├── llms/                    # @page-agent/llms
 ├── page-controller/         # @page-agent/page-controller
@@ -43,8 +45,8 @@ packages/
 
 - **Page Agent**: Core lib. Imports from `@page-agent/llms`, `@page-agent/page-controller`, `@page-agent/ui`
 - **LLMs**: LLM client with MacroToolInput contract. No dependency on page-agent
-- **UI**: Panel, Mask, i18n. No dependency on page-agent
-- **Page Controller**: Pure DOM operations. No LLM or UI dependency
+- **UI**: Panel and i18n. No dependency on page-agent
+- **Page Controller**: DOM operations with optional visual feedback (SimulatorMask). No LLM dependency. Enable mask via `enableMask: true` config
 
 ### PageController ↔ PageAgent Communication
 
@@ -69,41 +71,43 @@ const pageInfo = await this.pageController.getPageInfo()
 3. **LLM Processing**: AI returns action plans (page-agent)
 4. **Indexed Operations**: PageAgent calls PageController by element index
 
-### CDN Auto-Injection
+### CDN Builds (`packages/cdn/`)
 
-Library auto-initializes via script tag:
+Two IIFE builds for script tag usage:
 
-```html
-<script src="page-agent.js?model=gpt-4"></script>
-```
+| Build | File                 | Description                      |
+| ----- | -------------------- | -------------------------------- |
+| Demo  | `page-agent.demo.js` | Auto-init with built-in test API |
+| Full  | `page-agent.js`      | Exposes `PageAgent` class only   |
 
-Query params configure `PageAgentConfig` in `src/umd.ts`.
+Demo build supports query params (e.g., `?model=gpt-4&lang=en-US`).
 
 ## Key Files Reference
 
 ### Page Agent (`packages/page-agent/`)
 
-| File | Description |
-|------|-------------|
-| `src/PageAgent.ts` | ⭐ Main AI agent class |
-| `src/umd.ts` | CDN/UMD entry with auto-init |
-| `src/tools/` | Tool definitions calling PageController |
+| File               | Description                             |
+| ------------------ | --------------------------------------- |
+| `src/PageAgent.ts` | ⭐ Main AI agent class                  |
+| `src/umd.ts`       | CDN/UMD entry with auto-init            |
+| `src/tools/`       | Tool definitions calling PageController |
 
 ### LLMs (`packages/llms/`)
 
-| File | Description |
-|------|-------------|
-| `src/index.ts` | ⭐ LLM class with retry logic |
-| `src/types.ts` | MacroToolInput, AgentBrain, LLMConfig |
-| `src/OpenAILenientClient.ts` | OpenAI-compatible client |
+| File                         | Description                           |
+| ---------------------------- | ------------------------------------- |
+| `src/index.ts`               | ⭐ LLM class with retry logic         |
+| `src/types.ts`               | MacroToolInput, AgentBrain, LLMConfig |
+| `src/OpenAILenientClient.ts` | OpenAI-compatible client              |
 
 ### Page Controller (`packages/page-controller/`)
 
-| File | Description |
-|------|-------------|
-| `src/PageController.ts` | ⭐ Main controller class |
-| `src/actions.ts` | Element interactions (click, input, scroll) |
-| `src/dom/dom_tree/index.js` | Core DOM extraction engine |
+| File                        | Description                                                |
+| --------------------------- | ---------------------------------------------------------- |
+| `src/PageController.ts`     | ⭐ Main controller class with optional mask support        |
+| `src/SimulatorMask.ts`      | Visual overlay blocking user interaction during automation |
+| `src/actions.ts`            | Element interactions (click, input, scroll)                |
+| `src/dom/dom_tree/index.js` | Core DOM extraction engine                                 |
 
 ## Adding New Features
 
@@ -123,4 +127,5 @@ Query params configure `PageAgentConfig` in `src/umd.ts`.
 
 - Explicit typing for exported/public APIs
 - ESLint relaxes some unsafe rules for rapid iteration
+- Every change you make should not only implement the desired functionality but also improve the quality of the codebase
 - All code and comments must be in English.

CONTRIBUTING.md

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

LICENSE

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

README-zh.md

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

README.md

@@ -1,16 +1,19 @@
 # PageAgent 🤖🪄
 
-![banner](https://img.alicdn.com/imgextra/i3/O1CN01MyVCS21EoKkIHUT1s_!!6000000000398-49-tps-1280-353.webp)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://img.alicdn.com/imgextra/i4/O1CN01qKig1P1FnhpFKNdi6_!!6000000000532-2-tps-1280-256.png">
+  <img alt="Page Agent Banner" src="https://img.alicdn.com/imgextra/i1/O1CN01NCMKXj1Gn4tkFTsxf_!!6000000000666-2-tps-1280-256.png">
+</picture>
 
-[![npm version](https://badge.fury.io/js/page-agent.svg)](https://badge.fury.io/js/page-agent) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) [![Downloads](https://img.shields.io/npm/dt/page-agent.svg)](https://www.npmjs.com/package/page-agent) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/page-agent)](https://bundlephobia.com/package/page-agent) [![GitHub stars](https://img.shields.io/github/stars/alibaba/page-agent.svg)](https://github.com/alibaba/page-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) [![Downloads](https://img.shields.io/npm/dt/page-agent.svg)](https://www.npmjs.com/package/page-agent) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/page-agent)](https://bundlephobia.com/package/page-agent) [![GitHub stars](https://img.shields.io/github/stars/alibaba/page-agent.svg)](https://github.com/alibaba/page-agent)
 
 The GUI Agent Living in Your Webpage. Control web interfaces with natural language.
 
 🌐 **English** | [中文](./README-zh.md)
 
-👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a> 
+👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a>
 
-<video id="demo-video" src="https://github.com/user-attachments/assets/de8d1964-8bde-494f-a52f-2975469557a5" width="640" crossorigin muted autoplay loop></video>
+<video id="demo-video" src="https://github.com/user-attachments/assets/34d8444d-cbfb-44a3-a24e-fd5c167bb0bf" controls crossorigin muted></video>
 
 ---
 
@@ -24,22 +27,28 @@ The GUI Agent Living in Your Webpage. Control web interfaces with natural langua
 
 ## 🗺️ Roadmap
 
-👉 [**Roadmap**](./ROADMAP.md)
+👉 [**Roadmap**](https://github.com/alibaba/page-agent/issues/96)
 
 ## 🚀 Quick Start
 
-### CDN Integration
+### Quick Try (With Testing LLM)
+
+Fastest way to try PageAgent:
 
 ```html
-// CDN        - https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js
-// Mirror(CN) - https://registry.npmmirror.com/page-agent/latest/files/dist/umd/page-agent.js
-<script 
-	src="https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js" 
-	crossorigin="true" 
-	type="text/javascript"
+<script
+    src="https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js"
+    crossorigin="true"
 ></script>
 ```
 
+> ⚠️ **For technical evaluation only.** Demo model has rate limits and usage restrictions. Use NPM for production.
+
+| Mirrors | URL                                                                                 |
+| ------- | ----------------------------------------------------------------------------------- |
+| Global  | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js                |
+| China   | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js |
+
 ### NPM Installation
 
 ```bash
@@ -49,23 +58,18 @@ npm install page-agent
 ```javascript
 import { PageAgent } from 'page-agent'
 
-// test server
-// @note: rate limit. prompt limit. Origin limit. May change anytime. Use your own llm!
-// @note Using official DeepSeek-chat(3.2). Go to DeepSeek website for privacy policy.
-const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
 const agent = new PageAgent({
-	modelName: DEMO_MODEL,
-	baseURL: DEMO_BASE_URL,
-	apiKey: DEMO_API_KEY,
-	language: 'en-US',
+    model: 'deepseek-chat',
+    baseURL: 'https://api.deepseek.com',
+    apiKey: 'YOUR_API_KEY',
+    language: 'en-US',
 })
 
 await agent.execute('Click the login button')
 ```
 
+For environments where NPM is not available. We do offer a IIFE build via CDN. [@see CDN Usage](https://alibaba.github.io/page-agent/#/docs/integration/cdn-setup)
+
 ## 🏗️ Structure
 
 PageAgent adopts a simplified monorepo structure:
@@ -74,8 +78,9 @@ PageAgent adopts a simplified monorepo structure:
 packages/
 ├── page-agent/          # AI agent (npm: page-agent)
 ├── llms/                # LLM client (npm: @page-agent/llms)
-├── page-controller/     # DOM operations (npm: @page-agent/page-controller)
-├── ui/                  # Panel & Mask & Mouse Animation (npm: @page-agent/ui)
+├── page-controller/     # DOM operations & Visual Mask (npm: @page-agent/page-controller)
+├── ui/                  # Panel & i18n (npm: @page-agent/ui)
+├── cdn/                 # CDN IIFE builds (npm: @page-agent/cdn)
 └── website/             # Demo & Documentation site
 ```
 
@@ -83,28 +88,19 @@ packages/
 
 We welcome contributions from the community! Here's how to get started:
 
-### Setup
+1. Fork and clone. `git clone https://github.com/alibaba/page-agent.git && cd page-agent`
+2. Install dependencies: `npm install`
+3. Start development: `npm start`
 
-1. Fork the repository
-2. Clone your fork: `git clone https://github.com/alibaba/page-agent.git && cd page-agent`
-3. Install dependencies: `npm install`
-4. Start development: `npm start`
+More details in [CONTRIBUTING.md](CONTRIBUTING.md).
 
-### Contributing Guidelines
-
-Please read our [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing Guide](CONTRIBUTING.md) before contributing.
+Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
 
 ## 👏 Acknowledgments
 
-This project builds upon the excellent work of:
+This project builds upon the excellent work of **[`browser-use`](https://github.com/browser-use/browser-use)**.
 
-- **[browser-use](https://github.com/browser-use/browser-use)**
-
-PageAgent is designed for **client-side web enhancement**, not server-side automation.
-
-## 📄 License
-
-MIT License - see the [LICENSE](LICENSE) file for details.
+`PageAgent` is designed for **client-side web enhancement**, not server-side automation.
 
 ```
 DOM processing components and prompt are derived from browser-use:
@@ -123,6 +119,10 @@ Third-party dependencies and their licenses can be found in the package.json
 file and in the node_modules directory after installation.
 ```
 
+## 📄 License
+
+[MIT License](LICENSE)
+
 ---
 
 **⭐ Star this repo if you find PageAgent helpful!**

ROADMAP.md

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

eslint.config.js

@@ -8,12 +8,7 @@ import globals from 'globals'
 import tseslint from 'typescript-eslint'
 
 export default defineConfig([
-	globalIgnores([
-		'**/dist',
-		'**/test-pages',
-		'**/node_modules',
-		'packages/website/src/components/ui',
-	]),
+	globalIgnores(['**/dist', '**/node_modules', 'packages/website/src/components/ui']),
 	{
 		plugins: {
 			'react-hooks': reactHooks,

package.json

@@ -1,13 +1,14 @@
 {
 	"name": "root",
 	"private": true,
-	"version": "0.0.16",
+	"version": "0.2.5",
 	"type": "module",
 	"workspaces": [
 		"packages/page-controller",
 		"packages/ui",
 		"packages/llms",
 		"packages/page-agent",
+		"packages/cdn",
 		"packages/website"
 	],
 	"description": "AI-powered UI agent for web applications",
@@ -28,36 +29,39 @@
 		"build:website": "npm run build:website --workspace=@page-agent/website",
 		"build:libs": "npm run build --workspaces --if-present",
 		"build": "npm run build:libs && npm run build:website",
-		"dev:umd": "npm run dev:umd --workspace=page-agent",
+		"dev:iife": "npm run dev:iife --workspace=page-agent",
 		"version": "node scripts/sync-version.js",
 		"lint": "eslint .",
 		"prepare": "husky"
 	},
 	"devDependencies": {
-		"@commitlint/cli": "^20.2.0",
-		"@commitlint/config-conventional": "^20.2.0",
+		"@commitlint/cli": "^20.3.1",
+		"@commitlint/config-conventional": "^20.3.1",
 		"@eslint/js": "^9.39.2",
 		"@microsoft/api-extractor": "^7.55.2",
-		"@trivago/prettier-plugin-sort-imports": "^6.0.0",
-		"@types/node": "^25.0.3",
+		"@trivago/prettier-plugin-sort-imports": "^6.0.2",
+		"@types/node": "^25.0.7",
 		"concurrently": "^9.2.1",
 		"dotenv": "^17.2.3",
 		"eslint": "^9.39.2",
 		"eslint-config-prettier": "^10.1.8",
-		"eslint-plugin-react-dom": "^2.3.13",
+		"eslint-plugin-react-dom": "^2.5.7",
 		"eslint-plugin-react-hooks": "^7.0.1",
 		"eslint-plugin-react-refresh": "^0.4.26",
-		"eslint-plugin-react-x": "^2.3.13",
-		"globals": "^16.4.0",
+		"eslint-plugin-react-x": "^2.5.7",
+		"globals": "^17.0.0",
 		"husky": "^9.1.7",
 		"lint-staged": "^16.2.4",
 		"prettier": "^3.7.4",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.50.1",
+		"typescript-eslint": "^8.53.0",
 		"unplugin-dts": "^1.0.0-beta.6",
-		"vite": "^7.3.0",
+		"vite": "^7.3.1",
 		"vite-plugin-css-injected-by-js": "^3.5.2"
 	},
+	"overrides": {
+		"typescript": "^5.9.3"
+	},
 	"lint-staged": {
 		"*.{js,ts,cjs,cts,mjs,mts}": [
 			"npx prettier --write --ignore-unknown",
@@ -98,6 +102,22 @@
 			".css$"
 		],
 		"importOrderSeparation": true,
-		"importOrderSortSpecifiers": true
+		"importOrderSortSpecifiers": true,
+		"overrides": [
+			{
+				"files": "*.md",
+				"options": {
+					"useTabs": false,
+					"tabWidth": 4
+				}
+			},
+			{
+				"files": "*.json",
+				"options": {
+					"useTabs": false,
+					"tabWidth": 4
+				}
+			}
+		]
 	}
 }

packages/cdn/package.json

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

packages/cdn/src/demo.js

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

packages/cdn/src/full.js

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

packages/cdn/vite.config.js

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

packages/llms/README.md

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

packages/llms/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@page-agent/llms",
-	"version": "0.0.16",
+	"version": "0.2.5",
 	"type": "module",
 	"main": "./dist/lib/page-agent-llms.js",
 	"module": "./dist/lib/page-agent-llms.js",
@@ -38,6 +38,6 @@
 	},
 	"dependencies": {
 		"chalk": "^5.6.2",
-		"zod": "^4.2.1"
+		"zod": "^4.3.5"
 	}
 }

packages/llms/src/OpenAIClient.ts

@@ -1,61 +1,58 @@
 /**
  * OpenAI Client implementation
- * @note This client is only for demonstrating how to implement a LLM client.
- * @note Use OpenAILenientClient instead.
  */
 import { InvokeError, InvokeErrorType } from './errors'
-import type { InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
+import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
 import { modelPatch, zodToOpenAITool } from './utils'
 
 /**
- * @deprecated Use OpenAILenientClient instead.
+ * Client for OpenAI compatible APIs
  */
 export class OpenAIClient implements LLMClient {
-	config: LLMConfig
+	config: Required<LLMConfig>
+	private fetch: typeof globalThis.fetch
 
-	constructor(config: LLMConfig) {
+	constructor(config: Required<LLMConfig>) {
 		this.config = config
+		this.fetch = config.customFetch
 	}
 
 	async invoke(
 		messages: Message[],
 		tools: Record<string, Tool>,
-		abortSignal?: AbortSignal
+		abortSignal?: AbortSignal,
+		options?: InvokeOptions
 	): Promise<InvokeResult> {
 		// 1. Convert tools to OpenAI format
-		const openaiTools = Object.entries(tools).map(([name, tool]) => zodToOpenAITool(name, tool))
+		const openaiTools = Object.entries(tools).map(([name, t]) => zodToOpenAITool(name, t))
+
+		// Build request body
+		const requestBody: Record<string, unknown> = {
+			model: this.config.model,
+			temperature: this.config.temperature,
+			messages,
+			tools: openaiTools,
+			parallel_tool_calls: false,
+			// Require tool call: specific tool if provided, otherwise any tool
+			tool_choice: options?.toolChoiceName
+				? { type: 'function', function: { name: options.toolChoiceName } }
+				: 'required',
+		}
 
 		// 2. Call API
 		let response: Response
 		try {
-			response = await fetch(`${this.config.baseURL}/chat/completions`, {
+			response = await this.fetch(`${this.config.baseURL}/chat/completions`, {
 				method: 'POST',
 				headers: {
 					'Content-Type': 'application/json',
 					Authorization: `Bearer ${this.config.apiKey}`,
 				},
-				body: JSON.stringify(
-					modelPatch({
-						model: this.config.model,
-						temperature: this.config.temperature,
-						max_tokens: this.config.maxTokens,
-						messages,
-
-						tools: openaiTools,
-						// tool_choice: 'required',
-						tool_choice: { type: 'function', function: { name: 'AgentOutput' } },
-
-						// model specific params
-
-						// reasoning_effort: 'minimal',
-						// verbosity: 'low',
-						parallel_tool_calls: false,
-					})
-				),
+				body: JSON.stringify(modelPatch(requestBody)),
 				signal: abortSignal,
 			})
 		} catch (error: unknown) {
-			// Network error
+			console.error(error)
 			throw new InvokeError(InvokeErrorType.NETWORK_ERROR, 'Network request failed', error)
 		}
 
@@ -93,77 +90,94 @@ export class OpenAIClient implements LLMClient {
 			)
 		}
 
+		// 4. Parse and validate response
 		const data = await response.json()
 
-		// 4. Check finish_reason
 		const choice = data.choices?.[0]
 		if (!choice) {
 			throw new InvokeError(InvokeErrorType.UNKNOWN, 'No choices in response', data)
 		}
 
+		// Check finish_reason
 		switch (choice.finish_reason) {
 			case 'tool_calls':
-				// ✅ Normal
+			case 'function_call': // gemini
+			case 'stop': // some models use this even with tool calls
 				break
 			case 'length':
-				// ⚠️ Token limit reached
 				throw new InvokeError(
 					InvokeErrorType.CONTEXT_LENGTH,
-					'Response truncated: max tokens reached',
-					data
+					'Response truncated: max tokens reached'
 				)
 			case 'content_filter':
-				// ❌ Content filtered
-				throw new InvokeError(
-					InvokeErrorType.CONTENT_FILTER,
-					'Content filtered by safety system',
-					data
-				)
-			case 'stop':
-				// ❌ Did not call tool (we require tool call)
-				throw new InvokeError(InvokeErrorType.NO_TOOL_CALL, 'Model did not call any tool', data)
+				throw new InvokeError(InvokeErrorType.CONTENT_FILTER, 'Content filtered by safety system')
 			default:
 				throw new InvokeError(
 					InvokeErrorType.UNKNOWN,
-					`Unexpected finish_reason: ${choice.finish_reason}`,
-					data
+					`Unexpected finish_reason: ${choice.finish_reason}`
 				)
 		}
 
-		// 5. Parse tool call
-		const toolCall = choice.message?.tool_calls?.[0]
-		if (!toolCall) {
-			throw new InvokeError(InvokeErrorType.NO_TOOL_CALL, 'No tool call found in response', data)
-		}
+		// Apply normalizeResponse if provided (for fixing format issues automatically)
+		const normalizedData = options?.normalizeResponse ? options.normalizeResponse(data) : data
+		const normalizedChoice = (normalizedData as any).choices?.[0]
 
-		const toolName = toolCall.function.name
-		const tool = tools[toolName]
-		if (!tool) {
-			throw new InvokeError(InvokeErrorType.UNKNOWN, `Tool ${toolName} not found`, data)
-		}
-
-		// 6. Parse and validate arguments
-		let toolArgs: unknown
-		try {
-			toolArgs = JSON.parse(toolCall.function.arguments)
-		} catch (e) {
-			throw new InvokeError(InvokeErrorType.INVALID_TOOL_ARGS, 'Invalid JSON in tool arguments', e)
-		}
-
-		// Validate against zod schema
-		const validation = tool.inputSchema.safeParse(toolArgs)
-		if (!validation.success) {
+		// Get tool name from response
+		const toolCallName = normalizedChoice?.message?.tool_calls?.[0]?.function?.name
+		if (!toolCallName) {
 			throw new InvokeError(
-				InvokeErrorType.INVALID_TOOL_ARGS,
-				`Tool arguments validation failed: ${validation.error.message}`,
-				validation.error
+				InvokeErrorType.NO_TOOL_CALL,
+				'No tool call found in response',
+				normalizedData
 			)
 		}
 
-		// 7. Execute tool
+		const tool = tools[toolCallName]
+		if (!tool) {
+			throw new InvokeError(
+				InvokeErrorType.UNKNOWN,
+				`Tool "${toolCallName}" not found in tools`,
+				normalizedData
+			)
+		}
+
+		// Extract and parse tool arguments
+		const argString = normalizedChoice.message?.tool_calls?.[0]?.function?.arguments
+		if (!argString) {
+			throw new InvokeError(
+				InvokeErrorType.INVALID_TOOL_ARGS,
+				'No tool call arguments found',
+				normalizedData
+			)
+		}
+
+		let parsedArgs: unknown
+		try {
+			parsedArgs = JSON.parse(argString)
+		} catch (error) {
+			throw new InvokeError(
+				InvokeErrorType.INVALID_TOOL_ARGS,
+				'Failed to parse tool arguments as JSON',
+				error
+			)
+		}
+
+		// Validate with schema
+		const validation = tool.inputSchema.safeParse(parsedArgs)
+		if (!validation.success) {
+			console.error(validation.error)
+			throw new InvokeError(
+				InvokeErrorType.INVALID_TOOL_ARGS,
+				'Tool arguments validation failed',
+				validation.error
+			)
+		}
+		const toolInput = validation.data
+
+		// 5. Execute tool
 		let toolResult: unknown
 		try {
-			toolResult = await tool.execute(validation.data)
+			toolResult = await tool.execute(toolInput)
 		} catch (e) {
 			throw new InvokeError(
 				InvokeErrorType.TOOL_EXECUTION_ERROR,
@@ -172,12 +186,11 @@ export class OpenAIClient implements LLMClient {
 			)
 		}
 
-		// 8. Return result (including cache tokens)
+		// Return result
 		return {
 			toolCall: {
-				// id: toolCall.id,
-				name: toolName,
-				args: validation.data as Record<string, unknown>,
+				name: toolCallName,
+				args: toolInput,
 			},
 			toolResult,
 			usage: {

packages/llms/src/OpenAILenientClient.ts

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

packages/llms/src/constants.ts

@@ -1,21 +1,3 @@
-// Dev environment: use .env config if available, otherwise fallback to testing api
-export const DEFAULT_MODEL_NAME: string =
-	import.meta.env.DEV && import.meta.env.LLM_MODEL_NAME
-		? import.meta.env.LLM_MODEL_NAME
-		: 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
-export const DEFAULT_API_KEY: string =
-	import.meta.env.DEV && import.meta.env.LLM_API_KEY
-		? import.meta.env.LLM_API_KEY
-		: 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
-export const DEFAULT_BASE_URL: string =
-	import.meta.env.DEV && import.meta.env.LLM_BASE_URL
-		? import.meta.env.LLM_BASE_URL
-		: 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-
-// internal
-
+// Internal constants
 export const LLM_MAX_RETRIES = 2
 export const DEFAULT_TEMPERATURE = 0.7 // higher randomness helps auto-recovery
-export const DEFAULT_MAX_TOKENS = 16000

packages/llms/src/index.ts

@@ -1,77 +1,26 @@
-/**
- * @topic LLM 与主流程的隔离
- * @reasoning
- * 将 llm 的调用和主流程分开是复杂的，
- * 因为 agent 的 tool call 通常集成在 llm 模块中，而而先得到 llm 返回，然后处理工具调用
- * tools 和 llm 调用的逻辑不可避免地耦合在一起，tool 的执行又和主流程耦合在一起
- * 而 history 的维护和更新逻辑，又必须嵌入多轮 tool call 中
- * @reasoning
- * - 放弃框架提供的自动的多轮调用，每轮调用都由主流程发起
- * - 理想情况下，llm 调用应该获得 structured output，然后由额外的模块触发 tool call，目前模型和框架都无法实现
- * - 当前只能将 llm api 和 本地 tool call 耦合在一起，不关心其中的衔接方式
- * @conclusion
- * - @llm responsibility boundary:
- *   - call llm api with given messages and tools
- *   - invoke tool call and get the result of the tool
- *   - return the result to main loop
- * - @main_loop responsibility boundary:
- *   - maintain all behaviors of an **agent**
- * @conclusion
- * - 这里的 llm 模块不是 agent，只负责一轮 llm 调用和工具调用，无状态
- */
-/**
- * @topic 结构化输出
- * @facts
- * - 几乎所有模型都支持 tool call schema
- * - 几乎所有模型都支持返回 json
- *   - 只有 openAI/grok/gemini 支持 schema 并保证格式
- * - 主流模型都支持 tool_choice: required
- *   - 除了 qwen 必须指定一个函数名 (9月上新后支持)
- * @conclusion
- * - 永远使用 tool call 来返回结构化数据，禁止模型直接返回（视为出错）
- * - 不能假设 tool 参数合法，必须有修复机制，而且修复也应该使用 tool call 返回
- */
-import { OpenAIClient } from './OpenAILenientClient'
-import {
-	DEFAULT_API_KEY,
-	DEFAULT_BASE_URL,
-	DEFAULT_MAX_TOKENS,
-	DEFAULT_MODEL_NAME,
-	DEFAULT_TEMPERATURE,
-	LLM_MAX_RETRIES,
-} from './constants'
+import { OpenAIClient } from './OpenAIClient'
+import { DEFAULT_TEMPERATURE, LLM_MAX_RETRIES } from './constants'
 import { InvokeError } from './errors'
-import type {
-	AgentBrain,
-	InvokeResult,
-	LLMClient,
-	LLMConfig,
-	MacroToolInput,
-	MacroToolResult,
-	Message,
-	Tool,
-} from './types'
+import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
 
-export type {
-	AgentBrain,
-	InvokeResult,
-	LLMClient,
-	LLMConfig,
-	MacroToolInput,
-	MacroToolResult,
-	Message,
-	Tool,
-}
+export type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool }
 
 export function parseLLMConfig(config: LLMConfig): Required<LLMConfig> {
+	// Runtime validation as defensive programming (types already guarantee these)
+	if (!config.baseURL || !config.apiKey || !config.model) {
+		throw new Error(
+			'[PageAgent] LLM configuration required. Please provide: baseURL, apiKey, model. ' +
+				'See: https://alibaba.github.io/page-agent/#/docs/features/models'
+		)
+	}
+
 	return {
-		baseURL: config.baseURL ?? DEFAULT_BASE_URL,
-		apiKey: config.apiKey ?? DEFAULT_API_KEY,
-		model: config.model ?? DEFAULT_MODEL_NAME,
+		baseURL: config.baseURL,
+		apiKey: config.apiKey,
+		model: config.model,
 		temperature: config.temperature ?? DEFAULT_TEMPERATURE,
-		maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS,
 		maxRetries: config.maxRetries ?? LLM_MAX_RETRIES,
-		customFetch: config.customFetch ?? globalThis.fetch,
+		customFetch: (config.customFetch ?? fetch).bind(globalThis), // fetch will be illegal unless bound
 	}
 }
 
@@ -95,11 +44,12 @@ export class LLM extends EventTarget {
 	async invoke(
 		messages: Message[],
 		tools: Record<string, Tool>,
-		abortSignal: AbortSignal
+		abortSignal: AbortSignal,
+		options?: InvokeOptions
 	): Promise<InvokeResult> {
 		return await withRetry(
 			async () => {
-				const result = await this.client.invoke(messages, tools, abortSignal)
+				const result = await this.client.invoke(messages, tools, abortSignal, options)
 
 				return result
 			},

packages/llms/src/types.ts

@@ -32,6 +32,24 @@ export interface Tool<TParams = any, TResult = any> {
 	execute: (args: TParams) => Promise<TResult>
 }
 
+/**
+ * Invoke options for LLM call
+ */
+export interface InvokeOptions {
+	/**
+	 * Force LLM to call a specific tool by name.
+	 * If provided: tool_choice = { type: 'function', function: { name: toolChoiceName } }
+	 * If not provided: tool_choice = 'required' (must call some tool, but model chooses which)
+	 */
+	toolChoiceName?: string
+	/**
+	 * Response normalization function.
+	 * Called before parsing the response.
+	 * Used to fix various response format errors from the model.
+	 */
+	normalizeResponse?: (response: any) => any
+}
+
 /**
  * LLM Client interface
  * Note: Does not use generics because each tool in the tools array has different types
@@ -40,7 +58,8 @@ export interface LLMClient {
 	invoke(
 		messages: Message[],
 		tools: Record<string, Tool>,
-		abortSignal?: AbortSignal
+		abortSignal?: AbortSignal,
+		options?: InvokeOptions
 	): Promise<InvokeResult>
 }
 
@@ -68,12 +87,11 @@ export interface InvokeResult<TResult = unknown> {
  * LLM configuration
  */
 export interface LLMConfig {
-	baseURL?: string
-	apiKey?: string
-	model?: string
+	baseURL: string
+	apiKey: string
+	model: string
 
 	temperature?: number
-	maxTokens?: number
 	maxRetries?: number
 
 	/**
@@ -83,36 +101,3 @@ export interface LLMConfig {
 	 */
 	customFetch?: typeof globalThis.fetch
 }
-
-/**
- * Agent brain state - the reflection-before-action model
- *
- * Every tool call must first reflect on:
- * - evaluation_previous_goal: How well did the previous action achieve its goal?
- * - memory: Key information to remember for future steps
- * - next_goal: What should be accomplished in the next action?
- */
-export interface AgentBrain {
-	// thinking?: string
-	evaluation_previous_goal: string
-	memory: string
-	next_goal: string
-}
-
-/**
- * MacroTool input structure
- *
- * This is the core abstraction that enforces the "reflection-before-action" mental model.
- * Before executing any action, the LLM must output its reasoning state.
- */
-export interface MacroToolInput extends AgentBrain {
-	action: Record<string, any>
-}
-
-/**
- * MacroTool output structure
- */
-export interface MacroToolResult {
-	input: MacroToolInput
-	output: string
-}

packages/llms/src/utils.ts

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

packages/llms/tsconfig.dts.json

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

packages/llms/tsconfig.json

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

packages/llms/vite.config.js

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

packages/page-agent/package.json

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

packages/page-agent/src/PageAgent.ts

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

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

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

packages/page-agent/src/iife.ts

@@ -35,7 +35,16 @@ setTimeout(() => {
 		window.pageAgent = new PageAgent(config)
 	} else {
 		console.log('🚀 page-agent.js no current script detected, using default demo config')
-		window.pageAgent = new PageAgent()
+		const config: PageAgentConfig = {
+			// model: DEMO_MODEL,
+			// baseURL: DEMO_BASE_URL,
+			// apiKey: DEMO_API_KEY,
+
+			model: import.meta.env.LLM_MODEL_NAME ? import.meta.env.LLM_MODEL_NAME : DEMO_MODEL,
+			baseURL: import.meta.env.LLM_BASE_URL ? import.meta.env.LLM_BASE_URL : DEMO_BASE_URL,
+			apiKey: import.meta.env.LLM_API_KEY ? import.meta.env.LLM_API_KEY : DEMO_API_KEY,
+		}
+		window.pageAgent = new PageAgent(config)
 	}
 
 	console.log('🚀 page-agent.js initialized with config:', window.pageAgent.config)

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

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

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

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

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

@@ -57,6 +57,15 @@ tools.set(
 			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.`
 		},
 	})
@@ -71,6 +80,9 @@ tools.set(
 			question: zod.string(),
 		}),
 		execute: async function (this: PageAgent, input) {
+			if (!this.panel) {
+				throw new Error('ask_user tool requires panel to be enabled')
+			}
 			const answer = await this.panel.askUser(input.question)
 			return `✅ Received user answer: ${answer}`
 		},

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

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

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

@@ -6,8 +6,6 @@ export interface PageAgentEventMap {
 	// PageAgent status events
 	// 'agent:execute': { params: { task: string } }
 	// 'agent:done': { params: { text: string; success: boolean } }
-	// 'agent:paused': { params: undefined }
-	// 'agent:resumed': { params: undefined }
 	// 'agent:disposed': { params: undefined }
 	// 'agent:error': { params: { error: string | Error } }
 

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

@@ -1,3 +1,5 @@
+export { normalizeResponse } from './autoFixer'
+
 /**
  * Wait until condition becomes true
  * @returns Returns when condition becomes true, throws otherwise

packages/page-agent/tsconfig.dts.json

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

packages/page-agent/tsconfig.json

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

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

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

packages/page-controller/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@page-agent/page-controller",
-	"version": "0.0.16",
+	"version": "0.2.5",
 	"type": "module",
 	"main": "./dist/lib/page-controller.js",
 	"module": "./dist/lib/page-controller.js",
@@ -34,5 +34,8 @@
 		"build": "vite build",
 		"prepublishOnly": "node -e \"const fs=require('fs');['LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
 		"postpublish": "node -e \"['LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
+	},
+	"dependencies": {
+		"ai-motion": "^0.4.8"
 	}
 }

packages/page-controller/src/PageController.ts

@@ -18,13 +18,32 @@ import { VIEWPORT_EXPANSION } from './constants'
 import * as dom from './dom'
 import type { FlatDomTree, InteractiveElementDomNode } from './dom/dom_tree/type'
 import { getPageInfo } from './dom/getPageInfo'
+import { SimulatorMask } from './mask/SimulatorMask'
 import { patchReact } from './patches/react'
 
+export { SimulatorMask }
+
 /**
  * Configuration for PageController
  */
 export interface PageControllerConfig extends dom.DomConfig {
 	viewportExpansion?: number
+	/** Enable visual mask overlay during operations (default: false) */
+	enableMask?: boolean
+}
+
+/**
+ * Structured browser state for LLM consumption
+ */
+export interface BrowserState {
+	url: string
+	title: string
+	/** Page info + scroll position hint (e.g. "Page info: 1920x1080px...\n[Start of page]") */
+	header: string
+	/** Simplified HTML of interactive elements */
+	content: string
+	/** Page footer hint (e.g. "... 300 pixels below ..." or "[End of page]") */
+	footer: string
 }
 
 interface ActionResult {
@@ -64,12 +83,19 @@ export class PageController extends EventTarget {
 	/** last time the tree was updated */
 	private lastTimeUpdate = 0
 
+	/** Visual mask overlay for blocking user interaction during automation */
+	private mask: SimulatorMask | null = null
+
 	constructor(config: PageControllerConfig = {}) {
 		super()
 
 		this.config = config
 
 		patchReact(this)
+
+		if (config.enableMask) {
+			this.mask = new SimulatorMask()
+		}
 	}
 
 	// ======= State Queries =======
@@ -81,42 +107,6 @@ export class PageController extends EventTarget {
 		return window.location.href
 	}
 
-	/**
-	 * Get current page title
-	 */
-	async getPageTitle(): Promise<string> {
-		return document.title
-	}
-
-	/**
-	 * Get page scroll and size info
-	 */
-	async getPageInfo() {
-		return getPageInfo()
-	}
-
-	/**
-	 * Get the simplified HTML representation of the page.
-	 * This is used by LLM to understand the page structure.
-	 */
-	async getSimplifiedHTML(): Promise<string> {
-		return this.simplifiedHTML
-	}
-
-	/**
-	 * Get text description for an element by index
-	 */
-	async getElementText(index: number): Promise<string | undefined> {
-		return this.elementTextMap.get(index)
-	}
-
-	/**
-	 * Get total number of indexed interactive elements
-	 */
-	async getElementCount(): Promise<number> {
-		return this.selectorMap.size
-	}
-
 	/**
 	 * Get last tree update timestamp
 	 */
@@ -125,10 +115,43 @@ export class PageController extends EventTarget {
 	}
 
 	/**
-	 * Get the viewport expansion setting
+	 * Get structured browser state for LLM consumption.
+	 * Automatically calls updateTree() to refresh the DOM state.
 	 */
-	async getViewportExpansion(): Promise<number> {
-		return this.config.viewportExpansion ?? VIEWPORT_EXPANSION
+	async getBrowserState(): Promise<BrowserState> {
+		const url = window.location.href
+		const title = document.title
+		const pi = getPageInfo()
+		const viewportExpansion = this.config.viewportExpansion ?? VIEWPORT_EXPANSION
+
+		await this.updateTree()
+
+		const content = this.simplifiedHTML
+
+		// Build header: page info + scroll position hint
+		const pageInfoLine = `Page info: ${pi.viewport_width}x${pi.viewport_height}px viewport, ${pi.page_width}x${pi.page_height}px total page size, ${pi.pages_above.toFixed(1)} pages above, ${pi.pages_below.toFixed(1)} pages below, ${pi.total_pages.toFixed(1)} total pages, at ${(pi.current_page_position * 100).toFixed(0)}% of page`
+
+		const elementsLabel =
+			viewportExpansion === -1
+				? 'Interactive elements from top layer of the current page (full page):'
+				: 'Interactive elements from top layer of the current page inside the viewport:'
+
+		const hasContentAbove = pi.pixels_above > 4
+		const scrollHintAbove =
+			hasContentAbove && viewportExpansion !== -1
+				? `... ${pi.pixels_above} pixels above (${pi.pages_above.toFixed(1)} pages) - scroll to see more ...`
+				: '[Start of page]'
+
+		const header = `${pageInfoLine}\n\n${elementsLabel}\n\n${scrollHintAbove}`
+
+		// Build footer: scroll position hint
+		const hasContentBelow = pi.pixels_below > 4
+		const footer =
+			hasContentBelow && viewportExpansion !== -1
+				? `... ${pi.pixels_below} pixels below (${pi.pages_below.toFixed(1)} pages) - scroll to see more ...`
+				: '[End of page]'
+
+		return { url, title, header, content, footer }
 	}
 
 	// ======= DOM Tree Operations =======
@@ -136,12 +159,18 @@ export class PageController extends EventTarget {
 	/**
 	 * Update DOM tree, returns simplified HTML for LLM.
 	 * This is the main method to refresh the page state.
+	 * Automatically bypasses mask during DOM extraction if enabled.
 	 */
 	async updateTree(): Promise<string> {
 		this.dispatchEvent(new Event('beforeUpdate'))
 
 		this.lastTimeUpdate = Date.now()
 
+		// Temporarily bypass mask to allow DOM extraction
+		if (this.mask) {
+			this.mask.wrapper.style.pointerEvents = 'none'
+		}
+
 		dom.cleanUpHighlights()
 
 		const blacklist = [
@@ -162,6 +191,11 @@ export class PageController extends EventTarget {
 		this.elementTextMap.clear()
 		this.elementTextMap = dom.getElementTextMap(this.simplifiedHTML)
 
+		// Restore mask blocking
+		if (this.mask) {
+			this.mask.wrapper.style.pointerEvents = 'auto'
+		}
+
 		this.dispatchEvent(new Event('afterUpdate'))
 
 		return this.simplifiedHTML
@@ -326,6 +360,24 @@ export class PageController extends EventTarget {
 		}
 	}
 
+	// ======= Mask Operations =======
+
+	/**
+	 * Show the visual mask overlay.
+	 * Only works if enableMask was set to true in config.
+	 */
+	showMask(): void {
+		this.mask?.show()
+	}
+
+	/**
+	 * Hide the visual mask overlay.
+	 * Only works if enableMask was set to true in config.
+	 */
+	hideMask(): void {
+		this.mask?.hide()
+	}
+
 	/**
 	 * Dispose and clean up resources
 	 */
@@ -335,5 +387,7 @@ export class PageController extends EventTarget {
 		this.selectorMap.clear()
 		this.elementTextMap.clear()
 		this.simplifiedHTML = '<EMPTY>'
+		this.mask?.dispose()
+		this.mask = null
 	}
 }

packages/page-controller/src/actions.ts

@@ -287,12 +287,52 @@ export async function scrollVertically(
 			(document.documentElement as HTMLElement)
 
 	if (el === document.scrollingElement || el === document.documentElement || el === document.body) {
+		// Page-level scroll
+		const scrollBefore = window.scrollY
+		const scrollMax = document.documentElement.scrollHeight - window.innerHeight
+
 		window.scrollBy(0, dy)
-		return `✅ Scrolled page by ${dy}px.`
+
+		const scrollAfter = window.scrollY
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dy > 0
+				? `⚠️ Already at the bottom of the page, cannot scroll down further.`
+				: `⚠️ Already at the top of the page, cannot scroll up further.`
+		}
+
+		const reachedBottom = dy > 0 && scrollAfter >= scrollMax - 1
+		const reachedTop = dy < 0 && scrollAfter <= 1
+
+		if (reachedBottom) return `✅ Scrolled page by ${scrolled}px. Reached the bottom of the page.`
+		if (reachedTop) return `✅ Scrolled page by ${scrolled}px. Reached the top of the page.`
+		return `✅ Scrolled page by ${scrolled}px.`
 	} else {
+		// Container scroll
+		const scrollBefore = el!.scrollTop
+		const scrollMax = el!.scrollHeight - el!.clientHeight
+
 		el!.scrollBy({ top: dy, behavior: 'smooth' })
-		await waitFor(0.1) // Animation playback
-		return `✅ Scrolled container (${el!.tagName}) by ${dy}px.`
+		await waitFor(0.1)
+
+		const scrollAfter = el!.scrollTop
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dy > 0
+				? `⚠️ Already at the bottom of container (${el!.tagName}), cannot scroll down further.`
+				: `⚠️ Already at the top of container (${el!.tagName}), cannot scroll up further.`
+		}
+
+		const reachedBottom = dy > 0 && scrollAfter >= scrollMax - 1
+		const reachedTop = dy < 0 && scrollAfter <= 1
+
+		if (reachedBottom)
+			return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the bottom.`
+		if (reachedTop)
+			return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the top.`
+		return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px.`
 	}
 }
 
@@ -410,11 +450,52 @@ export async function scrollHorizontally(
 			(document.documentElement as HTMLElement)
 
 	if (el === document.scrollingElement || el === document.documentElement || el === document.body) {
+		// Page-level scroll
+		const scrollBefore = window.scrollX
+		const scrollMax = document.documentElement.scrollWidth - window.innerWidth
+
 		window.scrollBy(dx, 0)
-		return `✅ Scrolled page horizontally by ${dx}px`
+
+		const scrollAfter = window.scrollX
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dx > 0
+				? `⚠️ Already at the right edge of the page, cannot scroll right further.`
+				: `⚠️ Already at the left edge of the page, cannot scroll left further.`
+		}
+
+		const reachedRight = dx > 0 && scrollAfter >= scrollMax - 1
+		const reachedLeft = dx < 0 && scrollAfter <= 1
+
+		if (reachedRight)
+			return `✅ Scrolled page by ${scrolled}px. Reached the right edge of the page.`
+		if (reachedLeft) return `✅ Scrolled page by ${scrolled}px. Reached the left edge of the page.`
+		return `✅ Scrolled page horizontally by ${scrolled}px.`
 	} else {
+		// Container scroll
+		const scrollBefore = el!.scrollLeft
+		const scrollMax = el!.scrollWidth - el!.clientWidth
+
 		el!.scrollBy({ left: dx, behavior: 'smooth' })
-		await waitFor(0.1) // Animation playback
-		return `✅ Scrolled container (${el!.tagName}) horizontally by ${dx}px`
+		await waitFor(0.1)
+
+		const scrollAfter = el!.scrollLeft
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dx > 0
+				? `⚠️ Already at the right edge of container (${el!.tagName}), cannot scroll right further.`
+				: `⚠️ Already at the left edge of container (${el!.tagName}), cannot scroll left further.`
+		}
+
+		const reachedRight = dx > 0 && scrollAfter >= scrollMax - 1
+		const reachedLeft = dx < 0 && scrollAfter <= 1
+
+		if (reachedRight)
+			return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the right edge.`
+		if (reachedLeft)
+			return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the left edge.`
+		return `✅ Scrolled container (${el!.tagName}) horizontally by ${scrolled}px.`
 	}
 }

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

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

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

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

packages/page-controller/tsconfig.dts.json

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

packages/page-controller/tsconfig.json

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

packages/page-controller/vite.config.js

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

packages/ui/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@page-agent/ui",
-	"version": "0.0.16",
+	"version": "0.2.5",
 	"type": "module",
 	"main": "./dist/lib/page-agent-ui.js",
 	"module": "./dist/lib/page-agent-ui.js",
@@ -15,7 +15,7 @@
 	"files": [
 		"dist/"
 	],
-	"description": "UI components for page-agent - Panel, SimulatorMask, and i18n",
+	"description": "UI components for page-agent - Panel and i18n",
 	"keywords": [
 		"page-agent",
 		"ui",
@@ -34,8 +34,5 @@
 		"build": "vite build",
 		"prepublishOnly": "node -e \"const fs=require('fs');['LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
 		"postpublish": "node -e \"['LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
-	},
-	"dependencies": {
-		"ai-motion": "^0.4.7"
 	}
 }

packages/ui/src/Panel.module.css

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

packages/ui/src/Panel.ts

@@ -1,6 +1,6 @@
 import { type Step, UIState } from './UIState'
 import { I18n, type SupportedLanguage } from './i18n'
-import { truncate } from './utils'
+import { escapeHtml, truncate } from './utils'
 
 import styles from './Panel.module.css'
 
@@ -11,8 +11,11 @@ export interface PanelConfig {
 	language?: SupportedLanguage
 	onExecuteTask: (task: string) => void
 	onStop: () => void
-	onPauseToggle: () => boolean // returns new paused state
-	getPaused: () => boolean
+	/**
+	 * Whether to prompt for next task after task completion
+	 * @default true
+	 */
+	promptForNextTask?: boolean
 }
 
 /**
@@ -29,6 +32,7 @@ export type PanelUpdate =
 	| { type: 'completed' }
 	| { type: 'toolExecuting'; toolName: string; args: any }
 	| { type: 'toolCompleted'; toolName: string; args: any; result?: string; duration?: number }
+	| { type: 'observation'; content: string }
 
 /**
  * Agent control panel
@@ -39,7 +43,6 @@ export class Panel {
 	#statusText: HTMLElement
 	#historySection: HTMLElement
 	#expandButton: HTMLElement
-	#pauseButton: HTMLElement
 	#stopButton: HTMLElement
 	#inputSection: HTMLElement
 	#taskInput: HTMLInputElement
@@ -66,7 +69,6 @@ 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.#pauseButton = this.#wrapper.querySelector(`.${styles.pauseButton}`)!
 		this.#stopButton = this.#wrapper.querySelector(`.${styles.stopButton}`)!
 		this.#inputSection = this.#wrapper.querySelector(`.${styles.inputSectionWrapper}`)!
 		this.#taskInput = this.#wrapper.querySelector(`.${styles.taskInput}`)!
@@ -75,6 +77,8 @@ export class Panel {
 		this.#startHeaderUpdateLoop()
 
 		this.#showInputArea()
+
+		this.hide() // Start hidden
 	}
 
 	/**
@@ -120,11 +124,6 @@ export class Panel {
 		this.#updateStatusIndicator('thinking')
 		this.#updateHistory()
 		this.#collapse()
-		// Reset pause state via callback
-		if (this.#config.getPaused()) {
-			this.#config.onPauseToggle()
-		}
-		this.#updatePauseButton()
 		// Reset user input state
 		this.#isWaitingForUserAnswer = false
 		this.#userAnswerResolver = null
@@ -205,6 +204,8 @@ export class Panel {
 					duration: data.duration,
 				}
 			}
+			case 'observation':
+				return { type: 'observation', displayText: data.content }
 		}
 	}
 
@@ -277,39 +278,6 @@ export class Panel {
 		}
 	}
 
-	/**
-	 * Toggle pause state
-	 */
-	#togglePause(): void {
-		const paused = this.#config.onPauseToggle()
-		this.#updatePauseButton()
-
-		// Update status display
-		if (paused) {
-			this.#statusText.textContent = this.#i18n.t('ui.panel.paused')
-			this.#updateStatusIndicator('thinking')
-		} else {
-			this.#statusText.textContent = this.#i18n.t('ui.panel.continueExecution')
-			this.#updateStatusIndicator('tool_executing')
-		}
-	}
-
-	/**
-	 * Update pause button state
-	 */
-	#updatePauseButton(): void {
-		const paused = this.#config.getPaused()
-		if (paused) {
-			this.#pauseButton.textContent = '▶'
-			this.#pauseButton.title = this.#i18n.t('ui.panel.continue')
-			this.#pauseButton.classList.add(styles.paused)
-		} else {
-			this.#pauseButton.textContent = '⏸︎'
-			this.#pauseButton.title = this.#i18n.t('ui.panel.pause')
-			this.#pauseButton.classList.remove(styles.paused)
-		}
-	}
-
 	/**
 	 * Stop Agent
 	 */
@@ -395,13 +363,20 @@ export class Panel {
 		}
 
 		const lastStep = steps[steps.length - 1]
-		return lastStep.type === 'completed' || lastStep.type === 'error'
+		const isTaskEnded = lastStep.type === 'completed' || lastStep.type === 'error'
+
+		// Only show input area after task completion if configured to do so
+		if (isTaskEnded) {
+			return this.#config.promptForNextTask ?? true
+		}
+
+		return false
 	}
 
 	#createWrapper(): HTMLElement {
 		const wrapper = document.createElement('div')
 		wrapper.id = 'page-agent-runtime_agent-panel'
-		wrapper.className = `${styles.wrapper} ${styles.collapsed}`
+		wrapper.className = styles.wrapper
 		wrapper.setAttribute('data-browser-use-ignore', 'true')
 
 		wrapper.innerHTML = `
@@ -426,9 +401,6 @@ export class Panel {
 					<button class="${styles.controlButton} ${styles.expandButton}" title="${this.#i18n.t('ui.panel.expand')}">
 						▼
 					</button>
-					<button class="${styles.controlButton} ${styles.pauseButton}" title="${this.#i18n.t('ui.panel.pause')}">
-						⏸︎
-					</button>
 					<button class="${styles.controlButton} ${styles.stopButton}" title="${this.#i18n.t('ui.panel.stop')}">
 						X
 					</button>
@@ -466,12 +438,6 @@ export class Panel {
 			this.#toggle()
 		})
 
-		// Pause/continue button
-		this.#pauseButton.addEventListener('click', (e) => {
-			e.stopPropagation()
-			this.#togglePause()
-		})
-
 		// Stop button
 		this.#stopButton.addEventListener('click', (e) => {
 			e.stopPropagation()
@@ -503,7 +469,6 @@ export class Panel {
 
 	#expand(): void {
 		this.#isExpanded = true
-		this.wrapper.classList.remove(styles.collapsed)
 		this.wrapper.classList.add(styles.expanded)
 		this.#expandButton.textContent = '▲'
 	}
@@ -511,7 +476,6 @@ export class Panel {
 	#collapse(): void {
 		this.#isExpanded = false
 		this.wrapper.classList.remove(styles.expanded)
-		this.wrapper.classList.add(styles.collapsed)
 		this.#expandButton.textContent = '▼'
 	}
 
@@ -590,10 +554,7 @@ export class Panel {
 
 	#updateHistory(): void {
 		const steps = this.#state.getAllSteps()
-
 		this.#historySection.innerHTML = steps.map((step) => this.#createHistoryItem(step)).join('')
-
-		// Scroll to bottom to show latest records
 		this.#scrollToBottom()
 	}
 
@@ -635,7 +596,7 @@ export class Panel {
 			typeClass = styles.error
 			statusIcon = '❌'
 		} else if (step.type === 'tool_executing') {
-			statusIcon = '⚙️'
+			statusIcon = '🔨'
 		} else if (step.type === 'output') {
 			typeClass = styles.output
 			statusIcon = '🤖'
@@ -645,6 +606,9 @@ export class Panel {
 		} else if (step.type === 'retry') {
 			typeClass = styles.retry
 			statusIcon = '🔄'
+		} else if (step.type === 'observation') {
+			typeClass = styles.observation
+			statusIcon = '👁️'
 		} else {
 			statusIcon = '🧠'
 		}
@@ -660,7 +624,7 @@ export class Panel {
 			<div class="${styles.historyItem} ${typeClass}">
 				<div class="${styles.historyContent}">
 					<span class="${styles.statusIcon}">${statusIcon}</span>
-					<span>${step.displayText}</span>
+					<span>${escapeHtml(step.displayText)}</span>
 				</div>
 				<div class="${styles.historyMeta}">
 					${stepLabel}

packages/ui/src/UIState.ts

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

packages/ui/src/i18n/index.ts

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

packages/ui/src/i18n/locales.ts

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

packages/ui/src/index.ts

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

packages/ui/src/motion-css/readme

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

packages/ui/src/utils.ts

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

packages/ui/tsconfig.dts.json

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

packages/ui/tsconfig.json

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

packages/ui/vite.config.js

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

packages/website/AGENTS.md

@@ -37,14 +37,17 @@ Available Magic UI components: https://magicui.design/docs/components
 Located in `src/components/ui/`:
 
 **From shadcn/ui:**
+
 - `alert`, `badge`, `button`, `separator`, `sonner`, `switch`, `tooltip`
 
 **From Magic UI:**
+
 - `animated-gradient-text`, `animated-shiny-text`, `aurora-text`
 - `hyper-text`, `magic-card`, `neon-gradient-card`, `particles`
 - `sparkles-text`, `text-animate`, `typing-animation`
 
 **Custom:**
+
 - `highlighter`, `kbd`, `spinner`
 
 ### Styling Rules
@@ -58,17 +61,17 @@ Located in `src/components/ui/`:
 
 ```
 src/
+├── pages/
+│   ├── Home.tsx         # Homepage
+│   └── docs/
+│       ├── Layout.tsx   # Documentation sidebar
+│       └── [section]/[topic]/page.tsx
 ├── components/
 │   ├── ui/              # shadcn/ui + Magic UI components
 │   ├── Header.tsx       # Site header
-│   ├── Footer.tsx       # Site footer
-│   └── DocsLayout.tsx   # Documentation sidebar
-├── docs/                # Documentation pages
-│   └── [section]/[topic]/page.tsx
-├── test-pages/          # Library integration tests
+│   └── Footer.tsx       # Site footer
 ├── i18n/                # Internationalization
 ├── router.tsx           # Central routing
-├── page.tsx             # Homepage
 └── main.tsx             # App entry
 ```
 
@@ -76,14 +79,9 @@ src/
 
 ### Documentation Page
 
-1. Create `src/docs/<section>/<slug>/page.tsx`
+1. Create `src/pages/docs/<section>/<slug>/page.tsx`
 2. Add route to `src/router.tsx` with `<Header /> + <DocsLayout>` wrapper
-3. Add navigation item to `DocsLayout.tsx`
-
-### Test Page
-
-1. Create `src/test-pages/<name>.tsx`
-2. Add route to `src/test-pages/router.tsx`
+3. Add navigation item to `pages/docs/Layout.tsx`
 
 ## Routing
 
@@ -93,18 +91,16 @@ Uses hash-based routing for static hosting:
 import { Router } from 'wouter'
 import { useHashLocation } from 'wouter/use-hash-location'
 
-<Router hook={useHashLocation}>
-  {/* routes */}
-</Router>
+;<Router hook={useHashLocation}>{/* routes */}</Router>
 ```
 
 ## Configuration Files
 
-| File | Purpose |
-|------|---------|
+| File              | Purpose                 |
+| ----------------- | ----------------------- |
 | `components.json` | shadcn/ui configuration |
-| `vite.config.js` | Vite build settings |
-| `tsconfig.json` | TypeScript config |
+| `vite.config.js`  | Vite build settings     |
+| `tsconfig.json`   | TypeScript config       |
 
 ## Commands
 
@@ -112,4 +108,3 @@ import { useHashLocation } from 'wouter/use-hash-location'
 npm start        # Dev server (from root)
 npm run build:website    # Build website (from root)
 ```
-

packages/website/README.md

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

packages/website/components.json

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

packages/website/package.json

@@ -1,24 +1,24 @@
 {
 	"name": "@page-agent/website",
 	"private": true,
-	"version": "0.0.16",
+	"version": "0.2.5",
 	"type": "module",
 	"scripts": {
-		"dev": "vite",
+		"dev": "vite --host 0.0.0.0",
 		"build:website": "vite build",
 		"preview": "vite preview",
 		"typecheck": "tsc --noEmit"
 	},
 	"devDependencies": {
 		"@tailwindcss/vite": "^4.1.18",
-		"@types/react": "^19.2.2",
+		"@types/react": "^19.2.8",
 		"@types/react-dom": "^19.2.1",
 		"@vitejs/plugin-react-swc": "^4.1.0",
-		"i18next": "^25.7.3",
+		"i18next": "^25.7.4",
 		"i18next-browser-languagedetector": "^8.2.0",
 		"react": "^19.2.3",
 		"react-dom": "^19.2.3",
-		"react-i18next": "^16.5.0",
+		"react-i18next": "^16.5.2",
 		"tailwindcss": "^4.1.14",
 		"tw-animate-css": "^1.4.0",
 		"wouter": "^3.9.0"
@@ -32,10 +32,10 @@
 		"class-variance-authority": "^0.7.1",
 		"clsx": "^2.1.1",
 		"lucide-react": "^0.562.0",
-		"motion": "^12.23.26",
+		"motion": "^12.26.1",
 		"next-themes": "^0.4.6",
 		"rough-notation": "^0.5.1",
-		"simple-icons": "^16.2.0",
+		"simple-icons": "^16.5.0",
 		"sonner": "^2.0.7",
 		"tailwind-merge": "^3.4.0"
 	}

packages/website/src/components/Header.tsx

@@ -22,7 +22,7 @@ export default function Header() {
 					<div className="flex items-center justify-between gap-2">
 						{/* Logo */}
 						<Link
-							href="/"
+							href="~/"
 							className="flex items-center gap-2 sm:gap-3 group shrink-0"
 							aria-label={t('header.logo_alt')}
 							onClick={() => setMobileMenuOpen(false)}
@@ -41,6 +41,7 @@ export default function Header() {
 									className="hidden sm:block text-xs text-gray-600 dark:text-gray-300 py-0 font-normal overflow-visible"
 									duration={600}
 									animateOnHover={true}
+									aria-hidden="true"
 								>
 									{t('header.slogan')}
 								</HyperText>
@@ -54,7 +55,7 @@ export default function Header() {
 							aria-label="Mobile navigation"
 						>
 							<Link
-								href="/docs/introduction/overview"
+								href="~/docs/introduction/overview"
 								className="p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200 shrink-0"
 								aria-label={t('header.nav_docs')}
 							>
@@ -84,8 +85,11 @@ export default function Header() {
 							role="navigation"
 							aria-label={t('header.nav_docs')}
 						>
+							<span className="text-xs font-mono text-gray-400 dark:text-gray-500 tabular-nums before:content-['v']">
+								{import.meta.env.VERSION}
+							</span>
 							<Link
-								href="/docs/introduction/overview"
+								href="~/docs/introduction/overview"
 								className="flex items-center gap-1.5 text-gray-600 dark:text-gray-300 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
 							>
 								<BookOpen className="w-4 h-4" />
@@ -133,7 +137,7 @@ export default function Header() {
 							role="navigation"
 						>
 							<Link
-								href="/docs/introduction/overview"
+								href="~/docs/introduction/overview"
 								className="flex items-center gap-2 px-3 py-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
 								onClick={() => setMobileMenuOpen(false)}
 							>

packages/website/src/constants.ts

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

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

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

packages/website/src/docs/features/knowledge-injection/page.tsx

@@ -1,162 +0,0 @@
-import BetaNotice from '@/components/BetaNotice'
-import CodeEditor from '@/components/CodeEditor'
-
-export default function KnowledgeInjection() {
-	return (
-		<div>
-			<h1 className="text-4xl font-bold mb-6">知识库注入</h1>
-
-			<BetaNotice />
-
-			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
-				通过多层次的知识注入，让 AI 深度理解你的业务场景和应用逻辑，实现更精准的自动化操作。
-			</p>
-
-			{/* Custom Instruction */}
-			<section className="mb-12">
-				<h2 className="text-3xl font-bold mb-6">Instruction - 系统指令</h2>
-
-				<div className="p-6 bg-purple-50 dark:bg-purple-900/20 rounded-lg mb-6">
-					<h3 className="text-xl font-semibold mb-3 text-purple-900 dark:text-purple-300">
-						🎯 系统级指令
-					</h3>
-					<p className="text-gray-600 dark:text-gray-300 mb-4">
-						为 AI 设定全局行为准则和工作风格。
-					</p>
-					<ul className="list-disc list-inside space-y-2 text-gray-500 dark:text-gray-400">
-						<li>定义 AI 的工作风格和交互方式</li>
-						<li>设置安全边界和操作限制</li>
-						<li>指定错误处理和异常情况的应对策略</li>
-						<li>配置输出格式和反馈机制</li>
-					</ul>
-				</div>
-
-				<CodeEditor
-					className="mb-6"
-					code={`// 构造函数中设置系统指令
-const pageAgent = new PageAgent({
-  instruction: \`
-# 角色定义
-你是专业的电商运营助手。
-
-# 工作风格
-- 谨慎：操作前确认
-- 准确：确保正确性
-- 高效：优化流程
-
-# 错误处理
-遇到错误时暂停并报告。
-\`
-});`}
-				/>
-			</section>
-
-			{/* App Knowledge */}
-			<section className="mb-12">
-				<h2 className="text-3xl font-bold mb-6">App Knowledge - 应用知识</h2>
-
-				<div className="p-6 bg-blue-50 dark:bg-blue-900/20 rounded-lg mb-6">
-					<h3 className="text-xl font-semibold mb-3 text-blue-900 dark:text-blue-300">
-						� 业务领域知识
-					</h3>
-					<p className="text-gray-600 dark:text-gray-300 mb-4">
-						注入应用的核心业务知识，包括产品介绍、操作流程、术语定义等，让 AI 理解业务上下文。
-					</p>
-					<div className="grid md:grid-cols-2 gap-4">
-						<div className="space-y-2">
-							<h4 className="font-semibold text-blue-800 dark:text-blue-200">产品知识</h4>
-							<ul className="list-disc list-inside text-sm text-gray-500 dark:text-gray-400 space-y-1">
-								<li>产品功能和特性介绍</li>
-								<li>用户角色和权限体系</li>
-								<li>业务规则和约束条件</li>
-							</ul>
-						</div>
-						<div className="space-y-2">
-							<h4 className="font-semibold text-blue-800 dark:text-blue-200">操作指南</h4>
-							<ul className="list-disc list-inside text-sm text-gray-500 dark:text-gray-400 space-y-1">
-								<li>标准操作流程定义</li>
-								<li>异常情况处理方案</li>
-								<li>术语和概念解释</li>
-							</ul>
-						</div>
-					</div>
-				</div>
-
-				<CodeEditor
-					className="mb-6"
-					code={`// 应用知识
-pageAgent.knowledge.setAppKnowledge(\`
-# 产品介绍
-电商管理系统：面向中小企业的一站式解决方案。
-
-# 操作流程
-## 商品上架
-1. 进入商品管理页面 2. 点击新增商品 3. 填写基本信息 4. 设置库存 5. 提交审核
-
-# 术语解释
-- SKU：库存量单位
-- SPU：标准产品单位
-- 运费模板：物流费用计算规则
-
-# 业务规则
-- 库存为0时自动下架
-- VIP会员享9.5折
-\`);`}
-				/>
-			</section>
-
-			{/* Page Knowledge */}
-			<section className="mb-12">
-				<h2 className="text-3xl font-bold mb-6">Page Knowledge - 页面知识</h2>
-
-				<div className="p-6 bg-green-50 dark:bg-green-900/20 rounded-lg mb-6">
-					<h3 className="text-xl font-semibold mb-3 text-green-900 dark:text-green-300">
-						📄 页面级精准指导
-					</h3>
-					<p className="text-gray-600 dark:text-gray-300 mb-4">
-						为特定页面提供精确的操作指导和元素说明，让 AI 准确理解页面结构和交互逻辑。
-					</p>
-					<div className="grid md:grid-cols-3 gap-4">
-						<div className="space-y-2">
-							<h4 className="font-semibold text-green-800 dark:text-green-200">元素标注</h4>
-							<p className="text-sm text-gray-500 dark:text-gray-400">为页面元素添加语义化描述</p>
-						</div>
-						<div className="space-y-2">
-							<h4 className="font-semibold text-green-800 dark:text-green-200">交互说明</h4>
-							<p className="text-sm text-gray-500 dark:text-gray-400">
-								定义元素的交互行为和预期结果
-							</p>
-						</div>
-						<div className="space-y-2">
-							<h4 className="font-semibold text-green-800 dark:text-green-200">页面逻辑</h4>
-							<p className="text-sm text-gray-500 dark:text-gray-400">
-								说明页面的业务逻辑和状态变化
-							</p>
-						</div>
-					</div>
-				</div>
-
-				<CodeEditor
-					className="mb-6"
-					code={`// 页面知识库
-// 添加页面知识
-pageAgent.knowledge.addPageKnowledge("/products", \`
-商品列表页面，包含搜索、筛选、批量操作功能。
-#add-product-btn：新增商品按钮
-.product-item：商品列表项
-#search-input：搜索框，最少2个字符
-\`);
-
-pageAgent.knowledge.addPageKnowledge("/orders/*", \`
-订单详情页面。
-.order-status：订单状态标签
-#update-status-btn：状态更新按钮
-\`);
-
-// 移除页面知识
-pageAgent.knowledge.removePageKnowledge("/products");`}
-				/>
-			</section>
-		</div>
-	)
-}

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

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

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

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

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

@@ -1,116 +0,0 @@
-import CodeEditor from '@/components/CodeEditor'
-
-export default function Configuration() {
-	return (
-		<div>
-			<h1 className="text-4xl font-bold mb-6">配置选项</h1>
-
-			<CodeEditor
-				className="mb-8"
-				language="typescript"
-				code={`// config
-type PageAgentConfig = LLMConfig & AgentConfig & PageControllerConfig
-
-interface LLMConfig {
-	baseURL?: string
-	apiKey?: string
-	model?: string
-	temperature?: number
-	maxTokens?: number
-	maxRetries?: number
-
-	/**
-	 * Custom fetch function for LLM API requests.
-	 * Use this to customize headers, credentials, proxy, etc.
-	 * The response should follow OpenAI API format.
-	 */
-	customFetch?: typeof globalThis.fetch
-}
-
-interface AgentConfig {
-	language?: "en-US" | "zh-CN"
-
-	/**
-	 * Custom tools to extend PageAgent capabilities
-	 * @experimental
-	 * @note You can also override or remove internal tools by using the same name.
-	 * @see [tools](../tools/index.ts)
-	 *
-	 * @example
-	 * // override internal tool
-	 * import { tool } from 'page-agent'
-	 * const customTools = {
-	 * ask_user: tool({
-	 * 	description:
-	 * 		'Ask the user or parent model a question and wait for their answer. Use this if you need more information or clarification.',
-	 * 	inputSchema: zod.object({
-	 * 		question: zod.string(),
-	 * 	}),
-	 * 	execute: async function (this: PageAgent, input) {
-	 * 		const answer = await do_some_thing(input.question)
-	 * 		return "✅ Received user answer: " + answer
-	 * 	},
-	 * })
-	 * }
-	 *
-	 * @example
-	 * // remove internal tool
-	 * const customTools = {
-	 * 	ask_user: null // never ask user questions
-	 * }
-	 */
-	customTools?: Record<string, PageAgentTool | null>
-
-	// lifecycle hooks
-	// @todo: use event instead of hooks
-
-	onBeforeStep?: (this: PageAgent, stepCnt: number) => Promise<void> | void
-	onAfterStep?: (this: PageAgent, stepCnt: number, history: AgentHistory[]) => Promise<void> | void
-	onBeforeTask?: (this: PageAgent) => Promise<void> | void
-	onAfterTask?: (this: PageAgent, result: ExecutionResult) => Promise<void> | void
-
-	/**
-	 * @note this hook can block the disposal process
-	 * @note when dispose caused by page unload, "reason" will be 'PAGE_UNLOADING'. this method CANNOT block unloading. async operations may be cut.
-	 */
-	onDispose?: (this: PageAgent, reason?: string) => void
-
-	// page behavior hooks
-
-	/**
-	 * @experimental
-	 * Enable the experimental script execution tool that allows executing generated JavaScript code on the page.
-	 * @note Can cause unpredictable side effects.
-	 * @note May bypass some safe guards and data-masking mechanisms.
-	 */
-	experimentalScriptExecutionTool?: boolean
-
-	/**
-	 * TODO: @unimplemented
-	 * hook when action causes a new page to be opened
-	 * @note PageAgent will try to detect new pages and decide if it's caused by an action. But not very reliable.
-	 */
-	onNewPageOpen?: (this: PageAgent, url: string) => Promise<void> | void
-
-	/**
-	 * TODO: @unimplemented
-	 * try to navigate to a new page instead of opening a new tab/window.
-	 * @note will unload the current page when a action tries to open a new page. so that things keep in the same tab/window.
-	 */
-	experimentalPreventNewPage?: boolean
-}
-
-interface PageControllerConfig {
-	interactiveBlacklist?: (Element | (() => Element))[]
-	interactiveWhitelist?: (Element | (() => Element))[]
-	include_attributes?: string[]
-	highlightOpacity?: number
-	highlightLabelOpacity?: number
-	viewportExpansion?: number
-}
-
-`}
-			/>
-		</div>
-	)
-}

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

@@ -1,84 +0,0 @@
-import { useTranslation } from 'react-i18next'
-
-import BetaNotice from '@/components/BetaNotice'
-import CodeEditor from '@/components/CodeEditor'
-import { CDN_CN_URL, CDN_URL } from '@/constants'
-
-export default function QuickStart() {
-	const { t } = useTranslation('docs')
-
-	return (
-		<div>
-			<h1 className="text-4xl font-bold mb-6">{t('quick_start.title')}</h1>
-
-			<p className=" mb-6 leading-relaxed">{t('quick_start.subtitle')}</p>
-
-			<h2 className="text-2xl font-bold mb-3">{t('quick_start.installation')}</h2>
-
-			<div className="space-y-4 mb-6">
-				<div className="p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg">
-					<h3 className="text-lg font-semibold mb-2 text-blue-900 dark:text-blue-300">
-						{t('quick_start.step1_title')}
-					</h3>
-					<div className="space-y-3">
-						<div>
-							<p className="text-sm font-medium mb-2">{t('quick_start.step1_cdn')}</p>
-							<CodeEditor
-								code={`// CDN: \t${CDN_URL}
-// Mirror: \t${CDN_CN_URL}
-<script src="${CDN_URL}" crossorigin="true" type="text/javascript"></script>`}
-								language="html"
-							/>
-						</div>
-						<div>
-							<p className="text-sm font-medium mb-2">{t('quick_start.step1_npm')}</p>
-							<CodeEditor
-								code={`// npm install page-agent
-import PageAgent from 'page-agent'`}
-								language="bash"
-							/>
-						</div>
-					</div>
-				</div>
-
-				<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
-					<h3 className="text-lg font-semibold mb-2 text-green-900 dark:text-green-300">
-						{t('quick_start.step2_title')}
-					</h3>
-					<CodeEditor
-						code={`// 仅供测试使用，生产环境需要配置 LLM 接入点，本工具不提供 LLM 服务
-// 测试接口
-// @note: 限流，限制 prompt 内容，限制来源，随时变更，请替换成你自己的
-// @note: 使用 DeepSeek-chat(3.2) 官方版本，使用协议和隐私策略见 DeepSeek 网站
-const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
-const agent = new PageAgent({
-  modelName: DEMO_MODEL,
-  baseURL: DEMO_BASE_URL,
-  apiKey: DEMO_API_KEY,
-  language: 'zh-CN'
-})`}
-						language="javascript"
-					/>
-				</div>
-
-				<div className="p-4 bg-purple-50 dark:bg-purple-900/20 rounded-lg">
-					<h3 className="text-lg font-semibold mb-2 text-purple-900 dark:text-purple-300">
-						{t('quick_start.step3_title')}
-					</h3>
-					<CodeEditor
-						code={`// 程序化执行自然语言指令
-await pageAgent.execute('点击提交按钮，然后填写用户名为张三');
-
-// 或者显示对话框让用户输入指令
-pageAgent.panel.show()
-`}
-						language="javascript"
-					/>
-				</div>
-			</div>
-		</div>
-	)
-}

packages/website/src/env.d.ts

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

packages/website/src/i18n/README.md

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

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

@@ -27,14 +27,14 @@ export default {
 		overview: 'Overview',
 		quick_start: 'Quick Start',
 		limitations: 'Limitations',
-		model_integration: 'Model Integration',
+		models: 'Models',
 		custom_tools: 'Custom Tools',
-		knowledge_injection: 'Knowledge Injection',
-		security_permissions: 'Security & Permissions',
+		knowledge_injection: 'Instructions',
 		data_masking: 'Data Masking',
 		cdn_setup: 'CDN Setup',
 		configuration: 'Configuration',
 		best_practices: 'Best Practices',
 		third_party_agent: 'Third-party Agent',
+		security_permissions: 'Security & Permissions',
 	},
 }

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

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

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

@@ -26,14 +26,14 @@ export default {
 		overview: '概览',
 		quick_start: '快速开始',
 		limitations: '使用限制',
-		model_integration: '模型接入',
+		models: '模型',
 		custom_tools: '自定义工具',
-		knowledge_injection: '知识库注入',
-		security_permissions: '安全与权限',
+		knowledge_injection: '知识注入',
 		data_masking: '数据脱敏',
 		cdn_setup: 'CDN 引入',
 		configuration: '配置选项',
 		best_practices: '最佳实践',
 		third_party_agent: '接入第三方 Agent',
+		security_permissions: '安全与权限',
 	},
 }

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

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

packages/website/src/main.tsx

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

packages/website/src/pages/Home.tsx

@@ -1,21 +1,26 @@
 /* eslint-disable react-dom/no-dangerously-set-innerhtml */
 import { Bot, Box, MessageSquare, PlayCircle, Shield, Sparkles, Users, Zap } from 'lucide-react'
-import { PageAgent } from 'page-agent'
 import { useEffect, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import { Link, useSearchParams } from 'wouter'
 
-import Footer from './components/Footer'
-import 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_CN_URL, CDN_URL } from './constants'
+import Footer from '../components/Footer'
+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'
 
 function getInjection(useCN?: boolean) {
-	const cdn = useCN ? CDN_CN_URL : CDN_URL
+	const cdn = useCN ? CDN_DEMO_CN_URL : CDN_DEMO_URL
 
 	const injection = encodeURI(
 		`javascript:(function(){var s=document.createElement('script');s.src=\`${cdn}?t=\${Math.random()}\`;s.setAttribute('crossorigin', true);s.type="text/javascript";s.onload=()=>console.log('PageAgent script loaded!');document.body.appendChild(s);})();`
@@ -53,30 +58,45 @@ export default function HomePage() {
 	const handleExecute = async () => {
 		if (!task.trim()) return
 
-		let pageAgent: PageAgent
 		const win = window as any
 
-		if (win.pageAgent && !win.pageAgent.disposed) {
-			pageAgent = win.pageAgent
-		} else {
-			pageAgent = new PageAgent({
+		// 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: i18n.language as any,
 
-				// experimentalScriptExecutionTool: true,
+				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
+					},
+				},
 
-				// testing server
-				// @note: rate limit. prompt limit.
-				// model: DEMO_MODEL,
-				// baseURL: DEMO_BASE_URL,
-				// apiKey: DEMO_API_KEY,
+				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,
 			})
-			win.pageAgent = pageAgent
 		}
 
-		const result = await pageAgent.execute(task)
-
+		const result = await win.pageAgent.execute(task)
 		console.log(result)
 	}
 
@@ -86,7 +106,10 @@ export default function HomePage() {
 
 			{/* Hero Section */}
 			<main id="main-content">
-				<section className="relative px-6 py-22 lg:py-28" aria-labelledby="hero-heading">
+				<section
+					className="relative px-6 py-22 pb-18 lg:py-28 overflow-hidden"
+					aria-labelledby="hero-heading"
+				>
 					<div className="max-w-7xl mx-auto text-center">
 						{/* Background Pattern + Particles */}
 						<div className="absolute inset-0 opacity-30" aria-hidden="true">

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

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

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

@@ -0,0 +1,135 @@
+import { useTranslation } from 'react-i18next'
+
+import CodeEditor from '@/components/CodeEditor'
+
+export default function Instructions() {
+	const { i18n } = useTranslation()
+	const isZh = i18n.language === 'zh-CN'
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">{isZh ? '知识注入' : 'Instructions'}</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? '通过 instructions 配置，为 AI 注入系统级指导和页面级上下文，让它更好地理解你的业务场景。'
+					: 'Use the instructions config to inject system-level directives and page-specific context, helping the AI better understand your application.'}
+			</p>
+
+			{/* System Instructions */}
+			<section className="mb-12">
+				<h2 className="text-3xl font-bold mb-6">
+					{isZh ? '系统级指导 (System Instructions)' : 'System Instructions'}
+				</h2>
+
+				<p className="text-gray-600 dark:text-gray-300 mb-6">
+					{isZh
+						? '全局提示词，应用于所有任务。定义 AI 的角色、工作风格和行为边界。'
+						: "Global directives applied to all tasks. Define the AI's role, working style, and behavioral boundaries."}
+				</p>
+
+				<CodeEditor
+					className="mb-6"
+					code={`const agent = new PageAgent({
+  // ...other config
+  instructions: {
+    system: \`
+You are a professional e-commerce assistant.
+
+Guidelines:
+- Always confirm before submitting orders
+- Double-check prices and quantities
+- Report errors immediately instead of retrying blindly
+\`
+  }
+})`}
+				/>
+			</section>
+
+			{/* Page Instructions */}
+			<section className="mb-12">
+				<h2 className="text-3xl font-bold mb-6">
+					{isZh ? '页面级指导 (Page Instructions)' : 'Page Instructions'}
+				</h2>
+
+				<p className="text-gray-600 dark:text-gray-300 mb-6">
+					{isZh
+						? '动态回调函数，在每个 step 执行前调用，根据当前页面 URL 返回特定提示词。适用于为不同页面提供针对性的操作引导。'
+						: 'A dynamic callback invoked before each step. Returns page-specific instructions based on the current URL. Useful for providing targeted guidance on different pages.'}
+				</p>
+
+				<CodeEditor
+					className="mb-6"
+					code={`const agent = new PageAgent({
+  // ...other config
+  instructions: {
+    system: 'You are an order management assistant.',
+
+    getPageInstructions: (url) => {
+      if (url.includes('/checkout')) {
+        return \`
+This is the checkout page.
+- Verify shipping address before proceeding
+- Check if any discounts are applied
+- Confirm the total amount with the user
+\`
+      }
+
+      if (url.includes('/products')) {
+        return \`
+This is the product listing page.
+- Use filters to narrow down search results
+- Check stock availability before adding to cart
+\`
+      }
+
+      return undefined // No special instructions for other pages
+    }
+  }
+})`}
+				/>
+			</section>
+
+			{/* How It Works */}
+			<section className="mb-12">
+				<h2 className="text-3xl font-bold mb-6">{isZh ? '工作原理' : 'How It Works'}</h2>
+
+				<p className="text-gray-600 dark:text-gray-300 mb-4">
+					{isZh
+						? '在每个执行步骤之前，page-agent 会将 instructions 拼接到用户提示词中：'
+						: 'Before each execution step, page-agent prepends the instructions to the user prompt:'}
+				</p>
+
+				<CodeEditor
+					language="xml"
+					className="mb-6"
+					code={`<instructions>
+<system_instructions>
+You are a professional e-commerce assistant.
+...
+</system_instructions>
+<page_instructions>
+This is the checkout page.
+...
+</page_instructions>
+</instructions>
+
+<!-- followed by agent state, history, and browser state -->`}
+				/>
+
+				<ul className="list-disc list-inside space-y-2 text-gray-600 dark:text-gray-400">
+					<li>
+						{isZh
+							? '如果 system 为空，则不输出 <system_instructions> 标签'
+							: 'If system is empty, the <system_instructions> tag is omitted'}
+					</li>
+					<li>
+						{isZh
+							? '如果 getPageInstructions 返回空值，则不输出 <page_instructions> 标签'
+							: 'If getPageInstructions returns empty, the <page_instructions> tag is omitted'}
+					</li>
+				</ul>
+			</section>
+		</div>
+	)
+}

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

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

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

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

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

@@ -0,0 +1,110 @@
+import { Suspense } from 'react'
+import { Route, Switch } from 'wouter'
+
+import Header from '../../components/Header'
+import DocsLayout from './Layout'
+import Instructions from './features/custom-instructions/page'
+// Features
+import CustomTools from './features/custom-tools/page'
+import DataMasking from './features/data-masking/page'
+import Models from './features/models/page'
+import BestPractices from './integration/best-practices/page'
+// Integration
+import CdnSetup from './integration/cdn-setup/page'
+import Configuration from './integration/configuration/page'
+import SecurityPermissions from './integration/security-permissions/page'
+import ThirdPartyAgent from './integration/third-party-agent/page'
+import Limitations from './introduction/limitations/page'
+// Introduction
+import Overview from './introduction/overview/page'
+import QuickStart from './introduction/quick-start/page'
+
+function DocsPage({ children }: { children: React.ReactNode }) {
+	return (
+		<div className="min-h-screen bg-white dark:bg-gray-900">
+			<Header />
+			<DocsLayout>
+				<Suspense>{children}</Suspense>
+			</DocsLayout>
+		</div>
+	)
+}
+
+export default function DocsRouter() {
+	return (
+		<Switch>
+			{/* Introduction */}
+			<Route path="/introduction/overview">
+				<DocsPage>
+					<Overview />
+				</DocsPage>
+			</Route>
+			<Route path="/introduction/quick-start">
+				<DocsPage>
+					<QuickStart />
+				</DocsPage>
+			</Route>
+			<Route path="/introduction/limitations">
+				<DocsPage>
+					<Limitations />
+				</DocsPage>
+			</Route>
+
+			{/* Features */}
+			<Route path="/features/custom-tools">
+				<DocsPage>
+					<CustomTools />
+				</DocsPage>
+			</Route>
+			<Route path="/features/data-masking">
+				<DocsPage>
+					<DataMasking />
+				</DocsPage>
+			</Route>
+			<Route path="/features/custom-instructions">
+				<DocsPage>
+					<Instructions />
+				</DocsPage>
+			</Route>
+			<Route path="/features/models">
+				<DocsPage>
+					<Models />
+				</DocsPage>
+			</Route>
+
+			{/* Integration */}
+			<Route path="/integration/cdn-setup">
+				<DocsPage>
+					<CdnSetup />
+				</DocsPage>
+			</Route>
+			<Route path="/integration/security-permissions">
+				<DocsPage>
+					<SecurityPermissions />
+				</DocsPage>
+			</Route>
+			<Route path="/integration/configuration">
+				<DocsPage>
+					<Configuration />
+				</DocsPage>
+			</Route>
+			<Route path="/integration/best-practices">
+				<DocsPage>
+					<BestPractices />
+				</DocsPage>
+			</Route>
+			<Route path="/integration/third-party-agent">
+				<DocsPage>
+					<ThirdPartyAgent />
+				</DocsPage>
+			</Route>
+
+			{/* Default redirect or 404 */}
+			<Route path="/docs">
+				<DocsPage>
+					<Overview />
+				</DocsPage>
+			</Route>
+		</Switch>
+	)
+}

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

@@ -0,0 +1,125 @@
+import { useTranslation } from 'react-i18next'
+
+import CodeEditor from '@/components/CodeEditor'
+import { CDN_DEMO_CN_URL, CDN_DEMO_URL, CDN_FULL_CN_URL, CDN_FULL_URL } from '@/constants'
+
+export default function CdnSetup() {
+	const { i18n } = useTranslation()
+	const isZh = i18n.language === 'zh-CN'
+
+	return (
+		<div className="space-y-10">
+			<header>
+				<h1 className="text-4xl font-bold mb-4">{isZh ? 'CDN 引入' : 'CDN Setup'}</h1>
+				<p className="text-lg text-gray-600 dark:text-gray-300 leading-relaxed">
+					{isZh
+						? 'CDN 提供两种构建版本：Demo 版用于快速体验，标准版用法与 NPM 一致。'
+						: 'CDN provides two builds: Demo for quick testing, standard build with usage identical to NPM.'}
+				</p>
+			</header>
+
+			{/* Demo Build Section */}
+			<section>
+				<h2 className="text-2xl font-bold mb-3">{isZh ? '🚀 快速体验' : '🚀 Quick Try'}</h2>
+
+				<p className="text-gray-600 dark:text-gray-300 mb-3">
+					{isZh
+						? '自动初始化并使用内置 Demo LLM，无需任何配置：'
+						: 'Auto-initializes with built-in demo LLM, no configuration needed:'}
+				</p>
+
+				<CodeEditor
+					className="mb-3"
+					code={`<script src="${CDN_DEMO_URL}" crossorigin="true"></script>`}
+				/>
+
+				<div className="bg-yellow-50 dark:bg-yellow-900/20 px-4 py-3 rounded-lg mb-4 text-sm">
+					<span className="text-yellow-800 dark:text-yellow-200">
+						⚠️{' '}
+						{isZh
+							? '仅用于技术评估，Demo 模型有速率限制。'
+							: 'For evaluation only. Demo model has rate limits.'}
+					</span>
+				</div>
+
+				<table className="w-full border-collapse text-sm">
+					<thead>
+						<tr className="border-b border-gray-200 dark:border-gray-700">
+							<th className="text-left py-2 px-3 font-semibold w-28">
+								{isZh ? '位置' : 'Location'}
+							</th>
+							<th className="text-left py-2 px-3 font-semibold">URL</th>
+						</tr>
+					</thead>
+					<tbody>
+						<tr className="border-b border-gray-100 dark:border-gray-800">
+							<td className="py-2 px-3">{isZh ? '全球' : 'Global'}</td>
+							<td className="py-2 px-3 font-mono text-xs break-all">{CDN_DEMO_URL}</td>
+						</tr>
+						<tr>
+							<td className="py-2 px-3">{isZh ? '中国' : 'China'}</td>
+							<td className="py-2 px-3 font-mono text-xs break-all">{CDN_DEMO_CN_URL}</td>
+						</tr>
+					</tbody>
+				</table>
+			</section>
+
+			{/* CDN Build Section */}
+			<section>
+				<h2 className="text-2xl font-bold mb-3">{isZh ? '📦 标准版' : '📦 Standard Build'}</h2>
+
+				<p className="text-gray-600 dark:text-gray-300 mb-3">
+					{isZh
+						? '将 PageAgent 类暴露到 globalThis，用法与 NPM 一致：'
+						: 'Exposes PageAgent class to globalThis, usage identical to NPM:'}
+				</p>
+
+				<CodeEditor
+					className="mb-4"
+					code={`<script src="${CDN_FULL_URL}" crossorigin="true"></script>
+<script>
+const agent = new PageAgent({
+  model: 'deepseek-chat',
+  baseURL: 'https://api.deepseek.com',
+  apiKey: 'YOUR_API_KEY',
+})
+await agent.execute('Click the submit button')
+</script>`}
+				/>
+
+				<table className="w-full border-collapse text-sm">
+					<thead>
+						<tr className="border-b border-gray-200 dark:border-gray-700">
+							<th className="text-left py-2 px-3 font-semibold w-28">
+								{isZh ? '位置' : 'Location'}
+							</th>
+							<th className="text-left py-2 px-3 font-semibold">URL</th>
+						</tr>
+					</thead>
+					<tbody>
+						<tr className="border-b border-gray-100 dark:border-gray-800">
+							<td className="py-2 px-3">{isZh ? '全球' : 'Global'}</td>
+							<td className="py-2 px-3 font-mono text-xs break-all">{CDN_FULL_URL}</td>
+						</tr>
+						<tr>
+							<td className="py-2 px-3">{isZh ? '中国' : 'China'}</td>
+							<td className="py-2 px-3 font-mono text-xs break-all">{CDN_FULL_CN_URL}</td>
+						</tr>
+					</tbody>
+				</table>
+			</section>
+
+			{/* Tips */}
+			<section className="bg-blue-50 dark:bg-blue-900/20 p-4 rounded-lg">
+				<h3 className="text-base font-semibold mb-2 text-blue-900 dark:text-blue-300">
+					💡 {isZh ? '提示' : 'Tips'}
+				</h3>
+				<ul className="text-gray-600 dark:text-gray-300 text-sm space-y-1">
+					<li>• {isZh ? '生产环境推荐使用 NPM' : 'NPM is recommended for production'}</li>
+					<li>• {isZh ? '生产环境建议锁定版本号' : 'Lock version number in production'}</li>
+					<li>• {isZh ? '确保 HTTPS 环境' : 'Ensure HTTPS environment'}</li>
+				</ul>
+			</section>
+		</div>
+	)
+}

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

@@ -0,0 +1,199 @@
+import { useTranslation } from 'react-i18next'
+
+import CodeEditor from '@/components/CodeEditor'
+
+export default function Configuration() {
+	const { i18n } = useTranslation()
+	const isZh = i18n.language === 'zh-CN'
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">{isZh ? '配置选项' : 'Configuration'}</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? 'PageAgent 的完整配置接口定义。'
+					: 'Complete configuration interface for PageAgent.'}
+			</p>
+
+			{/* LLM Configuration */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">{isZh ? 'LLM 配置' : 'LLM Configuration'}</h2>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '配置与大语言模型的连接参数。'
+						: 'Configure connection parameters for the language model.'}
+				</p>
+				<CodeEditor
+					className="mb-4"
+					language="typescript"
+					code={`interface LLMConfig {
+  baseURL: string
+  apiKey: string
+  model: string
+
+  temperature?: number
+  maxRetries?: number
+
+  /**
+   * Custom fetch function for LLM API requests.
+   * Use this to customize headers, credentials, proxy, etc.
+   * The response should follow OpenAI API format.
+   */
+  customFetch?: typeof globalThis.fetch
+}`}
+				/>
+			</section>
+
+			{/* Agent Configuration */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">
+					{isZh ? 'Agent 配置' : 'Agent Configuration'}
+				</h2>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '配置 Agent 的行为、生命周期钩子和扩展能力。'
+						: 'Configure agent behavior, lifecycle hooks, and extension capabilities.'}
+				</p>
+				<CodeEditor
+					className="mb-4"
+					language="typescript"
+					code={`interface AgentConfig {
+  language?: 'en-US' | 'zh-CN'
+
+  /**
+   * Whether to prompt for next task after task completion
+   * @default true
+   */
+  promptForNextTask?: boolean
+
+  /**
+   * Enable the UI panel for visual feedback and user interaction
+   * When disabled, the panel will not be created and all UI operations will be skipped.
+   * Useful for automated testing or when integrating PageAgent as a library.
+   * @default true
+   */
+  enablePanel?: boolean
+
+  /**
+   * Enable the ask_user tool for agent to ask questions
+   * When disabled, the agent cannot ask user questions during execution.
+   * @default true
+   */
+  enableAskUser?: boolean
+
+  /** Custom tools to extend or override built-in tools */
+  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 */
+    getPageInstructions?: (url: string) => string | undefined | null
+  }
+
+  // Lifecycle hooks (with \`this\` bound to PageAgent instance)
+  onBeforeStep?: (this: PageAgent, stepCnt: number) => Promise<void> | void
+  onAfterStep?: (this: PageAgent, stepCnt: number, history: HistoryEvent[]) => Promise<void> | void
+  onBeforeTask?: (this: PageAgent) => Promise<void> | void
+  onAfterTask?: (this: PageAgent, result: ExecutionResult) => Promise<void> | void
+  onDispose?: (this: PageAgent, reason?: string) => void
+
+  /**
+   * Transform page content before sending to LLM.
+   * Use cases: inspect extraction results, modify page info, mask sensitive data.
+   */
+  transformPageContent?: (content: string) => Promise<string> | string
+
+  /** @experimental Enable JavaScript execution tool */
+  experimentalScriptExecutionTool?: boolean
+}`}
+				/>
+			</section>
+
+			{/* PageController Configuration */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">
+					{isZh ? 'PageController 配置' : 'PageController Configuration'}
+				</h2>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '配置 DOM 提取、元素交互和视觉高亮的细节。'
+						: 'Configure DOM extraction, element interaction, and visual highlighting.'}
+				</p>
+				<CodeEditor
+					className="mb-4"
+					language="typescript"
+					code={`interface DomConfig {
+  /** Elements to exclude from interaction */
+  interactiveBlacklist?: (Element | (() => Element))[]
+
+  /** Elements to force include for interaction */
+  interactiveWhitelist?: (Element | (() => Element))[]
+
+  /** Additional attributes to include in DOM extraction */
+  include_attributes?: string[]
+
+  /** Highlight overlay opacity (0-1) */
+  highlightOpacity?: number
+
+  /** Highlight label opacity (0-1) */
+  highlightLabelOpacity?: number
+}
+
+interface PageControllerConfig extends DomConfig {
+  /** Viewport expansion in pixels */
+  viewportExpansion?: number
+
+  /** Enable visual mask overlay during operations (default: false) */
+  enableMask?: boolean
+}`}
+				/>
+			</section>
+
+			{/* Complete Type */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">{isZh ? '完整类型' : 'Complete Type'}</h2>
+				<CodeEditor
+					language="typescript"
+					code={`type PageAgentConfig = LLMConfig & AgentConfig & PageControllerConfig`}
+				/>
+			</section>
+
+			{/* Programmatic Usage Example */}
+			<section className="mb-10">
+				<h2 className="text-2xl font-semibold mb-4">
+					{isZh ? '程序化使用配置' : 'Programmatic Usage'}
+				</h2>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '对于程序化集成场景，可以禁用 UI。'
+						: 'For programmatic integration, you can disable UI.'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`const agent = new PageAgent({
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: 'your-api-key',
+  model: 'your-model-name',
+
+  // Disable all UI features for pure programmatic usage
+  enablePanel: false,        // Don't create Panel UI
+  enableMask: false,         // Don't show visual overlay (mask and pointer)
+  // enableAskUser is automatically disabled when enablePanel is false
+
+  // Or keep Panel but disable post-task prompts
+  // enablePanel: true,
+  // promptForNextTask: false,
+})
+
+// Pure programmatic execution
+const result = await agent.execute('search for TypeScript documentation')
+console.log(result.success, result.data, result.history)`}
+				/>
+			</section>
+		</div>
+	)
+}

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

@@ -0,0 +1,90 @@
+import { useTranslation } from 'react-i18next'
+
+import BetaNotice from '@/components/BetaNotice'
+
+export default function SecurityPermissions() {
+	const { i18n } = useTranslation()
+	const isZh = i18n.language === 'zh-CN'
+
+	return (
+		<div>
+			<BetaNotice />
+
+			<h1 className="text-4xl font-bold mb-6">{isZh ? '安全与权限' : 'Security & Permissions'}</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? 'page-agent 提供多种安全机制，确保 AI 操作在可控范围内进行。'
+					: 'page-agent provides multiple security mechanisms to ensure AI operations stay within controlled boundaries.'}
+			</p>
+
+			<div className="space-y-6">
+				<section>
+					<h2 className="text-2xl font-bold mb-3">
+						{isZh ? '元素操作黑白名单' : 'Element Interaction Allowlist/Blocklist'}
+					</h2>
+					<div className="space-y-3">
+						<div className="p-4 bg-red-50 dark:bg-red-900/20 rounded-lg">
+							<h3 className="text-lg font-semibold text-red-900 dark:text-red-300">
+								🚫 {isZh ? '操作黑名单' : 'Blocklist'}
+							</h3>
+							<p className="text-gray-600 dark:text-gray-300">
+								{isZh
+									? '禁止 AI 操作敏感元素，如删除按钮、支付按钮等。'
+									: 'Prevent AI from interacting with sensitive elements like delete buttons, payment buttons, etc.'}
+							</p>
+						</div>
+						<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
+							<h3 className="text-lg font-semibold text-green-900 dark:text-green-300">
+								✅ {isZh ? '操作白名单' : 'Allowlist'}
+							</h3>
+							<p className="text-gray-600 dark:text-gray-300">
+								{isZh
+									? '明确定义 AI 可以操作的元素范围。'
+									: 'Explicitly define which elements AI can interact with.'}
+							</p>
+						</div>
+					</div>
+				</section>
+
+				<section>
+					<h2 className="text-2xl font-bold mb-3">
+						{isZh ? 'Instruction 安全约束' : 'Instruction Safety Constraints'}
+					</h2>
+					<div className="p-4 bg-yellow-50 dark:bg-yellow-900/20 rounded-lg">
+						<h3 className="text-lg font-semibold mb-2 text-yellow-900 dark:text-yellow-300">
+							⚠️ {isZh ? '高危操作控制' : 'High-Risk Operation Control'}
+						</h3>
+						<p className="text-gray-600 dark:text-gray-300 mb-3">
+							{isZh
+								? '在 AI 指令中明确列举高危操作，通过两种策略进行控制：'
+								: 'Define high-risk operations in AI instructions and control them through two strategies:'}
+						</p>
+						<div className="space-y-2">
+							<div className="pl-3 border-l-2 border-red-400">
+								<p className="font-medium text-red-700 dark:text-red-300">
+									{isZh ? '完全禁止操作' : 'Completely Forbidden'}
+								</p>
+								<p className="text-sm text-gray-500 dark:text-gray-400">
+									{isZh
+										? '对极高风险操作明确禁止执行'
+										: 'Explicitly prohibit execution of extremely high-risk operations'}
+								</p>
+							</div>
+							<div className="pl-3 border-l-2 border-orange-400">
+								<p className="font-medium text-orange-700 dark:text-orange-300">
+									{isZh ? '需用户确认操作' : 'Requires User Confirmation'}
+								</p>
+								<p className="text-sm text-gray-500 dark:text-gray-400">
+									{isZh
+										? '对中等风险操作要求用户明确同意'
+										: 'Require explicit user consent for medium-risk operations'}
+								</p>
+							</div>
+						</div>
+					</div>
+				</section>
+			</div>
+		</div>
+	)
+}

packages/website/src/pages/docs/integration/third-party-agent/page.tsx

@@ -36,7 +36,7 @@ const pageAgentTool = {
   },
   execute: async (params) => {
     const result = await pageAgent.execute(params.instruction)
-    return { success: result.success, message: result.message }
+    return { success: result.success, message: result.data }
   }
 }
 
@@ -74,19 +74,6 @@ const pageAgentTool = {
 				</div>
 			</div>
 
-			<h2 className="text-2xl font-bold mb-4">最佳实践</h2>
-			<div className="space-y-4 mb-6">
-				<div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg">
-					<h3 className="text-lg font-semibold mb-2 text-gray-900 dark:text-white">错误处理</h3>
-					<CodeEditor code={`// @TODO`} language="javascript" />
-				</div>
-
-				<div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg">
-					<h3 className="text-lg font-semibold mb-2 text-gray-900 dark:text-white">权限控制</h3>
-					<CodeEditor code={`// @TODO`} language="javascript" />
-				</div>
-			</div>
-
 			<div className="bg-yellow-50 dark:bg-yellow-900/20 border border-yellow-200 dark:border-yellow-800 rounded-lg p-4 mb-6">
 				<h3 className="text-lg font-semibold text-yellow-900 dark:text-yellow-100 mb-2">
 					⚠️ 注意事项
@@ -97,19 +84,6 @@ const pageAgentTool = {
 					<li>• 敏感操作建议要求人工确认</li>
 				</ul>
 			</div>
-
-			<div className="bg-linear-to-r from-green-50 to-blue-50 dark:from-green-900/20 dark:to-blue-900/20 p-4 rounded-lg">
-				<h3 className="text-lg font-semibold mb-2 text-gray-900 dark:text-white">🎉 开始集成</h3>
-				<p className="mb-3 text-gray-700 dark:text-gray-300">
-					通过这种方式，你的 Agent 系统就能真正成为用户的智能助手。
-				</p>
-				<a
-					href="/docs/integration/configuration"
-					className="inline-flex items-center px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition-colors duration-200"
-				>
-					查看配置选项 →
-				</a>
-			</div>
 		</div>
 	)
 }

packages/website/src/pages/docs/introduction/overview/page.tsx

@@ -6,13 +6,13 @@ export default function Overview() {
 	return (
 		<article>
 			{/* 头图 */}
-			<figure className="mb-8 rounded-xl overflow-hidden">
+			{/* <figure className="mb-8 rounded-xl overflow-hidden">
 				<img
 					src="https://img.alicdn.com/imgextra/i3/O1CN014xLeic1gnF2iWdzjJ_!!6000000004186-49-tps-1280-353.webp"
 					alt="page-agent"
 					className="w-full h-64 object-cover"
 				/>
-			</figure>
+			</figure> */}
 
 			<div className="mb-8">
 				<h1 className="text-4xl font-bold mb-4">{t('overview.title')}</h1>
@@ -22,13 +22,6 @@ export default function Overview() {
 
 				{/* Status Badges */}
 				<div className="flex flex-wrap gap-2 items-center">
-					<a
-						href="https://www.npmjs.com/package/page-agent"
-						target="_blank"
-						rel="noopener noreferrer"
-					>
-						<img src="https://badge.fury.io/js/page-agent.svg" alt="npm version" />
-					</a>
 					<a href="https://opensource.org/licenses/MIT" target="_blank" rel="noopener noreferrer">
 						<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License" />
 					</a>

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

@@ -0,0 +1,83 @@
+import { useTranslation } from 'react-i18next'
+
+import BetaNotice from '@/components/BetaNotice'
+import CodeEditor from '@/components/CodeEditor'
+import { CDN_DEMO_CN_URL, CDN_DEMO_URL } from '@/constants'
+
+export default function QuickStart() {
+	const { t, i18n } = useTranslation('docs')
+	const isZh = i18n.language === 'zh-CN'
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">{t('quick_start.title')}</h1>
+
+			<p className=" mb-6 leading-relaxed">{t('quick_start.subtitle')}</p>
+
+			<h2 className="text-2xl font-bold mb-3">{t('quick_start.installation')}</h2>
+
+			<div className="space-y-4 mb-6">
+				{/* Demo CDN - One Line */}
+				<div className="p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-blue-900 dark:text-blue-300">
+						{isZh ? '🚀 快速体验（Demo CDN）' : '🚀 Quick Try (Demo CDN)'}
+					</h3>
+					<div className="bg-yellow-50 dark:bg-yellow-900/20 p-2 rounded mb-3 text-sm">
+						<span className="text-yellow-800 dark:text-yellow-200">
+							⚠️ {isZh ? '仅用于技术评估' : 'For evaluation only'}
+						</span>
+					</div>
+					<CodeEditor
+						code={`// Global: ${CDN_DEMO_URL}
+// China:  ${CDN_DEMO_CN_URL}
+<script src="${isZh ? CDN_DEMO_CN_URL : CDN_DEMO_URL}" crossorigin="true"></script>`}
+						language="html"
+					/>
+				</div>
+
+				{/* NPM - Recommended */}
+				<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-green-900 dark:text-green-300">
+						{isZh ? '📦 NPM 安装（推荐）' : '📦 NPM Install (Recommended)'}
+					</h3>
+					<CodeEditor
+						code={`npm install page-agent
+
+import { PageAgent } from 'page-agent'`}
+						language="bash"
+					/>
+				</div>
+
+				<div className="p-4 bg-purple-50 dark:bg-purple-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-purple-900 dark:text-purple-300">
+						{t('quick_start.step2_title')}
+					</h3>
+					<CodeEditor
+						code={`const agent = new PageAgent({
+  model: 'deepseek-chat',
+  baseURL: 'https://api.deepseek.com',
+  apiKey: 'YOUR_API_KEY',
+  language: '${isZh ? 'zh-CN' : 'en-US'}'
+})`}
+						language="javascript"
+					/>
+				</div>
+
+				<div className="p-4 bg-orange-50 dark:bg-orange-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-orange-900 dark:text-orange-300">
+						{t('quick_start.step3_title')}
+					</h3>
+					<CodeEditor
+						code={`// ${isZh ? '程序化执行自然语言指令' : 'Execute natural language instructions programmatically'}
+await agent.execute('${isZh ? '点击提交按钮，然后填写用户名为张三' : 'Click submit button, then fill username as John'}');
+
+// ${isZh ? '或者显示对话框让用户输入指令' : 'Or show panel for user to input instructions'}
+agent.panel.show()
+`}
+						language="javascript"
+					/>
+				</div>
+			</div>
+		</div>
+	)
+}