chore(version): bump version to 1.0.0

chore(deps-dev): bump the development-dependencies group with 6 updates

.github/workflows/release.yml

@@ -32,4 +32,12 @@ jobs:
         run: npm run build:libs
 
       - name: Publish all public packages
-        run: npm publish --workspaces --access public
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          if [[ "$VERSION" == *"-"* ]]; then
+            # Prerelease version (e.g., 0.3.0-beta.1) -> extract tag name before the dot
+            TAG=$(echo "$VERSION" | sed 's/.*-\([a-zA-Z]*\).*/\1/')
+            npm publish --workspaces --access public --tag "$TAG"
+          else
+            npm publish --workspaces --access public
+          fi

.gitignore

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

.vscode/extensions.json

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

.vscode/settings.json

@@ -2,14 +2,17 @@
     "editor.fontLigatures": true,
     "cSpell.words": [
         "deepseek",
+        "historychange",
         "HITL",
         "innerhtml",
         "llms",
+        "npmmirror",
         "onwarn",
         "opensource",
         "qwen",
         "retryable",
         "shadcn",
+        "statuschange",
         "wouter"
     ],
     "markdownlint.config": {

AGENTS.md

@@ -4,12 +4,12 @@
 
 This is a **monorepo** with npm workspaces:
 
-- **Core Library** (`packages/page-agent/`) - AI agent for browser DOM automation, published as `page-agent` on npm
+- **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel, published as `page-agent` on npm
 - **Website** (`packages/website/`) - React docs and landing page. **When working on website, follow `packages/website/AGENTS.md`**
 
 Internal packages:
 
-- **CDN** (`packages/cdn/`) - IIFE builds for script tag usage (npm: `@page-agent/cdn`)
+- **Core** (`packages/core/`) - PageAgentCore without UI (npm: `@page-agent/core`)
 - **LLMs** (`packages/llms/`) - LLM client with reflection-before-action mental model
 - **Page Controller** (`packages/page-controller/`) - DOM operations and visual feedback (SimulatorMask), independent of LLM
 - **UI** (`packages/ui/`) - Panel and i18n. Decoupled from PageAgent
@@ -31,8 +31,8 @@ Simple monorepo solution: TypeScript references + Vite aliases. Update tsconfig
 
 ```
 packages/
-├── page-agent/              # npm: "page-agent" ⭐ MAIN
-├── cdn/                     # npm: "@page-agent/cdn" (IIFE builds)
+├── core/                    # npm: "@page-agent/core" ⭐ Core agent logic (headless)
+├── page-agent/              # npm: "page-agent" entry class (with UI + controller + demo builds)
 ├── website/                 # @page-agent/website (private)
 ├── llms/                    # @page-agent/llms
 ├── page-controller/         # @page-agent/page-controller
@@ -43,9 +43,10 @@ packages/
 
 ### Module Boundaries
 
-- **Page Agent**: Core lib. Imports from `@page-agent/llms`, `@page-agent/page-controller`, `@page-agent/ui`
+- **Page Agent**: Main entry with UI. Extends PageAgentCore and adds Panel. Imports from `@page-agent/core`, `@page-agent/ui`
+- **Core**: PageAgentCore without UI. Imports from `@page-agent/llms`, `@page-agent/page-controller`
 - **LLMs**: LLM client with MacroToolInput contract. No dependency on page-agent
-- **UI**: Panel and i18n. No dependency on page-agent
+- **UI**: Panel and i18n. Decoupled from PageAgent via PanelAgentAdapter interface
 - **Page Controller**: DOM operations with optional visual feedback (SimulatorMask). No LLM dependency. Enable mask via `enableMask: true` config
 
 ### PageController ↔ PageAgent Communication
@@ -71,34 +72,31 @@ 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 Builds (`packages/cdn/`)
-
-Two IIFE builds for script tag usage:
-
-| Build | File                 | Description                      |
-| ----- | -------------------- | -------------------------------- |
-| Demo  | `page-agent.demo.js` | Auto-init with built-in test API |
-| Full  | `page-agent.js`      | Exposes `PageAgent` class only   |
-
-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 class with UI, extends PageAgentCore |
+| `src/demo.ts`      | IIFE demo entry (auto-init with demo API)    |
+
+### Core (`packages/core/`)
+
+| File                   | Description                             |
+| ---------------------- | --------------------------------------- |
+| `src/PageAgentCore.ts` | ⭐ Core agent class without UI          |
+| `src/tools/`           | Tool definitions calling PageController |
+| `src/config/`          | Configuration types and constants       |
+| `src/prompts/`         | System prompt templates                 |
 
 ### LLMs (`packages/llms/`)
 
-| File                         | Description                           |
-| ---------------------------- | ------------------------------------- |
-| `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/OpenAIClient.ts` | OpenAI-compatible client              |
 
 ### Page Controller (`packages/page-controller/`)
 
@@ -113,7 +111,7 @@ Demo build supports query params (e.g., `?model=gpt-4&lang=en-US`).
 
 ### New Agent Tool
 
-1. Implement in `packages/page-agent/src/tools/index.ts`
+1. Implement in `packages/core/src/tools/index.ts`
 2. If tool needs DOM ops, add method to PageController first
 3. Tool calls `this.pageController.methodName()` for DOM interactions
 

CHANGELOG.md

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

CODE_OF_CONDUCT.md

@@ -69,10 +69,10 @@ members of the project's leadership.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][https://www.contributor-covenant.org], version 1.4,
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 1.4,
 available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
 
-----
+---
 
 > Chinese Version
 > 《阿里巴巴开源行为准则》

CONTRIBUTING.md

@@ -20,10 +20,11 @@ Thank you for your interest in contributing to Page-Agent! We welcome contributi
 
 ### Project Structure
 
-This is a **monorepo** with npm workspaces containing **two main packages**:
+This is a **monorepo** with npm workspaces containing **3 main packages**:
 
-1. **Core Library** (`packages/page-agent/`) - Pure JavaScript/TypeScript AI agent library for browser DOM automation, published as `page-agent` on npm
-2. **Website** (`packages/website/`) - React documentation and landing page. Also as demo and test page for the core lib. private package `@page-agent/website`
+- **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel, published as `page-agent` on npm
+- **Core** (`packages/core/`) - Core agent logic without UI (npm: `@page-agent/core`)
+- **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.
 
@@ -121,13 +122,13 @@ npm start
 - Start and serve a local `iife` script
 
     ```bash
-    npm run dev:iife # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.js
+    npm run dev:demo # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.demo.js
     ```
 
 - Add a new bookmark
 
     ```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:5174/page-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
     ```
 
 - Click the bookmark on any page to load Page-Agent

README-zh.md

@@ -20,34 +20,38 @@
 ## ✨ Features
 
 - **🎯 轻松集成**
+    - 无需 Python，无需无头浏览器，无需浏览器插件。纯页面内脚本。
 - **🔐 端侧运行**
 - **🧠 HTML 脱水**
 - **💬 自然语言接口**
 - **🎨 HITL 交互界面**
 
-## 🗺️ Roadmap
+以及 😉
 
-👉 [**Roadmap**](https://github.com/alibaba/page-agent/issues/96)
+- **🧪 实验性的 Chrome 扩展，支持跨页面控制** - `-b feat/ext`
+
+👉 [**🗺️ Roadmap**](https://github.com/alibaba/page-agent/issues/96)
 
 ## 🚀 快速开始
 
-### 快速体验 (With Testing LLM)
+### 一行代码集成
 
-最快的体验方式：
+通过我们免费的 Demo LLM 快速体验 PageAgent：
 
 ```html
 <script
-    src="https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js"
+    src="https://registry.npmmirror.com/page-agent/1.0.0/files/dist/iife/page-agent.demo.js"
     crossorigin="true"
 ></script>
 ```
 
-> ⚠️ **仅用于技术评估。** Demo 模型有速率限制和使用限制，生产环境请使用 NPM 方式。
+> - **⚠️ 仅用于技术评估。** Demo LLM 有速率和使用限制，可能随时变更。
+> - **🌷 建议使用自己的 LLM API。**
 
-| 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 |
+| 镜像   | URL                                                                                       |
+| ------ | ----------------------------------------------------------------------------------------- |
+| Global | https://cdn.jsdelivr.net/npm/page-agent@1.0.0/dist/iife/page-agent.demo.js         |
+| China  | https://registry.npmmirror.com/page-agent/1.0.0/files/dist/iife/page-agent.demo.js |
 
 ### NPM 安装
 
@@ -76,25 +80,19 @@ PageAgent adopts a simplified monorepo structure:
 
 ```
 packages/
-├── page-agent/          # AI agent (npm: page-agent)
+├── core/                # ** Core agent logic without UI(npm: @page-agent/core) **
+├── page-agent/          # Exported agent and demo(npm: page-agent)
 ├── llms/                # LLM 客户端 (npm: @page-agent/llms)
 ├── page-controller/     # DOM 操作 & 蒙层 & 模拟鼠标 (npm: @page-agent/page-controller)
 ├── ui/                  # 面板 & i18n (npm: @page-agent/ui)
-├── cdn/                 # CDN IIFE builds (npm: @page-agent/cdn)
 └── website/             # 文档站点
 ```
 
 ## 🤝 贡献
 
-欢迎社区贡献！以下是参与方式：
+欢迎社区贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解环境配置和本地开发说明。
 
-1. Fork 并 clone。`git clone https://github.com/alibaba/page-agent.git && cd page-agent`
-2. 安装依赖: `npm install`
-3. 启动开发: `npm start`
-
-更多详情请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
-
-请在贡献前阅读我们的[行为准则](CODE_OF_CONDUCT.md)。
+请在贡献前阅读[行为准则](CODE_OF_CONDUCT.md)。
 
 ## 👏 致谢
 

README.md

@@ -19,35 +19,39 @@ The GUI Agent Living in Your Webpage. Control web interfaces with natural langua
 
 ## ✨ Features
 
-- **🎯 Easy Integration** - Transform your webpage into an agent with a single script tag.
+- **🎯 Easy Integration**
+    - No python. No headless browser. No browser extension. Just in-page scripts.
 - **🔐 Client-Side Processing**
 - **🧠 DOM Extraction**
 - **💬 Natural Language Interface**
 - **🎨 UI with Human in the loop**
 
-## 🗺️ Roadmap
+And 😉
 
-👉 [**Roadmap**](https://github.com/alibaba/page-agent/issues/96)
+- **🧪 `cross-page` control with an experimental chrome extension** - `-b feat/ext`
+
+👉 [**🗺️ Roadmap**](https://github.com/alibaba/page-agent/issues/96)
 
 ## 🚀 Quick Start
 
-### Quick Try (With Testing LLM)
+### One-line integration
 
-Fastest way to try PageAgent:
+Fastest way to try PageAgent with our free Demo LLM:
 
 ```html
 <script
-    src="https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js"
+    src="https://cdn.jsdelivr.net/npm/page-agent@1.0.0/dist/iife/page-agent.demo.js"
     crossorigin="true"
 ></script>
 ```
 
-> ⚠️ **For technical evaluation only.** Demo model has rate limits and usage restrictions. Use NPM for production.
+> - **⚠️ For technical evaluation only.** Demo LLM has rate limits and usage restrictions. May change without notice.
+> - **🌷 Bring your own LLM API.**
 
-| Mirrors | URL                                                                                 |
-| ------- | ----------------------------------------------------------------------------------- |
-| Global  | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js                |
-| China   | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js |
+| Mirrors | URL                                                                                       |
+| ------- | ----------------------------------------------------------------------------------------- |
+| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.0.0/dist/iife/page-agent.demo.js         |
+| China   | https://registry.npmmirror.com/page-agent/1.0.0/files/dist/iife/page-agent.demo.js |
 
 ### NPM Installation
 
@@ -68,33 +72,25 @@ const agent = new PageAgent({
 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:
 
 ```
 packages/
-├── page-agent/          # AI agent (npm: page-agent)
+├── core/                # ** Core agent logic without UI(npm: @page-agent/core) **
+├── page-agent/          # Exported agent and demo(npm: page-agent)
 ├── llms/                # LLM client (npm: @page-agent/llms)
 ├── page-controller/     # DOM operations & Visual Mask (npm: @page-agent/page-controller)
 ├── ui/                  # Panel & i18n (npm: @page-agent/ui)
-├── cdn/                 # CDN IIFE builds (npm: @page-agent/cdn)
 └── website/             # Demo & Documentation site
 ```
 
 ## 🤝 Contributing
 
-We welcome contributions from the community! Here's how to get started:
+We welcome contributions from the community! Follow our instructions in [CONTRIBUTING.md](CONTRIBUTING.md) for environment setup and local development.
 
-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`
-
-More details in [CONTRIBUTING.md](CONTRIBUTING.md).
-
-Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
+Please read [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
 
 ## 👏 Acknowledgments
 

package.json

@@ -1,123 +1,123 @@
 {
-	"name": "root",
-	"private": true,
-	"version": "0.2.4",
-	"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",
-	"author": "Simon<gaomeng1900>",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/alibaba/page-agent.git"
-	},
-	"homepage": "https://alibaba.github.io/page-agent/",
-	"engines": {
-		"node": ">=20.0.0",
-		"npm": ">=10.0.0"
-	},
-	"scripts": {
-		"cleanup": "rm -rf packages/*/dist",
-		"start": "npm run dev --workspace=@page-agent/website",
-		"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:iife": "npm run dev:iife --workspace=page-agent",
-		"version": "node scripts/sync-version.js",
-		"lint": "eslint .",
-		"prepare": "husky"
-	},
-	"devDependencies": {
-		"@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.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.5.7",
-		"eslint-plugin-react-hooks": "^7.0.1",
-		"eslint-plugin-react-refresh": "^0.4.26",
-		"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.53.0",
-		"unplugin-dts": "^1.0.0-beta.6",
-		"vite": "^7.3.1",
-		"vite-plugin-css-injected-by-js": "^3.5.2"
-	},
-	"overrides": {
-		"typescript": "^5.9.3"
-	},
-	"lint-staged": {
-		"*.{js,ts,cjs,cts,mjs,mts}": [
-			"npx prettier --write --ignore-unknown",
-			"npx eslint --quiet"
-		],
-		"*.{jsx,tsx}": [
-			"npx prettier --write --ignore-unknown",
-			"npx eslint --quiet"
-		],
-		"*.css": [
-			"npx prettier --write --ignore-unknown"
-		]
-	},
-	"commitlint": {
-		"extends": [
-			"@commitlint/config-conventional"
-		],
-		"rules": {
-			"subject-case": [
-				0,
-				"never"
-			]
-		}
-	},
-	"prettier": {
-		"singleQuote": true,
-		"semi": false,
-		"useTabs": true,
-		"printWidth": 100,
-		"trailingComma": "es5",
-		"plugins": [
-			"@trivago/prettier-plugin-sort-imports"
-		],
-		"importOrder": [
-			"<THIRD_PARTY_MODULES>",
-			"^(@/).*(?<!css)$",
-			"^[./].*(?<!css)$",
-			".css$"
-		],
-		"importOrderSeparation": true,
-		"importOrderSortSpecifiers": true,
-		"overrides": [
-			{
-				"files": "*.md",
-				"options": {
-					"useTabs": false,
-					"tabWidth": 4
-				}
-			},
-			{
-				"files": "*.json",
-				"options": {
-					"useTabs": false,
-					"tabWidth": 4
-				}
-			}
-		]
-	}
+    "name": "root",
+    "private": true,
+    "version": "1.0.0",
+    "type": "module",
+    "workspaces": [
+        "packages/page-controller",
+        "packages/ui",
+        "packages/llms",
+        "packages/core",
+        "packages/page-agent",
+        "packages/website"
+    ],
+    "description": "AI-powered UI agent for web applications",
+    "author": "Simon<gaomeng1900>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/alibaba/page-agent.git"
+    },
+    "homepage": "https://alibaba.github.io/page-agent/",
+    "engines": {
+        "node": ">=20.0.0",
+        "npm": ">=10.0.0"
+    },
+    "scripts": {
+        "cleanup": "rm -rf packages/*/dist",
+        "start": "npm run dev --workspace=@page-agent/website",
+        "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:demo": "npm run dev:demo --workspace=page-agent",
+        "version": "node scripts/sync-version.js",
+        "lint": "eslint .",
+        "prepare": "husky"
+    },
+    "devDependencies": {
+        "@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.2",
+        "@types/node": "^25.0.9",
+        "concurrently": "^9.2.1",
+        "dotenv": "^17.2.3",
+        "eslint": "^9.39.2",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-react-dom": "^2.7.2",
+        "eslint-plugin-react-hooks": "^7.0.1",
+        "eslint-plugin-react-refresh": "^0.4.26",
+        "eslint-plugin-react-x": "^2.7.2",
+        "globals": "^17.0.0",
+        "husky": "^9.1.7",
+        "lint-staged": "^16.2.4",
+        "prettier": "^3.8.0",
+        "typescript": "^5.9.3",
+        "typescript-eslint": "^8.53.1",
+        "unplugin-dts": "^1.0.0-beta.6",
+        "vite": "^7.3.1",
+        "vite-plugin-css-injected-by-js": "^3.5.2"
+    },
+    "overrides": {
+        "typescript": "^5.9.3"
+    },
+    "lint-staged": {
+        "*.{js,ts,cjs,cts,mjs,mts}": [
+            "npx prettier --write --ignore-unknown",
+            "npx eslint --quiet"
+        ],
+        "*.{jsx,tsx}": [
+            "npx prettier --write --ignore-unknown",
+            "npx eslint --quiet"
+        ],
+        "*.css": [
+            "npx prettier --write --ignore-unknown"
+        ]
+    },
+    "commitlint": {
+        "extends": [
+            "@commitlint/config-conventional"
+        ],
+        "rules": {
+            "subject-case": [
+                0,
+                "never"
+            ]
+        }
+    },
+    "prettier": {
+        "singleQuote": true,
+        "semi": false,
+        "useTabs": true,
+        "printWidth": 100,
+        "trailingComma": "es5",
+        "plugins": [
+            "@trivago/prettier-plugin-sort-imports"
+        ],
+        "importOrder": [
+            "<THIRD_PARTY_MODULES>",
+            "^(@/).*(?<!css)$",
+            "^[./].*(?<!css)$",
+            ".css$"
+        ],
+        "importOrderSeparation": true,
+        "importOrderSortSpecifiers": true,
+        "overrides": [
+            {
+                "files": "*.md",
+                "options": {
+                    "useTabs": false,
+                    "tabWidth": 4
+                }
+            },
+            {
+                "files": "*.json",
+                "options": {
+                    "useTabs": false,
+                    "tabWidth": 4
+                }
+            }
+        ]
+    }
 }

packages/cdn/package.json

@@ -1,23 +0,0 @@
-{
-	"name": "@page-agent/cdn",
-	"private": false,
-	"version": "0.2.4",
-	"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.4"
-	}
-}

packages/cdn/src/demo.js

@@ -1,64 +0,0 @@
-// @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

@@ -1,15 +0,0 @@
-// @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

@@ -1,49 +0,0 @@
-// @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/core/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "@page-agent/core",
+    "private": false,
+    "version": "1.0.0",
+    "type": "module",
+    "main": "./dist/esm/page-agent-core.js",
+    "module": "./dist/esm/page-agent-core.js",
+    "types": "./dist/esm/PageAgentCore.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/esm/PageAgentCore.d.ts",
+            "import": "./dist/esm/page-agent-core.js",
+            "default": "./dist/esm/page-agent-core.js"
+        }
+    },
+    "files": [
+        "dist/"
+    ],
+    "description": "GUI agent for web applications - add intelligent automation to any webpage with a single script",
+    "keywords": [
+        "ai",
+        "automation",
+        "ui-agent",
+        "GUI-agent",
+        "browser-automation",
+        "web-agent",
+        "llm",
+        "dom-interaction",
+        "web-automation",
+        "GUI-simulation"
+    ],
+    "author": "Simon<gaomeng1900>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/alibaba/page-agent.git"
+    },
+    "homepage": "https://alibaba.github.io/page-agent/",
+    "scripts": {
+        "build": "vite build",
+        "dev:iife": "concurrently \"vite build --config vite.iife.config.js --watch\" \"npx serve dist/iife -p 5174\"",
+        "prepublishOnly": "node -e \"const fs=require('fs');['README.md','LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
+        "postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
+    },
+    "dependencies": {
+        "chalk": "^5.6.2",
+        "zod": "^4.3.5",
+        "@page-agent/llms": "1.0.0",
+        "@page-agent/page-controller": "1.0.0"
+    }
+}

packages/core/src/PageAgentCore.ts

@@ -0,0 +1,592 @@
+/**
+ * Copyright (C) 2025 Alibaba Group Holding Limited
+ * All rights reserved.
+ */
+import { InvokeError, LLM, type Tool } from '@page-agent/llms'
+import type { PageController } from '@page-agent/page-controller'
+import chalk from 'chalk'
+import zod from 'zod'
+
+import { type PageAgentConfig } from './config'
+import { DEFAULT_MAX_STEPS } from './config/constants'
+import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
+import { tools } from './tools'
+import {
+	AgentActivity,
+	AgentReflection,
+	AgentStatus,
+	AgentStepEvent,
+	ExecutionResult,
+	HistoricalEvent,
+	MacroToolInput,
+	MacroToolResult,
+} from './types'
+import { normalizeResponse, trimLines, uid, waitFor } from './utils'
+import { assert } from './utils/assert'
+
+export { type PageAgentConfig }
+export { tool, type PageAgentTool } from './tools'
+export type * from './types'
+
+/**
+ * AI agent for browser DOM automation.
+ *
+ * @remarks
+ * ## Event System
+ * - `statuschange` - Agent status transitions (idle → running → completed/error)
+ * - `historychange` - History events updated (persistent, part of agent memory)
+ * - `activity` - Real-time activity feedback (transient, for UI only)
+ * - `dispose` - Agent cleanup triggered
+ *
+ * ## Information Streams
+ * 1. **History Events** (`history` array)
+ *    - Persistent event stream that forms agent's memory
+ *    - Included in LLM context across steps
+ *    - Types: steps, observations, user takeovers, llm errors
+ *
+ * 2. **Activity Events** (via `activity` event)
+ *    - Transient UI feedback during task execution
+ *    - NOT included in LLM context
+ *    - Types: thinking, executing, executed, retrying, error
+ */
+export class PageAgentCore extends EventTarget {
+	config: PageAgentConfig & { maxSteps: number }
+	id = uid()
+	tools: typeof tools
+	disposed = false
+	task = ''
+	taskId = ''
+
+	/** Agent execution status */
+	#status: AgentStatus = 'idle'
+
+	/**
+	 * Callback for when agent needs user input (ask_user tool)
+	 * If not set, ask_user tool will be disabled
+	 * @example onAskUser: (q) => window.prompt(q) || ''
+	 */
+	onAskUser?: (question: string) => Promise<string>
+
+	#llm: LLM
+	#abortController = new AbortController()
+
+	/** PageController for DOM operations */
+	pageController: PageController
+
+	/** Runtime states for tracking across steps */
+	states = {
+		/** Accumulated wait time in seconds, used by wait tool */
+		totalWaitTime: 0,
+		/** Last known URL for detecting navigation */
+		lastURL: '',
+	}
+
+	/** History events */
+	history: HistoricalEvent[] = []
+
+	constructor(config: PageAgentConfig & { pageController: PageController }) {
+		super()
+
+		this.config = { ...config, maxSteps: config.maxSteps || DEFAULT_MAX_STEPS }
+
+		this.#llm = new LLM(this.config)
+		this.tools = new Map(tools)
+		this.pageController = config.pageController
+
+		// Listen to LLM retry events
+		this.#llm.addEventListener('retry', (e) => {
+			const { attempt, maxAttempts } = (e as CustomEvent).detail
+			this.emitActivity({ type: 'retrying', attempt, maxAttempts })
+			// Also push to history for panel rendering
+			this.history.push({
+				type: 'retry',
+				message: `LLM retry attempt ${attempt} of ${maxAttempts}`,
+				attempt,
+				maxAttempts,
+			})
+			this.#emitHistoryChange()
+		})
+		this.#llm.addEventListener('error', (e) => {
+			const error = (e as CustomEvent).detail.error as Error | InvokeError
+			const message = String(error)
+			this.emitActivity({ type: 'error', message })
+			// Also push to history for panel rendering
+			this.history.push({
+				type: 'error',
+				message,
+				rawResponse: (error as InvokeError).rawResponse,
+			})
+			this.#emitHistoryChange()
+		})
+
+		if (this.config.customTools) {
+			for (const [name, tool] of Object.entries(this.config.customTools)) {
+				if (tool === null) {
+					this.tools.delete(name)
+					continue
+				}
+				this.tools.set(name, tool)
+			}
+		}
+
+		if (!this.config.experimentalScriptExecutionTool) {
+			this.tools.delete('execute_javascript')
+		}
+	}
+
+	/** Get current agent status */
+	get status(): AgentStatus {
+		return this.#status
+	}
+
+	/** Emit statuschange event */
+	#emitStatusChange(): void {
+		this.dispatchEvent(new Event('statuschange'))
+	}
+
+	/** Emit historychange event */
+	#emitHistoryChange(): void {
+		this.dispatchEvent(new Event('historychange'))
+	}
+
+	/**
+	 * Emit activity event - for transient UI feedback
+	 * @param activity - Current agent activity
+	 */
+	emitActivity(activity: AgentActivity): void {
+		this.dispatchEvent(new CustomEvent('activity', { detail: activity }))
+	}
+
+	/** Update status and emit event */
+	#setStatus(status: AgentStatus): void {
+		if (this.#status !== status) {
+			this.#status = status
+			this.#emitStatusChange()
+		}
+	}
+
+	/**
+	 * Push a persistent observation to the history event stream.
+	 * This will be visible in <agent_history> and remain in memory across steps.
+	 */
+	pushObservation(content: string): void {
+		this.history.push({ type: 'observation', content })
+		this.#emitHistoryChange()
+	}
+
+	async execute(task: string): Promise<ExecutionResult> {
+		if (!task) throw new Error('Task is required')
+		this.task = task
+		this.taskId = uid()
+
+		// Disable ask_user tool if onAskUser is not set
+		if (!this.onAskUser) {
+			this.tools.delete('ask_user')
+		}
+
+		const onBeforeStep = this.config.onBeforeStep
+		const onAfterStep = this.config.onAfterStep
+		const onBeforeTask = this.config.onBeforeTask
+		const onAfterTask = this.config.onAfterTask
+
+		await onBeforeTask?.(this)
+
+		// Show mask
+		await this.pageController.showMask()
+
+		if (this.#abortController) {
+			this.#abortController.abort()
+			this.#abortController = new AbortController()
+		}
+
+		this.history = []
+		this.#setStatus('running')
+		this.#emitHistoryChange()
+
+		// Reset states
+		this.states = {
+			totalWaitTime: 0,
+			lastURL: '',
+		}
+
+		try {
+			let step = 0
+
+			while (true) {
+				await this.#generateObservations(step)
+
+				await onBeforeStep?.(this, step)
+
+				console.group(`step: ${step}`)
+
+				// abort
+				if (this.#abortController.signal.aborted) throw new Error('AbortError')
+
+				// Thinking
+				console.log(chalk.blue('Thinking...'))
+				this.emitActivity({ type: 'thinking' })
+
+				const result = await this.#llm.invoke(
+					[
+						{
+							role: 'system',
+							content: this.#getSystemPrompt(),
+						},
+						{
+							role: 'user',
+							content: await this.#assembleUserPrompt(),
+						},
+					],
+					{ AgentOutput: this.#packMacroTool() },
+					this.#abortController.signal,
+					{
+						toolChoiceName: 'AgentOutput',
+						normalizeResponse,
+					}
+				)
+
+				const macroResult = result.toolResult as MacroToolResult
+				const input = macroResult.input
+				const output = macroResult.output
+				const reflection: Partial<AgentReflection> = {
+					evaluation_previous_goal: input.evaluation_previous_goal,
+					memory: input.memory,
+					next_goal: input.next_goal,
+				}
+				const actionName = Object.keys(input.action)[0]
+				const action: AgentStepEvent['action'] = {
+					name: actionName,
+					input: input.action[actionName],
+					output: output,
+				}
+
+				this.history.push({
+					type: 'step',
+					stepIndex: step,
+					reflection,
+					action,
+					usage: result.usage,
+					rawResponse: result.rawResponse,
+				} as AgentStepEvent)
+				this.#emitHistoryChange()
+
+				console.log(chalk.green('Step finished:'), actionName)
+				console.groupEnd()
+
+				await onAfterStep?.(this, this.history)
+
+				step++
+				if (step > this.config.maxSteps) {
+					this.#onDone('Step count exceeded maximum limit', false)
+					const result: ExecutionResult = {
+						success: false,
+						data: 'Step count exceeded maximum limit',
+						history: this.history,
+					}
+					await onAfterTask?.(this, result)
+					return result
+				}
+				if (actionName === 'done') {
+					const success = action.input?.success ?? false
+					const text = action.input?.text || 'no text provided'
+					console.log(chalk.green.bold('Task completed'), success, text)
+					this.#onDone(text, success)
+					const result: ExecutionResult = {
+						success,
+						data: text,
+						history: this.history,
+					}
+					await onAfterTask?.(this, result)
+					return result
+				}
+			}
+		} catch (error: unknown) {
+			console.error('Task failed', error)
+			const errorMessage = String(error)
+			this.emitActivity({ type: 'error', message: errorMessage })
+			this.#onDone(errorMessage, false)
+			const result: ExecutionResult = {
+				success: false,
+				data: errorMessage,
+				history: this.history,
+			}
+			await onAfterTask?.(this, result)
+			return result
+		}
+	}
+
+	/**
+	 * Merge all tools into a single MacroTool with the following input:
+	 * - thinking: string
+	 * - evaluation_previous_goal: string
+	 * - memory: string
+	 * - next_goal: string
+	 * - action: { toolName: toolInput }
+	 * where action must be selected from tools defined in this.tools
+	 */
+	#packMacroTool(): Tool<MacroToolInput, MacroToolResult> {
+		const tools = this.tools
+
+		const actionSchemas = Array.from(tools.entries()).map(([toolName, tool]) => {
+			return zod.object({ [toolName]: tool.inputSchema }).describe(tool.description)
+		})
+
+		const actionSchema = zod.union(
+			actionSchemas as unknown as [zod.ZodType, zod.ZodType, ...zod.ZodType[]]
+		)
+
+		const macroToolSchema = zod.object({
+			// thinking: zod.string().optional(),
+			evaluation_previous_goal: zod.string().optional(),
+			memory: zod.string().optional(),
+			next_goal: zod.string().optional(),
+			action: actionSchema,
+		})
+
+		return {
+			description: 'You MUST call this tool every step. Outputs your reflections and next action.',
+			inputSchema: macroToolSchema as zod.ZodType<MacroToolInput>,
+			execute: async (input: MacroToolInput): Promise<MacroToolResult> => {
+				// abort
+				if (this.#abortController.signal.aborted) throw new Error('AbortError')
+
+				console.log(chalk.blue.bold('MacroTool execute'), input)
+				const action = input.action
+
+				const toolName = Object.keys(action)[0]
+				const toolInput = action[toolName]
+
+				// Build reflection text, only include non-empty fields
+				const reflectionLines: string[] = []
+				if (input.evaluation_previous_goal)
+					reflectionLines.push(`✅: ${input.evaluation_previous_goal}`)
+				if (input.memory) reflectionLines.push(`💾: ${input.memory}`)
+				if (input.next_goal) reflectionLines.push(`🎯: ${input.next_goal}`)
+
+				const reflectionText = reflectionLines.length > 0 ? reflectionLines.join('\n') : ''
+
+				if (reflectionText) {
+					console.log(reflectionText)
+				}
+
+				// Find the corresponding tool
+				const tool = tools.get(toolName)
+				assert(tool, `Tool ${toolName} not found. (@note should have been caught before this!!!)`)
+
+				console.log(chalk.blue.bold(`Executing tool: ${toolName}`), toolInput)
+
+				// Emit executing activity
+				this.emitActivity({ type: 'executing', tool: toolName, input: toolInput })
+
+				const startTime = Date.now()
+
+				// Execute tool, bind `this` to PageAgent
+				const result = await tool.execute.bind(this)(toolInput)
+
+				const duration = Date.now() - startTime
+				console.log(chalk.green.bold(`Tool (${toolName}) executed for ${duration}ms`), result)
+
+				// Emit executed activity
+				this.emitActivity({
+					type: 'executed',
+					tool: toolName,
+					input: toolInput,
+					output: result,
+					duration,
+				})
+
+				// Reset wait time for non-wait tools
+				if (toolName !== 'wait') {
+					this.states.totalWaitTime = 0
+				}
+
+				// Return structured result
+				return {
+					input,
+					output: result,
+				}
+			},
+		}
+	}
+
+	/**
+	 * Get system prompt, dynamically replace language settings based on configured language
+	 */
+	#getSystemPrompt(): string {
+		let systemPrompt = SYSTEM_PROMPT
+
+		const targetLanguage = this.config.language === 'zh-CN' ? '中文' : 'English'
+		systemPrompt = systemPrompt.replace(
+			/Default working language: \*\*.*?\*\*/,
+			`Default working language: **${targetLanguage}**`
+		)
+
+		return systemPrompt
+	}
+
+	/**
+	 * Get instructions from config and format as XML block
+	 */
+	async #getInstructions(): Promise<string> {
+		const { instructions } = this.config
+		if (!instructions) return ''
+
+		const systemInstructions = instructions.system?.trim()
+		const url = await this.pageController.getCurrentUrl()
+		let pageInstructions: string | undefined
+
+		if (instructions.getPageInstructions) {
+			try {
+				pageInstructions = instructions.getPageInstructions(url)?.trim()
+			} catch (error) {
+				console.error(
+					chalk.red('[PageAgent] Failed to execute getPageInstructions callback:'),
+					error
+				)
+			}
+		}
+		if (!systemInstructions && !pageInstructions) return ''
+
+		let result = '<instructions>\n'
+
+		if (systemInstructions) {
+			result += `<system_instructions>\n${systemInstructions}\n</system_instructions>\n`
+		}
+
+		if (pageInstructions) {
+			result += `<page_instructions>\n${pageInstructions}\n</page_instructions>\n`
+		}
+
+		result += '</instructions>\n\n'
+
+		return result
+	}
+
+	/**
+	 * Generate observations before each step
+	 * - URL change detection
+	 * - Too many steps warning
+	 * @todo loop detection
+	 * @todo console error
+	 */
+	async #generateObservations(stepCount: number): Promise<void> {
+		// Detect URL change
+		const currentURL = await this.pageController.getCurrentUrl()
+		if (currentURL !== this.states.lastURL) {
+			this.pushObservation(`Page navigated to → ${currentURL}`)
+			this.states.lastURL = currentURL
+			await waitFor(0.5) // wait for page to stabilize
+		}
+
+		// Warn about remaining steps
+		const remaining = this.config.maxSteps - stepCount
+		if (remaining === 5) {
+			this.pushObservation(
+				`⚠️ Only ${remaining} steps remaining. Consider wrapping up or calling done with partial results.`
+			)
+		} else if (remaining === 2) {
+			this.pushObservation(
+				`⚠️ Critical: Only ${remaining} steps left! You must finish the task or call done immediately.`
+			)
+		}
+	}
+
+	async #assembleUserPrompt(): Promise<string> {
+		let prompt = ''
+
+		// <instructions> (optional)
+		prompt += await this.#getInstructions()
+
+		// <agent_state>
+		//  - <user_request>
+		//  - <step_info>
+		// <agent_state>
+
+		const stepCount = this.history.filter((e) => e.type === 'step').length
+
+		prompt += `<agent_state>
+			<user_request>
+			${this.task}
+			</user_request>
+			<step_info>
+			Step ${stepCount + 1} of ${this.config.maxSteps} max possible steps
+			Current date and time: ${new Date().toISOString()}
+			</step_info>
+			</agent_state>
+		`
+
+		// <agent_history>
+		//  - <step_N> for steps
+		//  - <sys> for observations and system messages
+
+		prompt += '\n<agent_history>\n'
+
+		let stepIndex = 0
+		for (const event of this.history) {
+			if (event.type === 'step') {
+				stepIndex++
+				prompt += `<step_${stepIndex}>
+				Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}
+				Memory: ${event.reflection.memory}
+				Next Goal: ${event.reflection.next_goal}
+				Action Results: ${event.action.output}
+				</step_${stepIndex}>
+			`
+			} else if (event.type === 'observation') {
+				prompt += `<sys>${event.content}</sys>\n`
+			} else if (event.type === 'user_takeover') {
+				prompt += `<sys>User took over control and made changes to the page.</sys>\n`
+			} else if (event.type === 'error') {
+				// Error events are mainly for panel rendering, not included in LLM context
+				// to avoid polluting the agent's reasoning with transient errors
+			}
+		}
+
+		prompt += '</agent_history>\n\n'
+
+		// <browser_state>
+
+		prompt += await this.#getBrowserState()
+
+		return trimLines(prompt)
+	}
+
+	#onDone(text: string, success = true) {
+		this.pageController.cleanUpHighlights()
+		this.pageController.hideMask() // No await - fire and forget
+		this.#setStatus(success ? 'completed' : 'error')
+		this.#abortController.abort()
+	}
+
+	async #getBrowserState(): Promise<string> {
+		const state = await this.pageController.getBrowserState()
+
+		let content = state.content
+		if (this.config.transformPageContent) {
+			content = await this.config.transformPageContent(content)
+		}
+
+		return trimLines(`<browser_state>
+			Current Page: [${state.title}](${state.url})
+
+			${state.header}
+			${content}
+			${state.footer}
+
+			</browser_state>
+		`)
+	}
+
+	dispose(reason?: string) {
+		console.log('Disposing PageAgent...')
+		this.disposed = true
+		this.pageController.dispose()
+		this.history = []
+		this.#abortController.abort(reason ?? 'PageAgent disposed')
+
+		// Emit dispose event for UI cleanup
+		this.dispatchEvent(new Event('dispose'))
+
+		this.config.onDispose?.(this, reason)
+	}
+}

packages/core/src/config/constants.ts

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

packages/core/src/config/index.ts

@@ -1,21 +1,30 @@
 import type { LLMConfig } from '@page-agent/llms'
 import type { PageControllerConfig } from '@page-agent/page-controller'
-import type { SupportedLanguage } from '@page-agent/ui'
 
-import type { ExecutionResult, HistoryEvent, PageAgent } from '../PageAgent'
+import type { PageAgentCore } from '../PageAgentCore'
 import type { PageAgentTool } from '../tools'
+import type { ExecutionResult, HistoricalEvent } from '../types'
 
 export type { LLMConfig }
 
+/** Supported UI languages */
+export type SupportedLanguage = 'en-US' | 'zh-CN'
+
 export interface AgentConfig {
 	// theme?: 'light' | 'dark'
 	language?: SupportedLanguage
 
+	/**
+	 * Maximum number of steps the agent can take per task.
+	 * @default 20
+	 */
+	maxSteps?: number
+
 	/**
 	 * Custom tools to extend PageAgent capabilities
 	 * @experimental
 	 * @note You can also override or remove internal tools by using the same name.
-	 * @see [tools](../tools/index.ts)
+	 * @see PageAgentTool
 	 *
 	 * @example
 	 * // override internal tool
@@ -60,21 +69,52 @@ export interface AgentConfig {
 		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: HistoryEvent[]) => Promise<void> | void
-	onBeforeTask?: (this: PageAgent) => Promise<void> | void
-	onAfterTask?: (this: PageAgent, result: ExecutionResult) => Promise<void> | void
+	/**
+	 * Lifecycle hooks for task execution.
+	 * @experimental API may change in future versions.
+	 *
+	 * All hooks receive the agent instance as first parameter.
+	 */
 
 	/**
-	 * @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
+	 * Called before each step execution.
+	 * @experimental
+	 * @param agent - The PageAgentCore instance
+	 * @param stepCount - Current step number (0-indexed)
 	 */
-	onDispose?: (this: PageAgent, reason?: string) => void
+	onBeforeStep?: (agent: PageAgentCore, stepCount: number) => Promise<void> | void
+
+	/**
+	 * Called after each step execution.
+	 * @experimental
+	 * @param agent - The PageAgentCore instance
+	 * @param history - Current history of events
+	 */
+	onAfterStep?: (agent: PageAgentCore, history: HistoricalEvent[]) => Promise<void> | void
+
+	/**
+	 * Called before task execution starts.
+	 * @experimental
+	 * @param agent - The PageAgentCore instance
+	 */
+	onBeforeTask?: (agent: PageAgentCore) => Promise<void> | void
+
+	/**
+	 * Called after task execution completes (success or failure).
+	 * @experimental
+	 * @param agent - The PageAgentCore instance
+	 * @param result - The execution result
+	 */
+	onAfterTask?: (agent: PageAgentCore, result: ExecutionResult) => Promise<void> | void
+
+	/**
+	 * Called when the agent is disposed.
+	 * @experimental
+	 * @note This hook can block the disposal process if it's async.
+	 * @param agent - The PageAgentCore instance
+	 * @param reason - Optional reason for disposal
+	 */
+	onDispose?: (agent: PageAgentCore, reason?: string) => void
 
 	// page behavior hooks
 
@@ -101,21 +141,6 @@ export interface AgentConfig {
 	 * }
 	 */
 	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
-
-	/**
-	 * 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
 }
 
 export type PageAgentConfig = LLMConfig & AgentConfig & PageControllerConfig

packages/core/src/env.d.ts

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

packages/core/src/prompts/system_prompt.md

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

packages/core/src/tools/index.ts

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

packages/core/src/types.ts

@@ -0,0 +1,125 @@
+/**
+ * Agent reflection state - the reflection-before-action model
+ *
+ * Every tool call must first reflect on:
+ * - evaluation_previous_goal: How well did the previous action achieve its goal?
+ * - memory: Key information to remember for future steps
+ * - next_goal: What should be accomplished in the next action?
+ */
+export interface AgentReflection {
+	evaluation_previous_goal: string
+	memory: string
+	next_goal: string
+}
+
+/**
+ * MacroTool input structure
+ *
+ * This is the core abstraction that enforces the "reflection-before-action" mental model.
+ * Before executing any action, the LLM must output its reasoning state.
+ */
+export interface MacroToolInput extends Partial<AgentReflection> {
+	action: Record<string, any>
+}
+
+/**
+ * MacroTool output structure
+ */
+export interface MacroToolResult {
+	input: MacroToolInput
+	output: string
+}
+
+/**
+ * A single agent step with reflection and action
+ */
+export interface AgentStepEvent {
+	type: 'step'
+	stepIndex: number
+	reflection: Partial<AgentReflection>
+	action: {
+		name: string
+		input: any
+		output: string
+	}
+	usage: {
+		promptTokens: number
+		completionTokens: number
+		totalTokens: number
+		cachedTokens?: number
+		reasoningTokens?: number
+	}
+	/** Raw LLM response for debugging */
+	rawResponse?: unknown
+}
+
+/**
+ * Persistent observation event (stays in memory)
+ */
+export interface ObservationEvent {
+	type: 'observation'
+	content: string
+}
+
+/**
+ * User takeover event
+ */
+export interface UserTakeoverEvent {
+	type: 'user_takeover'
+}
+
+/**
+ * Retry event - LLM call is being retried
+ */
+export interface RetryEvent {
+	type: 'retry'
+	message: string
+	attempt: number
+	maxAttempts: number
+}
+
+/**
+ * Error event - fatal error from LLM or execution
+ */
+export interface AgentErrorEvent {
+	type: 'error'
+	message: string
+	rawResponse?: unknown
+}
+
+/**
+ * Union type for all history events
+ */
+export type HistoricalEvent =
+	| AgentStepEvent
+	| ObservationEvent
+	| UserTakeoverEvent
+	| RetryEvent
+	| AgentErrorEvent
+
+/**
+ * Agent execution status
+ */
+export type AgentStatus = 'idle' | 'running' | 'completed' | 'error'
+
+/**
+ * Agent activity - transient state for immediate UI feedback.
+ *
+ * Unlike historical events (which are persisted), activities are ephemeral
+ * and represent "what the agent is doing right now". UI components should
+ * listen to 'activity' events to show real-time feedback.
+ *
+ * Note: There is no 'idle' activity - absence of activity events means idle.
+ */
+export type AgentActivity =
+	| { type: 'thinking' }
+	| { type: 'executing'; tool: string; input: unknown }
+	| { type: 'executed'; tool: string; input: unknown; output: string; duration: number }
+	| { type: 'retrying'; attempt: number; maxAttempts: number }
+	| { type: 'error'; message: string }
+
+export interface ExecutionResult {
+	success: boolean
+	data: string
+	history: HistoricalEvent[]
+}

packages/core/src/utils/index.ts

@@ -68,12 +68,13 @@ export function randomID(existingIDs?: string[]): string {
 }
 
 //
+const _global = globalThis as any
 
-if (!window.__PAGE_AGENT_IDS__) {
-	window.__PAGE_AGENT_IDS__ = []
+if (!_global.__PAGE_AGENT_IDS__) {
+	_global.__PAGE_AGENT_IDS__ = []
 }
 
-const ids = window.__PAGE_AGENT_IDS__
+const ids = _global.__PAGE_AGENT_IDS__
 
 /**
  * Generate a random ID.

packages/core/tsconfig.dts.json

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

packages/core/tsconfig.json

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

packages/core/vite.config.js

@@ -0,0 +1,44 @@
+// @ts-check
+import { dirname, resolve } from 'path'
+import dts from 'unplugin-dts/vite'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// ES Module for NPM Package
+export default defineConfig({
+	clearScreen: false,
+	plugins: [
+		dts({ tsconfigPath: './tsconfig.dts.json', bundleTypes: true }),
+		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
+	],
+	publicDir: false,
+	esbuild: {
+		keepNames: true,
+	},
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/PageAgentCore.ts'),
+			name: 'PageAgentCore',
+			fileName: 'page-agent-core',
+			formats: ['es'],
+		},
+		outDir: resolve(__dirname, 'dist', 'esm'),
+		rollupOptions: {
+			external: [
+				'chalk',
+				'zod',
+				// all the internal packages
+				/^@page-agent\//,
+			],
+		},
+		minify: false,
+		sourcemap: true,
+		cssCodeSplit: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})

packages/llms/package.json

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

packages/llms/src/OpenAIClient.ts

@@ -107,14 +107,23 @@ export class OpenAIClient implements LLMClient {
 			case 'length':
 				throw new InvokeError(
 					InvokeErrorType.CONTEXT_LENGTH,
-					'Response truncated: max tokens reached'
+					'Response truncated: max tokens reached',
+					undefined,
+					data
 				)
 			case 'content_filter':
-				throw new InvokeError(InvokeErrorType.CONTENT_FILTER, 'Content filtered by safety system')
+				throw new InvokeError(
+					InvokeErrorType.CONTENT_FILTER,
+					'Content filtered by safety system',
+					undefined,
+					data
+				)
 			default:
 				throw new InvokeError(
 					InvokeErrorType.UNKNOWN,
-					`Unexpected finish_reason: ${choice.finish_reason}`
+					`Unexpected finish_reason: ${choice.finish_reason}`,
+					undefined,
+					data
 				)
 		}
 
@@ -128,7 +137,8 @@ export class OpenAIClient implements LLMClient {
 			throw new InvokeError(
 				InvokeErrorType.NO_TOOL_CALL,
 				'No tool call found in response',
-				normalizedData
+				undefined,
+				data
 			)
 		}
 
@@ -137,7 +147,8 @@ export class OpenAIClient implements LLMClient {
 			throw new InvokeError(
 				InvokeErrorType.UNKNOWN,
 				`Tool "${toolCallName}" not found in tools`,
-				normalizedData
+				undefined,
+				data
 			)
 		}
 
@@ -147,7 +158,8 @@ export class OpenAIClient implements LLMClient {
 			throw new InvokeError(
 				InvokeErrorType.INVALID_TOOL_ARGS,
 				'No tool call arguments found',
-				normalizedData
+				undefined,
+				data
 			)
 		}
 
@@ -158,7 +170,8 @@ export class OpenAIClient implements LLMClient {
 			throw new InvokeError(
 				InvokeErrorType.INVALID_TOOL_ARGS,
 				'Failed to parse tool arguments as JSON',
-				error
+				error,
+				data
 			)
 		}
 
@@ -169,7 +182,8 @@ export class OpenAIClient implements LLMClient {
 			throw new InvokeError(
 				InvokeErrorType.INVALID_TOOL_ARGS,
 				'Tool arguments validation failed',
-				validation.error
+				validation.error,
+				data
 			)
 		}
 		const toolInput = validation.data
@@ -182,7 +196,8 @@ export class OpenAIClient implements LLMClient {
 			throw new InvokeError(
 				InvokeErrorType.TOOL_EXECUTION_ERROR,
 				`Tool execution failed: ${(e as Error).message}`,
-				e
+				e,
+				data
 			)
 		}
 

packages/llms/src/errors.ts

@@ -25,14 +25,18 @@ export class InvokeError extends Error {
 	type: InvokeErrorType
 	retryable: boolean
 	statusCode?: number
+	/* raw error (provided if this error is caused by another error) */
 	rawError?: unknown
+	/* raw response from the API (provided if this error is caused by an API calling) */
+	rawResponse?: unknown
 
-	constructor(type: InvokeErrorType, message: string, rawError?: unknown) {
+	constructor(type: InvokeErrorType, message: string, rawError?: unknown, rawResponse?: unknown) {
 		super(message)
 		this.name = 'InvokeError'
 		this.type = type
 		this.retryable = this.isRetryable(type)
 		this.rawError = rawError
+		this.rawResponse = rawResponse
 	}
 
 	private isRetryable(type: InvokeErrorType): boolean {

packages/llms/src/index.ts

@@ -3,7 +3,7 @@ import { DEFAULT_TEMPERATURE, LLM_MAX_RETRIES } from './constants'
 import { InvokeError } from './errors'
 import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
 
-export type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool }
+export type { InvokeError, InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool }
 
 export function parseLLMConfig(config: LLMConfig): Required<LLMConfig> {
 	// Runtime validation as defensive programming (types already guarantee these)
@@ -56,9 +56,9 @@ export class LLM extends EventTarget {
 			// retry settings
 			{
 				maxRetries: this.config.maxRetries,
-				onRetry: (current: number) => {
+				onRetry: (attempt: number) => {
 					this.dispatchEvent(
-						new CustomEvent('retry', { detail: { current, max: this.config.maxRetries } })
+						new CustomEvent('retry', { detail: { attempt, maxAttempts: this.config.maxRetries } })
 					)
 				},
 				onError: (error: Error) => {
@@ -73,15 +73,15 @@ async function withRetry<T>(
 	fn: () => Promise<T>,
 	settings: {
 		maxRetries: number
-		onRetry: (retries: number) => void
+		onRetry: (attempt: number) => void
 		onError: (error: Error) => void
 	}
 ): Promise<T> {
-	let retries = 0
+	let attempt = 0
 	let lastError: Error | null = null
-	while (retries <= settings.maxRetries) {
-		if (retries > 0) {
-			settings.onRetry(retries)
+	while (attempt <= settings.maxRetries) {
+		if (attempt > 0) {
+			settings.onRetry(attempt)
 			await new Promise((resolve) => setTimeout(resolve, 100))
 		}
 
@@ -98,7 +98,7 @@ async function withRetry<T>(
 			if (error instanceof InvokeError && !error.retryable) throw error
 
 			lastError = error as Error
-			retries++
+			attempt++
 
 			await new Promise((resolve) => setTimeout(resolve, 100))
 		}

packages/page-agent/package.json

@@ -1,52 +1,54 @@
 {
-	"name": "page-agent",
-	"private": false,
-	"version": "0.2.4",
-	"type": "module",
-	"main": "./dist/esm/page-agent.js",
-	"module": "./dist/esm/page-agent.js",
-	"types": "./dist/esm/PageAgent.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/esm/PageAgent.d.ts",
-			"import": "./dist/esm/page-agent.js",
-			"default": "./dist/esm/page-agent.js"
-		}
-	},
-	"files": [
-		"dist/"
-	],
-	"description": "GUI agent for web applications - add intelligent automation to any webpage with a single script",
-	"keywords": [
-		"ai",
-		"automation",
-		"ui-agent",
-		"GUI-agent",
-		"browser-automation",
-		"web-agent",
-		"llm",
-		"dom-interaction",
-		"web-automation",
-		"GUI-simulation"
-	],
-	"author": "Simon<gaomeng1900>",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/alibaba/page-agent.git"
-	},
-	"homepage": "https://alibaba.github.io/page-agent/",
-	"scripts": {
-		"build": "vite build",
-		"dev:iife": "concurrently \"vite build --config vite.iife.config.js --watch\" \"npx serve dist/iife -p 5174\"",
-		"prepublishOnly": "node -e \"const fs=require('fs');['README.md','LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
-		"postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
-	},
-	"dependencies": {
-		"chalk": "^5.6.2",
-		"zod": "^4.3.5",
-		"@page-agent/llms": "0.2.4",
-		"@page-agent/page-controller": "0.2.4",
-		"@page-agent/ui": "0.2.4"
-	}
+    "name": "page-agent",
+    "private": false,
+    "version": "1.0.0",
+    "type": "module",
+    "main": "./dist/esm/page-agent.js",
+    "module": "./dist/esm/page-agent.js",
+    "types": "./dist/esm/PageAgent.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/esm/PageAgent.d.ts",
+            "import": "./dist/esm/page-agent.js",
+            "default": "./dist/esm/page-agent.js"
+        }
+    },
+    "files": [
+        "dist/"
+    ],
+    "description": "GUI agent for web applications - add intelligent automation to any webpage with a single script",
+    "keywords": [
+        "ai",
+        "automation",
+        "ui-agent",
+        "GUI-agent",
+        "browser-automation",
+        "web-agent",
+        "llm",
+        "dom-interaction",
+        "web-automation",
+        "GUI-simulation"
+    ],
+    "author": "Simon<gaomeng1900>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/alibaba/page-agent.git"
+    },
+    "homepage": "https://alibaba.github.io/page-agent/",
+    "scripts": {
+        "build": "vite build && npm run build:demo",
+        "build:demo": "vite build --config vite.iife.config.js",
+        "dev:demo": "concurrently \"vite build --config vite.iife.config.js --watch\" \"npx serve dist/iife -p 5174\"",
+        "prepublishOnly": "node -e \"const fs=require('fs');['README.md','LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
+        "postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
+    },
+    "dependencies": {
+        "chalk": "^5.6.2",
+        "zod": "^4.3.5",
+        "@page-agent/llms": "1.0.0",
+        "@page-agent/page-controller": "1.0.0",
+        "@page-agent/core": "1.0.0",
+        "@page-agent/ui": "1.0.0"
+    }
 }

packages/page-agent/src/PageAgent.ts

@@ -2,617 +2,26 @@
  * Copyright (C) 2025 Alibaba Group Holding Limited
  * All rights reserved.
  */
-import { LLM, type Tool } from '@page-agent/llms'
+import { type PageAgentConfig, PageAgentCore, type PageAgentTool, tool } from '@page-agent/core'
 import { PageController } from '@page-agent/page-controller'
 import { Panel } from '@page-agent/ui'
-import chalk from 'chalk'
-import zod from 'zod'
 
-import type { PageAgentConfig } from './config'
-import { MAX_STEPS } from './config/constants'
-import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
-import { tools } from './tools'
-import { normalizeResponse, trimLines, uid } from './utils'
-import { assert } from './utils/assert'
+export type { PageAgentConfig, PageAgentTool }
+export { tool }
 
-/**
- * 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'
-
-/**
- * A single agent step with reflection and action
- */
-export interface AgentStep {
-	type: 'step'
-	reflection: Partial<AgentReflection>
-	action: {
-		name: string
-		input: any
-		output: string
-	}
-	usage: {
-		promptTokens: number
-		completionTokens: number
-		totalTokens: number
-		cachedTokens?: number
-		reasoningTokens?: number
-	}
-}
-
-/**
- * Persistent observation event (stays in memory)
- */
-export interface ObservationEvent {
-	type: 'observation'
-	content: string
-}
-
-/**
- * User takeover event
- */
-export interface UserTakeoverEvent {
-	type: 'user_takeover'
-}
-
-/**
- * Union type for all history events
- */
-export type HistoryEvent = AgentStep | ObservationEvent | UserTakeoverEvent
-
-export interface ExecutionResult {
-	success: boolean
-	data: string
-	history: HistoryEvent[]
-}
-
-export class PageAgent extends EventTarget {
-	config: PageAgentConfig
-	id = uid()
+export class PageAgent extends PageAgentCore {
 	panel: Panel
-	tools: typeof tools
-	disposed = false
-	task = ''
-	taskId = ''
-
-	#llm: LLM
-	#abortController = new AbortController()
-	#llmRetryListener: ((e: Event) => void) | null = null
-	#llmErrorListener: ((e: Event) => void) | null = null
-	#beforeUnloadListener: ((e: Event) => void) | null = null
-
-	/** PageController for DOM operations */
-	pageController: PageController
-
-	/** Runtime states for tracking across steps */
-	states = {
-		/** Accumulated wait time in seconds, used by wait tool */
-		totalWaitTime: 0,
-		/** Last known URL for detecting navigation */
-		lastURL: '',
-	}
-
-	/** History event stream */
-	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(),
-		})
-		this.tools = new Map(tools)
-
-		// Initialize PageController with config (mask enabled by default)
-		this.pageController = new PageController({
-			...this.config,
-			enableMask: this.config.enableMask ?? true,
+		const pageController = new PageController({
+			...config,
+			enableMask: config.enableMask ?? true,
 		})
 
-		// Listen to LLM events
-		this.#llmRetryListener = (e) => {
-			const { current, max } = (e as CustomEvent).detail
-			this.panel.update({ type: 'retry', current, max })
-		}
-		this.#llmErrorListener = (e) => {
-			const { error } = (e as CustomEvent).detail
-			this.panel.update({ type: 'error', message: `step failed: ${error.message}` })
-		}
-		this.#llm.addEventListener('retry', this.#llmRetryListener)
-		this.#llm.addEventListener('error', this.#llmErrorListener)
+		super({ ...config, pageController })
 
-		if (this.config.customTools) {
-			for (const [name, tool] of Object.entries(this.config.customTools)) {
-				if (tool === null) {
-					this.tools.delete(name)
-					continue
-				}
-				this.tools.set(name, tool)
-			}
-		}
-
-		if (!this.config.experimentalScriptExecutionTool) {
-			this.tools.delete('execute_javascript')
-		}
-
-		this.#beforeUnloadListener = (e) => {
-			if (!this.disposed) this.dispose('PAGE_UNLOADING')
-		}
-		window.addEventListener('beforeunload', this.#beforeUnloadListener)
-	}
-
-	/**
-	 * 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
-		this.taskId = uid()
-
-		const onBeforeStep = this.config.onBeforeStep || (() => void 0)
-		const onAfterStep = this.config.onAfterStep || (() => void 0)
-		const onBeforeTask = this.config.onBeforeTask || (() => void 0)
-		const onAfterTask = this.config.onAfterTask || (() => void 0)
-
-		await onBeforeTask.call(this)
-
-		// Show mask and panel
-		this.pageController.showMask()
-
-		this.panel.show()
-		this.panel.reset()
-
-		this.panel.update({ type: 'input', task: this.task })
-
-		if (this.#abortController) {
-			this.#abortController.abort()
-			this.#abortController = new AbortController()
-		}
-
-		this.history = []
-
-		// 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')
-
-				// Update status to thinking
-				console.log(chalk.blue('Thinking...'))
-				this.panel.update({ type: 'thinking' })
-
-				const result = await this.#llm.invoke(
-					[
-						{
-							role: 'system',
-							content: this.#getSystemPrompt(),
-						},
-						{
-							role: 'user',
-							content: await this.#assembleUserPrompt(),
-						},
-					],
-					{ AgentOutput: this.#packMacroTool() },
-					this.#abortController.signal,
-					{
-						toolChoiceName: 'AgentOutput',
-						normalizeResponse,
-					}
-				)
-
-				const macroResult = result.toolResult as MacroToolResult
-				const input = macroResult.input
-				const output = macroResult.output
-				const reflection: Partial<AgentReflection> = {
-					evaluation_previous_goal: input.evaluation_previous_goal,
-					memory: input.memory,
-					next_goal: input.next_goal,
-				}
-				const actionName = Object.keys(input.action)[0]
-				const action: AgentStep['action'] = {
-					name: actionName,
-					input: input.action[actionName],
-					output: output,
-				}
-
-				this.history.push({
-					type: 'step',
-					reflection,
-					action,
-					usage: result.usage,
-				} as AgentStep)
-
-				console.log(chalk.green('Step finished:'), actionName)
-				console.groupEnd()
-
-				await onAfterStep.call(this, step, this.history)
-
-				step++
-				if (step > MAX_STEPS) {
-					this.#onDone('Step count exceeded maximum limit', false)
-					const result: ExecutionResult = {
-						success: false,
-						data: 'Step count exceeded maximum limit',
-						history: this.history,
-					}
-					await onAfterTask.call(this, result)
-					return result
-				}
-				if (actionName === 'done') {
-					const success = action.input?.success ?? false
-					const text = action.input?.text || 'no text provided'
-					console.log(chalk.green.bold('Task completed'), success, text)
-					this.#onDone(text, success)
-					const result: ExecutionResult = {
-						success,
-						data: text,
-						history: this.history,
-					}
-					await onAfterTask.call(this, result)
-					return result
-				}
-			}
-		} catch (error: unknown) {
-			console.error('Task failed', error)
-			this.#onDone(String(error), false)
-			const result: ExecutionResult = {
-				success: false,
-				data: String(error),
-				history: this.history,
-			}
-			await onAfterTask.call(this, result)
-			return result
-		}
-	}
-
-	/**
-	 * Merge all tools into a single MacroTool with the following input:
-	 * - thinking: string
-	 * - evaluation_previous_goal: string
-	 * - memory: string
-	 * - next_goal: string
-	 * - action: { toolName: toolInput }
-	 * where action must be selected from tools defined in this.tools
-	 */
-	#packMacroTool(): Tool<MacroToolInput, MacroToolResult> {
-		const tools = this.tools
-
-		const actionSchemas = Array.from(tools.entries()).map(([toolName, tool]) => {
-			return zod.object({ [toolName]: tool.inputSchema }).describe(tool.description)
+		this.panel = new Panel(this, {
+			language: config.language,
 		})
-
-		const actionSchema = zod.union(
-			actionSchemas as unknown as [zod.ZodType, zod.ZodType, ...zod.ZodType[]]
-		)
-
-		const macroToolSchema = zod.object({
-			// thinking: zod.string().optional(),
-			evaluation_previous_goal: zod.string().optional(),
-			memory: zod.string().optional(),
-			next_goal: zod.string().optional(),
-			action: actionSchema,
-		})
-
-		return {
-			description: 'You MUST call this tool every step. Outputs your reflections and next action.',
-			inputSchema: macroToolSchema as zod.ZodType<MacroToolInput>,
-			execute: async (input: MacroToolInput): Promise<MacroToolResult> => {
-				// abort
-				if (this.#abortController.signal.aborted) throw new Error('AbortError')
-
-				console.log(chalk.blue.bold('MacroTool execute'), input)
-				const action = input.action
-
-				const toolName = Object.keys(action)[0]
-				const toolInput = action[toolName]
-
-				// Build reflection text, only include non-empty fields
-				const reflectionLines: string[] = []
-				if (input.evaluation_previous_goal)
-					reflectionLines.push(`✅: ${input.evaluation_previous_goal}`)
-				if (input.memory) reflectionLines.push(`💾: ${input.memory}`)
-				if (input.next_goal) reflectionLines.push(`🎯: ${input.next_goal}`)
-
-				const reflectionText = reflectionLines.length > 0 ? reflectionLines.join('\n') : ''
-
-				if (reflectionText) {
-					console.log(reflectionText)
-					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 })
-
-				const startTime = Date.now()
-
-				// Execute tool, bind `this` to PageAgent
-				const result = await tool.execute.bind(this)(toolInput)
-
-				const duration = Date.now() - startTime
-				console.log(chalk.green.bold(`Tool (${toolName}) executed for ${duration}ms`), result)
-
-				// Reset wait time for non-wait tools
-				if (toolName !== 'wait') {
-					this.states.totalWaitTime = 0
-				}
-
-				// Briefly display execution result
-				this.panel.update({
-					type: 'toolCompleted',
-					toolName,
-					args: toolInput,
-					result,
-					duration,
-				})
-
-				// Wait a moment to let user see the result
-				await new Promise((resolve) => setTimeout(resolve, 100))
-
-				// Return structured result
-				return {
-					input,
-					output: result,
-				}
-			},
-		}
-	}
-
-	/**
-	 * Get system prompt, dynamically replace language settings based on configured language
-	 */
-	#getSystemPrompt(): string {
-		let systemPrompt = SYSTEM_PROMPT
-
-		const targetLanguage = this.config.language === 'zh-CN' ? '中文' : 'English'
-		systemPrompt = systemPrompt.replace(
-			/Default working language: \*\*.*?\*\*/,
-			`Default working language: **${targetLanguage}**`
-		)
-
-		return systemPrompt
-	}
-
-	/**
-	 * Get instructions from config and format as XML block
-	 */
-	async #getInstructions(): Promise<string> {
-		const { instructions } = this.config
-		if (!instructions) return ''
-
-		const systemInstructions = instructions.system?.trim()
-		const url = await this.pageController.getCurrentUrl()
-		let pageInstructions: string | undefined
-
-		if (instructions.getPageInstructions) {
-			try {
-				pageInstructions = instructions.getPageInstructions(url)?.trim()
-			} catch (error) {
-				console.error(
-					chalk.red('[PageAgent] Failed to execute getPageInstructions callback:'),
-					error
-				)
-			}
-		}
-		if (!systemInstructions && !pageInstructions) return ''
-
-		let result = '<instructions>\n'
-
-		if (systemInstructions) {
-			result += `<system_instructions>\n${systemInstructions}\n</system_instructions>\n`
-		}
-
-		if (pageInstructions) {
-			result += `<page_instructions>\n${pageInstructions}\n</page_instructions>\n`
-		}
-
-		result += '</instructions>\n\n'
-
-		return result
-	}
-
-	/**
-	 * Generate observations before each step
-	 * - URL change detection
-	 * - Too many steps warning
-	 * @todo loop detection
-	 * @todo console error
-	 */
-	async #generateObservations(stepCount: number): Promise<void> {
-		// Detect URL change
-		const currentURL = await this.pageController.getCurrentUrl()
-		if (currentURL !== this.states.lastURL) {
-			this.pushObservation(`Page navigated to → ${currentURL}`)
-			this.states.lastURL = currentURL
-		}
-
-		// Warn about remaining steps
-		const remaining = MAX_STEPS - stepCount
-		if (remaining === 5) {
-			this.pushObservation(
-				`⚠️ Only ${remaining} steps remaining. Consider wrapping up or calling done with partial results.`
-			)
-		} else if (remaining === 2) {
-			this.pushObservation(
-				`⚠️ Critical: Only ${remaining} steps left! You must finish the task or call done immediately.`
-			)
-		}
-	}
-
-	async #assembleUserPrompt(): Promise<string> {
-		let prompt = ''
-
-		// <instructions> (optional)
-		prompt += await this.#getInstructions()
-
-		// <agent_state>
-		//  - <user_request>
-		//  - <step_info>
-		// <agent_state>
-
-		const stepCount = this.history.filter((e) => e.type === 'step').length
-
-		prompt += `<agent_state>
-			<user_request>
-			${this.task}
-			</user_request>
-			<step_info>
-			Step ${stepCount + 1} of ${MAX_STEPS} max possible steps
-			Current date and time: ${new Date().toISOString()}
-			</step_info>
-			</agent_state>
-		`
-
-		// <agent_history>
-		//  - <step_N> for steps
-		//  - <sys> for observations and system messages
-
-		prompt += '\n<agent_history>\n'
-
-		let stepIndex = 0
-		for (const event of this.history) {
-			if (event.type === 'step') {
-				stepIndex++
-				prompt += `<step_${stepIndex}>
-				Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}
-				Memory: ${event.reflection.memory}
-				Next Goal: ${event.reflection.next_goal}
-				Action Results: ${event.action.output}
-				</step_${stepIndex}>
-			`
-			} else if (event.type === 'observation') {
-				prompt += `<sys>${event.content}</sys>\n`
-			} else if (event.type === 'user_takeover') {
-				prompt += `<sys>User took over control and made changes to the page.</sys>\n`
-			}
-		}
-
-		prompt += '</agent_history>\n\n'
-
-		// <browser_state>
-
-		prompt += await this.#getBrowserState()
-
-		return trimLines(prompt)
-	}
-
-	#onDone(text: string, success = true) {
-		this.pageController.cleanUpHighlights()
-
-		// Update panel status
-		if (success) {
-			this.panel.update({ type: 'output', text })
-		} else {
-			this.panel.update({ type: 'error', message: text })
-		}
-
-		// Task completed
-		this.panel.update({ type: 'completed' })
-
-		this.pageController.hideMask()
-
-		this.#abortController.abort()
-	}
-
-	async #getBrowserState(): Promise<string> {
-		const state = await this.pageController.getBrowserState()
-
-		let content = state.content
-		if (this.config.transformPageContent) {
-			content = await this.config.transformPageContent(content)
-		}
-
-		return trimLines(`<browser_state>
-			Current Page: [${state.title}](${state.url})
-
-			${state.header}
-			${content}
-			${state.footer}
-
-			</browser_state>
-		`)
-	}
-
-	dispose(reason?: string) {
-		console.log('Disposing PageAgent...')
-		this.disposed = true
-		this.pageController.dispose()
-		this.panel.dispose()
-		this.history = []
-		this.#abortController.abort(reason ?? 'PageAgent disposed')
-
-		// Clean up LLM event listeners
-		if (this.#llmRetryListener) {
-			this.#llm.removeEventListener('retry', this.#llmRetryListener)
-			this.#llmRetryListener = null
-		}
-		if (this.#llmErrorListener) {
-			this.#llm.removeEventListener('error', this.#llmErrorListener)
-			this.#llmErrorListener = null
-		}
-
-		// Clean up window event listeners
-		if (this.#beforeUnloadListener) {
-			window.removeEventListener('beforeunload', this.#beforeUnloadListener)
-			this.#beforeUnloadListener = null
-		}
-
-		this.config.onDispose?.call(this, reason)
 	}
 }

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

@@ -1,2 +0,0 @@
-// Agent-specific constants (LLM constants moved to @page-agent/llms)
-export const MAX_STEPS = 20

packages/page-agent/src/demo.ts

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

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

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

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

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

packages/page-agent/tsconfig.json

@@ -10,6 +10,7 @@
             //
             "@page-agent/llms": ["../llms/src/index.ts"],
             "@page-agent/page-controller": ["../page-controller/src/PageController.ts"],
+            "@page-agent/core": ["../core/src/PageAgentCore.ts"],
             "@page-agent/ui": ["../ui/src/index.ts"]
         }
     },
@@ -19,6 +20,7 @@
         //
         { "path": "../llms" },
         { "path": "../page-controller" },
+        { "path": "../core" },
         { "path": "../ui" }
     ]
 }

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

@@ -24,24 +24,25 @@ export default defineConfig(({ mode }) => ({
 		alias: {
 			'@page-agent/page-controller': resolve(__dirname, '../page-controller/src/PageController.ts'),
 			'@page-agent/llms': resolve(__dirname, '../llms/src/index.ts'),
+			'@page-agent/core': resolve(__dirname, '../core/src/PageAgentCore.ts'),
 			'@page-agent/ui': resolve(__dirname, '../ui/src/index.ts'),
 		},
 	},
 	build: {
 		lib: {
-			entry: resolve(__dirname, 'src/iife.ts'),
+			entry: resolve(__dirname, 'src/demo.ts'),
 			name: 'PageAgent',
-			fileName: 'page-agent',
+			fileName: () => `page-agent.demo.js`,
 			formats: ['iife'],
 		},
 		outDir: resolve(__dirname, 'dist', 'iife'),
 		cssCodeSplit: true,
-		minify: false,
+		// minify: false,
 		rollupOptions: {
-			output: {
-				// force use .js as extension
-				entryFileNames: 'page-agent.js',
-			},
+			// output: {
+			// 	// force use .js as extension
+			// 	entryFileNames: 'page-agent.js',
+			// },
 			onwarn: function (message, handler) {
 				if (message.code === 'EVAL') return
 				handler(message)

packages/page-controller/package.json

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

packages/page-controller/src/PageController.ts

@@ -18,11 +18,8 @@ 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
  */
@@ -83,8 +80,12 @@ export class PageController extends EventTarget {
 	/** last time the tree was updated */
 	private lastTimeUpdate = 0
 
+	/** Whether the tree has been indexed at least once */
+	private isIndexed = false
+
 	/** Visual mask overlay for blocking user interaction during automation */
-	private mask: SimulatorMask | null = null
+	private mask: InstanceType<typeof import('./mask/SimulatorMask').SimulatorMask> | null = null
+	private maskReady: Promise<void> | null = null
 
 	constructor(config: PageControllerConfig = {}) {
 		super()
@@ -94,10 +95,17 @@ export class PageController extends EventTarget {
 		patchReact(this)
 
 		if (config.enableMask) {
-			this.mask = new SimulatorMask()
+			this.maskReady = this.initMask()
 		}
 	}
 
+	/**
+	 * Initialize mask asynchronously (dynamic import to avoid CSS loading in Node)
+	 */
+	private async initMask(): Promise<void> {
+		const { SimulatorMask } = await import('./mask/SimulatorMask')
+		this.mask = new SimulatorMask()
+	}
 	// ======= State Queries =======
 
 	/**
@@ -191,6 +199,9 @@ export class PageController extends EventTarget {
 		this.elementTextMap.clear()
 		this.elementTextMap = dom.getElementTextMap(this.simplifiedHTML)
 
+		// Mark as indexed - now element actions are allowed
+		this.isIndexed = true
+
 		// Restore mask blocking
 		if (this.mask) {
 			this.mask.wrapper.style.pointerEvents = 'auto'
@@ -210,11 +221,22 @@ export class PageController extends EventTarget {
 
 	// ======= Element Actions =======
 
+	/**
+	 * Ensure the tree has been indexed before any index-based operation.
+	 * Throws if updateTree() hasn't been called yet.
+	 */
+	private assertIndexed(): void {
+		if (!this.isIndexed) {
+			throw new Error('DOM tree not indexed. Can not perform actions on elements.')
+		}
+	}
+
 	/**
 	 * Click element by index
 	 */
 	async clickElement(index: number): Promise<ActionResult> {
 		try {
+			this.assertIndexed()
 			const element = getElementByIndex(this.selectorMap, index)
 			const elemText = this.elementTextMap.get(index)
 			await clickElement(element)
@@ -244,6 +266,7 @@ export class PageController extends EventTarget {
 	 */
 	async inputText(index: number, text: string): Promise<ActionResult> {
 		try {
+			this.assertIndexed()
 			const element = getElementByIndex(this.selectorMap, index)
 			const elemText = this.elementTextMap.get(index)
 			await inputTextElement(element, text)
@@ -265,6 +288,7 @@ export class PageController extends EventTarget {
 	 */
 	async selectOption(index: number, optionText: string): Promise<ActionResult> {
 		try {
+			this.assertIndexed()
 			const element = getElementByIndex(this.selectorMap, index)
 			const elemText = this.elementTextMap.get(index)
 			await selectOptionElement(element as HTMLSelectElement, optionText)
@@ -293,6 +317,8 @@ export class PageController extends EventTarget {
 		try {
 			const { down, numPages, pixels, index } = options
 
+			this.assertIndexed()
+
 			const scrollAmount = pixels ?? numPages * (down ? 1 : -1) * window.innerHeight
 
 			const element = index !== undefined ? getElementByIndex(this.selectorMap, index) : null
@@ -322,6 +348,8 @@ export class PageController extends EventTarget {
 		try {
 			const { right, pixels, index } = options
 
+			this.assertIndexed()
+
 			const scrollAmount = pixels * (right ? 1 : -1)
 
 			const element = index !== undefined ? getElementByIndex(this.selectorMap, index) : null
@@ -366,7 +394,8 @@ export class PageController extends EventTarget {
 	 * Show the visual mask overlay.
 	 * Only works if enableMask was set to true in config.
 	 */
-	showMask(): void {
+	async showMask(): Promise<void> {
+		await this.maskReady
 		this.mask?.show()
 	}
 
@@ -374,7 +403,8 @@ export class PageController extends EventTarget {
 	 * Hide the visual mask overlay.
 	 * Only works if enableMask was set to true in config.
 	 */
-	hideMask(): void {
+	async hideMask(): Promise<void> {
+		await this.maskReady
 		this.mask?.hide()
 	}
 
@@ -387,6 +417,7 @@ export class PageController extends EventTarget {
 		this.selectorMap.clear()
 		this.elementTextMap.clear()
 		this.simplifiedHTML = '<EMPTY>'
+		this.isIndexed = false
 		this.mask?.dispose()
 		this.mask = null
 	}

packages/ui/package.json

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

packages/ui/src/UIState.ts

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

packages/ui/src/i18n/locales.ts

@@ -22,6 +22,7 @@ const enUS = {
 			selecting: 'Selecting option "{{text}}"...',
 			scrolling: 'Scrolling page...',
 			waiting: 'Waiting {{seconds}} seconds...',
+			askingUser: 'Asking user...',
 			done: 'Task done',
 			clicked: '🖱️ Clicked element [{{index}}]',
 			inputted: '⌨️ Inputted text "{{text}}"',
@@ -68,6 +69,7 @@ const zhCN = {
 			selecting: '正在选择选项 "{{text}}"...',
 			scrolling: '正在滚动页面...',
 			waiting: '等待 {{seconds}} 秒...',
+			askingUser: '正在询问用户...',
 			done: '结束任务',
 			clicked: '🖱️ 已点击元素 [{{index}}]',
 			inputted: '⌨️ 已输入文本 "{{text}}"',

packages/ui/src/index.ts

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

packages/ui/src/panel/Panel.module.css

@@ -357,6 +357,11 @@
 				background: linear-gradient(135deg, rgba(147, 51, 234, 0.1), rgba(147, 51, 234, 0.05));
 			}
 
+			&.question {
+				border-left-color: rgb(255, 159, 67);
+				background: linear-gradient(135deg, rgba(255, 159, 67, 0.15), rgba(255, 159, 67, 0.08));
+			}
+
 			/* 突出显示 done 成功结果 */
 			&.doneSuccess {
 				background: linear-gradient(
@@ -439,7 +444,7 @@
 
 			.historyContent {
 				display: flex;
-				align-items: center;
+				align-items: flex-start;
 				gap: 8px;
 
 				word-break: break-all;
@@ -453,6 +458,12 @@
 					line-height: 1;
 					transition: all 0.3s ease;
 				}
+
+				.reflectionLines {
+					display: flex;
+					flex-direction: column;
+					gap: 4px;
+				}
 			}
 
 			.historyMeta {

packages/ui/src/panel/Panel.ts

@@ -1,6 +1,7 @@
-import { type Step, UIState } from './UIState'
-import { I18n, type SupportedLanguage } from './i18n'
-import { escapeHtml, truncate } from './utils'
+import { I18n, type SupportedLanguage } from '../i18n'
+import { truncate } from '../utils'
+import { createCard, createReflectionLines, formatTime } from './cards'
+import type { AgentActivity, PanelAgentAdapter } from './types'
 
 import styles from './Panel.module.css'
 
@@ -9,28 +10,22 @@ import styles from './Panel.module.css'
  */
 export interface PanelConfig {
 	language?: SupportedLanguage
-	onExecuteTask: (task: string) => void
-	onStop: () => void
+	/**
+	 * Whether to prompt for next task after task completion
+	 * @default true
+	 */
+	promptForNextTask?: boolean
 }
 
-/**
- * Semantic update types - Panel handles i18n internally
- */
-export type PanelUpdate =
-	| { type: 'thinking'; text?: string } // text is optional, defaults to i18n thinking text
-	| { type: 'input'; task: string }
-	| { type: 'question'; question: string }
-	| { type: 'userAnswer'; input: string }
-	| { type: 'retry'; current: number; max: number }
-	| { type: 'error'; message: string }
-	| { type: 'output'; text: string }
-	| { type: 'completed' }
-	| { type: 'toolExecuting'; toolName: string; args: any }
-	| { type: 'toolCompleted'; toolName: string; args: any; result?: string; duration?: number }
-	| { type: 'observation'; content: string }
-
 /**
  * Agent control panel
+ *
+ * Architecture:
+ * - History list: renders directly from agent.history (historical events)
+ * - Header bar: shows activity events (transient state) and agent status
+ *
+ * This separation ensures data consistency - history is the single source of truth
+ * for what has been done, while activity shows what is happening now.
  */
 export class Panel {
 	#wrapper: HTMLElement
@@ -42,9 +37,9 @@ export class Panel {
 	#inputSection: HTMLElement
 	#taskInput: HTMLInputElement
 
-	#state = new UIState()
-	#isExpanded = false
+	#agent: PanelAgentAdapter
 	#config: PanelConfig
+	#isExpanded = false
 	#i18n: I18n
 	#userAnswerResolver: ((input: string) => void) | null = null
 	#isWaitingForUserAnswer: boolean = false
@@ -52,13 +47,30 @@ export class Panel {
 	#pendingHeaderText: string | null = null
 	#isAnimating = false
 
+	// Event handlers (bound for removal)
+	#onStatusChange = () => this.#handleStatusChange()
+	#onHistoryChange = () => this.#handleHistoryChange()
+	#onActivity = (e: Event) => this.#handleActivity((e as CustomEvent<AgentActivity>).detail)
+	#onAgentDispose = () => this.dispose()
+
 	get wrapper(): HTMLElement {
 		return this.#wrapper
 	}
 
-	constructor(config: PanelConfig) {
+	/**
+	 * Create a Panel bound to an agent
+	 * @param agent - Agent instance that implements PanelAgentAdapter
+	 * @param config - Optional panel configuration
+	 */
+	constructor(agent: PanelAgentAdapter, config: PanelConfig = {}) {
+		this.#agent = agent
 		this.#config = config
 		this.#i18n = new I18n(config.language ?? 'en-US')
+
+		// Set up askUser callback on agent
+		this.#agent.onAskUser = (question) => this.#askUser(question)
+
+		// Create UI elements
 		this.#wrapper = this.#createWrapper()
 		this.#indicator = this.#wrapper.querySelector(`.${styles.indicator}`)!
 		this.#statusText = this.#wrapper.querySelector(`.${styles.statusText}`)!
@@ -68,6 +80,12 @@ export class Panel {
 		this.#inputSection = this.#wrapper.querySelector(`.${styles.inputSectionWrapper}`)!
 		this.#taskInput = this.#wrapper.querySelector(`.${styles.taskInput}`)!
 
+		// Listen to agent events
+		this.#agent.addEventListener('statuschange', this.#onStatusChange)
+		this.#agent.addEventListener('historychange', this.#onHistoryChange)
+		this.#agent.addEventListener('activity', this.#onActivity)
+		this.#agent.addEventListener('dispose', this.#onAgentDispose)
+
 		this.#setupEventListeners()
 		this.#startHeaderUpdateLoop()
 
@@ -76,24 +94,98 @@ export class Panel {
 		this.hide() // Start hidden
 	}
 
+	// ========== Agent event handlers ==========
+
+	/** Handle agent status change */
+	#handleStatusChange(): void {
+		const status = this.#agent.status
+
+		// Map agent status to UI indicator type
+		const indicatorType =
+			status === 'running' ? 'thinking' : status === 'idle' ? 'thinking' : status
+		this.#updateStatusIndicator(indicatorType)
+
+		// Show/hide based on status
+		if (status === 'running') {
+			this.show()
+			this.#hideInputArea() // Hide input while running
+		}
+
+		// Handle completion
+		if (status === 'completed' || status === 'error') {
+			if (!this.#isExpanded) {
+				this.#expand()
+			}
+			if (this.#shouldShowInputArea()) {
+				this.#showInputArea()
+			}
+		}
+	}
+
+	/** Handle agent history change - re-render history list from agent.history */
+	#handleHistoryChange(): void {
+		this.#renderHistory()
+	}
+
 	/**
-	 * Ask for user input
+	 * Handle agent activity - transient state for immediate UI feedback
+	 * Activity events are NOT persisted in history, only used for header bar updates
 	 */
-	async askUser(question: string): Promise<string> {
+	#handleActivity(activity: AgentActivity): void {
+		switch (activity.type) {
+			case 'thinking':
+				this.#pendingHeaderText = this.#i18n.t('ui.panel.thinking')
+				this.#updateStatusIndicator('thinking')
+				break
+
+			case 'executing':
+				this.#pendingHeaderText = this.#getToolExecutingText(activity.tool, activity.input)
+				this.#updateStatusIndicator('executing')
+				break
+
+			case 'executed':
+				this.#pendingHeaderText = truncate(activity.output, 50)
+				break
+
+			case 'retrying':
+				this.#pendingHeaderText = `Retrying (${activity.attempt}/${activity.maxAttempts})`
+				this.#updateStatusIndicator('retrying')
+				break
+
+			case 'error':
+				this.#pendingHeaderText = truncate(activity.message, 50)
+				this.#updateStatusIndicator('error')
+				break
+		}
+	}
+
+	/**
+	 * Ask for user input (internal, called by agent via onAskUser)
+	 */
+	#askUser(question: string): Promise<string> {
 		return new Promise((resolve) => {
 			// Set `waiting for user answer` state
 			this.#isWaitingForUserAnswer = true
 			this.#userAnswerResolver = resolve
 
-			// Update state to `running`
-			this.#updateInternal({
-				type: 'output',
-				displayText: this.#i18n.t('ui.panel.question', { question }),
-			}) // Expand history panel
+			// Expand history panel
 			if (!this.#isExpanded) {
 				this.#expand()
 			}
 
+			// Add temporary question card so user can see the full question
+			const tempCard = document.createElement('div')
+			tempCard.innerHTML = createCard({
+				icon: '❓',
+				content: `Question: ${question}`,
+				meta: formatTime(this.#config.language ?? 'en-US'),
+				type: 'question',
+			})
+			const cardElement = tempCard.firstElementChild as HTMLElement
+			cardElement.setAttribute('data-temp-card', 'true')
+			this.#historySection.appendChild(cardElement)
+			this.#scrollToBottom()
+
 			this.#showInputArea(this.#i18n.t('ui.panel.userAnswerPrompt'))
 		})
 	}
@@ -114,10 +206,9 @@ export class Panel {
 	}
 
 	reset(): void {
-		this.#state.reset()
 		this.#statusText.textContent = this.#i18n.t('ui.panel.ready')
 		this.#updateStatusIndicator('thinking')
-		this.#updateHistory()
+		this.#renderHistory()
 		this.#collapse()
 		// Reset user input state
 		this.#isWaitingForUserAnswer = false
@@ -135,17 +226,16 @@ export class Panel {
 	}
 
 	/**
-	 * Update panel with semantic data - i18n handled internally
-	 */
-	update(data: PanelUpdate): void {
-		const stepData = this.#toStepData(data)
-		this.#updateInternal(stepData)
-	}
-
-	/**
-	 * Dispose panel
+	 * Dispose panel and clean up event listeners
 	 */
 	dispose(): void {
+		// Remove agent event listeners
+		this.#agent.removeEventListener('statuschange', this.#onStatusChange)
+		this.#agent.removeEventListener('historychange', this.#onHistoryChange)
+		this.#agent.removeEventListener('activity', this.#onActivity)
+		this.#agent.removeEventListener('dispose', this.#onAgentDispose)
+
+		// Clean up UI
 		this.#isWaitingForUserAnswer = false
 		this.#stopHeaderUpdateLoop()
 		this.wrapper.remove()
@@ -153,69 +243,21 @@ export class Panel {
 
 	// ========== Private methods ==========
 
-	/**
-	 * Convert semantic update to step data with i18n
-	 */
-	#toStepData(data: PanelUpdate): Omit<Step, 'id' | 'stepNumber' | 'timestamp'> {
-		switch (data.type) {
-			case 'thinking':
-				return { type: 'thinking', displayText: data.text ?? this.#i18n.t('ui.panel.thinking') }
-			case 'input':
-				return { type: 'input', displayText: data.task }
-			case 'question':
-				return {
-					type: 'output',
-					displayText: this.#i18n.t('ui.panel.question', { question: data.question }),
-				}
-			case 'userAnswer':
-				return {
-					type: 'input',
-					displayText: this.#i18n.t('ui.panel.userAnswer', { input: data.input }),
-				}
-			case 'retry':
-				return { type: 'retry', displayText: `retry-ing (${data.current} / ${data.max})` }
-			case 'error':
-				return { type: 'error', displayText: data.message }
-			case 'output':
-				return { type: 'output', displayText: data.text }
-			case 'completed':
-				return { type: 'completed', displayText: this.#i18n.t('ui.panel.taskCompleted') }
-			case 'toolExecuting':
-				return {
-					type: 'tool_executing',
-					toolName: data.toolName,
-					toolArgs: data.args,
-					displayText: this.#getToolExecutingText(data.toolName, data.args),
-				}
-			case 'toolCompleted': {
-				const displayText = this.#getToolCompletedText(data.toolName, data.args)
-				if (!displayText) return { type: 'tool_executing', displayText: '' } // will be filtered
-				return {
-					type: 'tool_executing',
-					toolName: data.toolName,
-					toolArgs: data.args,
-					toolResult: data.result,
-					displayText,
-					duration: data.duration,
-				}
-			}
-			case 'observation':
-				return { type: 'observation', displayText: data.content }
-		}
-	}
-
-	#getToolExecutingText(toolName: string, args: any): string {
+	#getToolExecutingText(toolName: string, args: unknown): string {
+		const a = args as Record<string, string | number>
 		switch (toolName) {
 			case 'click_element_by_index':
-				return this.#i18n.t('ui.tools.clicking', { index: args.index })
+				return this.#i18n.t('ui.tools.clicking', { index: a.index })
 			case 'input_text':
-				return this.#i18n.t('ui.tools.inputting', { index: args.index })
+				return this.#i18n.t('ui.tools.inputting', { index: a.index })
 			case 'select_dropdown_option':
-				return this.#i18n.t('ui.tools.selecting', { text: args.text })
+				return this.#i18n.t('ui.tools.selecting', { text: a.text })
 			case 'scroll':
 				return this.#i18n.t('ui.tools.scrolling')
 			case 'wait':
-				return this.#i18n.t('ui.tools.waiting', { seconds: args.seconds })
+				return this.#i18n.t('ui.tools.waiting', { seconds: a.seconds })
+			case 'ask_user':
+				return this.#i18n.t('ui.tools.askingUser')
 			case 'done':
 				return this.#i18n.t('ui.tools.done')
 			default:
@@ -223,67 +265,11 @@ export class Panel {
 		}
 	}
 
-	#getToolCompletedText(toolName: string, args: any): string | null {
-		switch (toolName) {
-			case 'click_element_by_index':
-				return this.#i18n.t('ui.tools.clicked', { index: args.index })
-			case 'input_text':
-				return this.#i18n.t('ui.tools.inputted', { text: args.text })
-			case 'select_dropdown_option':
-				return this.#i18n.t('ui.tools.selected', { text: args.text })
-			case 'scroll':
-				return this.#i18n.t('ui.tools.scrolled')
-			case 'wait':
-				return this.#i18n.t('ui.tools.waited')
-			case 'done':
-				return null
-			default:
-				return null
-		}
-	}
-
-	/**
-	 * Update status (internal)
-	 */
-	#updateInternal(stepData: Omit<Step, 'id' | 'stepNumber' | 'timestamp'>): void {
-		// Skip empty displayText (filtered toolCompleted for 'done')
-		if (!stepData.displayText) return
-
-		const step = this.#state.addStep(stepData)
-
-		// Queue header text update (will be processed by periodic check)
-		const headerText = truncate(step.displayText, 20)
-		this.#pendingHeaderText = headerText
-
-		this.#updateStatusIndicator(step.type)
-		this.#updateHistory()
-
-		// Auto-expand history after task completion
-		if (step.type === 'completed' || step.type === 'error') {
-			if (!this.#isExpanded) {
-				this.#expand()
-			}
-		}
-
-		// Control input area display based on status
-		if (this.#shouldShowInputArea()) {
-			this.#showInputArea()
-		} else {
-			this.#hideInputArea()
-		}
-	}
-
 	/**
 	 * Stop Agent
 	 */
 	#stopAgent(): void {
-		// Update status display
-		this.#updateInternal({
-			type: 'error',
-			displayText: this.#i18n.t('ui.panel.taskTerminated'),
-		})
-
-		this.#config.onStop()
+		this.#agent.dispose()
 	}
 
 	/**
@@ -300,7 +286,8 @@ export class Panel {
 			// Handle user input mode
 			this.#handleUserAnswer(input)
 		} else {
-			this.#config.onExecuteTask(input)
+			// Execute task via agent
+			this.#agent.execute(input)
 		}
 	}
 
@@ -308,10 +295,11 @@ export class Panel {
 	 * Handle user answer
 	 */
 	#handleUserAnswer(input: string): void {
-		// Add user input to history
-		this.#updateInternal({
-			type: 'input',
-			displayText: this.#i18n.t('ui.panel.userAnswer', { input }),
+		// Remove temporary question cards (only direct children for safety)
+		Array.from(this.#historySection.children).forEach((child) => {
+			if (child.getAttribute('data-temp-card') === 'true') {
+				child.remove()
+			}
 		})
 
 		// Reset state
@@ -352,13 +340,20 @@ export class Panel {
 		// Always show input area if waiting for user input
 		if (this.#isWaitingForUserAnswer) return true
 
-		const steps = this.#state.getAllSteps()
-		if (steps.length === 0) {
+		const history = this.#agent.history
+		if (history.length === 0) {
 			return true // Initial state
 		}
 
-		const lastStep = steps[steps.length - 1]
-		return lastStep.type === 'completed' || lastStep.type === 'error'
+		const status = this.#agent.status
+		const isTaskEnded = status === 'completed' || status === 'error'
+
+		// Only show input area after task completion if configured to do so
+		if (isTaskEnded) {
+			return this.#config.promptForNextTask ?? true
+		}
+
+		return false
 	}
 
 	#createWrapper(): HTMLElement {
@@ -371,13 +366,12 @@ export class Panel {
 			<div class="${styles.background}"></div>
 			<div class="${styles.historySectionWrapper}">
 				<div class="${styles.historySection}">
-					${this.#createHistoryItem({
-						id: 'placeholder',
-						stepNumber: 0,
-						timestamp: new Date(),
-						type: 'thinking',
-						displayText: this.#i18n.t('ui.panel.waitingPlaceholder'),
-					})}
+					<div class="${styles.historyItem}">
+						<div class="${styles.historyContent}">
+							<span class="${styles.statusIcon}">🧠</span>
+							<span>${this.#i18n.t('ui.panel.waitingPlaceholder')}</span>
+						</div>
+					</div>
 				</div>
 			</div>
 			<div class="${styles.header}">
@@ -532,7 +526,9 @@ export class Panel {
 		}, 150) // Half the duration of fade out animation
 	}
 
-	#updateStatusIndicator(type: Step['type']): void {
+	#updateStatusIndicator(
+		type: 'thinking' | 'executing' | 'executed' | 'retrying' | 'completed' | 'error'
+	): void {
 		// Clear all status classes
 		this.#indicator.className = styles.indicator
 
@@ -540,12 +536,6 @@ export class Panel {
 		this.#indicator.classList.add(styles[type])
 	}
 
-	#updateHistory(): void {
-		const steps = this.#state.getAllSteps()
-		this.#historySection.innerHTML = steps.map((step) => this.#createHistoryItem(step)).join('')
-		this.#scrollToBottom()
-	}
-
 	#scrollToBottom(): void {
 		// Execute in next event loop to ensure DOM update completion
 		setTimeout(() => {
@@ -553,71 +543,116 @@ export class Panel {
 		}, 0)
 	}
 
-	#createHistoryItem(step: Step): string {
-		const time = step.timestamp.toLocaleTimeString('zh-CN', {
-			hour12: false,
-			hour: '2-digit',
-			minute: '2-digit',
-			second: '2-digit',
-		})
+	/**
+	 * Render history directly from agent.history
+	 *
+	 * Renders:
+	 * 1. Task (first item, from agent.task)
+	 * 2. Reflection cards (evaluation, memory, next_goal)
+	 * 3. Tool execution with output
+	 * 4. Observations
+	 */
+	#renderHistory(): void {
+		const items: string[] = []
 
-		let typeClass = ''
-		let statusIcon = ''
-
-		// Set styles and icons based on step type
-		if (step.type === 'completed') {
-			// Check if this is a result from done tool
-			if (step.toolName === 'done') {
-				// Judge success or failure based on result
-				const failureKeyword = this.#i18n.t('ui.tools.resultFailure')
-				const errorKeyword = this.#i18n.t('ui.tools.resultError')
-				const isSuccess =
-					!step.toolResult ||
-					(!step.toolResult.includes(failureKeyword) && !step.toolResult.includes(errorKeyword))
-				typeClass = isSuccess ? styles.doneSuccess : styles.doneError
-				statusIcon = isSuccess ? '🎉' : '❌'
-			} else {
-				typeClass = styles.completed
-				statusIcon = '✅'
-			}
-		} else if (step.type === 'error') {
-			typeClass = styles.error
-			statusIcon = '❌'
-		} else if (step.type === 'tool_executing') {
-			statusIcon = '🔨'
-		} else if (step.type === 'output') {
-			typeClass = styles.output
-			statusIcon = '🤖'
-		} else if (step.type === 'input') {
-			typeClass = styles.input
-			statusIcon = '🎯'
-		} else if (step.type === 'retry') {
-			typeClass = styles.retry
-			statusIcon = '🔄'
-		} else if (step.type === 'observation') {
-			typeClass = styles.observation
-			statusIcon = '👁️'
-		} else {
-			statusIcon = '🧠'
+		// 1. Task card (always first)
+		const task = this.#agent.task
+		if (task) {
+			items.push(this.#createTaskCard(task))
 		}
 
-		const durationText = step.duration ? ` · ${step.duration}ms` : ''
-		const stepLabel = this.#i18n.t('ui.panel.step', {
-			number: step.stepNumber.toString(),
-			time,
-			duration: durationText || '', // Explicitly pass empty string to replace template
-		})
+		// 2. Render each history event
+		const history = this.#agent.history
+		for (const event of history) {
+			items.push(...this.#createHistoryCards(event))
+		}
 
-		return `
-			<div class="${styles.historyItem} ${typeClass}">
-				<div class="${styles.historyContent}">
-					<span class="${styles.statusIcon}">${statusIcon}</span>
-					<span>${escapeHtml(step.displayText)}</span>
-				</div>
-				<div class="${styles.historyMeta}">
-					${stepLabel}
-				</div>
-			</div>
-		`
+		this.#historySection.innerHTML = items.join('')
+		this.#scrollToBottom()
+	}
+
+	#createTaskCard(task: string): string {
+		return createCard({ icon: '🎯', content: task, type: 'input' })
+	}
+
+	/** Create cards for a history event */
+	#createHistoryCards(event: PanelAgentAdapter['history'][number]): string[] {
+		const cards: string[] = []
+		const time = formatTime(this.#config.language ?? 'en-US')
+		const meta =
+			event.type === 'step' && event.stepIndex !== undefined
+				? this.#i18n.t('ui.panel.step', {
+						number: (event.stepIndex + 1).toString(),
+						time,
+						duration: '',
+					})
+				: time
+
+		if (event.type === 'step') {
+			// Reflection card
+			if (event.reflection) {
+				const lines = createReflectionLines(event.reflection)
+				if (lines.length > 0) {
+					cards.push(createCard({ icon: '🧠', content: lines, meta }))
+				}
+			}
+
+			// Action card
+			const action = event.action
+			if (action) {
+				cards.push(...this.#createActionCards(action, meta))
+			}
+		} else if (event.type === 'observation') {
+			cards.push(
+				createCard({ icon: '👁️', content: event.content || '', meta, type: 'observation' })
+			)
+		} else if (event.type === 'user_takeover') {
+			cards.push(createCard({ icon: '👤', content: 'User takeover', meta, type: 'input' }))
+		} else if (event.type === 'retry') {
+			const retryInfo = `${event.message || 'Retrying'} (${event.attempt}/${event.maxAttempts})`
+			cards.push(createCard({ icon: '🔄', content: retryInfo, meta, type: 'observation' }))
+		} else if (event.type === 'error') {
+			cards.push(
+				createCard({ icon: '❌', content: event.message || 'Error', meta, type: 'observation' })
+			)
+		}
+
+		return cards
+	}
+
+	/** Create cards for an action */
+	#createActionCards(
+		action: { name: string; input: unknown; output: string },
+		meta: string
+	): string[] {
+		const cards: string[] = []
+
+		if (action.name === 'done') {
+			const input = action.input as { text?: string }
+			const text = input.text || action.output || ''
+			if (text) {
+				cards.push(createCard({ icon: '🤖', content: text, meta, type: 'output' }))
+			}
+		} else if (action.name === 'ask_user') {
+			const input = action.input as { question?: string }
+			const answer = action.output.replace(/^User answered:\s*/i, '')
+			cards.push(
+				createCard({
+					icon: '❓',
+					content: `Question: ${input.question || ''}`,
+					meta,
+					type: 'question',
+				})
+			)
+			cards.push(createCard({ icon: '💬', content: `Answer: ${answer}`, meta, type: 'input' }))
+		} else {
+			const toolText = this.#getToolExecutingText(action.name, action.input)
+			cards.push(createCard({ icon: '🔨', content: toolText, meta }))
+			if (action.output?.length > 0) {
+				cards.push(createCard({ icon: '🔨', content: action.output, meta, type: 'output' }))
+			}
+		}
+
+		return cards
 	}
 }

packages/ui/src/panel/cards.ts

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

packages/ui/src/panel/types.ts

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

packages/website/package.json

@@ -1,42 +1,42 @@
 {
-	"name": "@page-agent/website",
-	"private": true,
-	"version": "0.2.4",
-	"type": "module",
-	"scripts": {
-		"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.8",
-		"@types/react-dom": "^19.2.1",
-		"@vitejs/plugin-react-swc": "^4.1.0",
-		"i18next": "^25.7.4",
-		"i18next-browser-languagedetector": "^8.2.0",
-		"react": "^19.2.3",
-		"react-dom": "^19.2.3",
-		"react-i18next": "^16.5.2",
-		"tailwindcss": "^4.1.14",
-		"tw-animate-css": "^1.4.0",
-		"wouter": "^3.9.0"
-	},
-	"dependencies": {
-		"@radix-ui/react-icons": "^1.3.2",
-		"@radix-ui/react-separator": "^1.1.8",
-		"@radix-ui/react-slot": "^1.2.4",
-		"@radix-ui/react-switch": "^1.2.6",
-		"@radix-ui/react-tooltip": "^1.2.8",
-		"class-variance-authority": "^0.7.1",
-		"clsx": "^2.1.1",
-		"lucide-react": "^0.562.0",
-		"motion": "^12.26.1",
-		"next-themes": "^0.4.6",
-		"rough-notation": "^0.5.1",
-		"simple-icons": "^16.5.0",
-		"sonner": "^2.0.7",
-		"tailwind-merge": "^3.4.0"
-	}
+    "name": "@page-agent/website",
+    "private": true,
+    "version": "1.0.0",
+    "type": "module",
+    "scripts": {
+        "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.8",
+        "@types/react-dom": "^19.2.1",
+        "@vitejs/plugin-react-swc": "^4.1.0",
+        "i18next": "^25.7.4",
+        "i18next-browser-languagedetector": "^8.2.0",
+        "react": "^19.2.3",
+        "react-dom": "^19.2.3",
+        "react-i18next": "^16.5.3",
+        "tailwindcss": "^4.1.14",
+        "tw-animate-css": "^1.4.0",
+        "wouter": "^3.9.0"
+    },
+    "dependencies": {
+        "@radix-ui/react-icons": "^1.3.2",
+        "@radix-ui/react-separator": "^1.1.8",
+        "@radix-ui/react-slot": "^1.2.4",
+        "@radix-ui/react-switch": "^1.2.6",
+        "@radix-ui/react-tooltip": "^1.2.8",
+        "class-variance-authority": "^0.7.1",
+        "clsx": "^2.1.1",
+        "lucide-react": "^0.562.0",
+        "motion": "^12.27.1",
+        "next-themes": "^0.4.6",
+        "rough-notation": "^0.5.1",
+        "simple-icons": "^16.6.0",
+        "sonner": "^2.0.7",
+        "tailwind-merge": "^3.4.0"
+    }
 }

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

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

packages/website/src/constants.ts

@@ -1,12 +1,8 @@
 // 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_URL =
+	'https://cdn.jsdelivr.net/npm/page-agent@1.0.0/dist/iife/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'
+	'https://registry.npmmirror.com/page-agent/1.0.0/files/dist/iife/page-agent.demo.js'
 
 // Demo LLM for website testing
 export const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'

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

@@ -24,6 +24,7 @@ export default {
 		introduction: 'Introduction',
 		features: 'Features',
 		integration: 'Integration',
+		advanced: 'Advanced',
 		overview: 'Overview',
 		quick_start: 'Quick Start',
 		limitations: 'Limitations',
@@ -32,9 +33,10 @@ export default {
 		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',
+		page_agent: 'PageAgent',
+		page_agent_core: 'PageAgentCore',
 	},
 }

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

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

packages/website/src/pages/Home.tsx

@@ -89,6 +89,10 @@ export default function HomePage() {
 					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,
 			})
 		}
 

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

@@ -41,7 +41,6 @@ export default function DocsLayout({ children }: DocsLayoutProps) {
 		{
 			title: t('nav.integration'),
 			items: [
-				{ 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' },
 				{
@@ -51,6 +50,13 @@ export default function DocsLayout({ children }: DocsLayoutProps) {
 				{ title: '🚧 ' + t('nav.best_practices'), path: '/integration/best-practices' },
 			],
 		},
+		{
+			title: t('nav.advanced'),
+			items: [
+				{ title: t('nav.page_agent'), path: '/advanced/page-agent' },
+				{ title: t('nav.page_agent_core'), path: '/advanced/page-agent-core' },
+			],
+		},
 	]
 
 	return (

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

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

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

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

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

@@ -3,6 +3,9 @@ import { Route, Switch } from 'wouter'
 
 import Header from '../../components/Header'
 import DocsLayout from './Layout'
+import PageAgentCoreDocs from './advanced/page-agent-core/page'
+// Advanced
+import PageAgentDocs from './advanced/page-agent/page'
 import Instructions from './features/custom-instructions/page'
 // Features
 import CustomTools from './features/custom-tools/page'
@@ -11,7 +14,6 @@ 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'
@@ -83,11 +85,6 @@ export default function DocsRouter() {
 					<SecurityPermissions />
 				</DocsPage>
 			</Route>
-			<Route path="/integration/configuration">
-				<DocsPage>
-					<Configuration />
-				</DocsPage>
-			</Route>
 			<Route path="/integration/best-practices">
 				<DocsPage>
 					<BestPractices />
@@ -99,6 +96,18 @@ export default function DocsRouter() {
 				</DocsPage>
 			</Route>
 
+			{/* Advanced */}
+			<Route path="/advanced/page-agent">
+				<DocsPage>
+					<PageAgentDocs />
+				</DocsPage>
+			</Route>
+			<Route path="/advanced/page-agent-core">
+				<DocsPage>
+					<PageAgentCoreDocs />
+				</DocsPage>
+			</Route>
+
 			{/* Default redirect or 404 */}
 			<Route path="/docs">
 				<DocsPage>

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

@@ -1,7 +1,7 @@
 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'
+import { CDN_DEMO_CN_URL, CDN_DEMO_URL } from '@/constants'
 
 export default function CdnSetup() {
 	const { i18n } = useTranslation()
@@ -63,63 +63,6 @@ export default function CdnSetup() {
 					</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

@@ -1,145 +0,0 @@
-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'
-
-  /** 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>
-		</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 }
   }
 }
 

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

@@ -1,6 +1,5 @@
 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'
 
@@ -28,11 +27,29 @@ export default function QuickStart() {
 						</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>`}
+						code={`<script src="${isZh ? CDN_DEMO_CN_URL : CDN_DEMO_URL}" crossorigin="true"></script>`}
 						language="html"
 					/>
+					<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 ? '镜像' : 'Mirrors'}
+								</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>
 				</div>
 
 				{/* NPM - Recommended */}
@@ -41,7 +58,7 @@ export default function QuickStart() {
 						{isZh ? '📦 NPM 安装（推荐）' : '📦 NPM Install (Recommended)'}
 					</h3>
 					<CodeEditor
-						code={`npm install page-agent
+						code={`// npm install page-agent
 
 import { PageAgent } from 'page-agent'`}
 						language="bash"
@@ -71,7 +88,8 @@ import { PageAgent } from 'page-agent'`}
 						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'}
+// ${isZh ? '或者' : 'Or:'}
+// ${isZh ? '显示对话框让用户输入指令' : 'Show panel for user to input instructions'}
 agent.panel.show()
 `}
 						language="javascript"

packages/website/src/router.tsx

@@ -1,9 +1,10 @@
 import { Suspense, lazy } from 'react'
 import { Route, Switch } from 'wouter'
 
-// Lazy load pages
-const HomePage = lazy(() => import('./pages/Home'))
-const DocsPages = lazy(() => import('./pages/docs/index'))
+import HomePage from './pages/Home'
+import DocsPages from './pages/docs/index'
+
+// const DocsPages = lazy(() => import('./pages/docs/index'))
 
 export default function Router() {
 	return (

packages/website/tsconfig.json

@@ -10,11 +10,12 @@
             // Self root
             "@/*": ["src/*"],
 
-            // Simplified monorepo solution (raw npm workspace with hoisting)
-            "page-agent": ["../page-agent/src/PageAgent.ts"],
             "@page-agent/llms": ["../llms/src/index.ts"],
             "@page-agent/page-controller": ["../page-controller/src/PageController.ts"],
-            "@page-agent/ui": ["../ui/src/index.ts"]
+            "@page-agent/core": ["../core/src/PageAgentCore.ts"],
+            "@page-agent/ui": ["../ui/src/index.ts"],
+
+            "page-agent": ["../page-agent/src/PageAgent.ts"]
         }
     },
     "include": ["**/*.ts", "**/*.tsx"],
@@ -22,8 +23,10 @@
     "references": [
         //
         { "path": "../llms" },
-        { "path": "../page-agent" },
         { "path": "../page-controller" },
-        { "path": "../ui" }
+        { "path": "../core" },
+        { "path": "../ui" },
+
+        { "path": "../page-agent" }
     ]
 }

packages/website/vite.config.js

@@ -36,9 +36,11 @@ export default defineConfig(({ mode }) => ({
 			'@': resolve(__dirname, 'src'),
 
 			// Monorepo packages (always bundle local code instead of npm versions)
-			'@page-agent/llms': resolve(__dirname, '../llms/src/index.ts'),
 			'@page-agent/page-controller': resolve(__dirname, '../page-controller/src/PageController.ts'),
+			'@page-agent/llms': resolve(__dirname, '../llms/src/index.ts'),
+			'@page-agent/core': resolve(__dirname, '../core/src/PageAgentCore.ts'),
 			'@page-agent/ui': resolve(__dirname, '../ui/src/index.ts'),
+
 			'page-agent': resolve(__dirname, '../page-agent/src/PageAgent.ts'),
 		},
 	},

scripts/sync-version.js

@@ -9,6 +9,7 @@
 import chalk from 'chalk'
 import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs'
 import { dirname, join } from 'path'
+import { exit } from 'process'
 import { fileURLToPath } from 'url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -17,17 +18,23 @@ const rootDir = join(__dirname, '..')
 // Parse arguments
 const versionArg = process.argv[2]
 
+if (!versionArg) {
+	console.log(chalk.yellow('⚠️  No version specified.\n'))
+	exit(1)
+}
+
 // Read root package.json
 const rootPkgPath = join(rootDir, 'package.json')
 const rootPkg = JSON.parse(readFileSync(rootPkgPath, 'utf-8'))
-const newVersion = versionArg || rootPkg.version
+const oldVersion = rootPkg.version
+const newVersion = versionArg
 
 console.log(chalk.cyan.bold('\n📦 Syncing version\n'))
 
 // Update root package.json if new version specified
 if (versionArg) {
 	rootPkg.version = newVersion
-	writeFileSync(rootPkgPath, JSON.stringify(rootPkg, null, '\t') + '\n')
+	writeFileSync(rootPkgPath, JSON.stringify(rootPkg, null, '    ') + '\n')
 	console.log(chalk.green('✓') + ` ${chalk.bold('root')} → ${chalk.yellow(newVersion)}`)
 } else {
 	console.log(chalk.dim('  root:') + ` ${chalk.yellow(newVersion)} ${chalk.dim('(source)')}`)
@@ -69,11 +76,10 @@ for (const pkg of packages) {
 	if (!existsSync(pkgPath)) continue
 
 	const pkgJson = JSON.parse(readFileSync(pkgPath, 'utf-8'))
-	const oldVersion = pkgJson.version
 	let pkgChanged = false
 
 	// Update package version
-	if (oldVersion !== newVersion) {
+	if (pkgJson.version !== newVersion) {
 		pkgJson.version = newVersion
 		pkgChanged = true
 	}
@@ -88,7 +94,7 @@ for (const pkg of packages) {
 		continue
 	}
 
-	writeFileSync(pkgPath, JSON.stringify(pkgJson, null, '\t') + '\n')
+	writeFileSync(pkgPath, JSON.stringify(pkgJson, null, '    ') + '\n')
 	console.log(
 		chalk.green('✓') +
 			` ${chalk.bold(pkgJson.name)}: ${chalk.dim(oldVersion)} → ${chalk.yellow(newVersion)}`
@@ -96,6 +102,31 @@ for (const pkg of packages) {
 	hasChanges = true
 }
 
+// Update CDN URLs in documentation and source files
+const CDN_DEMO_URL_OLD = `https://cdn.jsdelivr.net/npm/page-agent@${oldVersion}/dist/iife/page-agent.demo.js`
+const CDN_DEMO_URL_NEW = `https://cdn.jsdelivr.net/npm/page-agent@${newVersion}/dist/iife/page-agent.demo.js`
+const CDN_DEMO_CN_URL_OLD = `https://registry.npmmirror.com/page-agent/${oldVersion}/files/dist/iife/page-agent.demo.js`
+const CDN_DEMO_CN_URL_NEW = `https://registry.npmmirror.com/page-agent/${newVersion}/files/dist/iife/page-agent.demo.js`
+
+const filesToUpdateCdn = ['README.md', 'README-zh.md', 'packages/website/src/constants.ts']
+
+for (const relPath of filesToUpdateCdn) {
+	const filePath = join(rootDir, relPath)
+	if (!existsSync(filePath)) continue
+
+	let content = readFileSync(filePath, 'utf-8')
+	const original = content
+
+	content = content.replaceAll(CDN_DEMO_URL_OLD, CDN_DEMO_URL_NEW)
+	content = content.replaceAll(CDN_DEMO_CN_URL_OLD, CDN_DEMO_CN_URL_NEW)
+
+	if (content !== original) {
+		writeFileSync(filePath, content)
+		console.log(chalk.green('✓') + ` ${chalk.bold(relPath)}: CDN URLs updated`)
+		hasChanges = true
+	}
+}
+
 console.log(chalk.green.bold(`\n✓ Version synced: ${newVersion}\n`))
 
 // Show git commands hint