chore(version): bump version to 0.2.2

BREAKING CHANGES: remove umd build from npm package and cdn

.vscode/settings.json

@@ -5,6 +5,7 @@
 		"HITL",
 		"innerhtml",
 		"llms",
+		"onwarn",
 		"opensource",
 		"qwen",
 		"retryable",

AGENTS.md

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

CONTRIBUTING.md

@@ -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

@@ -28,7 +28,22 @@
 
 ## 🚀 快速开始
 
-### NPM 安装
+### 快速体验 (Demo CDN)
+
+最快的体验方式：
+
+```html
+<script src="https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js" crossorigin="true"></script>
+```
+
+> ⚠️ **仅用于技术评估。** Demo 模型有速率限制和使用限制，生产环境请使用 NPM 方式。
+
+| 位置   | URL                                                                                     |
+| ------ | --------------------------------------------------------------------------------------- |
+| 全球   | 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     |
+
+### NPM 安装（推荐）
 
 ```bash
 npm install page-agent
@@ -37,40 +52,37 @@ npm install page-agent
 ```javascript
 import { PageAgent } from 'page-agent'
 
-// 测试接口
-// @note: 限流，限制 prompt 内容，限制来源，随时变更，请替换成你自己的
-// @note: 使用 DeepSeek-chat(3.2) 官方版本，使用协议和隐私策略见 DeepSeek 网站
-const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
 const agent = new PageAgent({
-	model: DEMO_MODEL,
+	model: 'deepseek-chat',
-	baseURL: DEMO_BASE_URL,
+	baseURL: 'https://api.deepseek.com',
-	apiKey: DEMO_API_KEY,
+	apiKey: 'YOUR_API_KEY',
 	language: 'zh-CN',
 })
 
 await agent.execute('点击登录按钮')
 ```
 
-### CDN 集成
+### CDN 引入
 
-Fastest way to try PageAgent is to include it via CDN. Demo model will be used by default.
+适用于无法使用 NPM 的环境，用法与 NPM 一致：
-
-| Location | URL                                                                           |
-| -------- | ----------------------------------------------------------------------------- |
-| Global   | https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js         |
-| China    | https://registry.npmmirror.com/page-agent/latest/files/dist/umd/page-agent.js |
 
 ```html
-<script
+<script src="https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.js" crossorigin="true"></script>
-	src="https://registry.npmmirror.com/page-agent/latest/files/dist/umd/page-agent.js"
+<script>
-	crossorigin="true"
+const agent = new PageAgent({
-	type="text/javascript"
+	model: 'deepseek-chat',
-></script>
+	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      |
+
 ## 🏗️ 架构设计
 
 PageAgent adopts a simplified monorepo structure:
@@ -79,8 +91,9 @@ PageAgent adopts a simplified monorepo structure:
 packages/
 ├── page-agent/          # AI agent (npm: page-agent)
 ├── llms/                # LLM 客户端 (npm: @page-agent/llms)
-├── page-controller/     # DOM 操作 (npm: @page-agent/page-controller)
+├── page-controller/     # DOM 操作 & 蒙层 & 模拟鼠标 (npm: @page-agent/page-controller)
-├── ui/                  # 面板 & 蒙层 & 模拟鼠标 (npm: @page-agent/ui)
+├── ui/                  # 面板 & i18n (npm: @page-agent/ui)
+├── cdn/                 # CDN IIFE builds (npm: @page-agent/cdn)
 └── website/             # 文档站点
 ```
 

README.md

@@ -28,7 +28,22 @@ The GUI Agent Living in Your Webpage. Control web interfaces with natural langua
 
 ## 🚀 Quick Start
 
-### NPM Installation
+### Quick Try (Demo CDN)
+
+Fastest way to try PageAgent:
+
+```html
+<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                                                                                     |
+| -------- | --------------------------------------------------------------------------------------- |
+| Global   | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js                    |
+| China    | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js     |
+
+### NPM Installation (Recommended)
 
 ```bash
 npm install page-agent
@@ -37,40 +52,37 @@ npm install page-agent
 ```javascript
 import { PageAgent } from 'page-agent'
 
-// test server
-// @note: rate limit. prompt limit. Origin limit. May change anytime. Use your own llm!
-// @note Using official DeepSeek-chat(3.2). Go to DeepSeek website for privacy policy.
-const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
 const agent = new PageAgent({
-	model: DEMO_MODEL,
+	model: 'deepseek-chat',
-	baseURL: DEMO_BASE_URL,
+	baseURL: 'https://api.deepseek.com',
-	apiKey: DEMO_API_KEY,
+	apiKey: 'YOUR_API_KEY',
 	language: 'en-US',
 })
 
 await agent.execute('Click the login button')
 ```
 
-### CDN Integration
+### CDN Build
 
-Fastest way to try PageAgent is to include it via CDN. Demo model will be used by default.
+For environments where NPM is not available. Usage is identical to NPM:
-
-| Location | URL                                                                           |
-| -------- | ----------------------------------------------------------------------------- |
-| Global   | https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js         |
-| China    | https://registry.npmmirror.com/page-agent/latest/files/dist/umd/page-agent.js |
 
 ```html
-<script
+<script src="https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.js" crossorigin="true"></script>
-	src="https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js"
+<script>
-	crossorigin="true"
+const agent = new PageAgent({
-	type="text/javascript"
+	model: 'deepseek-chat',
-></script>
+	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
 
 PageAgent adopts a simplified monorepo structure:
@@ -79,8 +91,9 @@ PageAgent adopts a simplified monorepo structure:
 packages/
 ├── page-agent/          # AI agent (npm: page-agent)
 ├── llms/                # LLM client (npm: @page-agent/llms)
-├── page-controller/     # DOM operations (npm: @page-agent/page-controller)
+├── page-controller/     # DOM operations & Visual Mask (npm: @page-agent/page-controller)
-├── ui/                  # Panel & Mask & Mouse Animation (npm: @page-agent/ui)
+├── ui/                  # Panel & i18n (npm: @page-agent/ui)
+├── cdn/                 # CDN IIFE builds (npm: @page-agent/cdn)
 └── website/             # Demo & Documentation site
 ```
 

package-lock.json

@@ -1,43 +1,44 @@
 {
 	"name": "root",
-	"version": "0.0.20",
+	"version": "0.2.2",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "root",
-			"version": "0.0.20",
+			"version": "0.2.2",
 			"license": "MIT",
 			"workspaces": [
 				"packages/page-controller",
 				"packages/ui",
 				"packages/llms",
 				"packages/page-agent",
+				"packages/cdn",
 				"packages/website"
 			],
 			"devDependencies": {
-				"@commitlint/cli": "^20.3.0",
+				"@commitlint/cli": "^20.3.1",
-				"@commitlint/config-conventional": "^20.3.0",
+				"@commitlint/config-conventional": "^20.3.1",
 				"@eslint/js": "^9.39.2",
 				"@microsoft/api-extractor": "^7.55.2",
-				"@trivago/prettier-plugin-sort-imports": "^6.0.1",
+				"@trivago/prettier-plugin-sort-imports": "^6.0.2",
-				"@types/node": "^25.0.3",
+				"@types/node": "^25.0.7",
 				"concurrently": "^9.2.1",
 				"dotenv": "^17.2.3",
 				"eslint": "^9.39.2",
 				"eslint-config-prettier": "^10.1.8",
-				"eslint-plugin-react-dom": "^2.5.1",
+				"eslint-plugin-react-dom": "^2.5.7",
 				"eslint-plugin-react-hooks": "^7.0.1",
 				"eslint-plugin-react-refresh": "^0.4.26",
-				"eslint-plugin-react-x": "^2.5.1",
+				"eslint-plugin-react-x": "^2.5.7",
-				"globals": "^16.4.0",
+				"globals": "^17.0.0",
 				"husky": "^9.1.7",
 				"lint-staged": "^16.2.4",
 				"prettier": "^3.7.4",
 				"typescript": "^5.9.3",
-				"typescript-eslint": "^8.52.0",
+				"typescript-eslint": "^8.53.0",
 				"unplugin-dts": "^1.0.0-beta.6",
-				"vite": "^7.3.0",
+				"vite": "^7.3.1",
 				"vite-plugin-css-injected-by-js": "^3.5.2"
 			},
 			"engines": {
@@ -316,17 +317,17 @@
 			}
 		},
 		"node_modules/@commitlint/cli": {
-			"version": "20.3.0",
+			"version": "20.3.1",
-			"resolved": "https://registry.npmjs.org/@commitlint/cli/-/cli-20.3.0.tgz",
+			"resolved": "https://registry.npmjs.org/@commitlint/cli/-/cli-20.3.1.tgz",
-			"integrity": "sha512-HXO8YVfqdBK+MnlX2zqNrv6waGYPs6Ysjm5W2Y0GMagWXwiIKx7C8dcIX9ca+QdHq4WA0lcMnZLQ0pzQh1piZg==",
+			"integrity": "sha512-NtInjSlyev/+SLPvx/ulz8hRE25Wf5S9dLNDcIwazq0JyB4/w1ROF/5nV0ObPTX8YpRaKYeKtXDYWqumBNHWsw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@commitlint/format": "^20.2.0",
+				"@commitlint/format": "^20.3.1",
-				"@commitlint/lint": "^20.3.0",
+				"@commitlint/lint": "^20.3.1",
-				"@commitlint/load": "^20.3.0",
+				"@commitlint/load": "^20.3.1",
-				"@commitlint/read": "^20.2.0",
+				"@commitlint/read": "^20.3.1",
-				"@commitlint/types": "^20.2.0",
+				"@commitlint/types": "^20.3.1",
 				"tinyexec": "^1.0.0",
 				"yargs": "^17.0.0"
 			},
@@ -338,13 +339,13 @@
 			}
 		},
 		"node_modules/@commitlint/config-conventional": {
-			"version": "20.3.0",
+			"version": "20.3.1",
-			"resolved": "https://registry.npmjs.org/@commitlint/config-conventional/-/config-conventional-20.3.0.tgz",
+			"resolved": "https://registry.npmjs.org/@commitlint/config-conventional/-/config-conventional-20.3.1.tgz",
-			"integrity": "sha512-g1OXVl6E2v0xF1Ru2RpxQ+Vfy7XUcUsCmLKzGUrhFLS4hSNykje0QSy6djBtzOiOBQCepBrmIlqx/gRlzrSh5A==",
+			"integrity": "sha512-NCzwvxepstBZbmVXsvg49s+shCxlJDJPWxXqONVcAtJH9wWrOlkMQw/zyl+dJmt8lyVopt5mwQ3mR5M2N2rUWg==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@commitlint/types": "^20.2.0",
+				"@commitlint/types": "^20.3.1",
 				"conventional-changelog-conventionalcommits": "^7.0.2"
 			},
 			"engines": {
@@ -352,13 +353,13 @@
 			}
 		},
 		"node_modules/@commitlint/config-validator": {
-			"version": "20.2.0",
+			"version": "20.3.1",
-			"resolved": "https://registry.npmjs.org/@commitlint/config-validator/-/config-validator-20.2.0.tgz",
+			"resolved": "https://registry.npmjs.org/@commitlint/config-validator/-/config-validator-20.3.1.tgz",
-			"integrity": "sha512-SQCBGsL9MFk8utWNSthdxd9iOD1pIVZSHxGBwYIGfd67RTjxqzFOSAYeQVXOu3IxRC3YrTOH37ThnTLjUlyF2w==",
+			"integrity": "sha512-ErVLC/IsHhcvxCyh+FXo7jy12/nkQySjWXYgCoQbZLkFp4hysov8KS6CdxBB0cWjbZWjvNOKBMNoUVqkmGmahw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@commitlint/types": "^20.2.0",
+				"@commitlint/types": "^20.3.1",
 				"ajv": "^8.11.0"
 			},
 			"engines": {
@@ -366,13 +367,13 @@
 			}
 		},
 		"node_modules/@commitlint/ensure": {
-			"version": "20.2.0",
+			"version": "20.3.1",
-			"resolved": "https://registry.npmjs.org/@commitlint/ensure/-/ensure-20.2.0.tgz",
+			"resolved": "https://registry.npmjs.org/@commitlint/ensure/-/ensure-20.3.1.tgz",
-			"integrity": "sha512-+8TgIGv89rOWyt3eC6lcR1H7hqChAKkpawytlq9P1i/HYugFRVqgoKJ8dhd89fMnlrQTLjA5E97/4sF09QwdoA==",
+			"integrity": "sha512-h664FngOEd7bHAm0j8MEKq+qm2mH+V+hwJiIE2bWcw3pzJMlO0TPKtk0ATyRAtV6jQw+xviRYiIjjSjfajiB5w==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@commitlint/types": "^20.2.0",
+				"@commitlint/types": "^20.3.1",
 				"lodash.camelcase": "^4.3.0",
 				"lodash.kebabcase": "^4.1.1",
 				"lodash.snakecase": "^4.1.1",
@@ -394,13 +395,13 @@
 			}
 		},
 		"node_modules/@commitlint/format": {
-			"version": "20.2.0",
+			"version": "20.3.1",
-			"resolved": "https://registry.npmjs.org/@commitlint/format/-/format-20.2.0.tgz",
+			"resolved": "https://registry.npmjs.org/@commitlint/format/-/format-20.3.1.tgz",
-			"integrity": "sha512-PhNoLNhxpfIBlW/i90uZ3yG3hwSSYx7n4d9Yc+2FAorAHS0D9btYRK4ZZXX+Gm3W5tDtu911ow/eWRfcRVgNWg==",
+			"integrity": "sha512-jfsjGPFTd2Yti2YHwUH4SPRPbWKAJAwrfa3eNa9bXEdrXBb9mCwbIrgYX38LdEJK9zLJ3AsLBP4/FLEtxyu2AA==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@commitlint/types": "^20.2.0",
+				"@commitlint/types": "^20.3.1",
 				"chalk": "^5.3.0"
 			},
 			"engines": {
@@ -408,13 +409,13 @@
 			}
 		},
 		"node_modules/@commitlint/is-ignored": {
-			"version": "20.2.0",
+			"version": "20.3.1",
-			"resolved": "https://registry.npmjs.org/@commitlint/is-ignored/-/is-ignored-20.2.0.tgz",
+			"resolved": "https://registry.npmjs.org/@commitlint/is-ignored/-/is-ignored-20.3.1.tgz",
-			"integrity": "sha512-Lz0OGeZCo/QHUDLx5LmZc0EocwanneYJUM8z0bfWexArk62HKMLfLIodwXuKTO5y0s6ddXaTexrYHs7v96EOmw==",
+			"integrity": "sha512-tWwAoh93QvAhxgp99CzCuHD86MgxE4NBtloKX+XxQxhfhSwHo7eloiar/yzx53YW9eqSLP95zgW2KDDk4/WX+A==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@commitlint/types": "^20.2.0",
+				"@commitlint/types": "^20.3.1",
 				"semver": "^7.6.0"
 			},
 			"engines": {
@@ -422,32 +423,32 @@
 			}
 		},
 		"node_modules/@commitlint/lint": {
-			"version": "20.3.0",
+			"version": "20.3.1",
-			"resolved": "https://registry.npmjs.org/@commitlint/lint/-/lint-20.3.0.tgz",
+			"resolved": "https://registry.npmjs.org/@commitlint/lint/-/lint-20.3.1.tgz",
-			"integrity": "sha512-X19HOGU5nRo6i9DIY0kG0mhgtvpn1UGO1D6aLX1ILLyeqSM5yJyMcrRqNj8SLgeSeUDODhLY9QYsBIG0LdNHkA==",
+			"integrity": "sha512-LaOtrQ24+6SfUaWg8A+a+Wc77bvLbO5RIr6iy9F7CI3/0iq1uPEWgGRCwqWTuLGHkZDAcwaq0gZ01zpwZ1jCGw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@commitlint/is-ignored": "^20.2.0",
+				"@commitlint/is-ignored": "^20.3.1",
-				"@commitlint/parse": "^20.2.0",
+				"@commitlint/parse": "^20.3.1",
-				"@commitlint/rules": "^20.3.0",
+				"@commitlint/rules": "^20.3.1",
-				"@commitlint/types": "^20.2.0"
+				"@commitlint/types": "^20.3.1"
 			},
 			"engines": {
 				"node": ">=v18"
 			}
 		},
 		"node_modules/@commitlint/load": {
-			"version": "20.3.0",
+			"version": "20.3.1",
-			"resolved": "https://registry.npmjs.org/@commitlint/load/-/load-20.3.0.tgz",
+			"resolved": "https://registry.npmjs.org/@commitlint/load/-/load-20.3.1.tgz",
-			"integrity": "sha512-amkdVZTXp5R65bsRXRSCwoNXbJHR2aAIY/RGFkoyd63t8UEwqEgT3f0MgeLqYw4hwXyq+TYXKdaW133E29pnGQ==",
+			"integrity": "sha512-YDD9XA2XhgYgbjju8itZ/weIvOOobApDqwlPYCX5NLO/cPtw2UMO5Cmn44Ks8RQULUVI5fUT6roKvyxcoLbNmw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@commitlint/config-validator": "^20.2.0",
+				"@commitlint/config-validator": "^20.3.1",
 				"@commitlint/execute-rule": "^20.0.0",
-				"@commitlint/resolve-extends": "^20.2.0",
+				"@commitlint/resolve-extends": "^20.3.1",
-				"@commitlint/types": "^20.2.0",
+				"@commitlint/types": "^20.3.1",
 				"chalk": "^5.3.0",
 				"cosmiconfig": "^9.0.0",
 				"cosmiconfig-typescript-loader": "^6.1.0",
@@ -470,13 +471,13 @@
 			}
 		},
 		"node_modules/@commitlint/parse": {
-			"version": "20.2.0",
+			"version": "20.3.1",
-			"resolved": "https://registry.npmjs.org/@commitlint/parse/-/parse-20.2.0.tgz",
+			"resolved": "https://registry.npmjs.org/@commitlint/parse/-/parse-20.3.1.tgz",
-			"integrity": "sha512-LXStagGU1ivh07X7sM+hnEr4BvzFYn1iBJ6DRg2QsIN8lBfSzyvkUcVCDwok9Ia4PWiEgei5HQjju6xfJ1YaSQ==",
+			"integrity": "sha512-TuUTdbLpyUNLgDzLDYlI2BeTE6V/COZbf3f8WwsV0K6eq/2nSpNTMw7wHtXb+YxeY9wwxBp/Ldad4P+YIxHJoA==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@commitlint/types": "^20.2.0",
+				"@commitlint/types": "^20.3.1",
 				"conventional-changelog-angular": "^7.0.0",
 				"conventional-commits-parser": "^5.0.0"
 			},
@@ -485,14 +486,14 @@
 			}
 		},
 		"node_modules/@commitlint/read": {
-			"version": "20.2.0",
+			"version": "20.3.1",
-			"resolved": "https://registry.npmjs.org/@commitlint/read/-/read-20.2.0.tgz",
+			"resolved": "https://registry.npmjs.org/@commitlint/read/-/read-20.3.1.tgz",
-			"integrity": "sha512-+SjF9mxm5JCbe+8grOpXCXMMRzAnE0WWijhhtasdrpJoAFJYd5UgRTj/oCq5W3HJTwbvTOsijEJ0SUGImECD7Q==",
+			"integrity": "sha512-nCmJAdIg3OdNVUpQW0Idk/eF/vfOo2W2xzmvRmNeptLrzFK7qhwwl/kIwy1Q1LZrKHUFNj7PGNpIT5INbgZWzA==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
 				"@commitlint/top-level": "^20.0.0",
-				"@commitlint/types": "^20.2.0",
+				"@commitlint/types": "^20.3.1",
 				"git-raw-commits": "^4.0.0",
 				"minimist": "^1.2.8",
 				"tinyexec": "^1.0.0"
@@ -502,14 +503,14 @@
 			}
 		},
 		"node_modules/@commitlint/resolve-extends": {
-			"version": "20.2.0",
+			"version": "20.3.1",
-			"resolved": "https://registry.npmjs.org/@commitlint/resolve-extends/-/resolve-extends-20.2.0.tgz",
+			"resolved": "https://registry.npmjs.org/@commitlint/resolve-extends/-/resolve-extends-20.3.1.tgz",
-			"integrity": "sha512-KVoLDi9BEuqeq+G0wRABn4azLRiCC22/YHR2aCquwx6bzCHAIN8hMt3Nuf1VFxq/c8ai6s8qBxE8+ZD4HeFTlQ==",
+			"integrity": "sha512-iGTGeyaoDyHDEZNjD8rKeosjSNs8zYanmuowY4ful7kFI0dnY4b5QilVYaFQJ6IM27S57LAeH5sKSsOHy4bw5w==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@commitlint/config-validator": "^20.2.0",
+				"@commitlint/config-validator": "^20.3.1",
-				"@commitlint/types": "^20.2.0",
+				"@commitlint/types": "^20.3.1",
 				"global-directory": "^4.0.1",
 				"import-meta-resolve": "^4.0.0",
 				"lodash.mergewith": "^4.6.2",
@@ -520,16 +521,16 @@
 			}
 		},
 		"node_modules/@commitlint/rules": {
-			"version": "20.3.0",
+			"version": "20.3.1",
-			"resolved": "https://registry.npmjs.org/@commitlint/rules/-/rules-20.3.0.tgz",
+			"resolved": "https://registry.npmjs.org/@commitlint/rules/-/rules-20.3.1.tgz",
-			"integrity": "sha512-TGgXN/qBEhbzVD13crE1l7YSMJRrbPbUL0OBZALbUM5ER36RZmiZRu2ud2W/AA7HO9YLBRbyx6YVi2t/2Be0yQ==",
+			"integrity": "sha512-/uic4P+4jVNpqQxz02+Y6vvIC0A2J899DBztA1j6q3f3MOKwydlNrojSh0dQmGDxxT1bXByiRtDhgFnOFnM6Pg==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@commitlint/ensure": "^20.2.0",
+				"@commitlint/ensure": "^20.3.1",
 				"@commitlint/message": "^20.0.0",
 				"@commitlint/to-lines": "^20.0.0",
-				"@commitlint/types": "^20.2.0"
+				"@commitlint/types": "^20.3.1"
 			},
 			"engines": {
 				"node": ">=v18"
@@ -559,9 +560,9 @@
 			}
 		},
 		"node_modules/@commitlint/types": {
-			"version": "20.2.0",
+			"version": "20.3.1",
-			"resolved": "https://registry.npmjs.org/@commitlint/types/-/types-20.2.0.tgz",
+			"resolved": "https://registry.npmjs.org/@commitlint/types/-/types-20.3.1.tgz",
-			"integrity": "sha512-KTy0OqRDLR5y/zZMnizyx09z/rPlPC/zKhYgH8o/q6PuAjoQAKlRfY4zzv0M64yybQ//6//4H1n14pxaLZfUnA==",
+			"integrity": "sha512-VmIFV/JkBRhDRRv7N5B7zEUkNZIx9Mp+8Pe65erz0rKycXLsi8Epcw0XJ+btSeRXgTzE7DyOyA9bkJ9mn/yqVQ==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
@@ -1057,16 +1058,16 @@
 			}
 		},
 		"node_modules/@eslint-react/ast": {
-			"version": "2.5.1",
+			"version": "2.5.7",
-			"resolved": "https://registry.npmjs.org/@eslint-react/ast/-/ast-2.5.1.tgz",
+			"resolved": "https://registry.npmjs.org/@eslint-react/ast/-/ast-2.5.7.tgz",
-			"integrity": "sha512-l+pEb3kS/RhFN+8ZOhL5+P5+Yj7iw+ta7+abUBNH+5PMyiixlnAJlJ7Wy+rsTGxjUJtzEff3CzSr06V7qwJuwQ==",
+			"integrity": "sha512-yQvKvyIzo9DPKFUOtFSEfpX0He763G1jFf/LQcIY9xoSOWP9pQ2X8ADNE6ZnmIc0L5zZLQ9nF/H0+MGh2NF3fA==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@eslint-react/eff": "2.5.1",
+				"@eslint-react/eff": "2.5.7",
-				"@typescript-eslint/types": "^8.51.0",
+				"@typescript-eslint/types": "^8.53.0",
-				"@typescript-eslint/typescript-estree": "^8.51.0",
+				"@typescript-eslint/typescript-estree": "^8.53.0",
-				"@typescript-eslint/utils": "^8.51.0",
+				"@typescript-eslint/utils": "^8.53.0",
 				"string-ts": "^2.3.1"
 			},
 			"engines": {
@@ -1078,19 +1079,19 @@
 			}
 		},
 		"node_modules/@eslint-react/core": {
-			"version": "2.5.1",
+			"version": "2.5.7",
-			"resolved": "https://registry.npmjs.org/@eslint-react/core/-/core-2.5.1.tgz",
+			"resolved": "https://registry.npmjs.org/@eslint-react/core/-/core-2.5.7.tgz",
-			"integrity": "sha512-48YQYhjHga0TAv7FI0uGGT+X3SITec89fJLKSTqIEa7jTLpXTV56B+B/V/IcfZ0s8I0lNVEmtHFTXaibAxmfyw==",
+			"integrity": "sha512-LqY4YV4Z/uiymdy2OLXkjsEVnoDjoFsxJZI4GWsZ9aBgGWYAsuoKKUG0bdMLp1U9jwMaY0OY9bYgBB5R1ANkoQ==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@eslint-react/ast": "2.5.1",
+				"@eslint-react/ast": "2.5.7",
-				"@eslint-react/eff": "2.5.1",
+				"@eslint-react/eff": "2.5.7",
-				"@eslint-react/shared": "2.5.1",
+				"@eslint-react/shared": "2.5.7",
-				"@eslint-react/var": "2.5.1",
+				"@eslint-react/var": "2.5.7",
-				"@typescript-eslint/scope-manager": "^8.51.0",
+				"@typescript-eslint/scope-manager": "^8.53.0",
-				"@typescript-eslint/types": "^8.51.0",
+				"@typescript-eslint/types": "^8.53.0",
-				"@typescript-eslint/utils": "^8.51.0",
+				"@typescript-eslint/utils": "^8.53.0",
 				"birecord": "^0.1.1",
 				"ts-pattern": "^5.9.0"
 			},
@@ -1103,9 +1104,9 @@
 			}
 		},
 		"node_modules/@eslint-react/eff": {
-			"version": "2.5.1",
+			"version": "2.5.7",
-			"resolved": "https://registry.npmjs.org/@eslint-react/eff/-/eff-2.5.1.tgz",
+			"resolved": "https://registry.npmjs.org/@eslint-react/eff/-/eff-2.5.7.tgz",
-			"integrity": "sha512-henDz7sTB67Q+YPb+Kiy0UpD7eHLvDtB2nOrRtHLTatS/LFr7wVr4J2muQPkPzY9KFF8pv811nrwW58FuDphPg==",
+			"integrity": "sha512-oxd8eP+dykyOUmQUEItnOZhitlKyo9yFq8Ne0k9+CJeV0Pk1db1+lNcDWswWYoeb1IFEloqHo6y63fVxQXvJew==",
 			"dev": true,
 			"license": "MIT",
 			"engines": {
@@ -1113,14 +1114,14 @@
 			}
 		},
 		"node_modules/@eslint-react/shared": {
-			"version": "2.5.1",
+			"version": "2.5.7",
-			"resolved": "https://registry.npmjs.org/@eslint-react/shared/-/shared-2.5.1.tgz",
+			"resolved": "https://registry.npmjs.org/@eslint-react/shared/-/shared-2.5.7.tgz",
-			"integrity": "sha512-JSTnpZdBu57ZvrJkBwUZXgkBW8iPiQfSiQMYHEjVFR2NHWFgcOd9qYJLX7mJLrdcw/j+GgRQeOAGok0a0xcxGA==",
+			"integrity": "sha512-ZjKO3rNDoLN2ZTn3PxmMcgoASPNiL3umK1BHQvYwCXqqnXlLEouu7sxK6htOvDu1NC+Dbwsqpu4JGUY7t0XQTw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@eslint-react/eff": "2.5.1",
+				"@eslint-react/eff": "2.5.7",
-				"@typescript-eslint/utils": "^8.51.0",
+				"@typescript-eslint/utils": "^8.53.0",
 				"ts-pattern": "^5.9.0",
 				"zod": "^4.3.5"
 			},
@@ -1133,17 +1134,17 @@
 			}
 		},
 		"node_modules/@eslint-react/var": {
-			"version": "2.5.1",
+			"version": "2.5.7",
-			"resolved": "https://registry.npmjs.org/@eslint-react/var/-/var-2.5.1.tgz",
+			"resolved": "https://registry.npmjs.org/@eslint-react/var/-/var-2.5.7.tgz",
-			"integrity": "sha512-O3rbdK8pHKZ4NYPD39Zq7zhWu76dvhyeroqG8nQzf667F/FdHGpGhsCPJOeIU5L/ooYO/3/Qz2vJD1pB5JeROQ==",
+			"integrity": "sha512-VWoyZENbK+OV70s/sE9E6T4HD0WO6lsg2CnYjjpKBKBDOBW67SRdIlM7dUPKzqQKsj6p4yNh59eQ5iKaH82LLg==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@eslint-react/ast": "2.5.1",
+				"@eslint-react/ast": "2.5.7",
-				"@eslint-react/eff": "2.5.1",
+				"@eslint-react/eff": "2.5.7",
-				"@typescript-eslint/scope-manager": "^8.51.0",
+				"@typescript-eslint/scope-manager": "^8.53.0",
-				"@typescript-eslint/types": "^8.51.0",
+				"@typescript-eslint/types": "^8.53.0",
-				"@typescript-eslint/utils": "^8.51.0",
+				"@typescript-eslint/utils": "^8.53.0",
 				"ts-pattern": "^5.9.0"
 			},
 			"engines": {
@@ -1539,20 +1540,6 @@
 				"node": ">=10"
 			}
 		},
-		"node_modules/@microsoft/api-extractor/node_modules/typescript": {
-			"version": "5.8.2",
-			"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.8.2.tgz",
-			"integrity": "sha512-aJn6wq13/afZp/jT9QZmwEjDqqvSGp1VT5GVg+f/t6/oVyrgXM6BY1h9BRh/O5p3PlUPAe+WuiEZOmb/49RqoQ==",
-			"dev": true,
-			"license": "Apache-2.0",
-			"bin": {
-				"tsc": "bin/tsc",
-				"tsserver": "bin/tsserver"
-			},
-			"engines": {
-				"node": ">=14.17"
-			}
-		},
 		"node_modules/@microsoft/api-extractor/node_modules/yallist": {
 			"version": "4.0.0",
 			"resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
@@ -1597,6 +1584,10 @@
 				"url": "https://github.com/sponsors/epoberezkin"
 			}
 		},
+		"node_modules/@page-agent/cdn": {
+			"resolved": "packages/cdn",
+			"link": true
+		},
 		"node_modules/@page-agent/llms": {
 			"resolved": "packages/llms",
 			"link": true
@@ -3458,9 +3449,9 @@
 			}
 		},
 		"node_modules/@trivago/prettier-plugin-sort-imports": {
-			"version": "6.0.1",
+			"version": "6.0.2",
-			"resolved": "https://registry.npmjs.org/@trivago/prettier-plugin-sort-imports/-/prettier-plugin-sort-imports-6.0.1.tgz",
+			"resolved": "https://registry.npmjs.org/@trivago/prettier-plugin-sort-imports/-/prettier-plugin-sort-imports-6.0.2.tgz",
-			"integrity": "sha512-6B13DCWDfAfh4AEJ43gRgeCSAQmlKG5LHqHzHc0lbUwgBy0rX7o41US+46Fd4XiXBx+JDGEz3NBadCbUls0dUQ==",
+			"integrity": "sha512-3DgfkukFyC/sE/VuYjaUUWoFfuVjPK55vOFDsxD56XXynFMCZDYFogH2l/hDfOsQAm1myoU/1xByJ3tWqtulXA==",
 			"dev": true,
 			"license": "Apache-2.0",
 			"dependencies": {
@@ -3556,9 +3547,9 @@
 			"license": "MIT"
 		},
 		"node_modules/@types/node": {
-			"version": "25.0.3",
+			"version": "25.0.7",
-			"resolved": "https://registry.npmjs.org/@types/node/-/node-25.0.3.tgz",
+			"resolved": "https://registry.npmjs.org/@types/node/-/node-25.0.7.tgz",
-			"integrity": "sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA==",
+			"integrity": "sha512-C/er7DlIZgRJO7WtTdYovjIFzGsz0I95UlMyR9anTb4aCpBSRWe5Jc1/RvLKUfzmOxHPGjSE5+63HgLtndxU4w==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
@@ -3566,9 +3557,9 @@
 			}
 		},
 		"node_modules/@types/react": {
-			"version": "19.2.7",
+			"version": "19.2.8",
-			"resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.7.tgz",
+			"resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.8.tgz",
-			"integrity": "sha512-MWtvHrGZLFttgeEj28VXHxpmwYbor/ATPYbBfSFZEIRK0ecCFLl2Qo55z52Hss+UV9CRN7trSeq1zbgx7YDWWg==",
+			"integrity": "sha512-3MbSL37jEchWZz2p2mjntRZtPt837ij10ApxKfgmXCTuHWagYg7iA5bqPw6C8BMPfwidlvfPI/fxOc42HLhcyg==",
 			"devOptional": true,
 			"license": "MIT",
 			"dependencies": {
@@ -3586,17 +3577,17 @@
 			}
 		},
 		"node_modules/@typescript-eslint/eslint-plugin": {
-			"version": "8.52.0",
+			"version": "8.53.0",
-			"resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.52.0.tgz",
+			"resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.53.0.tgz",
-			"integrity": "sha512-okqtOgqu2qmZJ5iN4TWlgfF171dZmx2FzdOv2K/ixL2LZWDStL8+JgQerI2sa8eAEfoydG9+0V96m7V+P8yE1Q==",
+			"integrity": "sha512-eEXsVvLPu8Z4PkFibtuFJLJOTAV/nPdgtSjkGoPpddpFk3/ym2oy97jynY6ic2m6+nc5M8SE1e9v/mHKsulcJg==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
 				"@eslint-community/regexpp": "^4.12.2",
-				"@typescript-eslint/scope-manager": "8.52.0",
+				"@typescript-eslint/scope-manager": "8.53.0",
-				"@typescript-eslint/type-utils": "8.52.0",
+				"@typescript-eslint/type-utils": "8.53.0",
-				"@typescript-eslint/utils": "8.52.0",
+				"@typescript-eslint/utils": "8.53.0",
-				"@typescript-eslint/visitor-keys": "8.52.0",
+				"@typescript-eslint/visitor-keys": "8.53.0",
 				"ignore": "^7.0.5",
 				"natural-compare": "^1.4.0",
 				"ts-api-utils": "^2.4.0"
@@ -3609,7 +3600,7 @@
 				"url": "https://opencollective.com/typescript-eslint"
 			},
 			"peerDependencies": {
-				"@typescript-eslint/parser": "^8.52.0",
+				"@typescript-eslint/parser": "^8.53.0",
 				"eslint": "^8.57.0 || ^9.0.0",
 				"typescript": ">=4.8.4 <6.0.0"
 			}
@@ -3625,16 +3616,16 @@
 			}
 		},
 		"node_modules/@typescript-eslint/parser": {
-			"version": "8.52.0",
+			"version": "8.53.0",
-			"resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.52.0.tgz",
+			"resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.53.0.tgz",
-			"integrity": "sha512-iIACsx8pxRnguSYhHiMn2PvhvfpopO9FXHyn1mG5txZIsAaB6F0KwbFnUQN3KCiG3Jcuad/Cao2FAs1Wp7vAyg==",
+			"integrity": "sha512-npiaib8XzbjtzS2N4HlqPvlpxpmZ14FjSJrteZpPxGUaYPlvhzlzUZ4mZyABo0EFrOWnvyd0Xxroq//hKhtAWg==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@typescript-eslint/scope-manager": "8.52.0",
+				"@typescript-eslint/scope-manager": "8.53.0",
-				"@typescript-eslint/types": "8.52.0",
+				"@typescript-eslint/types": "8.53.0",
-				"@typescript-eslint/typescript-estree": "8.52.0",
+				"@typescript-eslint/typescript-estree": "8.53.0",
-				"@typescript-eslint/visitor-keys": "8.52.0",
+				"@typescript-eslint/visitor-keys": "8.53.0",
 				"debug": "^4.4.3"
 			},
 			"engines": {
@@ -3650,14 +3641,14 @@
 			}
 		},
 		"node_modules/@typescript-eslint/project-service": {
-			"version": "8.52.0",
+			"version": "8.53.0",
-			"resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.52.0.tgz",
+			"resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.53.0.tgz",
-			"integrity": "sha512-xD0MfdSdEmeFa3OmVqonHi+Cciab96ls1UhIF/qX/O/gPu5KXD0bY9lu33jj04fjzrXHcuvjBcBC+D3SNSadaw==",
+			"integrity": "sha512-Bl6Gdr7NqkqIP5yP9z1JU///Nmes4Eose6L1HwpuVHwScgDPPuEWbUVhvlZmb8hy0vX9syLk5EGNL700WcBlbg==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@typescript-eslint/tsconfig-utils": "^8.52.0",
+				"@typescript-eslint/tsconfig-utils": "^8.53.0",
-				"@typescript-eslint/types": "^8.52.0",
+				"@typescript-eslint/types": "^8.53.0",
 				"debug": "^4.4.3"
 			},
 			"engines": {
@@ -3672,14 +3663,14 @@
 			}
 		},
 		"node_modules/@typescript-eslint/scope-manager": {
-			"version": "8.52.0",
+			"version": "8.53.0",
-			"resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.52.0.tgz",
+			"resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.53.0.tgz",
-			"integrity": "sha512-ixxqmmCcc1Nf8S0mS0TkJ/3LKcC8mruYJPOU6Ia2F/zUUR4pApW7LzrpU3JmtePbRUTes9bEqRc1Gg4iyRnDzA==",
+			"integrity": "sha512-kWNj3l01eOGSdVBnfAF2K1BTh06WS0Yet6JUgb9Cmkqaz3Jlu0fdVUjj9UI8gPidBWSMqDIglmEXifSgDT/D0g==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@typescript-eslint/types": "8.52.0",
+				"@typescript-eslint/types": "8.53.0",
-				"@typescript-eslint/visitor-keys": "8.52.0"
+				"@typescript-eslint/visitor-keys": "8.53.0"
 			},
 			"engines": {
 				"node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@@ -3690,9 +3681,9 @@
 			}
 		},
 		"node_modules/@typescript-eslint/tsconfig-utils": {
-			"version": "8.52.0",
+			"version": "8.53.0",
-			"resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.52.0.tgz",
+			"resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.53.0.tgz",
-			"integrity": "sha512-jl+8fzr/SdzdxWJznq5nvoI7qn2tNYV/ZBAEcaFMVXf+K6jmXvAFrgo/+5rxgnL152f//pDEAYAhhBAZGrVfwg==",
+			"integrity": "sha512-K6Sc0R5GIG6dNoPdOooQ+KtvT5KCKAvTcY8h2rIuul19vxH5OTQk7ArKkd4yTzkw66WnNY0kPPzzcmWA+XRmiA==",
 			"dev": true,
 			"license": "MIT",
 			"engines": {
@@ -3707,15 +3698,15 @@
 			}
 		},
 		"node_modules/@typescript-eslint/type-utils": {
-			"version": "8.52.0",
+			"version": "8.53.0",
-			"resolved": "https://registry.npmjs.org/@typescript-eslint/type-utils/-/type-utils-8.52.0.tgz",
+			"resolved": "https://registry.npmjs.org/@typescript-eslint/type-utils/-/type-utils-8.53.0.tgz",
-			"integrity": "sha512-JD3wKBRWglYRQkAtsyGz1AewDu3mTc7NtRjR/ceTyGoPqmdS5oCdx/oZMWD5Zuqmo6/MpsYs0wp6axNt88/2EQ==",
+			"integrity": "sha512-BBAUhlx7g4SmcLhn8cnbxoxtmS7hcq39xKCgiutL3oNx1TaIp+cny51s8ewnKMpVUKQUGb41RAUWZ9kxYdovuw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@typescript-eslint/types": "8.52.0",
+				"@typescript-eslint/types": "8.53.0",
-				"@typescript-eslint/typescript-estree": "8.52.0",
+				"@typescript-eslint/typescript-estree": "8.53.0",
-				"@typescript-eslint/utils": "8.52.0",
+				"@typescript-eslint/utils": "8.53.0",
 				"debug": "^4.4.3",
 				"ts-api-utils": "^2.4.0"
 			},
@@ -3732,9 +3723,9 @@
 			}
 		},
 		"node_modules/@typescript-eslint/types": {
-			"version": "8.52.0",
+			"version": "8.53.0",
-			"resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.52.0.tgz",
+			"resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.53.0.tgz",
-			"integrity": "sha512-LWQV1V4q9V4cT4H5JCIx3481iIFxH1UkVk+ZkGGAV1ZGcjGI9IoFOfg3O6ywz8QqCDEp7Inlg6kovMofsNRaGg==",
+			"integrity": "sha512-Bmh9KX31Vlxa13+PqPvt4RzKRN1XORYSLlAE+sO1i28NkisGbTtSLFVB3l7PWdHtR3E0mVMuC7JilWJ99m2HxQ==",
 			"dev": true,
 			"license": "MIT",
 			"engines": {
@@ -3746,16 +3737,16 @@
 			}
 		},
 		"node_modules/@typescript-eslint/typescript-estree": {
-			"version": "8.52.0",
+			"version": "8.53.0",
-			"resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.52.0.tgz",
+			"resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.53.0.tgz",
-			"integrity": "sha512-XP3LClsCc0FsTK5/frGjolyADTh3QmsLp6nKd476xNI9CsSsLnmn4f0jrzNoAulmxlmNIpeXuHYeEQv61Q6qeQ==",
+			"integrity": "sha512-pw0c0Gdo7Z4xOG987u3nJ8akL9093yEEKv8QTJ+Bhkghj1xyj8cgPaavlr9rq8h7+s6plUJ4QJYw2gCZodqmGw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@typescript-eslint/project-service": "8.52.0",
+				"@typescript-eslint/project-service": "8.53.0",
-				"@typescript-eslint/tsconfig-utils": "8.52.0",
+				"@typescript-eslint/tsconfig-utils": "8.53.0",
-				"@typescript-eslint/types": "8.52.0",
+				"@typescript-eslint/types": "8.53.0",
-				"@typescript-eslint/visitor-keys": "8.52.0",
+				"@typescript-eslint/visitor-keys": "8.53.0",
 				"debug": "^4.4.3",
 				"minimatch": "^9.0.5",
 				"semver": "^7.7.3",
@@ -3800,16 +3791,16 @@
 			}
 		},
 		"node_modules/@typescript-eslint/utils": {
-			"version": "8.52.0",
+			"version": "8.53.0",
-			"resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-8.52.0.tgz",
+			"resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-8.53.0.tgz",
-			"integrity": "sha512-wYndVMWkweqHpEpwPhwqE2lnD2DxC6WVLupU/DOt/0/v+/+iQbbzO3jOHjmBMnhu0DgLULvOaU4h4pwHYi2oRQ==",
+			"integrity": "sha512-XDY4mXTez3Z1iRDI5mbRhH4DFSt46oaIFsLg+Zn97+sYrXACziXSQcSelMybnVZ5pa1P6xYkPr5cMJyunM1ZDA==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
 				"@eslint-community/eslint-utils": "^4.9.1",
-				"@typescript-eslint/scope-manager": "8.52.0",
+				"@typescript-eslint/scope-manager": "8.53.0",
-				"@typescript-eslint/types": "8.52.0",
+				"@typescript-eslint/types": "8.53.0",
-				"@typescript-eslint/typescript-estree": "8.52.0"
+				"@typescript-eslint/typescript-estree": "8.53.0"
 			},
 			"engines": {
 				"node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@@ -3824,13 +3815,13 @@
 			}
 		},
 		"node_modules/@typescript-eslint/visitor-keys": {
-			"version": "8.52.0",
+			"version": "8.53.0",
-			"resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.52.0.tgz",
+			"resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.53.0.tgz",
-			"integrity": "sha512-ink3/Zofus34nmBsPjow63FP5M7IGff0RKAgqR6+CFpdk22M7aLwC9gOcLGYqr7MczLPzZVERW9hRog3O4n1sQ==",
+			"integrity": "sha512-LZ2NqIHFhvFwxG0qZeLL9DvdNAHPGCY5dIRwBhyYeU+LfLhcStE1ImjsuTG/WaVh3XysGaeLW8Rqq7cGkPCFvw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@typescript-eslint/types": "8.52.0",
+				"@typescript-eslint/types": "8.53.0",
 				"eslint-visitor-keys": "^4.2.1"
 			},
 			"engines": {
@@ -3911,9 +3902,9 @@
 			}
 		},
 		"node_modules/ai-motion": {
-			"version": "0.4.7",
+			"version": "0.4.8",
-			"resolved": "https://registry.npmjs.org/ai-motion/-/ai-motion-0.4.7.tgz",
+			"resolved": "https://registry.npmjs.org/ai-motion/-/ai-motion-0.4.8.tgz",
-			"integrity": "sha512-yuFtVgWeaxKyvfSFocA01Mr4UbRvwwy7HWZ6Mq9NM/yccAkqp3UCGdWX6AflNB8cU27PgwTBiMRfx6C9di7xkQ==",
+			"integrity": "sha512-9nQVjf8lrYQWSW0sZdb9bES4x8Ei1w9C0S62po2KvRbMjslmjm0WMeszyW771SEauDnu4YGWqurLZ/gCkCTosQ==",
 			"license": "MIT"
 		},
 		"node_modules/ajv": {
@@ -4622,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": {
@@ -4860,20 +4851,20 @@
 			}
 		},
 		"node_modules/eslint-plugin-react-dom": {
-			"version": "2.5.1",
+			"version": "2.5.7",
-			"resolved": "https://registry.npmjs.org/eslint-plugin-react-dom/-/eslint-plugin-react-dom-2.5.1.tgz",
+			"resolved": "https://registry.npmjs.org/eslint-plugin-react-dom/-/eslint-plugin-react-dom-2.5.7.tgz",
-			"integrity": "sha512-7x3k0bQwtTOSxjReH11buYL6aSMopBzSaWr2bU/LPOuy1dDxvqE6HC2Y6QPEyZjLJ1ppUSKwRmcX85uiF0jHAA==",
+			"integrity": "sha512-KHCU7KRXeLYlrrXKtInpCqHzt+nYhIGpYIuMM4Q0FyGBOcswRS2Gv9PhN+yQqDI9PRBhnjCuRf+q2Y3ZrYWjsw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@eslint-react/ast": "2.5.1",
+				"@eslint-react/ast": "2.5.7",
-				"@eslint-react/core": "2.5.1",
+				"@eslint-react/core": "2.5.7",
-				"@eslint-react/eff": "2.5.1",
+				"@eslint-react/eff": "2.5.7",
-				"@eslint-react/shared": "2.5.1",
+				"@eslint-react/shared": "2.5.7",
-				"@eslint-react/var": "2.5.1",
+				"@eslint-react/var": "2.5.7",
-				"@typescript-eslint/scope-manager": "^8.51.0",
+				"@typescript-eslint/scope-manager": "^8.53.0",
-				"@typescript-eslint/types": "^8.51.0",
+				"@typescript-eslint/types": "^8.53.0",
-				"@typescript-eslint/utils": "^8.51.0",
+				"@typescript-eslint/utils": "^8.53.0",
 				"compare-versions": "^6.1.1",
 				"string-ts": "^2.3.1",
 				"ts-pattern": "^5.9.0"
@@ -4917,21 +4908,21 @@
 			}
 		},
 		"node_modules/eslint-plugin-react-x": {
-			"version": "2.5.1",
+			"version": "2.5.7",
-			"resolved": "https://registry.npmjs.org/eslint-plugin-react-x/-/eslint-plugin-react-x-2.5.1.tgz",
+			"resolved": "https://registry.npmjs.org/eslint-plugin-react-x/-/eslint-plugin-react-x-2.5.7.tgz",
-			"integrity": "sha512-w3KtEG8M7sFRh/psUmep3H+i2O/5Nn9wI8GXjlqzwp8zLb4ax66Ue+1oecLTzY/0j/M1xRfB3hzk5oio54RwLA==",
+			"integrity": "sha512-EU+h7eUHNg9ikLaGOa0Tjsc/o4FO2KdyT3M97TkQmaKc9tzpcy8nlPQp/czBMbUuxAgbj2495wzOvCZ0fEK4mw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@eslint-react/ast": "2.5.1",
+				"@eslint-react/ast": "2.5.7",
-				"@eslint-react/core": "2.5.1",
+				"@eslint-react/core": "2.5.7",
-				"@eslint-react/eff": "2.5.1",
+				"@eslint-react/eff": "2.5.7",
-				"@eslint-react/shared": "2.5.1",
+				"@eslint-react/shared": "2.5.7",
-				"@eslint-react/var": "2.5.1",
+				"@eslint-react/var": "2.5.7",
-				"@typescript-eslint/scope-manager": "^8.51.0",
+				"@typescript-eslint/scope-manager": "^8.53.0",
-				"@typescript-eslint/type-utils": "^8.51.0",
+				"@typescript-eslint/type-utils": "^8.53.0",
-				"@typescript-eslint/types": "^8.51.0",
+				"@typescript-eslint/types": "^8.53.0",
-				"@typescript-eslint/utils": "^8.51.0",
+				"@typescript-eslint/utils": "^8.53.0",
 				"compare-versions": "^6.1.1",
 				"is-immutable-type": "^5.0.1",
 				"string-ts": "^2.3.1",
@@ -5310,13 +5301,13 @@
 			"license": "ISC"
 		},
 		"node_modules/framer-motion": {
-			"version": "12.24.0",
+			"version": "12.26.1",
-			"resolved": "https://registry.npmjs.org/framer-motion/-/framer-motion-12.24.0.tgz",
+			"resolved": "https://registry.npmjs.org/framer-motion/-/framer-motion-12.26.1.tgz",
-			"integrity": "sha512-ggTMRkIDPc76lHmM+dRT1MmVfFV6t/y+jkWjWuzR7FG5xRvnAAl/5wFPjzSkLE8Nu5E5uIQRCNxmIXtWJVo6XQ==",
+			"integrity": "sha512-Uzc8wGldU4FpmGotthjjcj0SZhigcODjqvKT7lzVZHsmYkzQMFfMIv0vHQoXCeoe/Ahxqp4by4A6QbzFA/lblw==",
 			"license": "MIT",
 			"dependencies": {
-				"motion-dom": "^12.24.0",
+				"motion-dom": "^12.24.11",
-				"motion-utils": "^12.23.28",
+				"motion-utils": "^12.24.10",
 				"tslib": "^2.4.0"
 			},
 			"peerDependencies": {
@@ -5457,9 +5448,9 @@
 			}
 		},
 		"node_modules/globals": {
-			"version": "16.5.0",
+			"version": "17.0.0",
-			"resolved": "https://registry.npmjs.org/globals/-/globals-16.5.0.tgz",
+			"resolved": "https://registry.npmjs.org/globals/-/globals-17.0.0.tgz",
-			"integrity": "sha512-c/c15i26VrJ4IRt5Z89DnIzCGDn9EcebibhAOjw5ibqEHsE1wLUgkPn9RDmNcUKyU87GeaL633nyJ+pplFR2ZQ==",
+			"integrity": "sha512-gv5BeD2EssA793rlFWVPMMCqefTlpusw6/2TbAVMy0FzcG8wKJn4O+NqJ4+XWmmwrayJgw5TzrmWjFgmz1XPqw==",
 			"dev": true,
 			"license": "MIT",
 			"engines": {
@@ -5543,9 +5534,9 @@
 			}
 		},
 		"node_modules/i18next": {
-			"version": "25.7.3",
+			"version": "25.7.4",
-			"resolved": "https://registry.npmjs.org/i18next/-/i18next-25.7.3.tgz",
+			"resolved": "https://registry.npmjs.org/i18next/-/i18next-25.7.4.tgz",
-			"integrity": "sha512-2XaT+HpYGuc2uTExq9TVRhLsso+Dxym6PWaKpn36wfBmTI779OQ7iP/XaZHzrnGyzU4SHpFrTYLKfVyBfAhVNA==",
+			"integrity": "sha512-hRkpEblXXcXSNbw8mBNq9042OEetgyB/ahc/X17uV/khPwzV+uB8RHceHh3qavyrkPJvmXFKXME2Sy1E0KjAfw==",
 			"dev": true,
 			"funding": [
 				{
@@ -6523,12 +6514,12 @@
 			}
 		},
 		"node_modules/motion": {
-			"version": "12.24.0",
+			"version": "12.26.1",
-			"resolved": "https://registry.npmjs.org/motion/-/motion-12.24.0.tgz",
+			"resolved": "https://registry.npmjs.org/motion/-/motion-12.26.1.tgz",
-			"integrity": "sha512-FAnpl/DhCFct3p+T2hCjAY95w+3EggUk3b8Ql4jQ6mmdRbEaGD1000goqWeEYVoD7mqx9H0As9ORmRADD4LQAw==",
+			"integrity": "sha512-IVhzx9HOQTiJ9ykthMOlZPnLwrkXziN5Q/yebsqBYlFJb2rHP8yhmKc8O/YUT9byPJlxOeqkzfNYCrVKZx8vqg==",
 			"license": "MIT",
 			"dependencies": {
-				"framer-motion": "^12.24.0",
+				"framer-motion": "^12.26.1",
 				"tslib": "^2.4.0"
 			},
 			"peerDependencies": {
@@ -6549,18 +6540,18 @@
 			}
 		},
 		"node_modules/motion-dom": {
-			"version": "12.24.0",
+			"version": "12.24.11",
-			"resolved": "https://registry.npmjs.org/motion-dom/-/motion-dom-12.24.0.tgz",
+			"resolved": "https://registry.npmjs.org/motion-dom/-/motion-dom-12.24.11.tgz",
-			"integrity": "sha512-RD2kZkFd/GH4fITI8IJvypGgn0vIu5vkrJaXIAkYqORGs5P0CKDHKNvswmoY1H+tbUAOPSh6VtUqoAmc/3Gvig==",
+			"integrity": "sha512-DlWOmsXMJrV8lzZyd+LKjG2CXULUs++bkq8GZ2Sr0R0RRhs30K2wtY+LKiTjhmJU3W61HK+rB0GLz6XmPvTA1A==",
 			"license": "MIT",
 			"dependencies": {
-				"motion-utils": "^12.23.28"
+				"motion-utils": "^12.24.10"
 			}
 		},
 		"node_modules/motion-utils": {
-			"version": "12.23.28",
+			"version": "12.24.10",
-			"resolved": "https://registry.npmjs.org/motion-utils/-/motion-utils-12.23.28.tgz",
+			"resolved": "https://registry.npmjs.org/motion-utils/-/motion-utils-12.24.10.tgz",
-			"integrity": "sha512-0W6cWd5Okoyf8jmessVK3spOmbyE0yTdNKujHctHH9XdAE4QDuZ1/LjSXC68rrhsJU+TkzXURC5OdSWh9ibOwQ==",
+			"integrity": "sha512-x5TFgkCIP4pPsRLpKoI86jv/q8t8FQOiM/0E8QKBzfMozWHfkKap2gA1hOki+B5g3IsBNpxbUnfOum1+dgvYww==",
 			"license": "MIT"
 		},
 		"node_modules/ms": {
@@ -6935,9 +6926,9 @@
 			}
 		},
 		"node_modules/react-i18next": {
-			"version": "16.5.1",
+			"version": "16.5.2",
-			"resolved": "https://registry.npmjs.org/react-i18next/-/react-i18next-16.5.1.tgz",
+			"resolved": "https://registry.npmjs.org/react-i18next/-/react-i18next-16.5.2.tgz",
-			"integrity": "sha512-Hks6UIRZWW4c+qDAnx1csVsCGYeIR4MoBGQgJ+NUoNnO6qLxXuf8zu0xdcinyXUORgGzCdRsexxO1Xzv3sTdnw==",
+			"integrity": "sha512-GG/SBVxx9dvrO1uCs8VYdKfOP8NEBUhNP+2VDQLCifRJ8DL1qPq296k2ACNGyZMDe7iyIlz/LMJTQOs8HXSRvw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
@@ -7174,9 +7165,9 @@
 			}
 		},
 		"node_modules/simple-icons": {
-			"version": "16.4.0",
+			"version": "16.5.0",
-			"resolved": "https://registry.npmjs.org/simple-icons/-/simple-icons-16.4.0.tgz",
+			"resolved": "https://registry.npmjs.org/simple-icons/-/simple-icons-16.5.0.tgz",
-			"integrity": "sha512-8CKtCvx1Zq3L0CBsR4RR1MjGCXkXbzdspwl2yCxs8oWkstbzj2+DatRKDee/tuj3Ffd/2CDzwEky9RgG2yggew==",
+			"integrity": "sha512-72nn0oHADKx6Hknu7q6M0vfL8LiCUMKABOHane2+4xdqaFBSHfNNBjuZioihiqVQMz7IvVle4NKAM0IlXvl/9A==",
 			"funding": [
 				{
 					"type": "opencollective",
@@ -7577,16 +7568,16 @@
 			}
 		},
 		"node_modules/typescript-eslint": {
-			"version": "8.52.0",
+			"version": "8.53.0",
-			"resolved": "https://registry.npmjs.org/typescript-eslint/-/typescript-eslint-8.52.0.tgz",
+			"resolved": "https://registry.npmjs.org/typescript-eslint/-/typescript-eslint-8.53.0.tgz",
-			"integrity": "sha512-atlQQJ2YkO4pfTVQmQ+wvYQwexPDOIgo+RaVcD7gHgzy/IQA+XTyuxNM9M9TVXvttkF7koBHmcwisKdOAf2EcA==",
+			"integrity": "sha512-xHURCQNxZ1dsWn0sdOaOfCSQG0HKeqSj9OexIxrz6ypU6wHYOdX2I3D2b8s8wFSsSOYJb+6q283cLiLlkEsBYw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@typescript-eslint/eslint-plugin": "8.52.0",
+				"@typescript-eslint/eslint-plugin": "8.53.0",
-				"@typescript-eslint/parser": "8.52.0",
+				"@typescript-eslint/parser": "8.53.0",
-				"@typescript-eslint/typescript-estree": "8.52.0",
+				"@typescript-eslint/typescript-estree": "8.53.0",
-				"@typescript-eslint/utils": "8.52.0"
+				"@typescript-eslint/utils": "8.53.0"
 			},
 			"engines": {
 				"node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@@ -7772,9 +7763,9 @@
 			}
 		},
 		"node_modules/vite": {
-			"version": "7.3.0",
+			"version": "7.3.1",
-			"resolved": "https://registry.npmjs.org/vite/-/vite-7.3.0.tgz",
+			"resolved": "https://registry.npmjs.org/vite/-/vite-7.3.1.tgz",
-			"integrity": "sha512-dZwN5L1VlUBewiP6H9s2+B3e3Jg96D0vzN+Ry73sOefebhYr9f94wwkMNN/9ouoU8pV1BqA1d1zGk8928cx0rg==",
+			"integrity": "sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
@@ -8140,9 +8131,17 @@
 				"zod": "^3.25.0 || ^4.0.0"
 			}
 		},
+		"packages/cdn": {
+			"name": "@page-agent/cdn",
+			"version": "0.2.2",
+			"license": "MIT",
+			"dependencies": {
+				"page-agent": "0.2.2"
+			}
+		},
 		"packages/llms": {
 			"name": "@page-agent/llms",
-			"version": "0.0.20",
+			"version": "0.2.2",
 			"license": "MIT",
 			"dependencies": {
 				"chalk": "^5.6.2",
@@ -8150,32 +8149,32 @@
 			}
 		},
 		"packages/page-agent": {
-			"version": "0.0.20",
+			"version": "0.2.2",
 			"license": "MIT",
 			"dependencies": {
-				"@page-agent/llms": "0.0.20",
+				"@page-agent/llms": "0.2.2",
-				"@page-agent/page-controller": "0.0.20",
+				"@page-agent/page-controller": "0.2.2",
-				"@page-agent/ui": "0.0.20",
+				"@page-agent/ui": "0.2.2",
 				"chalk": "^5.6.2",
 				"zod": "^4.3.5"
 			}
 		},
 		"packages/page-controller": {
 			"name": "@page-agent/page-controller",
-			"version": "0.0.20",
+			"version": "0.2.2",
-			"license": "MIT"
+			"license": "MIT",
+			"dependencies": {
+				"ai-motion": "^0.4.8"
+			}
 		},
 		"packages/ui": {
 			"name": "@page-agent/ui",
-			"version": "0.0.20",
+			"version": "0.2.2",
-			"license": "MIT",
+			"license": "MIT"
-			"dependencies": {
-				"ai-motion": "^0.4.7"
-			}
 		},
 		"packages/website": {
 			"name": "@page-agent/website",
-			"version": "0.0.20",
+			"version": "0.2.2",
 			"dependencies": {
 				"@radix-ui/react-icons": "^1.3.2",
 				"@radix-ui/react-separator": "^1.1.8",
@@ -8185,23 +8184,23 @@
 				"class-variance-authority": "^0.7.1",
 				"clsx": "^2.1.1",
 				"lucide-react": "^0.562.0",
-				"motion": "^12.24.0",
+				"motion": "^12.26.1",
 				"next-themes": "^0.4.6",
 				"rough-notation": "^0.5.1",
-				"simple-icons": "^16.4.0",
+				"simple-icons": "^16.5.0",
 				"sonner": "^2.0.7",
 				"tailwind-merge": "^3.4.0"
 			},
 			"devDependencies": {
 				"@tailwindcss/vite": "^4.1.18",
-				"@types/react": "^19.2.2",
+				"@types/react": "^19.2.8",
 				"@types/react-dom": "^19.2.1",
 				"@vitejs/plugin-react-swc": "^4.1.0",
-				"i18next": "^25.7.3",
+				"i18next": "^25.7.4",
 				"i18next-browser-languagedetector": "^8.2.0",
 				"react": "^19.2.3",
 				"react-dom": "^19.2.3",
-				"react-i18next": "^16.5.1",
+				"react-i18next": "^16.5.2",
 				"tailwindcss": "^4.1.14",
 				"tw-animate-css": "^1.4.0",
 				"wouter": "^3.9.0"

package.json

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

packages/cdn/package.json

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

packages/cdn/src/demo.js

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

packages/cdn/src/full.js

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

packages/cdn/vite.config.js

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

packages/llms/package.json

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

packages/llms/src/OpenAIClient.ts

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

packages/llms/src/OpenAILenientClient.ts

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

packages/llms/src/constants.ts

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

packages/llms/src/index.ts

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

packages/llms/src/types.ts

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

packages/llms/src/utils.ts

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

packages/llms/vite.config.js

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

packages/page-agent/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "page-agent",
 	"private": false,
-	"version": "0.0.20",
+	"version": "0.2.2",
 	"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.0.20",
+		"@page-agent/llms": "0.2.2",
-		"@page-agent/page-controller": "0.0.20",
+		"@page-agent/page-controller": "0.2.2",
-		"@page-agent/ui": "0.0.20"
+		"@page-agent/ui": "0.2.2"
 	}
 }

packages/page-agent/src/PageAgent.ts

@@ -2,15 +2,9 @@
  * Copyright (C) 2025 Alibaba Group Holding Limited
  * All rights reserved.
  */
-import {
+import { LLM, type Tool } from '@page-agent/llms'
-	type AgentBrain,
-	LLM,
-	type MacroToolInput,
-	type MacroToolResult,
-	type Tool,
-} from '@page-agent/llms'
 import { PageController } from '@page-agent/page-controller'
-import { Panel, SimulatorMask } from '@page-agent/ui'
+import { Panel } from '@page-agent/ui'
 import chalk from 'chalk'
 import zod from 'zod'
 
@@ -18,15 +12,50 @@ import type { PageAgentConfig } from './config'
 import { MAX_STEPS } from './config/constants'
 import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
 import { tools } from './tools'
-import { trimLines, uid, waitUntil } from './utils'
+import { normalizeResponse, trimLines, uid } from './utils'
 import { assert } from './utils/assert'
 
+/**
+ * Agent reflection state - the reflection-before-action model
+ *
+ * Every tool call must first reflect on:
+ * - evaluation_previous_goal: How well did the previous action achieve its goal?
+ * - memory: Key information to remember for future steps
+ * - next_goal: What should be accomplished in the next action?
+ */
+export interface AgentReflection {
+	evaluation_previous_goal: string
+	memory: string
+	next_goal: string
+}
+
+/**
+ * MacroTool input structure
+ *
+ * This is the core abstraction that enforces the "reflection-before-action" mental model.
+ * Before executing any action, the LLM must output its reasoning state.
+ */
+export interface MacroToolInput extends Partial<AgentReflection> {
+	action: Record<string, any>
+}
+
+/**
+ * MacroTool output structure
+ */
+export interface MacroToolResult {
+	input: MacroToolInput
+	output: string
+}
+
 export type { PageAgentConfig }
 export { tool, type PageAgentTool } from './tools'
-export type { AgentBrain, MacroToolInput, MacroToolResult }
 
-export interface AgentHistory {
+/**
-	brain: AgentBrain
+ * A single agent step with reflection and action
+ */
+export interface AgentStep {
+	type: 'step'
+	reflection: Partial<AgentReflection>
 	action: {
 		name: string
 		input: any
@@ -41,10 +70,33 @@ export interface AgentHistory {
 	}
 }
 
+/**
+ * Persistent observation event (stays in memory)
+ */
+export interface ObservationEvent {
+	type: 'observation'
+	content: string
+}
+
+/**
+ * User takeover event
+ */
+export interface UserTakeoverEvent {
+	type: 'user_takeover'
+}
+
+/**
+ * Union type for all history events
+ */
+export type HistoryEvent = AgentStep | ObservationEvent | UserTakeoverEvent
+
+/** @deprecated Use AgentStep instead */
+export type AgentHistory = AgentStep
+
 export interface ExecutionResult {
 	success: boolean
 	data: string
-	history: AgentHistory[]
+	history: HistoryEvent[]
 }
 
 export class PageAgent extends EventTarget {
@@ -52,13 +104,11 @@ export class PageAgent extends EventTarget {
 	id = uid()
 	panel: Panel
 	tools: typeof tools
-	paused = false
 	disposed = false
 	task = ''
 	taskId = ''
 
 	#llm: LLM
-	#totalWaitTime = 0
 	#abortController = new AbortController()
 	#llmRetryListener: ((e: Event) => void) | null = null
 	#llmErrorListener: ((e: Event) => void) | null = null
@@ -67,12 +117,18 @@ export class PageAgent extends EventTarget {
 	/** PageController for DOM operations */
 	pageController: PageController
 
-	/** Fullscreen mask */
+	/** Runtime states for tracking across steps */
-	mask = new SimulatorMask()
+	states = {
-	/** History records */
+		/** Accumulated wait time in seconds, used by wait tool */
-	history: AgentHistory[] = []
+		totalWaitTime: 0,
+		/** Last known URL for detecting navigation */
+		lastURL: '',
+	}
 
-	constructor(config: PageAgentConfig = {}) {
+	/** History event stream */
+	history: HistoryEvent[] = []
+
+	constructor(config: PageAgentConfig) {
 		super()
 
 		this.config = config
@@ -81,16 +137,14 @@ export class PageAgent extends EventTarget {
 			language: this.config.language,
 			onExecuteTask: (task) => this.execute(task),
 			onStop: () => this.dispose(),
-			onPauseToggle: () => {
-				this.paused = !this.paused
-				return this.paused
-			},
-			getPaused: () => this.paused,
 		})
 		this.tools = new Map(tools)
 
-		// Initialize PageController with config
+		// Initialize PageController with config (mask enabled by default)
-		this.pageController = new PageController(this.config)
+		this.pageController = new PageController({
+			...this.config,
+			enableMask: this.config.enableMask ?? true,
+		})
 
 		// Listen to LLM events
 		this.#llmRetryListener = (e) => {
@@ -125,8 +179,14 @@ export class PageAgent extends EventTarget {
 	}
 
 	/**
-	 * @todo maybe return something?
+	 * Push a persistent observation to the history event stream.
+	 * This will be visible in <agent_history> and remain in memory across steps.
 	 */
+	pushObservation(content: string): void {
+		this.history.push({ type: 'observation', content })
+		this.panel.update({ type: 'observation', content })
+	}
+
 	async execute(task: string): Promise<ExecutionResult> {
 		if (!task) throw new Error('Task is required')
 		this.task = task
@@ -140,7 +200,7 @@ export class PageAgent extends EventTarget {
 		await onBeforeTask.call(this)
 
 		// Show mask and panel
-		this.mask.show()
+		this.pageController.showMask()
 
 		this.panel.show()
 		this.panel.reset()
@@ -154,18 +214,24 @@ export class PageAgent extends EventTarget {
 
 		this.history = []
 
+		// Reset states
+		this.states = {
+			totalWaitTime: 0,
+			lastURL: '',
+		}
+
 		try {
 			let step = 0
 
 			while (true) {
+				await this.#generateObservations(step)
+
 				await onBeforeStep.call(this, step)
 
 				console.group(`step: ${step}`)
 
 				// abort
 				if (this.#abortController.signal.aborted) throw new Error('AbortError')
-				// pause
-				await waitUntil(() => !this.paused)
 
 				// Update status to thinking
 				console.log(chalk.blue('Thinking...'))
@@ -183,29 +249,34 @@ export class PageAgent extends EventTarget {
 						},
 					],
 					{ AgentOutput: this.#packMacroTool() },
-					this.#abortController.signal
+					this.#abortController.signal,
+					{
+						toolChoiceName: 'AgentOutput',
+						normalizeResponse,
+					}
 				)
 
 				const macroResult = result.toolResult as MacroToolResult
 				const input = macroResult.input
 				const output = macroResult.output
-				const brain = {
+				const reflection: Partial<AgentReflection> = {
-					evaluation_previous_goal: input.evaluation_previous_goal || '',
+					evaluation_previous_goal: input.evaluation_previous_goal,
-					memory: input.memory || '',
+					memory: input.memory,
-					next_goal: input.next_goal || '',
+					next_goal: input.next_goal,
 				}
 				const actionName = Object.keys(input.action)[0]
-				const action = {
+				const action: AgentStep['action'] = {
 					name: actionName,
 					input: input.action[actionName],
 					output: output,
 				}
 
 				this.history.push({
-					brain,
+					type: 'step',
+					reflection,
 					action,
 					usage: result.usage,
-				})
+				} as AgentStep)
 
 				console.log(chalk.green('Step finished:'), actionName)
 				console.groupEnd()
@@ -279,25 +350,31 @@ export class PageAgent extends EventTarget {
 		})
 
 		return {
+			description: 'You MUST call this tool every step. Outputs your reflections and next action.',
 			inputSchema: macroToolSchema as zod.ZodType<MacroToolInput>,
 			execute: async (input: MacroToolInput): Promise<MacroToolResult> => {
 				// abort
 				if (this.#abortController.signal.aborted) throw new Error('AbortError')
-				// pause
-				await waitUntil(() => !this.paused)
 
 				console.log(chalk.blue.bold('MacroTool execute'), input)
 				const action = input.action
 
 				const toolName = Object.keys(action)[0]
 				const toolInput = action[toolName]
-				const brain = trimLines(`✅: ${input.evaluation_previous_goal}
-						💾: ${input.memory}
-						🎯: ${input.next_goal}
-					`)
 
-				console.log(brain)
+				// Build reflection text, only include non-empty fields
-				this.panel.update({ type: 'thinking', text: brain })
+				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)
@@ -309,20 +386,14 @@ export class PageAgent extends EventTarget {
 				const startTime = Date.now()
 
 				// Execute tool, bind `this` to PageAgent
-				let result = await tool.execute.bind(this)(toolInput)
+				const result = await tool.execute.bind(this)(toolInput)
 
 				const duration = Date.now() - startTime
 				console.log(chalk.green.bold(`Tool (${toolName}) executed for ${duration}ms`), result)
 
-				if (toolName === 'wait') {
+				// Reset wait time for non-wait tools
-					this.#totalWaitTime += Math.round(toolInput.seconds + duration / 1000)
+				if (toolName !== 'wait') {
-					result += `\n<sys> You have waited ${this.#totalWaitTime} seconds accumulatively.`
+					this.states.totalWaitTime = 0
-					if (this.#totalWaitTime >= 3)
-						result += '\nDo NOT wait any longer unless you have a good reason.\n'
-					result += '</sys>'
-				} else {
-					// For other tools, reset wait time
-					this.#totalWaitTime = 0
 				}
 
 				// Briefly display execution result
@@ -399,6 +470,34 @@ export class PageAgent extends EventTarget {
 		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 = ''
 
@@ -410,31 +509,42 @@ export class PageAgent extends EventTarget {
 		//  - <step_info>
 		// <agent_state>
 
+		const stepCount = this.history.filter((e) => e.type === 'step').length
+
 		prompt += `<agent_state>
 			<user_request>
 			${this.task}
 			</user_request>
 			<step_info>
-			Step ${this.history.length + 1} of ${MAX_STEPS} max possible steps
+			Step ${stepCount + 1} of ${MAX_STEPS} max possible steps
 			Current date and time: ${new Date().toISOString()}
 			</step_info>
 			</agent_state>
 		`
 
 		// <agent_history>
-		//  - <step_>
+		//  - <step_N> for steps
+		//  - <sys> for observations and system messages
 
 		prompt += '\n<agent_history>\n'
 
-		this.history.forEach((history, index) => {
+		let stepIndex = 0
-			prompt += `<step_${index + 1}>
+		for (const event of this.history) {
-				Evaluation of Previous Step: ${history.brain.evaluation_previous_goal}
+			if (event.type === 'step') {
-				Memory: ${history.brain.memory}
+				stepIndex++
-				Next Goal: ${history.brain.next_goal}
+				prompt += `<step_${stepIndex}>
-				Action Results: ${history.action.output}
+				Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}
-				</step_${index + 1}>
+				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'
 
@@ -458,59 +568,28 @@ export class PageAgent extends EventTarget {
 		// Task completed
 		this.panel.update({ type: 'completed' })
 
-		this.mask.hide()
+		this.pageController.hideMask()
 
 		this.#abortController.abort()
 	}
 
 	async #getBrowserState(): Promise<string> {
-		const pageUrl = await this.pageController.getCurrentUrl()
+		const state = await this.pageController.getBrowserState()
-		const pageTitle = await this.pageController.getPageTitle()
-		const pi = await this.pageController.getPageInfo()
-		const viewportExpansion = await this.pageController.getViewportExpansion()
-
-		this.mask.wrapper.style.pointerEvents = 'none'
-		await this.pageController.updateTree()
-		this.mask.wrapper.style.pointerEvents = 'auto'
-
-		let simplifiedHTML = await this.pageController.getSimplifiedHTML()
 
+		let content = state.content
 		if (this.config.transformPageContent) {
-			simplifiedHTML = await this.config.transformPageContent(simplifiedHTML)
+			content = await this.config.transformPageContent(content)
 		}
 
-		let prompt = trimLines(`<browser_state>
+		return trimLines(`<browser_state>
-			Current Page: [${pageTitle}](${pageUrl})
+			Current Page: [${state.title}](${state.url})
 
-			Page info: ${pi.viewport_width}x${pi.viewport_height}px viewport, ${pi.page_width}x${pi.page_height}px total page size, ${pi.pages_above.toFixed(1)} pages above, ${pi.pages_below.toFixed(1)} pages below, ${pi.total_pages.toFixed(1)} total pages, at ${(pi.current_page_position * 100).toFixed(0)}% of page
+			${state.header}
-
+			${content}
-			${viewportExpansion === -1 ? 'Interactive elements from top layer of the current page (full page):' : 'Interactive elements from top layer of the current page inside the viewport:'}
+			${state.footer}
 
+			</browser_state>
 		`)
-
-		// Page header info
-		const has_content_above = pi.pixels_above > 4
-		if (has_content_above && viewportExpansion !== -1) {
-			prompt += `... ${pi.pixels_above} pixels above (${pi.pages_above.toFixed(1)} pages) - scroll to see more ...\n`
-		} else {
-			prompt += `[Start of page]\n`
-		}
-
-		// Current viewport info
-		prompt += simplifiedHTML
-		prompt += `\n`
-
-		// Page footer info
-		const has_content_below = pi.pixels_below > 4
-		if (has_content_below && viewportExpansion !== -1) {
-			prompt += `... ${pi.pixels_below} pixels below (${pi.pages_below.toFixed(1)} pages) - scroll to see more ...\n`
-		} else {
-			prompt += `[End of page]\n`
-		}
-
-		prompt += `</browser_state>\n`
-
-		return prompt
 	}
 
 	dispose(reason?: string) {
@@ -518,7 +597,6 @@ export class PageAgent extends EventTarget {
 		this.disposed = true
 		this.pageController.dispose()
 		this.panel.dispose()
-		this.mask.dispose()
 		this.history = []
 		this.#abortController.abort(reason ?? 'PageAgent disposed')
 

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

@@ -2,7 +2,7 @@ import type { LLMConfig } from '@page-agent/llms'
 import type { PageControllerConfig } from '@page-agent/page-controller'
 import type { SupportedLanguage } from '@page-agent/ui'
 
-import type { AgentHistory, ExecutionResult, PageAgent } from '../PageAgent'
+import type { ExecutionResult, HistoryEvent, PageAgent } from '../PageAgent'
 import type { PageAgentTool } from '../tools'
 
 export type { LLMConfig }
@@ -65,7 +65,7 @@ export interface AgentConfig {
 	// @todo: remove `this` binding, pass agent as explicit parameter instead
 
 	onBeforeStep?: (this: PageAgent, stepCnt: number) => Promise<void> | void
-	onAfterStep?: (this: PageAgent, stepCnt: number, history: AgentHistory[]) => Promise<void> | void
+	onAfterStep?: (this: PageAgent, stepCnt: number, history: HistoryEvent[]) => Promise<void> | void
 	onBeforeTask?: (this: PageAgent) => Promise<void> | void
 	onAfterTask?: (this: PageAgent, result: ExecutionResult) => Promise<void> | void
 

packages/page-agent/src/iife.ts

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

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

@@ -57,6 +57,15 @@ tools.set(
 			const actualWaitTime = Math.max(0, input.seconds - (Date.now() - lastTimeUpdate) / 1000)
 			console.log(`actualWaitTime: ${actualWaitTime} seconds`)
 			await waitFor(actualWaitTime)
+
+			this.states.totalWaitTime += input.seconds
+
+			if (this.states.totalWaitTime >= 3) {
+				this.pushObservation(
+					`You have waited ${this.states.totalWaitTime} seconds accumulatively. Do NOT wait any longer unless you have a good reason.`
+				)
+			}
+
 			return `✅ Waited for ${input.seconds} seconds.`
 		},
 	})

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

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

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

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

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

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

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

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

packages/page-controller/package.json

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

packages/page-controller/src/PageController.ts

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

packages/page-controller/src/actions.ts

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

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

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

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

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

packages/page-controller/vite.config.js

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

packages/ui/package.json

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

packages/ui/src/Panel.module.css

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

packages/ui/src/Panel.ts

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

packages/ui/src/UIState.ts

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

packages/ui/src/i18n/locales.ts

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

packages/ui/src/index.ts

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

packages/ui/src/utils.ts

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

packages/ui/vite.config.js

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

packages/website/package.json

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

packages/website/src/components/Header.tsx

@@ -41,6 +41,7 @@ export default function Header() {
 									className="hidden sm:block text-xs text-gray-600 dark:text-gray-300 py-0 font-normal overflow-visible"
 									duration={600}
 									animateOnHover={true}
+									aria-hidden="true"
 								>
 									{t('header.slogan')}
 								</HyperText>
@@ -84,6 +85,9 @@ export default function Header() {
 							role="navigation"
 							aria-label={t('header.nav_docs')}
 						>
+							<span className="text-xs font-mono text-gray-400 dark:text-gray-500 tabular-nums before:content-['v']">
+								{import.meta.env.VERSION}
+							</span>
 							<Link
 								href="/docs/introduction/overview"
 								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"

packages/website/src/constants.ts

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

packages/website/src/env.d.ts

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

packages/website/src/pages/Home.tsx

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

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

@@ -32,7 +32,7 @@ export default function DocsLayout({ children }: DocsLayoutProps) {
 		{
 			title: t('nav.features'),
 			items: [
-				{ title: t('nav.models'), path: '/docs/features/model-integration' },
+				{ title: t('nav.models'), path: '/docs/features/models' },
 				{ title: t('nav.custom_tools'), path: '/docs/features/custom-tools' },
 				{ title: t('nav.knowledge_injection'), path: '/docs/features/custom-instructions' },
 				{ title: t('nav.data_masking'), path: '/docs/features/data-masking' },
@@ -43,7 +43,7 @@ export default function DocsLayout({ children }: DocsLayoutProps) {
 			items: [
 				{ title: t('nav.configuration'), path: '/docs/integration/configuration' },
 				{ title: t('nav.third_party_agent'), path: '/docs/integration/third-party-agent' },
-				{ title: '🚧 ' + t('nav.cdn_setup'), path: '/docs/integration/cdn-setup' },
+				{ title: t('nav.cdn_setup'), path: '/docs/integration/cdn-setup' },
 				{
 					title: '🚧 ' + t('nav.security_permissions'),
 					path: '/docs/integration/security-permissions',

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

@@ -4,13 +4,19 @@ import CodeEditor from '@/components/CodeEditor'
 
 // Recommended models: lightweight with excellent tool call capabilities
 const MODELS = {
-	recommended: ['gpt-4.1-mini', 'claude-haiku-4.5', 'gemini-3-flash', 'deepseek-3.2', 'gpt-5.2'],
+	recommended: [
-	verified: [
+		'gpt-4.1-mini',
+		'claude-haiku-4.5',
+		'gemini-3-flash',
+		'deepseek-3.2',
+		'gpt-5.2',
 		'qwen-3-max',
+	],
+	verified: [
+		'qwen-3-plus',
 		'gpt-4.1',
 		'gpt-5',
 		'gpt-5-mini',
-		'gpt-5.1',
 		'grok-4',
 		'grok-code-fast',
 		'claude-sonnet-3.5',
@@ -21,7 +27,7 @@ const MODELS = {
 	],
 }
 
-export default function ModelIntegration() {
+export default function Models() {
 	const { t } = useTranslation('docs')
 	const allModels = [...MODELS.recommended, ...MODELS.verified]
 

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

@@ -1,81 +1,124 @@
 import { useTranslation } from 'react-i18next'
 
-import BetaNotice from '@/components/BetaNotice'
 import CodeEditor from '@/components/CodeEditor'
-import { CDN_CN_URL, CDN_URL } from '@/constants'
+import { CDN_DEMO_CN_URL, CDN_DEMO_URL, CDN_FULL_CN_URL, CDN_FULL_URL } from '@/constants'
 
 export default function CdnSetup() {
 	const { i18n } = useTranslation()
 	const isZh = i18n.language === 'zh-CN'
 
 	return (
-		<div>
+		<div className="space-y-10">
-			<BetaNotice />
+			<header>
+				<h1 className="text-4xl font-bold mb-4">{isZh ? 'CDN 引入' : 'CDN Setup'}</h1>
+				<p className="text-lg text-gray-600 dark:text-gray-300 leading-relaxed">
+					{isZh
+						? 'CDN 提供两种构建版本：Demo 版用于快速体验，标准版用法与 NPM 一致。'
+						: 'CDN provides two builds: Demo for quick testing, standard build with usage identical to NPM.'}
+				</p>
+			</header>
 
-			<h1 className="text-4xl font-bold mb-6">{isZh ? 'CDN 引入' : 'CDN Setup'}</h1>
+			{/* Demo Build Section */}
+			<section>
+				<h2 className="text-2xl font-bold mb-3">{isZh ? '🚀 快速体验' : '🚀 Quick Try'}</h2>
 
-			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				<p className="text-gray-600 dark:text-gray-300 mb-3">
-				{isZh
+					{isZh
-					? '通过 CDN 快速集成 page-agent，无需复杂的构建配置。默认使用演示模型。'
+						? '自动初始化并使用内置 Demo LLM，无需任何配置：'
-					: 'Fastest way to integrate page-agent via CDN. No complex build setup needed. Demo model will be used by default.'}
+						: 'Auto-initializes with built-in demo LLM, no configuration needed:'}
-			</p>
+				</p>
-
-			<section className="mb-8">
-				<h2 className="text-2xl font-bold mb-4">{isZh ? 'CDN 地址' : 'CDN URLs'}</h2>
-
-				<div className="overflow-x-auto mb-6">
-					<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-3 px-4 font-semibold">{isZh ? '位置' : 'Location'}</th>
-								<th className="text-left py-3 px-4 font-semibold">URL</th>
-							</tr>
-						</thead>
-						<tbody>
-							<tr className="border-b border-gray-100 dark:border-gray-800">
-								<td className="py-3 px-4">{isZh ? '全球' : 'Global'}</td>
-								<td className="py-3 px-4 font-mono text-xs break-all">{CDN_URL}</td>
-							</tr>
-							<tr className="border-b border-gray-100 dark:border-gray-800">
-								<td className="py-3 px-4">{isZh ? '中国镜像' : 'China Mirror'}</td>
-								<td className="py-3 px-4 font-mono text-xs break-all">{CDN_CN_URL}</td>
-							</tr>
-						</tbody>
-					</table>
-				</div>
-			</section>
-
-			<section className="mb-8">
-				<h2 className="text-2xl font-bold mb-4">{isZh ? '快速开始' : 'Quick Start'}</h2>
 
 				<CodeEditor
-					className="mb-6"
+					className="mb-3"
-					code={`<script
+					code={`<script src="${CDN_DEMO_URL}" crossorigin="true"></script>`}
-  src="${CDN_URL}"
-  crossorigin="true"
-  type="text/javascript"
-></script>`}
 				/>
+
+				<div className="bg-yellow-50 dark:bg-yellow-900/20 px-4 py-3 rounded-lg mb-4 text-sm">
+					<span className="text-yellow-800 dark:text-yellow-200">
+						⚠️{' '}
+						{isZh
+							? '仅用于技术评估，Demo 模型有速率限制。'
+							: 'For evaluation only. Demo model has rate limits.'}
+					</span>
+				</div>
+
+				<table className="w-full border-collapse text-sm">
+					<thead>
+						<tr className="border-b border-gray-200 dark:border-gray-700">
+							<th className="text-left py-2 px-3 font-semibold w-28">
+								{isZh ? '位置' : 'Location'}
+							</th>
+							<th className="text-left py-2 px-3 font-semibold">URL</th>
+						</tr>
+					</thead>
+					<tbody>
+						<tr className="border-b border-gray-100 dark:border-gray-800">
+							<td className="py-2 px-3">{isZh ? '全球' : 'Global'}</td>
+							<td className="py-2 px-3 font-mono text-xs break-all">{CDN_DEMO_URL}</td>
+						</tr>
+						<tr>
+							<td className="py-2 px-3">{isZh ? '中国' : 'China'}</td>
+							<td className="py-2 px-3 font-mono text-xs break-all">{CDN_DEMO_CN_URL}</td>
+						</tr>
+					</tbody>
+				</table>
 			</section>
 
-			<section className="mb-8">
+			{/* CDN Build Section */}
-				<div className="bg-yellow-50 dark:bg-yellow-900/20 p-4 rounded-lg">
+			<section>
-					<h3 className="text-lg font-semibold mb-2 text-yellow-900 dark:text-yellow-300">
+				<h2 className="text-2xl font-bold mb-3">{isZh ? '📦 标准版' : '📦 Standard Build'}</h2>
-						⚠️ {isZh ? '注意事项' : 'Notes'}
+
-					</h3>
+				<p className="text-gray-600 dark:text-gray-300 mb-3">
-					<ul className="text-gray-600 dark:text-gray-300 space-y-1">
+					{isZh
-						<li>
+						? '将 PageAgent 类暴露到 globalThis，用法与 NPM 一致：'
-							• {isZh ? '生产环境建议使用固定版本号' : 'Use fixed version number in production'}
+						: 'Exposes PageAgent class to globalThis, usage identical to NPM:'}
-						</li>
+				</p>
-						<li>• {isZh ? '确保 HTTPS 环境下使用' : 'Ensure HTTPS environment'}</li>
+
-						<li>
+				<CodeEditor
-							•{' '}
+					className="mb-4"
-							{isZh
+					code={`<script src="${CDN_FULL_URL}" crossorigin="true"></script>
-								? '配置 CSP 策略允许脚本执行'
+<script>
-								: 'Configure CSP policy to allow script execution'}
+const agent = new PageAgent({
-						</li>
+  model: 'deepseek-chat',
-					</ul>
+  baseURL: 'https://api.deepseek.com',
-				</div>
+  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

@@ -121,6 +121,13 @@ export default function Configuration() {
 
   /** Viewport expansion in pixels (-1 for full page) */
   viewportExpansion?: number
+
+  /**
+   * Enable visual mask overlay during automation.
+   * Blocks user interaction while agent is running.
+   * Default: false for PageController, true for PageAgent.
+   */
+  enableMask?: boolean
 }`}
 				/>
 			</section>

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

@@ -2,10 +2,11 @@ import { useTranslation } from 'react-i18next'
 
 import BetaNotice from '@/components/BetaNotice'
 import CodeEditor from '@/components/CodeEditor'
-import { CDN_CN_URL, CDN_URL } from '@/constants'
+import { CDN_DEMO_CN_URL, CDN_DEMO_URL } from '@/constants'
 
 export default function QuickStart() {
-	const { t } = useTranslation('docs')
+	const { t, i18n } = useTranslation('docs')
+	const isZh = i18n.language === 'zh-CN'
 
 	return (
 		<div>
@@ -16,64 +17,62 @@ export default function QuickStart() {
 			<h2 className="text-2xl font-bold mb-3">{t('quick_start.installation')}</h2>
 
 			<div className="space-y-4 mb-6">
+				{/* Demo CDN - One Line */}
 				<div className="p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg">
 					<h3 className="text-lg font-semibold mb-2 text-blue-900 dark:text-blue-300">
-						{t('quick_start.step1_title')}
+						{isZh ? '🚀 快速体验（Demo CDN）' : '🚀 Quick Try (Demo CDN)'}
 					</h3>
-					<div className="space-y-3">
+					<div className="bg-yellow-50 dark:bg-yellow-900/20 p-2 rounded mb-3 text-sm">
-						<div>
+						<span className="text-yellow-800 dark:text-yellow-200">
-							<p className="text-sm font-medium mb-2">{t('quick_start.step1_cdn')}</p>
+							⚠️ {isZh ? '仅用于技术评估' : 'For evaluation only'}
-							<CodeEditor
+						</span>
-								code={`// CDN: \t${CDN_URL}
-// Mirror: \t${CDN_CN_URL}
-<script src="${CDN_URL}" crossorigin="true" type="text/javascript"></script>`}
-								language="html"
-							/>
-						</div>
-						<div>
-							<p className="text-sm font-medium mb-2">{t('quick_start.step1_npm')}</p>
-							<CodeEditor
-								code={`// npm install page-agent
-import PageAgent from 'page-agent'`}
-								language="bash"
-							/>
-						</div>
 					</div>
+					<CodeEditor
+						code={`// Global: ${CDN_DEMO_URL}
+// China:  ${CDN_DEMO_CN_URL}
+<script src="${isZh ? CDN_DEMO_CN_URL : CDN_DEMO_URL}" crossorigin="true"></script>`}
+						language="html"
+					/>
 				</div>
 
+				{/* NPM - Recommended */}
 				<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
 					<h3 className="text-lg font-semibold mb-2 text-green-900 dark:text-green-300">
-						{t('quick_start.step2_title')}
+						{isZh ? '📦 NPM 安装（推荐）' : '📦 NPM Install (Recommended)'}
 					</h3>
 					<CodeEditor
-						code={`// 仅供测试使用，生产环境需要配置 LLM 接入点，本工具不提供 LLM 服务
+						code={`npm install page-agent
-// 测试接口
-// @note: 限流，限制 prompt 内容，限制来源，随时变更，请替换成你自己的
-// @note: 使用 DeepSeek-chat(3.2) 官方版本，使用协议和隐私策略见 DeepSeek 网站
-const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
 
-const agent = new PageAgent({
+import { PageAgent } from 'page-agent'`}
-  model: DEMO_MODEL,
+						language="bash"
-  baseURL: DEMO_BASE_URL,
-  apiKey: DEMO_API_KEY,
-  language: 'zh-CN'
-})`}
-						language="javascript"
 					/>
 				</div>
 
 				<div className="p-4 bg-purple-50 dark:bg-purple-900/20 rounded-lg">
 					<h3 className="text-lg font-semibold mb-2 text-purple-900 dark:text-purple-300">
+						{t('quick_start.step2_title')}
+					</h3>
+					<CodeEditor
+						code={`const agent = new PageAgent({
+  model: 'deepseek-chat',
+  baseURL: 'https://api.deepseek.com',
+  apiKey: 'YOUR_API_KEY',
+  language: '${isZh ? 'zh-CN' : 'en-US'}'
+})`}
+						language="javascript"
+					/>
+				</div>
+
+				<div className="p-4 bg-orange-50 dark:bg-orange-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-orange-900 dark:text-orange-300">
 						{t('quick_start.step3_title')}
 					</h3>
 					<CodeEditor
-						code={`// 程序化执行自然语言指令
+						code={`// ${isZh ? '程序化执行自然语言指令' : 'Execute natural language instructions programmatically'}
-await pageAgent.execute('点击提交按钮，然后填写用户名为张三');
+await agent.execute('${isZh ? '点击提交按钮，然后填写用户名为张三' : 'Click submit button, then fill username as John'}');
 
-// 或者显示对话框让用户输入指令
+// ${isZh ? '或者显示对话框让用户输入指令' : 'Or show panel for user to input instructions'}
-pageAgent.panel.show()
+agent.panel.show()
 `}
 						language="javascript"
 					/>

packages/website/src/router.tsx

@@ -1,148 +1,123 @@
+import { Suspense, lazy } from 'react'
 import { Route, Switch } from 'wouter'
 
 import Header from './components/Header'
-import HomePage from './pages/Home'
 import DocsLayout from './pages/docs/Layout'
-// Features pages
+
-import Instructions from './pages/docs/features/custom-instructions/page'
+// Lazy load pages
-import CustomTools from './pages/docs/features/custom-tools/page'
+const HomePage = lazy(() => import('./pages/Home'))
-import DataMasking from './pages/docs/features/data-masking/page'
+// Introduction
-import ModelIntegration from './pages/docs/features/model-integration/page'
+const Overview = lazy(() => import('./pages/docs/introduction/overview/page'))
-// Integration pages
+const QuickStart = lazy(() => import('./pages/docs/introduction/quick-start/page'))
-import BestPractices from './pages/docs/integration/best-practices/page'
+const Limitations = lazy(() => import('./pages/docs/introduction/limitations/page'))
-import CdnSetup from './pages/docs/integration/cdn-setup/page'
+// Features
-import Configuration from './pages/docs/integration/configuration/page'
+const CustomTools = lazy(() => import('./pages/docs/features/custom-tools/page'))
-import SecurityPermissions from './pages/docs/integration/security-permissions/page'
+const DataMasking = lazy(() => import('./pages/docs/features/data-masking/page'))
-import ThirdPartyAgent from './pages/docs/integration/third-party-agent/page'
+const Instructions = lazy(() => import('./pages/docs/features/custom-instructions/page'))
-// Introduction pages
+const Models = lazy(() => import('./pages/docs/features/models/page'))
-import Limitations from './pages/docs/introduction/limitations/page'
+// Integration
-import Overview from './pages/docs/introduction/overview/page'
+const CdnSetup = lazy(() => import('./pages/docs/integration/cdn-setup/page'))
-import QuickStart from './pages/docs/introduction/quick-start/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 (
-		<Switch>
+		<Suspense>
-			{/* Home page */}
+			<Switch>
-			<Route path="/" component={HomePage} />
+				{/* Home page */}
+				<Route path="/">
+					<HomePage />
+				</Route>
 
-			{/* Documentation pages with layout */}
+				{/* Introduction */}
-			<Route path="/docs/introduction/overview">
+				<Route path="/docs/introduction/overview">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
+					<DocsPage>
-					<Header />
-					<DocsLayout>
 						<Overview />
-					</DocsLayout>
+					</DocsPage>
-				</div>
+				</Route>
-			</Route>
+				<Route path="/docs/introduction/quick-start">
-
+					<DocsPage>
-			<Route path="/docs/introduction/quick-start">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
 						<QuickStart />
-					</DocsLayout>
+					</DocsPage>
-				</div>
+				</Route>
-			</Route>
+				<Route path="/docs/introduction/limitations">
-
+					<DocsPage>
-			<Route path="/docs/introduction/limitations">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
 						<Limitations />
-					</DocsLayout>
+					</DocsPage>
-				</div>
+				</Route>
-			</Route>
 
-			<Route path="/docs/features/custom-tools">
+				{/* Features */}
-				<div className="min-h-screen bg-white dark:bg-gray-900">
+				<Route path="/docs/features/custom-tools">
-					<Header />
+					<DocsPage>
-					<DocsLayout>
 						<CustomTools />
-					</DocsLayout>
+					</DocsPage>
-				</div>
+				</Route>
-			</Route>
+				<Route path="/docs/features/data-masking">
-
+					<DocsPage>
-			<Route path="/docs/features/data-masking">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
 						<DataMasking />
-					</DocsLayout>
+					</DocsPage>
-				</div>
+				</Route>
-			</Route>
+				<Route path="/docs/features/custom-instructions">
-
+					<DocsPage>
-			<Route path="/docs/features/custom-instructions">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
 						<Instructions />
-					</DocsLayout>
+					</DocsPage>
-				</div>
+				</Route>
-			</Route>
+				<Route path="/docs/features/models">
+					<DocsPage>
+						<Models />
+					</DocsPage>
+				</Route>
 
-			<Route path="/docs/features/model-integration">
+				{/* Integration */}
-				<div className="min-h-screen bg-white dark:bg-gray-900">
+				<Route path="/docs/integration/cdn-setup">
-					<Header />
+					<DocsPage>
-					<DocsLayout>
-						<ModelIntegration />
-					</DocsLayout>
-				</div>
-			</Route>
-
-			<Route path="/docs/integration/cdn-setup">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
 						<CdnSetup />
-					</DocsLayout>
+					</DocsPage>
-				</div>
+				</Route>
-			</Route>
+				<Route path="/docs/integration/security-permissions">
-
+					<DocsPage>
-			<Route path="/docs/integration/security-permissions">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
 						<SecurityPermissions />
-					</DocsLayout>
+					</DocsPage>
-				</div>
+				</Route>
-			</Route>
+				<Route path="/docs/integration/configuration">
-
+					<DocsPage>
-			<Route path="/docs/integration/configuration">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
 						<Configuration />
-					</DocsLayout>
+					</DocsPage>
-				</div>
+				</Route>
-			</Route>
+				<Route path="/docs/integration/best-practices">
-
+					<DocsPage>
-			<Route path="/docs/integration/best-practices">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
 						<BestPractices />
-					</DocsLayout>
+					</DocsPage>
-				</div>
+				</Route>
-			</Route>
+				<Route path="/docs/integration/third-party-agent">
-
+					<DocsPage>
-			<Route path="/docs/integration/third-party-agent">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
 						<ThirdPartyAgent />
-					</DocsLayout>
+					</DocsPage>
-				</div>
+				</Route>
-			</Route>
 
-			{/* 404 page */}
+				{/* 404 */}
-			<Route>
+				<Route>
-				<div className="min-h-screen bg-white dark:bg-gray-900 flex items-center justify-center">
+					<div className="min-h-screen bg-white dark:bg-gray-900 flex items-center justify-center">
-					<div className="text-center">
+						<div className="text-center">
-						<h1 className="text-4xl font-bold mb-4 text-gray-900 dark:text-white">404</h1>
+							<h1 className="text-4xl font-bold mb-4 text-gray-900 dark:text-white">404</h1>
-						<p className="text-xl text-gray-600 dark:text-gray-300">页面未找到</p>
+							<p className="text-xl text-gray-600 dark:text-gray-300">页面未找到</p>
+						</div>
 					</div>
-				</div>
+				</Route>
-			</Route>
+			</Switch>
-		</Switch>
+		</Suspense>
 	)
 }

packages/website/vite.config.js

@@ -1,21 +1,35 @@
 import tailwindcss from '@tailwindcss/vite'
 import react from '@vitejs/plugin-react-swc'
 import { config as dotenvConfig } from 'dotenv'
+import { readFileSync } from 'node:fs'
 import process from 'node:process'
 import { dirname, resolve } from 'path'
 import { fileURLToPath } from 'url'
 import { defineConfig } from 'vite'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
+const pageAgentPkg = JSON.parse(
+	readFileSync(resolve(__dirname, '../page-agent/package.json'), 'utf-8')
+)
 
 // Load .env from repo root
 dotenvConfig({ path: resolve(__dirname, '../../.env') })
 
 // Website Config (React Documentation Site)
-export default defineConfig({
+export default defineConfig(({ mode }) => ({
 	base: './',
 	clearScreen: false,
 	plugins: [react(), tailwindcss()],
+	build: {
+		chunkSizeWarningLimit: 2000,
+		cssCodeSplit: true,
+		rollupOptions: {
+			onwarn: function (message, handler) {
+				if (message.code === 'EVAL') return
+				handler(message)
+			},
+		},
+	},
 	resolve: {
 		alias: {
 			// Self root
@@ -29,8 +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),
 	},
-})
+}))