chore(version): bump version to 0.2.2

chore: npm audit fix
feat!: local iife testing
2026-01-17 00:59:55 +08:00 · 2026-01-17 00:54:20 +08:00 · 2026-01-16 19:04:26 +08:00 · 2026-01-16 16:16:18 +08:00 · 2026-01-16 16:15:43 +08:00 · 2026-01-16 16:06:57 +08:00
43 changed files with 859 additions and 634 deletions
@@ -5,6 +5,7 @@
 		"HITL",
 		"innerhtml",
 		"llms",
+		"onwarn",
 		"opensource",
 		"qwen",
 		"retryable",
@@ -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**
-
-   ```bash
-   # TODO
-   ```
+   - Test in our demo website
+   - Test it on other websites if applicable
+   - `@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.
-   - Cursor and Cline: `./.cursor/rules`
-   - Github Copilot: `./.github/copilot-instructions.md`
-   - Claude Code: `./CLAUDE.md`
+- Update the [AI instructions](AGENTS.md) when structure changed.

 ## 🔧 Development Workflows

+### Test With Your Own LLM API
+
+- Create a `.env` file in the repo root with your LLM API config
+
+  ```env
+  LLM_MODEL_NAME=gpt-5.2
+  LLM_API_KEY=your-api-key
+  LLM_BASE_URL=https://api.your-llm-provider.com/v1
+  ```
+
+- Restart the dev server to load new env vars
+- If not provided, the demo will the free testing proxy by default
+
 ### Website Development

 ```bash
-npm start                # React development server
+npm start
 ```

-### Core Lib Development and Testing
+### Testing on Other Websites

-> @TODO this part is outdated. Update this.
+- Start and serve a local `iife` script

- Config your LLM API
- Start and serve a local umd script
+  ```bash
+  npm run dev:iife # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.js
+  ```

-   ```bash
-   npm run dev:umd # Serving UMD with auto rebuild at http://localhost:5173/page-agent.umd.cjs
-   ```
+- Add a new bookmark

- Add a new bookmark enable it on other website
+  ```javascript
+  javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.js?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
+  ```

-   ```
-   javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5173/page-agent.umd.cjs?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
-   ```
+- Click the bookmark on any page to load Page-Agent
+
+> Warning: AK in your local `.env` will be inlined in the iife script.

 ### Adding Documentation

-1. Create `website/src/docs/section/page-name/page.tsx`
-2. Add route to `website/src/router.tsx`
-3. Add navigation link to `website/src/components/DocsLayout.tsx`
+Ask an AI to help you add documentation to the `website/` package. Follow the existing style.
+
+> Our AGENTS.md file and guardrails are designed for this purpose. But please be careful and review anything AI generated.

 ## 🎯 Contribution Areas

@@ -143,7 +153,7 @@ We especially welcome contributions in:

 ## 🚫 What We Don't Accept

- Changes that break existing API compatibility
+- Changes that break existing API compatibility (Discuss first)
 - Heavy dependencies to core library
 - Contributions without proper testing
 - Code that doesn't follow project conventions
@@ -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
@@ -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,
-	baseURL: DEMO_BASE_URL,
-	apiKey: DEMO_API_KEY,
+	model: 'deepseek-chat',
+	baseURL: 'https://api.deepseek.com',
+	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.
-
-| 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 |
+适用于无法使用 NPM 的环境，用法与 NPM 一致：

 ```html
-<script
-	src="https://registry.npmmirror.com/page-agent/latest/files/dist/umd/page-agent.js"
-	crossorigin="true"
-	type="text/javascript"
-></script>
+<script src="https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.js" crossorigin="true"></script>
+<script>
+const agent = new PageAgent({
+	model: 'deepseek-chat',
+	baseURL: 'https://api.deepseek.com',
+	apiKey: 'YOUR_API_KEY',
+})
+await agent.execute('点击登录按钮')
+</script>
 ```

+| 位置   | URL                                                                                 |
+| ------ | ----------------------------------------------------------------------------------- |
+| 全球   | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.js                     |
+| 中国   | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.js      |
+
 ## 🏗️ 架构设计

 PageAgent adopts a simplified monorepo structure:
@@ -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,
-	baseURL: DEMO_BASE_URL,
-	apiKey: DEMO_API_KEY,
+	model: 'deepseek-chat',
+	baseURL: 'https://api.deepseek.com',
+	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.
-
-| 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 |
+For environments where NPM is not available. Usage is identical to NPM:

 ```html
-<script
-	src="https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js"
-	crossorigin="true"
-	type="text/javascript"
-></script>
+<script src="https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.js" crossorigin="true"></script>
+<script>
+const agent = new PageAgent({
+	model: 'deepseek-chat',
+	baseURL: 'https://api.deepseek.com',
+	apiKey: 'YOUR_API_KEY',
+})
+await agent.execute('Click the login button')
+</script>
 ```

+| Location | URL                                                                                 |
+| -------- | ----------------------------------------------------------------------------------- |
+| Global   | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.js                     |
+| China    | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.js      |
+
 ## 🏗️ Structure

 PageAgent adopts a simplified monorepo structure:
@@ -1,12 +1,12 @@
 {
 	"name": "root",
-	"version": "0.0.22",
+	"version": "0.2.2",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "root",
-			"version": "0.0.22",
+			"version": "0.2.2",
 			"license": "MIT",
 			"workspaces": [
 				"packages/page-controller",
@@ -1540,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",
@@ -4627,9 +4613,9 @@
 			}
 		},
 		"node_modules/diff": {
-			"version": "8.0.2",
-			"resolved": "https://registry.npmjs.org/diff/-/diff-8.0.2.tgz",
-			"integrity": "sha512-sSuxWU5j5SR9QQji/o2qMvqRNYRDOcBTgsJ/DeCf4iSN4gW+gNMXM7wFIP+fdXZxoNiAnHUTGjCr+TSWXdRDKg==",
+			"version": "8.0.3",
+			"resolved": "https://registry.npmjs.org/diff/-/diff-8.0.3.tgz",
+			"integrity": "sha512-qejHi7bcSD4hQAZE0tNAawRK1ZtafHDmMTMkrrIGgSLl7hTnQHmKCeB45xAcbfTqK2zowkM3j3bHt/4b/ARbYQ==",
 			"dev": true,
 			"license": "BSD-3-Clause",
 			"engines": {
@@ -8147,15 +8133,15 @@
 		},
 		"packages/cdn": {
 			"name": "@page-agent/cdn",
-			"version": "0.0.22",
+			"version": "0.2.2",
 			"license": "MIT",
 			"dependencies": {
-				"page-agent": "0.0.22"
+				"page-agent": "0.2.2"
 			}
 		},
 		"packages/llms": {
 			"name": "@page-agent/llms",
-			"version": "0.0.22",
+			"version": "0.2.2",
 			"license": "MIT",
 			"dependencies": {
 				"chalk": "^5.6.2",
@@ -8163,19 +8149,19 @@
 			}
 		},
 		"packages/page-agent": {
-			"version": "0.0.22",
+			"version": "0.2.2",
 			"license": "MIT",
 			"dependencies": {
-				"@page-agent/llms": "0.0.22",
-				"@page-agent/page-controller": "0.0.22",
-				"@page-agent/ui": "0.0.22",
+				"@page-agent/llms": "0.2.2",
+				"@page-agent/page-controller": "0.2.2",
+				"@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.22",
+			"version": "0.2.2",
 			"license": "MIT",
 			"dependencies": {
 				"ai-motion": "^0.4.8"
@@ -8183,12 +8169,12 @@
 		},
 		"packages/ui": {
 			"name": "@page-agent/ui",
-			"version": "0.0.22",
+			"version": "0.2.2",
 			"license": "MIT"
 		},
 		"packages/website": {
 			"name": "@page-agent/website",
-			"version": "0.0.22",
+			"version": "0.2.2",
 			"dependencies": {
 				"@radix-ui/react-icons": "^1.3.2",
 				"@radix-ui/react-separator": "^1.1.8",
@@ -1,7 +1,7 @@
 {
 	"name": "root",
 	"private": true,
-	"version": "0.0.22",
+	"version": "0.2.2",
 	"type": "module",
 	"workspaces": [
 		"packages/page-controller",
@@ -29,7 +29,7 @@
 		"build:website": "npm run build:website --workspace=@page-agent/website",
 		"build:libs": "npm run build --workspaces --if-present",
 		"build": "npm run build:libs && npm run build:website",
-		"dev:umd": "npm run dev:umd --workspace=page-agent",
+		"dev:iife": "npm run dev:iife --workspace=page-agent",
 		"version": "node scripts/sync-version.js",
 		"lint": "eslint .",
 		"prepare": "husky"
@@ -59,6 +59,9 @@
 		"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",
@@ -1,7 +1,7 @@
 {
 	"name": "@page-agent/cdn",
 	"private": false,
-	"version": "0.0.22",
+	"version": "0.2.2",
 	"type": "module",
 	"files": [
 		"dist/"
@@ -18,6 +18,6 @@
 		"build": "vite build && vite build --mode demo"
 	},
 	"dependencies": {
-		"page-agent": "0.0.22"
+		"page-agent": "0.2.2"
 	}
 }
@@ -50,7 +50,12 @@ 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 = {
+			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)
@@ -34,6 +34,13 @@ export default defineConfig(({ mode }) => {
 			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"',
@@ -1,6 +1,6 @@
 {
 	"name": "@page-agent/llms",
-	"version": "0.0.22",
+	"version": "0.2.2",
 	"type": "module",
 	"main": "./dist/lib/page-agent-llms.js",
 	"module": "./dist/lib/page-agent-llms.js",
@@ -1,20 +1,3 @@
-// Dev environment: use .env config if available, otherwise fallback to testing api
-export const DEFAULT_MODEL_NAME: string =
-	import.meta.env.DEV && import.meta.env.LLM_MODEL_NAME
-		? import.meta.env.LLM_MODEL_NAME
-		: 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
-export const DEFAULT_API_KEY: string =
-	import.meta.env.DEV && import.meta.env.LLM_API_KEY
-		? import.meta.env.LLM_API_KEY
-		: 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
-export const DEFAULT_BASE_URL: string =
-	import.meta.env.DEV && import.meta.env.LLM_BASE_URL
-		? import.meta.env.LLM_BASE_URL
-		: 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-
-// internal
-
+// Internal constants
 export const LLM_MAX_RETRIES = 2
 export const DEFAULT_TEMPERATURE = 0.7 // higher randomness helps auto-recovery
@@ -1,21 +1,23 @@
 import { OpenAIClient } from './OpenAIClient'
-import {
-	DEFAULT_API_KEY,
-	DEFAULT_BASE_URL,
-	DEFAULT_MODEL_NAME,
-	DEFAULT_TEMPERATURE,
-	LLM_MAX_RETRIES,
-} from './constants'
+import { DEFAULT_TEMPERATURE, LLM_MAX_RETRIES } from './constants'
 import { InvokeError } from './errors'
 import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'

 export type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool }

 export function parseLLMConfig(config: LLMConfig): Required<LLMConfig> {
+	// Runtime validation as defensive programming (types already guarantee these)
+	if (!config.baseURL || !config.apiKey || !config.model) {
+		throw new Error(
+			'[PageAgent] LLM configuration required. Please provide: baseURL, apiKey, model. ' +
+				'See: https://alibaba.github.io/page-agent/#/docs/features/models'
+		)
+	}
+
 	return {
-		baseURL: config.baseURL ?? DEFAULT_BASE_URL,
-		apiKey: config.apiKey ?? DEFAULT_API_KEY,
-		model: config.model ?? DEFAULT_MODEL_NAME,
+		baseURL: config.baseURL,
+		apiKey: config.apiKey,
+		model: config.model,
 		temperature: config.temperature ?? DEFAULT_TEMPERATURE,
 		maxRetries: config.maxRetries ?? LLM_MAX_RETRIES,
 		customFetch: (config.customFetch ?? fetch).bind(globalThis), // fetch will be illegal unless bound
@@ -87,9 +87,9 @@ export interface InvokeResult<TResult = unknown> {
 * LLM configuration
 */
 export interface LLMConfig {
-	baseURL?: string
-	apiKey?: string
-	model?: string
+	baseURL: string
+	apiKey: string
+	model: string

 	temperature?: number
 	maxRetries?: number
@@ -34,4 +34,3 @@ export default defineConfig({
 		'process.env.NODE_ENV': '"production"',
 	},
 })
-
@@ -1,7 +1,7 @@
 {
 	"name": "page-agent",
 	"private": false,
-	"version": "0.0.22",
+	"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",
-		"serve": "npx serve dist/umd -p 5173",
-		"dev:umd": "concurrently \"vite build --config vite.umd.config.js --watch\" \"npm run serve\"",
+		"build": "vite build",
+		"dev:iife": "concurrently \"vite build --config vite.iife.config.js --watch\" \"npx serve dist/iife -p 5174\"",
 		"prepublishOnly": "node -e \"const fs=require('fs');['README.md','LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
 		"postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
 	},
 	"dependencies": {
 		"chalk": "^5.6.2",
 		"zod": "^4.3.5",
-		"@page-agent/llms": "0.0.22",
-		"@page-agent/page-controller": "0.0.22",
-		"@page-agent/ui": "0.0.22"
+		"@page-agent/llms": "0.2.2",
+		"@page-agent/page-controller": "0.2.2",
+		"@page-agent/ui": "0.2.2"
 	}
 }
@@ -12,11 +12,11 @@ import type { PageAgentConfig } from './config'
 import { MAX_STEPS } from './config/constants'
 import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
 import { tools } from './tools'
-import { normalizeResponse, trimLines, uid, waitUntil } from './utils'
+import { normalizeResponse, trimLines, uid } from './utils'
 import { assert } from './utils/assert'

 /**
- * Agent brain state - the reflection-before-action model
+ * 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?
@@ -50,8 +50,12 @@ export interface MacroToolResult {
 export type { PageAgentConfig }
 export { tool, type PageAgentTool } from './tools'

-export interface AgentHistory {
-	brain: Partial<AgentReflection>
+/**
+ * A single agent step with reflection and action
+ */
+export interface AgentStep {
+	type: 'step'
+	reflection: Partial<AgentReflection>
 	action: {
 		name: string
 		input: any
@@ -66,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 {
@@ -77,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
@@ -92,10 +117,18 @@ export class PageAgent extends EventTarget {
 	/** PageController for DOM operations */
 	pageController: PageController

-	/** History records */
-	history: AgentHistory[] = []
+	/** Runtime states for tracking across steps */
+	states = {
+		/** Accumulated wait time in seconds, used by wait tool */
+		totalWaitTime: 0,
+		/** Last known URL for detecting navigation */
+		lastURL: '',
+	}

-	constructor(config: PageAgentConfig = {}) {
+	/** History event stream */
+	history: HistoryEvent[] = []
+
+	constructor(config: PageAgentConfig) {
 		super()

 		this.config = config
@@ -104,11 +137,6 @@ 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)

@@ -150,6 +178,15 @@ export class PageAgent extends EventTarget {
 		window.addEventListener('beforeunload', this.#beforeUnloadListener)
 	}

+	/**
+	 * Push a persistent observation to the history event stream.
+	 * This will be visible in <agent_history> and remain in memory across steps.
+	 */
+	pushObservation(content: string): void {
+		this.history.push({ type: 'observation', content })
+		this.panel.update({ type: 'observation', content })
+	}
+
 	async execute(task: string): Promise<ExecutionResult> {
 		if (!task) throw new Error('Task is required')
 		this.task = task
@@ -177,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...'))
@@ -216,23 +259,24 @@ export class PageAgent extends EventTarget {
 				const macroResult = result.toolResult as MacroToolResult
 				const input = macroResult.input
 				const output = macroResult.output
-				const brain = {
-					evaluation_previous_goal: input.evaluation_previous_goal || '',
-					memory: input.memory || '',
-					next_goal: input.next_goal || '',
+				const reflection: Partial<AgentReflection> = {
+					evaluation_previous_goal: input.evaluation_previous_goal,
+					memory: input.memory,
+					next_goal: input.next_goal,
 				}
 				const actionName = Object.keys(input.action)[0]
-				const action = {
+				const action: AgentStep['action'] = {
 					name: actionName,
 					input: input.action[actionName],
 					output: output,
 				}

 				this.history.push({
-					brain,
+					type: 'step',
+					reflection,
 					action,
 					usage: result.usage,
-				})
+				} as AgentStep)

 				console.log(chalk.green('Step finished:'), actionName)
 				console.groupEnd()
@@ -311,21 +355,26 @@ export class PageAgent extends EventTarget {
 			execute: async (input: MacroToolInput): Promise<MacroToolResult> => {
 				// abort
 				if (this.#abortController.signal.aborted) throw new Error('AbortError')
-				// pause
-				await waitUntil(() => !this.paused)

 				console.log(chalk.blue.bold('MacroTool execute'), input)
 				const action = input.action

 				const toolName = Object.keys(action)[0]
 				const toolInput = action[toolName]
-				const brain = trimLines(`✅: ${input.evaluation_previous_goal}
-						💾: ${input.memory}
-						🎯: ${input.next_goal}
-					`)

-				console.log(brain)
-				this.panel.update({ type: 'thinking', text: brain })
+				// Build reflection text, only include non-empty fields
+				const reflectionLines: string[] = []
+				if (input.evaluation_previous_goal)
+					reflectionLines.push(`✅: ${input.evaluation_previous_goal}`)
+				if (input.memory) reflectionLines.push(`💾: ${input.memory}`)
+				if (input.next_goal) reflectionLines.push(`🎯: ${input.next_goal}`)
+
+				const reflectionText = reflectionLines.length > 0 ? reflectionLines.join('\n') : ''
+
+				if (reflectionText) {
+					console.log(reflectionText)
+					this.panel.update({ type: 'thinking', text: reflectionText })
+				}

 				// Find the corresponding tool
 				const tool = tools.get(toolName)
@@ -337,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') {
-					this.#totalWaitTime += Math.round(toolInput.seconds + duration / 1000)
-					result += `\n<sys> You have waited ${this.#totalWaitTime} seconds accumulatively.`
-					if (this.#totalWaitTime >= 3)
-						result += '\nDo NOT wait any longer unless you have a good reason.\n'
-					result += '</sys>'
-				} else {
-					// For other tools, reset wait time
-					this.#totalWaitTime = 0
+				// Reset wait time for non-wait tools
+				if (toolName !== 'wait') {
+					this.states.totalWaitTime = 0
 				}

 				// Briefly display execution result
@@ -427,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 = ''

@@ -438,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) => {
-			prompt += `<step_${index + 1}>
-				Evaluation of Previous Step: ${history.brain.evaluation_previous_goal}
-				Memory: ${history.brain.memory}
-				Next Goal: ${history.brain.next_goal}
-				Action Results: ${history.action.output}
-				</step_${index + 1}>
+		let stepIndex = 0
+		for (const event of this.history) {
+			if (event.type === 'step') {
+				stepIndex++
+				prompt += `<step_${stepIndex}>
+				Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}
+				Memory: ${event.reflection.memory}
+				Next Goal: ${event.reflection.next_goal}
+				Action Results: ${event.action.output}
+				</step_${stepIndex}>
 			`
-		})
+			} else if (event.type === 'observation') {
+				prompt += `<sys>${event.content}</sys>\n`
+			} else if (event.type === 'user_takeover') {
+				prompt += `<sys>User took over control and made changes to the page.</sys>\n`
+			}
+		}

 		prompt += '</agent_history>\n\n'

@@ -492,51 +574,22 @@ export class PageAgent extends EventTarget {
 	}

 	async #getBrowserState(): Promise<string> {
-		const pageUrl = await this.pageController.getCurrentUrl()
-		const pageTitle = await this.pageController.getPageTitle()
-		const pi = await this.pageController.getPageInfo()
-		const viewportExpansion = await this.pageController.getViewportExpansion()
-
-		await this.pageController.updateTree()
-
-		let simplifiedHTML = await this.pageController.getSimplifiedHTML()
+		const state = await this.pageController.getBrowserState()

+		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>
-			Current Page: [${pageTitle}](${pageUrl})
+		return trimLines(`<browser_state>
+			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
-
-			${viewportExpansion === -1 ? 'Interactive elements from top layer of the current page (full page):' : 'Interactive elements from top layer of the current page inside the viewport:'}
+			${state.header}
+			${content}
+			${state.footer}

+			</browser_state>
 		`)
-
-		// Page header info
-		const has_content_above = pi.pixels_above > 4
-		if (has_content_above && viewportExpansion !== -1) {
-			prompt += `... ${pi.pixels_above} pixels above (${pi.pages_above.toFixed(1)} pages) - scroll to see more ...\n`
-		} else {
-			prompt += `[Start of page]\n`
-		}
-
-		// Current viewport info
-		prompt += simplifiedHTML
-		prompt += `\n`
-
-		// Page footer info
-		const has_content_below = pi.pixels_below > 4
-		if (has_content_below && viewportExpansion !== -1) {
-			prompt += `... ${pi.pixels_below} pixels below (${pi.pages_below.toFixed(1)} pages) - scroll to see more ...\n`
-		} else {
-			prompt += `[End of page]\n`
-		}
-
-		prompt += `</browser_state>\n`
-
-		return prompt
 	}

 	dispose(reason?: string) {
@@ -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

@@ -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)
@@ -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.`
 		},
 	})
@@ -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 } }

@@ -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),
 	},
-})
+}))
@@ -1,6 +1,6 @@
 {
 	"name": "@page-agent/page-controller",
-	"version": "0.0.22",
+	"version": "0.2.2",
 	"type": "module",
 	"main": "./dist/lib/page-controller.js",
 	"module": "./dist/lib/page-controller.js",
@@ -32,6 +32,20 @@ export interface PageControllerConfig extends dom.DomConfig {
 	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 {
 	success: boolean
 	message: string
@@ -93,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
 	 */
@@ -137,10 +115,43 @@ export class PageController extends EventTarget {
 	}

 	/**
-	 * Get the viewport expansion setting
+	 * Get structured browser state for LLM consumption.
+	 * Automatically calls updateTree() to refresh the DOM state.
 	 */
-	async getViewportExpansion(): Promise<number> {
-		return this.config.viewportExpansion ?? VIEWPORT_EXPANSION
+	async getBrowserState(): Promise<BrowserState> {
+		const url = window.location.href
+		const title = document.title
+		const pi = getPageInfo()
+		const viewportExpansion = this.config.viewportExpansion ?? VIEWPORT_EXPANSION
+
+		await this.updateTree()
+
+		const content = this.simplifiedHTML
+
+		// Build header: page info + scroll position hint
+		const pageInfoLine = `Page info: ${pi.viewport_width}x${pi.viewport_height}px viewport, ${pi.page_width}x${pi.page_height}px total page size, ${pi.pages_above.toFixed(1)} pages above, ${pi.pages_below.toFixed(1)} pages below, ${pi.total_pages.toFixed(1)} total pages, at ${(pi.current_page_position * 100).toFixed(0)}% of page`
+
+		const elementsLabel =
+			viewportExpansion === -1
+				? 'Interactive elements from top layer of the current page (full page):'
+				: 'Interactive elements from top layer of the current page inside the viewport:'
+
+		const hasContentAbove = pi.pixels_above > 4
+		const scrollHintAbove =
+			hasContentAbove && viewportExpansion !== -1
+				? `... ${pi.pixels_above} pixels above (${pi.pages_above.toFixed(1)} pages) - scroll to see more ...`
+				: '[Start of page]'
+
+		const header = `${pageInfoLine}\n\n${elementsLabel}\n\n${scrollHintAbove}`
+
+		// Build footer: scroll position hint
+		const hasContentBelow = pi.pixels_below > 4
+		const footer =
+			hasContentBelow && viewportExpansion !== -1
+				? `... ${pi.pixels_below} pixels below (${pi.pages_below.toFixed(1)} pages) - scroll to see more ...`
+				: '[End of page]'
+
+		return { url, title, header, content, footer }
 	}

 	// ======= DOM Tree Operations =======
@@ -287,12 +287,52 @@ export async function scrollVertically(
 			(document.documentElement as HTMLElement)

 	if (el === document.scrollingElement || el === document.documentElement || el === document.body) {
+		// Page-level scroll
+		const scrollBefore = window.scrollY
+		const scrollMax = document.documentElement.scrollHeight - window.innerHeight
+
 		window.scrollBy(0, dy)
-		return `✅ Scrolled page by ${dy}px.`
+
+		const scrollAfter = window.scrollY
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dy > 0
+				? `⚠️ Already at the bottom of the page, cannot scroll down further.`
+				: `⚠️ Already at the top of the page, cannot scroll up further.`
+		}
+
+		const reachedBottom = dy > 0 && scrollAfter >= scrollMax - 1
+		const reachedTop = dy < 0 && scrollAfter <= 1
+
+		if (reachedBottom) return `✅ Scrolled page by ${scrolled}px. Reached the bottom of the page.`
+		if (reachedTop) return `✅ Scrolled page by ${scrolled}px. Reached the top of the page.`
+		return `✅ Scrolled page by ${scrolled}px.`
 	} else {
+		// Container scroll
+		const scrollBefore = el!.scrollTop
+		const scrollMax = el!.scrollHeight - el!.clientHeight
+
 		el!.scrollBy({ top: dy, behavior: 'smooth' })
-		await waitFor(0.1) // Animation playback
-		return `✅ Scrolled container (${el!.tagName}) by ${dy}px.`
+		await waitFor(0.1)
+
+		const scrollAfter = el!.scrollTop
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dy > 0
+				? `⚠️ Already at the bottom of container (${el!.tagName}), cannot scroll down further.`
+				: `⚠️ Already at the top of container (${el!.tagName}), cannot scroll up further.`
+		}
+
+		const reachedBottom = dy > 0 && scrollAfter >= scrollMax - 1
+		const reachedTop = dy < 0 && scrollAfter <= 1
+
+		if (reachedBottom)
+			return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the bottom.`
+		if (reachedTop)
+			return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the top.`
+		return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px.`
 	}
 }

@@ -410,11 +450,52 @@ export async function scrollHorizontally(
 			(document.documentElement as HTMLElement)

 	if (el === document.scrollingElement || el === document.documentElement || el === document.body) {
+		// Page-level scroll
+		const scrollBefore = window.scrollX
+		const scrollMax = document.documentElement.scrollWidth - window.innerWidth
+
 		window.scrollBy(dx, 0)
-		return `✅ Scrolled page horizontally by ${dx}px`
+
+		const scrollAfter = window.scrollX
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dx > 0
+				? `⚠️ Already at the right edge of the page, cannot scroll right further.`
+				: `⚠️ Already at the left edge of the page, cannot scroll left further.`
+		}
+
+		const reachedRight = dx > 0 && scrollAfter >= scrollMax - 1
+		const reachedLeft = dx < 0 && scrollAfter <= 1
+
+		if (reachedRight)
+			return `✅ Scrolled page by ${scrolled}px. Reached the right edge of the page.`
+		if (reachedLeft) return `✅ Scrolled page by ${scrolled}px. Reached the left edge of the page.`
+		return `✅ Scrolled page horizontally by ${scrolled}px.`
 	} else {
+		// Container scroll
+		const scrollBefore = el!.scrollLeft
+		const scrollMax = el!.scrollWidth - el!.clientWidth
+
 		el!.scrollBy({ left: dx, behavior: 'smooth' })
-		await waitFor(0.1) // Animation playback
-		return `✅ Scrolled container (${el!.tagName}) horizontally by ${dx}px`
+		await waitFor(0.1)
+
+		const scrollAfter = el!.scrollLeft
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dx > 0
+				? `⚠️ Already at the right edge of container (${el!.tagName}), cannot scroll right further.`
+				: `⚠️ Already at the left edge of container (${el!.tagName}), cannot scroll left further.`
+		}
+
+		const reachedRight = dx > 0 && scrollAfter >= scrollMax - 1
+		const reachedLeft = dx < 0 && scrollAfter <= 1
+
+		if (reachedRight)
+			return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the right edge.`
+		if (reachedLeft)
+			return `✅ Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the left edge.`
+		return `✅ Scrolled container (${el!.tagName}) horizontally by ${scrolled}px.`
 	}
 }
@@ -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)
@@ -30,6 +30,10 @@ export default defineConfig({
 		outDir: resolve(__dirname, 'dist', 'lib'),
 		rollupOptions: {
 			external: ['@page-agent/*', 'ai-motion'],
+			onwarn: function (message, handler) {
+				if (message.code === 'EVAL') return
+				handler(message)
+			},
 		},
 		minify: false,
 		sourcemap: true,
@@ -1,6 +1,6 @@
 {
 	"name": "@page-agent/ui",
-	"version": "0.0.22",
+	"version": "0.2.2",
 	"type": "module",
 	"main": "./dist/lib/page-agent-ui.js",
 	"module": "./dist/lib/page-agent-ui.js",
@@ -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(
@@ -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}
@@ -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[] = []
@@ -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: '收起历史',
@@ -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, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#039;')
+}
@@ -1,10 +1,10 @@
 {
 	"name": "@page-agent/website",
 	"private": true,
-	"version": "0.0.22",
+	"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"
@@ -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"
@@ -1,3 +1,15 @@
-export const CDN_URL = 'https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js'
-export const CDN_CN_URL =
-	'https://registry.npmmirror.com/page-agent/latest/files/dist/umd/page-agent.js'
+// Demo build (auto-init with demo LLM, for quick testing)
+export const CDN_DEMO_URL = 'https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js'
+export const CDN_DEMO_CN_URL =
+	'https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js'
+
+// Full build (exports PageAgent class, usage identical to npm)
+export const CDN_FULL_URL = 'https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.js'
+export const CDN_FULL_CN_URL =
+	'https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.js'
+
+// Demo LLM for website testing
+export const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+export const DEMO_BASE_URL =
+	'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
+export const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
@@ -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
@@ -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) {
-			pageAgent = win.pageAgent
-		} else {
-			pageAgent = new PageAgent({
+		// Lazy load PageAgent only when user clicks execute
+		if (!win.pageAgent || win.pageAgent.disposed) {
+			const { PageAgent } = await import('page-agent')
+			win.pageAgent = new PageAgent({
 				// 把 react 根元素排除掉，挂了很多冒泡时间导致假阳
 				interactiveBlacklist: [document.getElementById('root')!],
 				language: i18n.language as any,
@@ -73,19 +77,22 @@ export default function HomePage() {
 					},
 				},

-				// experimentalScriptExecutionTool: true,
-
-				// testing server
-				// @note: rate limit. prompt limit.
-				// model: DEMO_MODEL,
-				// baseURL: DEMO_BASE_URL,
-				// apiKey: DEMO_API_KEY,
+				model:
+					import.meta.env.DEV && import.meta.env.LLM_MODEL_NAME
+						? import.meta.env.LLM_MODEL_NAME
+						: DEMO_MODEL,
+				baseURL:
+					import.meta.env.DEV && import.meta.env.LLM_BASE_URL
+						? import.meta.env.LLM_BASE_URL
+						: DEMO_BASE_URL,
+				apiKey:
+					import.meta.env.DEV && import.meta.env.LLM_API_KEY
+						? import.meta.env.LLM_API_KEY
+						: DEMO_API_KEY,
 			})
-			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">
@@ -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',
@@ -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>
-			<BetaNotice />
+		<div className="space-y-10">
+			<header>
+				<h1 className="text-4xl font-bold mb-4">{isZh ? 'CDN 引入' : 'CDN Setup'}</h1>
+				<p className="text-lg text-gray-600 dark:text-gray-300 leading-relaxed">
+					{isZh
+						? 'CDN 提供两种构建版本：Demo 版用于快速体验，标准版用法与 NPM 一致。'
+						: 'CDN provides two builds: Demo for quick testing, standard build with usage identical to NPM.'}
+				</p>
+			</header>

-			<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">
-				{isZh
-					? '通过 CDN 快速集成 page-agent，无需复杂的构建配置。默认使用演示模型。'
-					: 'Fastest way to integrate page-agent via CDN. No complex build setup needed. Demo model will be used by default.'}
-			</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>
+				<p className="text-gray-600 dark:text-gray-300 mb-3">
+					{isZh
+						? '自动初始化并使用内置 Demo LLM，无需任何配置：'
+						: 'Auto-initializes with built-in demo LLM, no configuration needed:'}
+				</p>

 				<CodeEditor
-					className="mb-6"
-					code={`<script
-  src="${CDN_URL}"
-  crossorigin="true"
-  type="text/javascript"
-></script>`}
+					className="mb-3"
+					code={`<script src="${CDN_DEMO_URL}" crossorigin="true"></script>`}
 				/>
+
+				<div className="bg-yellow-50 dark:bg-yellow-900/20 px-4 py-3 rounded-lg mb-4 text-sm">
+					<span className="text-yellow-800 dark:text-yellow-200">
+						⚠️{' '}
+						{isZh
+							? '仅用于技术评估，Demo 模型有速率限制。'
+							: 'For evaluation only. Demo model has rate limits.'}
+					</span>
+				</div>
+
+				<table className="w-full border-collapse text-sm">
+					<thead>
+						<tr className="border-b border-gray-200 dark:border-gray-700">
+							<th className="text-left py-2 px-3 font-semibold w-28">
+								{isZh ? '位置' : 'Location'}
+							</th>
+							<th className="text-left py-2 px-3 font-semibold">URL</th>
+						</tr>
+					</thead>
+					<tbody>
+						<tr className="border-b border-gray-100 dark:border-gray-800">
+							<td className="py-2 px-3">{isZh ? '全球' : 'Global'}</td>
+							<td className="py-2 px-3 font-mono text-xs break-all">{CDN_DEMO_URL}</td>
+						</tr>
+						<tr>
+							<td className="py-2 px-3">{isZh ? '中国' : 'China'}</td>
+							<td className="py-2 px-3 font-mono text-xs break-all">{CDN_DEMO_CN_URL}</td>
+						</tr>
+					</tbody>
+				</table>
 			</section>

-			<section className="mb-8">
-				<div className="bg-yellow-50 dark:bg-yellow-900/20 p-4 rounded-lg">
-					<h3 className="text-lg font-semibold mb-2 text-yellow-900 dark:text-yellow-300">
-						⚠️ {isZh ? '注意事项' : 'Notes'}
-					</h3>
-					<ul className="text-gray-600 dark:text-gray-300 space-y-1">
-						<li>
-							• {isZh ? '生产环境建议使用固定版本号' : 'Use fixed version number in production'}
-						</li>
-						<li>• {isZh ? '确保 HTTPS 环境下使用' : 'Ensure HTTPS environment'}</li>
-						<li>
-							•{' '}
-							{isZh
-								? '配置 CSP 策略允许脚本执行'
-								: 'Configure CSP policy to allow script execution'}
-						</li>
-					</ul>
-				</div>
+			{/* CDN Build Section */}
+			<section>
+				<h2 className="text-2xl font-bold mb-3">{isZh ? '📦 标准版' : '📦 Standard Build'}</h2>
+
+				<p className="text-gray-600 dark:text-gray-300 mb-3">
+					{isZh
+						? '将 PageAgent 类暴露到 globalThis，用法与 NPM 一致：'
+						: 'Exposes PageAgent class to globalThis, usage identical to NPM:'}
+				</p>
+
+				<CodeEditor
+					className="mb-4"
+					code={`<script src="${CDN_FULL_URL}" crossorigin="true"></script>
+<script>
+const agent = new PageAgent({
+  model: 'deepseek-chat',
+  baseURL: 'https://api.deepseek.com',
+  apiKey: 'YOUR_API_KEY',
+})
+await agent.execute('Click the submit button')
+</script>`}
+				/>
+
+				<table className="w-full border-collapse text-sm">
+					<thead>
+						<tr className="border-b border-gray-200 dark:border-gray-700">
+							<th className="text-left py-2 px-3 font-semibold w-28">
+								{isZh ? '位置' : 'Location'}
+							</th>
+							<th className="text-left py-2 px-3 font-semibold">URL</th>
+						</tr>
+					</thead>
+					<tbody>
+						<tr className="border-b border-gray-100 dark:border-gray-800">
+							<td className="py-2 px-3">{isZh ? '全球' : 'Global'}</td>
+							<td className="py-2 px-3 font-mono text-xs break-all">{CDN_FULL_URL}</td>
+						</tr>
+						<tr>
+							<td className="py-2 px-3">{isZh ? '中国' : 'China'}</td>
+							<td className="py-2 px-3 font-mono text-xs break-all">{CDN_FULL_CN_URL}</td>
+						</tr>
+					</tbody>
+				</table>
+			</section>
+
+			{/* Tips */}
+			<section className="bg-blue-50 dark:bg-blue-900/20 p-4 rounded-lg">
+				<h3 className="text-base font-semibold mb-2 text-blue-900 dark:text-blue-300">
+					💡 {isZh ? '提示' : 'Tips'}
+				</h3>
+				<ul className="text-gray-600 dark:text-gray-300 text-sm space-y-1">
+					<li>• {isZh ? '生产环境推荐使用 NPM' : 'NPM is recommended for production'}</li>
+					<li>• {isZh ? '生产环境建议锁定版本号' : 'Lock version number in production'}</li>
+					<li>• {isZh ? '确保 HTTPS 环境' : 'Ensure HTTPS environment'}</li>
+				</ul>
 			</section>
 		</div>
 	)
@@ -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>
-							<p className="text-sm font-medium mb-2">{t('quick_start.step1_cdn')}</p>
-							<CodeEditor
-								code={`// CDN: \t${CDN_URL}
-// Mirror: \t${CDN_CN_URL}
-<script src="${CDN_URL}" crossorigin="true" type="text/javascript"></script>`}
-								language="html"
-							/>
-						</div>
-						<div>
-							<p className="text-sm font-medium mb-2">{t('quick_start.step1_npm')}</p>
-							<CodeEditor
-								code={`// npm install page-agent
-import PageAgent from 'page-agent'`}
-								language="bash"
-							/>
-						</div>
+					<div className="bg-yellow-50 dark:bg-yellow-900/20 p-2 rounded mb-3 text-sm">
+						<span className="text-yellow-800 dark:text-yellow-200">
+							⚠️ {isZh ? '仅用于技术评估' : 'For evaluation only'}
+						</span>
 					</div>
+					<CodeEditor
+						code={`// Global: ${CDN_DEMO_URL}
+// China:  ${CDN_DEMO_CN_URL}
+<script src="${isZh ? CDN_DEMO_CN_URL : CDN_DEMO_URL}" crossorigin="true"></script>`}
+						language="html"
+					/>
 				</div>

+				{/* NPM - Recommended */}
 				<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
 					<h3 className="text-lg font-semibold mb-2 text-green-900 dark:text-green-300">
-						{t('quick_start.step2_title')}
+						{isZh ? '📦 NPM 安装（推荐）' : '📦 NPM Install (Recommended)'}
 					</h3>
 					<CodeEditor
-						code={`// 仅供测试使用，生产环境需要配置 LLM 接入点，本工具不提供 LLM 服务
-// 测试接口
-// @note: 限流，限制 prompt 内容，限制来源，随时变更，请替换成你自己的
-// @note: 使用 DeepSeek-chat(3.2) 官方版本，使用协议和隐私策略见 DeepSeek 网站
-const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+						code={`npm install page-agent

-const agent = new PageAgent({
-  model: DEMO_MODEL,
-  baseURL: DEMO_BASE_URL,
-  apiKey: DEMO_API_KEY,
-  language: 'zh-CN'
-})`}
-						language="javascript"
+import { PageAgent } from 'page-agent'`}
+						language="bash"
 					/>
 				</div>

 				<div className="p-4 bg-purple-50 dark:bg-purple-900/20 rounded-lg">
 					<h3 className="text-lg font-semibold mb-2 text-purple-900 dark:text-purple-300">
+						{t('quick_start.step2_title')}
+					</h3>
+					<CodeEditor
+						code={`const agent = new PageAgent({
+  model: 'deepseek-chat',
+  baseURL: 'https://api.deepseek.com',
+  apiKey: 'YOUR_API_KEY',
+  language: '${isZh ? 'zh-CN' : 'en-US'}'
+})`}
+						language="javascript"
+					/>
+				</div>
+
+				<div className="p-4 bg-orange-50 dark:bg-orange-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-orange-900 dark:text-orange-300">
 						{t('quick_start.step3_title')}
 					</h3>
 					<CodeEditor
-						code={`// 程序化执行自然语言指令
-await pageAgent.execute('点击提交按钮，然后填写用户名为张三');
+						code={`// ${isZh ? '程序化执行自然语言指令' : 'Execute natural language instructions programmatically'}
+await agent.execute('${isZh ? '点击提交按钮，然后填写用户名为张三' : 'Click submit button, then fill username as John'}');

-// 或者显示对话框让用户输入指令
-pageAgent.panel.show()
+// ${isZh ? '或者显示对话框让用户输入指令' : 'Or show panel for user to input instructions'}
+agent.panel.show()
 `}
 						language="javascript"
 					/>
@@ -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'
-import CustomTools from './pages/docs/features/custom-tools/page'
-import DataMasking from './pages/docs/features/data-masking/page'
-import Models from './pages/docs/features/models/page'
-// Integration pages
-import BestPractices from './pages/docs/integration/best-practices/page'
-import CdnSetup from './pages/docs/integration/cdn-setup/page'
-import Configuration from './pages/docs/integration/configuration/page'
-import SecurityPermissions from './pages/docs/integration/security-permissions/page'
-import ThirdPartyAgent from './pages/docs/integration/third-party-agent/page'
-// Introduction pages
-import Limitations from './pages/docs/introduction/limitations/page'
-import Overview from './pages/docs/introduction/overview/page'
-import QuickStart from './pages/docs/introduction/quick-start/page'
+
+// Lazy load pages
+const HomePage = lazy(() => import('./pages/Home'))
+// Introduction
+const Overview = lazy(() => import('./pages/docs/introduction/overview/page'))
+const QuickStart = lazy(() => import('./pages/docs/introduction/quick-start/page'))
+const Limitations = lazy(() => import('./pages/docs/introduction/limitations/page'))
+// Features
+const CustomTools = lazy(() => import('./pages/docs/features/custom-tools/page'))
+const DataMasking = lazy(() => import('./pages/docs/features/data-masking/page'))
+const Instructions = lazy(() => import('./pages/docs/features/custom-instructions/page'))
+const Models = lazy(() => import('./pages/docs/features/models/page'))
+// Integration
+const CdnSetup = lazy(() => import('./pages/docs/integration/cdn-setup/page'))
+const SecurityPermissions = lazy(() => import('./pages/docs/integration/security-permissions/page'))
+const Configuration = lazy(() => import('./pages/docs/integration/configuration/page'))
+const BestPractices = lazy(() => import('./pages/docs/integration/best-practices/page'))
+const ThirdPartyAgent = lazy(() => import('./pages/docs/integration/third-party-agent/page'))
+
+function DocsPage({ children }: { children: React.ReactNode }) {
+	return (
+		<div className="min-h-screen bg-white dark:bg-gray-900">
+			<Header />
+			<DocsLayout>
+				<Suspense>{children}</Suspense>
+			</DocsLayout>
+		</div>
+	)
+}

 export default function Router() {
 	return (
-		<Switch>
-			{/* Home page */}
-			<Route path="/" component={HomePage} />
+		<Suspense>
+			<Switch>
+				{/* Home page */}
+				<Route path="/">
+					<HomePage />
+				</Route>

-			{/* Documentation pages with layout */}
-			<Route path="/docs/introduction/overview">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
+				{/* Introduction */}
+				<Route path="/docs/introduction/overview">
+					<DocsPage>
 						<Overview />
-					</DocsLayout>
-				</div>
-			</Route>
-
-			<Route path="/docs/introduction/quick-start">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
+					</DocsPage>
+				</Route>
+				<Route path="/docs/introduction/quick-start">
+					<DocsPage>
 						<QuickStart />
-					</DocsLayout>
-				</div>
-			</Route>
-
-			<Route path="/docs/introduction/limitations">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
+					</DocsPage>
+				</Route>
+				<Route path="/docs/introduction/limitations">
+					<DocsPage>
 						<Limitations />
-					</DocsLayout>
-				</div>
-			</Route>
+					</DocsPage>
+				</Route>

-			<Route path="/docs/features/custom-tools">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
+				{/* Features */}
+				<Route path="/docs/features/custom-tools">
+					<DocsPage>
 						<CustomTools />
-					</DocsLayout>
-				</div>
-			</Route>
-
-			<Route path="/docs/features/data-masking">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
+					</DocsPage>
+				</Route>
+				<Route path="/docs/features/data-masking">
+					<DocsPage>
 						<DataMasking />
-					</DocsLayout>
-				</div>
-			</Route>
-
-			<Route path="/docs/features/custom-instructions">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
+					</DocsPage>
+				</Route>
+				<Route path="/docs/features/custom-instructions">
+					<DocsPage>
 						<Instructions />
-					</DocsLayout>
-				</div>
-			</Route>
-
-			<Route path="/docs/features/models">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
+					</DocsPage>
+				</Route>
+				<Route path="/docs/features/models">
+					<DocsPage>
 						<Models />
-					</DocsLayout>
-				</div>
-			</Route>
+					</DocsPage>
+				</Route>

-			<Route path="/docs/integration/cdn-setup">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
+				{/* Integration */}
+				<Route path="/docs/integration/cdn-setup">
+					<DocsPage>
 						<CdnSetup />
-					</DocsLayout>
-				</div>
-			</Route>
-
-			<Route path="/docs/integration/security-permissions">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
+					</DocsPage>
+				</Route>
+				<Route path="/docs/integration/security-permissions">
+					<DocsPage>
 						<SecurityPermissions />
-					</DocsLayout>
-				</div>
-			</Route>
-
-			<Route path="/docs/integration/configuration">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
+					</DocsPage>
+				</Route>
+				<Route path="/docs/integration/configuration">
+					<DocsPage>
 						<Configuration />
-					</DocsLayout>
-				</div>
-			</Route>
-
-			<Route path="/docs/integration/best-practices">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
+					</DocsPage>
+				</Route>
+				<Route path="/docs/integration/best-practices">
+					<DocsPage>
 						<BestPractices />
-					</DocsLayout>
-				</div>
-			</Route>
-
-			<Route path="/docs/integration/third-party-agent">
-				<div className="min-h-screen bg-white dark:bg-gray-900">
-					<Header />
-					<DocsLayout>
+					</DocsPage>
+				</Route>
+				<Route path="/docs/integration/third-party-agent">
+					<DocsPage>
 						<ThirdPartyAgent />
-					</DocsLayout>
-				</div>
-			</Route>
+					</DocsPage>
+				</Route>

-			{/* 404 page */}
-			<Route>
-				<div className="min-h-screen bg-white dark:bg-gray-900 flex items-center justify-center">
-					<div className="text-center">
-						<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>
+				{/* 404 */}
+				<Route>
+					<div className="min-h-screen bg-white dark:bg-gray-900 flex items-center justify-center">
+						<div className="text-center">
+							<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>
+						</div>
 					</div>
-				</div>
-			</Route>
-		</Switch>
+				</Route>
+			</Switch>
+		</Suspense>
 	)
 }
@@ -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),
-		'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),
+		...(mode === 'development' && {
+			'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),
+		}),
+		'import.meta.env.VERSION': JSON.stringify(pageAgentPkg.version),
 	},
-})
+}))
Author	SHA1	Message	Date
Simon	a1b485691f	chore(version): bump version to 0.2.2	2026-01-17 00:59:55 +08:00
Simon	694e05b800	chore: npm audit fix	2026-01-17 00:54:20 +08:00
Simon	b761795c1a	feat!: local iife testing BREAKING CHANGES: remove umd build from npm package and cdn	2026-01-16 19:04:26 +08:00
Simon	8cc54983aa	chore(version): bump version to 0.2.1	2026-01-16 16:16:18 +08:00
Simon	59a599285e	Merge pull request #115 from alibaba/fix/phantom-panel fix(panel): hide panel by default	2026-01-16 16:15:43 +08:00
Simon	2f8c2b395c	fix(panel): hide panel by default	2026-01-16 16:06:57 +08:00
Simon	28f836674c	feat: edge feedback for scroll actions	2026-01-16 15:53:47 +08:00
Simon	6f01632231	fix(website): build error	2026-01-16 15:09:30 +08:00
Simon	41123ac561	chore(website): optimize bundle size	2026-01-16 15:05:09 +08:00
Simon	c8bf0dd20f	chore: get rid of build warnings	2026-01-16 14:50:56 +08:00
Simon	ec2b744bab	Merge pull request #114 from alibaba/feat/user-takeover feat: remove `pause`	2026-01-15 21:51:01 +08:00
Simon	eab9cf64e8	feat: includes history events in panel	2026-01-15 21:48:14 +08:00
Simon	42130d6f1d	feat: remove `pause`	2026-01-15 21:37:03 +08:00
Simon	c0ce6e7d14	chore(version): bump version to 0.2.0	2026-01-15 20:47:39 +08:00
Simon	8f5f98f889	feat(agent)!: rename `brain` to `reflection`; fix `undefined` lines in panel	2026-01-15 20:45:40 +08:00
Simon	ee4719cdcf	feat: observation	2026-01-15 20:28:39 +08:00
Simon	b4c82b7833	refactor: mv `getBrowserState` to `Controller`; simplify `Agent`	2026-01-15 20:17:50 +08:00
Simon	aefc3cfb89	Merge pull request #111 from alibaba/feat/extend-agent-history-for-observation feat: extend history type	2026-01-15 19:57:41 +08:00
Simon	7f2b8c2766	feat: extend history type	2026-01-15 19:18:25 +08:00
Simon	62e24a3050	chore(version): bump version to 0.1.0	2026-01-14 18:50:06 +08:00
Simon	4f6249a252	feat!: require user to provide LLM api. do not fallback to demo LLM BREAKING CHANGE: LLM API will be required for agent constructor	2026-01-14 18:49:23 +08:00
Simon	62519416bb	chore(version): bump version to 0.0.24	2026-01-14 18:34:55 +08:00
Simon	a1e70e663d	feat(PageController): exclude `aria-hidden` elements	2026-01-14 18:04:31 +08:00
Simon	338e317be1	chore(website): fix homepage overflow	2026-01-14 17:45:49 +08:00
Simon	9a66d5205f	feat(website): display version in header and load from page-agent package	2026-01-14 17:42:18 +08:00
Simon	7d45bf6598	feat(website): update CDN links and usage	2026-01-14 17:27:35 +08:00
Simon	78ee72eea4	chore(version): bump version to 0.0.23	2026-01-14 15:46:10 +08:00
Simon	3b71c535b1	fix: clean up debug code	2026-01-14 15:23:02 +08:00
Simon	6615f7b300	Merge pull request #110 from alibaba/fix/panel-text-uncompleted feat: add HTML escaping to Panel	2026-01-14 15:17:43 +08:00
Simon	38caae5e23	feat: add HTML escaping to Panel	2026-01-14 15:15:51 +08:00