chore(version): bump version to 0.2.3

BREAKING CHANGES: remove umd build from npm package and cdn

CONTRIBUTING.md

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

LICENSE

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

README-zh.md

@@ -1,8 +1,11 @@
 # PageAgent 🤖🪄
 
-![banner](https://img.alicdn.com/imgextra/i1/O1CN01RY0Wvh26ATVeDIX7v_!!6000000007621-0-tps-1672-512.jpg)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://img.alicdn.com/imgextra/i4/O1CN01qKig1P1FnhpFKNdi6_!!6000000000532-2-tps-1280-256.png">
+  <img alt="Page Agent Banner" src="https://img.alicdn.com/imgextra/i1/O1CN01NCMKXj1Gn4tkFTsxf_!!6000000000666-2-tps-1280-256.png">
+</picture>
 
-[![npm version](https://badge.fury.io/js/page-agent.svg)](https://badge.fury.io/js/page-agent) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) [![Downloads](https://img.shields.io/npm/dt/page-agent.svg)](https://www.npmjs.com/package/page-agent) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/page-agent)](https://bundlephobia.com/package/page-agent) [![GitHub stars](https://img.shields.io/github/stars/alibaba/page-agent.svg)](https://github.com/alibaba/page-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) [![Downloads](https://img.shields.io/npm/dt/page-agent.svg)](https://www.npmjs.com/package/page-agent) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/page-agent)](https://bundlephobia.com/package/page-agent) [![GitHub stars](https://img.shields.io/github/stars/alibaba/page-agent.svg)](https://github.com/alibaba/page-agent)
 
 纯 JS 实现的 GUI agent。使用自然语言操作你的 Web 应用。无须后端、客户端、浏览器插件。
 
@@ -10,7 +13,7 @@
 
 👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a>
 
-<video id="demo-video" src="https://github.com/user-attachments/assets/141bbb01-8022-4d1f-919d-9efc9a1dc1cf" width="640" crossorigin muted autoplay loop></video>
+<video id="demo-video" src="https://github.com/user-attachments/assets/34d8444d-cbfb-44a3-a24e-fd5c167bb0bf" controls crossorigin muted></video>
 
 ---
 
@@ -28,22 +31,25 @@
 
 ## 🚀 快速开始
 
-### 快速体验 (Demo CDN)
+### 快速体验 (With Testing LLM)
 
 最快的体验方式：
 
 ```html
-<script src="https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js" crossorigin="true"></script>
+<script
+	src="https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js"
+	crossorigin="true"
+></script>
 ```
 
 > ⚠️ **仅用于技术评估。** Demo 模型有速率限制和使用限制，生产环境请使用 NPM 方式。
 
-| 位置   | URL                                                                                     |
+| Mirrors | URL                                                                                 |
-| ------ | --------------------------------------------------------------------------------------- |
+| ------- | ----------------------------------------------------------------------------------- |
-| 全球   | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js                    |
+| Global  | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js                |
-| 中国   | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js     |
+| China   | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js |
 
-### NPM 安装（推荐）
+### NPM 安装
 
 ```bash
 npm install page-agent
@@ -62,26 +68,7 @@ const agent = new PageAgent({
 await agent.execute('点击登录按钮')
 ```
 
-### CDN 引入
+适用于无法使用 NPM 的环境，我们也提供了 IIFE 构建的 CDN 方式。[@see CDN Usage](https://alibaba.github.io/page-agent/#/docs/integration/cdn-setup)
-
-适用于无法使用 NPM 的环境，用法与 NPM 一致：
-
-```html
-<script src="https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.js" crossorigin="true"></script>
-<script>
-const agent = new PageAgent({
-	model: 'deepseek-chat',
-	baseURL: 'https://api.deepseek.com',
-	apiKey: 'YOUR_API_KEY',
-})
-await agent.execute('点击登录按钮')
-</script>
-```
-
-| 位置   | URL                                                                                 |
-| ------ | ----------------------------------------------------------------------------------- |
-| 全球   | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.js                     |
-| 中国   | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.js      |
 
 ## 🏗️ 架构设计
 
@@ -101,28 +88,19 @@ packages/
 
 欢迎社区贡献！以下是参与方式：
 
-### 开发环境
+1. Fork 并 clone。`git clone https://github.com/alibaba/page-agent.git && cd page-agent`
+2. 安装依赖: `npm install`
+3. 启动开发: `npm start`
 
-1. Fork 项目仓库
+更多详情请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
-2. Clone or fork: `git clone https://github.com/alibaba/page-agent.git && cd page-agent`
-3. 安装依赖: `npm install`
-4. 启动开发: `npm start`
 
-### 贡献指南
+请在贡献前阅读我们的[行为准则](CODE_OF_CONDUCT.md)。
-
-请在贡献前阅读我们的[行为准则](CODE_OF_CONDUCT.md)和[贡献指南](CONTRIBUTING.md)。
 
 ## 👏 致谢
 
-本项目基于以下优秀项目构建：
+本项目基于 **[`browser-use`](https://github.com/browser-use/browser-use)** 的优秀工作构建。
 
-- **[browser-use](https://github.com/browser-use/browser-use)**
+`PageAgent` 专为**客户端网页增强**设计，不是服务端自动化工具。
-
-PageAgent 专为**客户端网页增强**设计，不是服务端自动化工具。
-
-## 📄 许可证
-
-MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。
 
 ```
 DOM processing components and prompt are derived from browser-use:
@@ -141,6 +119,10 @@ Third-party dependencies and their licenses can be found in the package.json
 file and in the node_modules directory after installation.
 ```
 
+## 📄 许可证
+
+[MIT License](LICENSE)
+
 ---
 
 **⭐ 如果觉得 PageAgent 有用或有趣，请给项目点个星！**

README.md

@@ -1,8 +1,11 @@
 # PageAgent 🤖🪄
 
-![banner](https://img.alicdn.com/imgextra/i3/O1CN01MyVCS21EoKkIHUT1s_!!6000000000398-49-tps-1280-353.webp)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://img.alicdn.com/imgextra/i4/O1CN01qKig1P1FnhpFKNdi6_!!6000000000532-2-tps-1280-256.png">
+  <img alt="Page Agent Banner" src="https://img.alicdn.com/imgextra/i1/O1CN01NCMKXj1Gn4tkFTsxf_!!6000000000666-2-tps-1280-256.png">
+</picture>
 
-[![npm version](https://badge.fury.io/js/page-agent.svg)](https://badge.fury.io/js/page-agent) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) [![Downloads](https://img.shields.io/npm/dt/page-agent.svg)](https://www.npmjs.com/package/page-agent) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/page-agent)](https://bundlephobia.com/package/page-agent) [![GitHub stars](https://img.shields.io/github/stars/alibaba/page-agent.svg)](https://github.com/alibaba/page-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) [![Downloads](https://img.shields.io/npm/dt/page-agent.svg)](https://www.npmjs.com/package/page-agent) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/page-agent)](https://bundlephobia.com/package/page-agent) [![GitHub stars](https://img.shields.io/github/stars/alibaba/page-agent.svg)](https://github.com/alibaba/page-agent)
 
 The GUI Agent Living in Your Webpage. Control web interfaces with natural language.
 
@@ -10,7 +13,7 @@ The GUI Agent Living in Your Webpage. Control web interfaces with natural langua
 
 👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a>
 
-<video id="demo-video" src="https://github.com/user-attachments/assets/de8d1964-8bde-494f-a52f-2975469557a5" width="640" crossorigin muted autoplay loop></video>
+<video id="demo-video" src="https://github.com/user-attachments/assets/34d8444d-cbfb-44a3-a24e-fd5c167bb0bf" controls crossorigin muted></video>
 
 ---
 
@@ -28,22 +31,25 @@ The GUI Agent Living in Your Webpage. Control web interfaces with natural langua
 
 ## 🚀 Quick Start
 
-### Quick Try (Demo CDN)
+### Quick Try (With Testing LLM)
 
 Fastest way to try PageAgent:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js" crossorigin="true"></script>
+<script
+	src="https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js"
+	crossorigin="true"
+></script>
 ```
 
 > ⚠️ **For technical evaluation only.** Demo model has rate limits and usage restrictions. Use NPM for production.
 
-| Location | URL                                                                                     |
+| Mirrors | URL                                                                                 |
-| -------- | --------------------------------------------------------------------------------------- |
+| ------- | ----------------------------------------------------------------------------------- |
-| Global   | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js                    |
+| 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     |
+| China   | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js |
 
-### NPM Installation (Recommended)
+### NPM Installation
 
 ```bash
 npm install page-agent
@@ -62,26 +68,7 @@ const agent = new PageAgent({
 await agent.execute('Click the login button')
 ```
 
-### CDN Build
+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)
-
-For environments where NPM is not available. Usage is identical to NPM:
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.js" 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 login button')
-</script>
-```
-
-| Location | URL                                                                                 |
-| -------- | ----------------------------------------------------------------------------------- |
-| Global   | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.js                     |
-| China    | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.js      |
 
 ## 🏗️ Structure
 
@@ -101,28 +88,19 @@ packages/
 
 We welcome contributions from the community! Here's how to get started:
 
-### Setup
+1. Fork and clone. `git clone https://github.com/alibaba/page-agent.git && cd page-agent`
+2. Install dependencies: `npm install`
+3. Start development: `npm start`
 
-1. Fork the repository
+More details in [CONTRIBUTING.md](CONTRIBUTING.md).
-2. Clone your fork: `git clone https://github.com/alibaba/page-agent.git && cd page-agent`
-3. Install dependencies: `npm install`
-4. Start development: `npm start`
 
-### Contributing Guidelines
+Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
-
-Please read our [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing Guide](CONTRIBUTING.md) before contributing.
 
 ## 👏 Acknowledgments
 
-This project builds upon the excellent work of:
+This project builds upon the excellent work of **[`browser-use`](https://github.com/browser-use/browser-use)**.
 
-- **[browser-use](https://github.com/browser-use/browser-use)**
+`PageAgent` is designed for **client-side web enhancement**, not server-side automation.
-
-PageAgent is designed for **client-side web enhancement**, not server-side automation.
-
-## 📄 License
-
-MIT License - see the [LICENSE](LICENSE) file for details.
 
 ```
 DOM processing components and prompt are derived from browser-use:
@@ -141,6 +119,10 @@ Third-party dependencies and their licenses can be found in the package.json
 file and in the node_modules directory after installation.
 ```
 
+## 📄 License
+
+[MIT License](LICENSE)
+
 ---
 
 **⭐ Star this repo if you find PageAgent helpful!**

package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "root",
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "root",
-			"version": "0.2.1",
+			"version": "0.2.3",
 			"license": "MIT",
 			"workspaces": [
 				"packages/page-controller",
@@ -4613,9 +4613,9 @@
 			}
 		},
 		"node_modules/diff": {
-			"version": "8.0.2",
+			"version": "8.0.3",
-			"resolved": "https://registry.npmjs.org/diff/-/diff-8.0.2.tgz",
+			"resolved": "https://registry.npmjs.org/diff/-/diff-8.0.3.tgz",
-			"integrity": "sha512-sSuxWU5j5SR9QQji/o2qMvqRNYRDOcBTgsJ/DeCf4iSN4gW+gNMXM7wFIP+fdXZxoNiAnHUTGjCr+TSWXdRDKg==",
+			"integrity": "sha512-qejHi7bcSD4hQAZE0tNAawRK1ZtafHDmMTMkrrIGgSLl7hTnQHmKCeB45xAcbfTqK2zowkM3j3bHt/4b/ARbYQ==",
 			"dev": true,
 			"license": "BSD-3-Clause",
 			"engines": {
@@ -8133,15 +8133,15 @@
 		},
 		"packages/cdn": {
 			"name": "@page-agent/cdn",
-			"version": "0.2.1",
+			"version": "0.2.3",
 			"license": "MIT",
 			"dependencies": {
-				"page-agent": "0.2.1"
+				"page-agent": "0.2.3"
 			}
 		},
 		"packages/llms": {
 			"name": "@page-agent/llms",
-			"version": "0.2.1",
+			"version": "0.2.3",
 			"license": "MIT",
 			"dependencies": {
 				"chalk": "^5.6.2",
@@ -8149,19 +8149,19 @@
 			}
 		},
 		"packages/page-agent": {
-			"version": "0.2.1",
+			"version": "0.2.3",
 			"license": "MIT",
 			"dependencies": {
-				"@page-agent/llms": "0.2.1",
+				"@page-agent/llms": "0.2.3",
-				"@page-agent/page-controller": "0.2.1",
+				"@page-agent/page-controller": "0.2.3",
-				"@page-agent/ui": "0.2.1",
+				"@page-agent/ui": "0.2.3",
 				"chalk": "^5.6.2",
 				"zod": "^4.3.5"
 			}
 		},
 		"packages/page-controller": {
 			"name": "@page-agent/page-controller",
-			"version": "0.2.1",
+			"version": "0.2.3",
 			"license": "MIT",
 			"dependencies": {
 				"ai-motion": "^0.4.8"
@@ -8169,12 +8169,12 @@
 		},
 		"packages/ui": {
 			"name": "@page-agent/ui",
-			"version": "0.2.1",
+			"version": "0.2.3",
 			"license": "MIT"
 		},
 		"packages/website": {
 			"name": "@page-agent/website",
-			"version": "0.2.1",
+			"version": "0.2.3",
 			"dependencies": {
 				"@radix-ui/react-icons": "^1.3.2",
 				"@radix-ui/react-separator": "^1.1.8",

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "root",
 	"private": true,
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"type": "module",
 	"workspaces": [
 		"packages/page-controller",
@@ -29,7 +29,7 @@
 		"build:website": "npm run build:website --workspace=@page-agent/website",
 		"build:libs": "npm run build --workspaces --if-present",
 		"build": "npm run build:libs && npm run build:website",
-		"dev:umd": "npm run dev:umd --workspace=page-agent",
+		"dev:iife": "npm run dev:iife --workspace=page-agent",
 		"version": "node scripts/sync-version.js",
 		"lint": "eslint .",
 		"prepare": "husky"

packages/cdn/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@page-agent/cdn",
 	"private": false,
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"type": "module",
 	"files": [
 		"dist/"
@@ -18,6 +18,6 @@
 		"build": "vite build && vite build --mode demo"
 	},
 	"dependencies": {
-		"page-agent": "0.2.1"
+		"page-agent": "0.2.3"
 	}
 }

packages/llms/README.md

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

packages/llms/package.json

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

packages/page-agent/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "page-agent",
 	"private": false,
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"type": "module",
 	"main": "./dist/esm/page-agent.js",
 	"module": "./dist/esm/page-agent.js",
@@ -37,17 +37,16 @@
 	},
 	"homepage": "https://alibaba.github.io/page-agent/",
 	"scripts": {
-		"build": "vite build && vite build --config vite.umd.config.js",
+		"build": "vite build",
-		"serve": "npx serve dist/umd -p 5173",
+		"dev:iife": "concurrently \"vite build --config vite.iife.config.js --watch\" \"npx serve dist/iife -p 5174\"",
-		"dev:umd": "concurrently \"vite build --config vite.umd.config.js --watch\" \"npm run serve\"",
 		"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.1",
+		"@page-agent/llms": "0.2.3",
-		"@page-agent/page-controller": "0.2.1",
+		"@page-agent/page-controller": "0.2.3",
-		"@page-agent/ui": "0.2.1"
+		"@page-agent/ui": "0.2.3"
 	}
 }

packages/page-agent/src/PageAgent.ts

@@ -90,9 +90,6 @@ export interface UserTakeoverEvent {
  */
 export type HistoryEvent = AgentStep | ObservationEvent | UserTakeoverEvent
 
-/** @deprecated Use AgentStep instead */
-export type AgentHistory = AgentStep
-
 export interface ExecutionResult {
 	success: boolean
 	data: string

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

@@ -108,14 +108,14 @@ export interface AgentConfig {
 	 * @note PageAgent will try to detect new pages and decide if it's caused by an action. But not very reliable.
 	 * @todo remove `this` binding, pass agent as explicit parameter instead
 	 */
-	onNewPageOpen?: (this: PageAgent, url: string) => Promise<void> | void
+	// onNewPageOpen?: (this: PageAgent, url: string) => Promise<void> | void
 
 	/**
 	 * TODO: @unimplemented
 	 * try to navigate to a new page instead of opening a new tab/window.
 	 * @note will unload the current page when a action tries to open a new page. so that things keep in the same tab/window.
 	 */
-	experimentalPreventNewPage?: boolean
+	// experimentalPreventNewPage?: boolean
 }
 
 export type PageAgentConfig = LLMConfig & AgentConfig & PageControllerConfig

packages/page-agent/src/iife.ts

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

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

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

packages/page-controller/package.json

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

packages/ui/package.json

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

packages/website/README.md

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

packages/website/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@page-agent/website",
 	"private": true,
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"type": "module",
 	"scripts": {
 		"dev": "vite --host 0.0.0.0",

packages/website/src/components/Header.tsx

@@ -22,7 +22,7 @@ export default function Header() {
 					<div className="flex items-center justify-between gap-2">
 						{/* Logo */}
 						<Link
-							href="/"
+							href="~/"
 							className="flex items-center gap-2 sm:gap-3 group shrink-0"
 							aria-label={t('header.logo_alt')}
 							onClick={() => setMobileMenuOpen(false)}
@@ -55,7 +55,7 @@ export default function Header() {
 							aria-label="Mobile navigation"
 						>
 							<Link
-								href="/docs/introduction/overview"
+								href="~/docs/introduction/overview"
 								className="p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200 shrink-0"
 								aria-label={t('header.nav_docs')}
 							>
@@ -89,7 +89,7 @@ export default function Header() {
 								{import.meta.env.VERSION}
 							</span>
 							<Link
-								href="/docs/introduction/overview"
+								href="~/docs/introduction/overview"
 								className="flex items-center gap-1.5 text-gray-600 dark:text-gray-300 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
 							>
 								<BookOpen className="w-4 h-4" />
@@ -137,7 +137,7 @@ export default function Header() {
 							role="navigation"
 						>
 							<Link
-								href="/docs/introduction/overview"
+								href="~/docs/introduction/overview"
 								className="flex items-center gap-2 px-3 py-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
 								onClick={() => setMobileMenuOpen(false)}
 							>

packages/website/src/pages/Home.tsx

@@ -103,7 +103,7 @@ export default function HomePage() {
 			{/* Hero Section */}
 			<main id="main-content">
 				<section
-					className="relative px-6 py-22 lg:py-28 overflow-hidden"
+					className="relative px-6 py-22 pb-18 lg:py-28 overflow-hidden"
 					aria-labelledby="hero-heading"
 				>
 					<div className="max-w-7xl mx-auto text-center">

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

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

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

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

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

@@ -28,15 +28,17 @@ export default function Configuration() {
 					className="mb-4"
 					language="typescript"
 					code={`interface LLMConfig {
-  baseURL?: string
+  baseURL: string
-  apiKey?: string
+  apiKey: string
-  model?: 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
 }`}
@@ -71,12 +73,12 @@ export default function Configuration() {
     getPageInstructions?: (url: string) => string | undefined | null
   }
 
-  // Lifecycle hooks
+  // Lifecycle hooks (with \`this\` bound to PageAgent instance)
-  onBeforeStep?: (stepCnt: number) => Promise<void> | void
+  onBeforeStep?: (this: PageAgent, stepCnt: number) => Promise<void> | void
-  onAfterStep?: (stepCnt: number, history: AgentHistory[]) => Promise<void> | void
+  onAfterStep?: (this: PageAgent, stepCnt: number, history: HistoryEvent[]) => Promise<void> | void
-  onBeforeTask?: () => Promise<void> | void
+  onBeforeTask?: (this: PageAgent) => Promise<void> | void
-  onAfterTask?: (result: ExecutionResult) => Promise<void> | void
+  onAfterTask?: (this: PageAgent, result: ExecutionResult) => Promise<void> | void
-  onDispose?: (reason?: string) => void
+  onDispose?: (this: PageAgent, reason?: string) => void
 
   /**
    * Transform page content before sending to LLM.
@@ -103,7 +105,7 @@ export default function Configuration() {
 				<CodeEditor
 					className="mb-4"
 					language="typescript"
-					code={`interface PageControllerConfig {
+					code={`interface DomConfig {
   /** Elements to exclude from interaction */
   interactiveBlacklist?: (Element | (() => Element))[]
 
@@ -118,15 +120,13 @@ export default function Configuration() {
 
   /** Highlight label opacity (0-1) */
   highlightLabelOpacity?: number
+}
 
-  /** Viewport expansion in pixels (-1 for full page) */
+interface PageControllerConfig extends DomConfig {
+  /** Viewport expansion in pixels */
   viewportExpansion?: number
 
-  /**
+  /** Enable visual mask overlay during operations (default: false) */
-   * Enable visual mask overlay during automation.
-   * Blocks user interaction while agent is running.
-   * Default: false for PageController, true for PageAgent.
-   */
   enableMask?: boolean
 }`}
 				/>

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

@@ -22,13 +22,6 @@ export default function Overview() {
 
 				{/* Status Badges */}
 				<div className="flex flex-wrap gap-2 items-center">
-					<a
-						href="https://www.npmjs.com/package/page-agent"
-						target="_blank"
-						rel="noopener noreferrer"
-					>
-						<img src="https://badge.fury.io/js/page-agent.svg" alt="npm version" />
-					</a>
 					<a href="https://opensource.org/licenses/MIT" target="_blank" rel="noopener noreferrer">
 						<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License" />
 					</a>

packages/website/src/router.tsx

@@ -1,37 +1,9 @@
 import { Suspense, lazy } from 'react'
 import { Route, Switch } from 'wouter'
 
-import Header from './components/Header'
-import DocsLayout from './pages/docs/Layout'
-
 // Lazy load pages
 const HomePage = lazy(() => import('./pages/Home'))
-// Introduction
+const DocsPages = lazy(() => import('./pages/docs/index'))
-const Overview = lazy(() => import('./pages/docs/introduction/overview/page'))
-const QuickStart = lazy(() => import('./pages/docs/introduction/quick-start/page'))
-const Limitations = lazy(() => import('./pages/docs/introduction/limitations/page'))
-// Features
-const CustomTools = lazy(() => import('./pages/docs/features/custom-tools/page'))
-const DataMasking = lazy(() => import('./pages/docs/features/data-masking/page'))
-const Instructions = lazy(() => import('./pages/docs/features/custom-instructions/page'))
-const Models = lazy(() => import('./pages/docs/features/models/page'))
-// Integration
-const CdnSetup = lazy(() => import('./pages/docs/integration/cdn-setup/page'))
-const SecurityPermissions = lazy(() => import('./pages/docs/integration/security-permissions/page'))
-const Configuration = lazy(() => import('./pages/docs/integration/configuration/page'))
-const BestPractices = lazy(() => import('./pages/docs/integration/best-practices/page'))
-const ThirdPartyAgent = lazy(() => import('./pages/docs/integration/third-party-agent/page'))
-
-function DocsPage({ children }: { children: React.ReactNode }) {
-	return (
-		<div className="min-h-screen bg-white dark:bg-gray-900">
-			<Header />
-			<DocsLayout>
-				<Suspense>{children}</Suspense>
-			</DocsLayout>
-		</div>
-	)
-}
 
 export default function Router() {
 	return (
@@ -42,70 +14,9 @@ export default function Router() {
 					<HomePage />
 				</Route>
 
-				{/* Introduction */}
+				{/* All docs pages */}
-				<Route path="/docs/introduction/overview">
+				<Route path="/docs" nest>
-					<DocsPage>
+					<DocsPages />
-						<Overview />
-					</DocsPage>
-				</Route>
-				<Route path="/docs/introduction/quick-start">
-					<DocsPage>
-						<QuickStart />
-					</DocsPage>
-				</Route>
-				<Route path="/docs/introduction/limitations">
-					<DocsPage>
-						<Limitations />
-					</DocsPage>
-				</Route>
-
-				{/* Features */}
-				<Route path="/docs/features/custom-tools">
-					<DocsPage>
-						<CustomTools />
-					</DocsPage>
-				</Route>
-				<Route path="/docs/features/data-masking">
-					<DocsPage>
-						<DataMasking />
-					</DocsPage>
-				</Route>
-				<Route path="/docs/features/custom-instructions">
-					<DocsPage>
-						<Instructions />
-					</DocsPage>
-				</Route>
-				<Route path="/docs/features/models">
-					<DocsPage>
-						<Models />
-					</DocsPage>
-				</Route>
-
-				{/* Integration */}
-				<Route path="/docs/integration/cdn-setup">
-					<DocsPage>
-						<CdnSetup />
-					</DocsPage>
-				</Route>
-				<Route path="/docs/integration/security-permissions">
-					<DocsPage>
-						<SecurityPermissions />
-					</DocsPage>
-				</Route>
-				<Route path="/docs/integration/configuration">
-					<DocsPage>
-						<Configuration />
-					</DocsPage>
-				</Route>
-				<Route path="/docs/integration/best-practices">
-					<DocsPage>
-						<BestPractices />
-					</DocsPage>
-				</Route>
-				<Route path="/docs/integration/third-party-agent">
-					<DocsPage>
-						<ThirdPartyAgent />
-					</DocsPage>
 				</Route>
 
 				{/* 404 */}

packages/website/vite.config.js

@@ -16,7 +16,7 @@ const pageAgentPkg = JSON.parse(
 dotenvConfig({ path: resolve(__dirname, '../../.env') })
 
 // Website Config (React Documentation Site)
-export default defineConfig({
+export default defineConfig(({ mode }) => ({
 	base: './',
 	clearScreen: false,
 	plugins: [react(), tailwindcss()],
@@ -43,9 +43,11 @@ export default defineConfig({
 		},
 	},
 	define: {
-		'import.meta.env.LLM_MODEL_NAME': JSON.stringify(process.env.LLM_MODEL_NAME),
+		...(mode === 'development' && {
-		'import.meta.env.LLM_API_KEY': JSON.stringify(process.env.LLM_API_KEY),
+			'import.meta.env.LLM_MODEL_NAME': JSON.stringify(process.env.LLM_MODEL_NAME),
-		'import.meta.env.LLM_BASE_URL': JSON.stringify(process.env.LLM_BASE_URL),
+			'import.meta.env.LLM_API_KEY': JSON.stringify(process.env.LLM_API_KEY),
+			'import.meta.env.LLM_BASE_URL': JSON.stringify(process.env.LLM_BASE_URL),
+		}),
 		'import.meta.env.VERSION': JSON.stringify(pageAgentPkg.version),
 	},
-})
+}))