chore(version): bump version to 0.2.2

BREAKING CHANGES: remove umd build from npm package and cdn

.github/workflows/ci.yml

@@ -13,10 +13,10 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20, 22]
+        node-version: [20, 24, 25]
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Setup Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v6
@@ -24,6 +24,13 @@ jobs:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'
 
+      # test on default version of npm
+      # - 9.6~10.8 on node@20
+      # - 11.3~11.6 on node@24
+
+      - name: Node and NPM version
+        run: node --version && npm --version
+
       - name: Install dependencies
         run: npm install
 

.github/workflows/deploy-demo.yml

@@ -13,19 +13,19 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 24
           cache: 'npm'
 
       - name: Install dependencies
         run: npm ci
 
       - name: Build demo
-        run: npm run build
+        run: npm run build:website
 
       - name: Setup Pages
         uses: actions/configure-pages@v5

.github/workflows/release.yml

@@ -13,12 +13,12 @@ jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 24
           registry-url: 'https://registry.npmjs.org'
 
       # Ensure npm 11.5.1 or later is installed
@@ -29,7 +29,7 @@ jobs:
         run: npm ci
 
       - name: Build
-        run: npm run build:lib
+        run: npm run build:libs
 
-      - name: Publish to npm
+      - name: Publish all public packages
-        run: npm publish --workspace=page-agent
+        run: npm publish --workspaces --access public

.gitignore

@@ -23,6 +23,7 @@ dist-ssr
 *.njsproj
 *.sln
 *.sw?
+.qoder
 
 
 # 

.husky/pre-commit

@@ -1 +1 @@
-npx lint-staged
+npx lint-staged --allow-empty

.vscode/extensions.json

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

.vscode/settings.json

@@ -1,6 +1,17 @@
 {
 	"editor.fontLigatures": true,
-	"cSpell.words": ["HITL", "innerhtml", "opensource", "retryable", "wouter"],
+	"cSpell.words": [
+		"deepseek",
+		"HITL",
+		"innerhtml",
+		"llms",
+		"onwarn",
+		"opensource",
+		"qwen",
+		"retryable",
+		"shadcn",
+		"wouter"
+	],
 	"markdownlint.config": {
 		// "comment": "Relaxed rules",
 		"default": true,

AGENTS.md

@@ -1,182 +1,131 @@
-# Instructions for coding assistants
+# Instructions for Coding Assistants
 
 ## Project Overview
 
-This is a **monorepo** with npm workspaces containing **two main packages**:
+This is a **monorepo** with npm workspaces:
 
-1. **Core Library** (`packages/page-agent/`) - Pure JavaScript/TypeScript AI agent library for browser DOM automation, published as `page-agent` on npm
+- **Core Library** (`packages/page-agent/`) - AI agent 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`
+- **Website** (`packages/website/`) - React docs and landing page. **When working on website, follow `packages/website/AGENTS.md`**
+
+Internal packages:
+
+- **CDN** (`packages/cdn/`) - IIFE builds for script tag usage (npm: `@page-agent/cdn`)
+- **LLMs** (`packages/llms/`) - LLM client with reflection-before-action mental model
+- **Page Controller** (`packages/page-controller/`) - DOM operations and visual feedback (SimulatorMask), independent of LLM
+- **UI** (`packages/ui/`) - Panel and i18n. Decoupled from PageAgent
 
 ## Development Commands
 
-### Core Commands
-
 ```bash
 npm start                    # Start website dev server
-npm run dev                  # Same as start
 npm run build                # Build all packages
-npm run build:lib            # Build page-agent library only
+npm run build:libs           # Build all libraries
 npm run lint                 # ESLint with TypeScript strict rules
 ```
 
-### Package-specific Commands
+## Architecture
-
-```bash
-# Core library
-npm run build --workspace=page-agent
-npm run build:watch --workspace=page-agent
-
-# Website
-npm run dev --workspace=@page-agent/website
-npm run build --workspace=@page-agent/website
-```
-
-## Architecture & Critical Patterns
 
 ### Monorepo Structure
 
+Simple monorepo solution: TypeScript references + Vite aliases. Update tsconfig and vite config when adding/removing packages.
+
 ```
 packages/
-├── page-agent/              # npm: "page-agent"
+├── page-agent/              # npm: "page-agent" ⭐ MAIN
-│   ├── src/                 # Core library source
+├── cdn/                     # npm: "@page-agent/cdn" (IIFE builds)
-│   ├── vite.config.js       # Library build (ES + UMD)
+├── website/                 # @page-agent/website (private)
-│   └── package.json
+├── llms/                    # @page-agent/llms
-└── website/                 # npm: "@page-agent/website" (private)
+├── page-controller/         # @page-agent/page-controller
-    ├── src/                 # Website source (formerly pages/)
+└── ui/                      # @page-agent/ui
-    ├── index.html
-    ├── vite.config.js       # Website build
-    └── package.json
 ```
 
-### Module Boundaries (Critical)
+`workspaces` in `package.json` must be in topological order.
 
-- **Core library** (`packages/page-agent/`): NEVER import from website - must remain pure JavaScript
+### Module Boundaries
-- **Website** (`packages/website/`): CAN import from `page-agent` for demos. Alias `@/` → `website/src/`
+
+- **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 and i18n. No dependency on page-agent
+- **Page Controller**: DOM operations with optional visual feedback (SimulatorMask). No LLM dependency. Enable mask via `enableMask: true` config
+
+### PageController ↔ PageAgent Communication
+
+All communication is async and isolated:
+
+```typescript
+// PageAgent delegates DOM operations to PageController
+await this.pageController.updateTree()
+await this.pageController.clickElement(index)
+await this.pageController.inputText(index, text)
+await this.pageController.scroll({ down: true, numPages: 1 })
+
+// PageController exposes state via async methods
+const simplifiedHTML = await this.pageController.getSimplifiedHTML()
+const pageInfo = await this.pageController.getPageInfo()
+```
 
 ### DOM Pipeline
 
-1. **DOM Extraction**: Convert live DOM to `FlatDomTree` via `src/dom/dom_tree/`
+1. **DOM Extraction**: Live DOM → `FlatDomTree` via `page-controller/src/dom/dom_tree/`
-2. **Dehydration**: DOM tree → simplified text for LLM processing
+2. **Dehydration**: DOM tree → simplified text for LLM
-3. **LLM Processing**: AI model returns action plans
+3. **LLM Processing**: AI returns action plans (page-agent)
-4. **Indexed Operations**: Map LLM responses back to specific DOM elements
+4. **Indexed Operations**: PageAgent calls PageController by element index
 
-### Event Bus Communication
+### CDN Builds (`packages/cdn/`)
 
-Use `src/utils/bus.ts` for decoupled PageAgent ↔ UI communication:
+Two IIFE builds for script tag usage:
 
-```typescript
+| Build | File                 | Description                      |
-// Emit from PageAgent
+| ----- | -------------------- | -------------------------------- |
-getEventBus().emit('panel:show')
+| Demo  | `page-agent.demo.js` | Auto-init with built-in test API |
-getEventBus().emit('panel:update', { status: 'thinking' })
+| Full  | `page-agent.js`      | Exposes `PageAgent` class only   |
 
-// Listen in UI components
+Demo build supports query params (e.g., `?model=gpt-4&lang=en-US`).
-getEventBus().on('panel:show', () => panel.show())
-```
 
-### Hash Routing Requirement
+## Key Files Reference
 
-Uses wouter with `useHashLocation` for static hosting:
+### Page Agent (`packages/page-agent/`)
 
-```tsx
+| File               | Description                             |
-<Router hook={useHashLocation}>  // Always hash-based routes
+| ------------------ | --------------------------------------- |
-```
+| `src/PageAgent.ts` | ⭐ Main AI agent class                  |
+| `src/umd.ts`       | CDN/UMD entry with auto-init            |
+| `src/tools/`       | Tool definitions calling PageController |
 
-### CDN Auto-Injection Pattern
+### LLMs (`packages/llms/`)
 
-Library auto-initializes when injected via script tag:
+| File                         | Description                           |
+| ---------------------------- | ------------------------------------- |
+| `src/index.ts`               | ⭐ LLM class with retry logic         |
+| `src/types.ts`               | MacroToolInput, AgentBrain, LLMConfig |
+| `src/OpenAILenientClient.ts` | OpenAI-compatible client              |
 
-```html
+### Page Controller (`packages/page-controller/`)
-<script src="page-agent.js?model=gpt-4"></script>
-```
 
-Query params configure `PageAgentConfig` automatically in `src/entry.ts`.
+| File                        | Description                                                |
-
+| --------------------------- | ---------------------------------------------------------- |
-## File Organization
+| `src/PageController.ts`     | ⭐ Main controller class with optional mask support        |
-
+| `src/SimulatorMask.ts`      | Visual overlay blocking user interaction during automation |
-### Core Library (`packages/page-agent/src/`)
+| `src/actions.ts`            | Element interactions (click, input, scroll)                |
-
+| `src/dom/dom_tree/index.js` | Core DOM extraction engine                                 |
-- `entry.ts` - CDN/UMD entry point with auto-initialization
-- `PageAgent.ts` - **Main AI agent class** orchestrating DOM operations
-- `tools/` - Agent tool implementations for web actions
-- `ui/` - UI components (Panel, SimulatorMask) with CSS modules
-- `utils/bus.ts` - **Type-safe event bus** for decoupled communication
-- `patches/` - Framework-specific optimizations (React, Antd compatibility)
-- `llms/` - LLM integration and communication layer
-- `dom/` - HTML serialization and page analysis utilities
-- `config/` - Configuration constants and settings
-
-### Website (`packages/website/src/`)
-
-- `main.tsx` - Site entry with hash routing setup
-- `router.tsx` - **Manual route definitions** (requires explicit registration)
-- `components/DocsLayout.tsx` - Navigation structure (hardcoded nav items)
-- `docs/[section]/[topic]/page.tsx` - Documentation pages
-- `test-pages/` - Library integration test pages
 
 ## Adding New Features
 
-### New Documentation Page
-
-1. Create `packages/website/src/docs/<section>/<slug>/page.tsx`
-2. Add route to `packages/website/src/router.tsx` with `<Header /> + <DocsLayout>` wrapper
-3. Add navigation item to `DocsLayout.tsx`
-
 ### New Agent Tool
 
-1. Implement under `packages/page-agent/src/tools/`
+1. Implement in `packages/page-agent/src/tools/index.ts`
-2. Export via `packages/page-agent/src/tools/index.ts`
+2. If tool needs DOM ops, add method to PageController first
-3. Wire into `PageAgent.ts` if needed
+3. Tool calls `this.pageController.methodName()` for DOM interactions
 
-### New UI Component
+### New PageController Action
 
-1. Create in `packages/page-agent/src/ui/` with colocated CSS modules
+1. Add implementation in `packages/page-controller/src/actions.ts`
-2. Use event bus for PageAgent communication
+2. Expose via async method in `PageController.ts`
+3. Export from `packages/page-controller/src/index.ts`
 
 ## Code Standards
 
-### TypeScript
-
 - 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
-### CSS & Styling
+- All code and comments must be in English.
-
-- **Prefer Tailwind CSS over custom CSS**
-- Custom CSS variables for theme gradients in `src/index.css`
-- Dark mode support via `dark:` classes
-- CSS modules for component-specific styles
-
-### Import Organization
-
-- External libraries first
-- Internal modules (`@/`, `@pages/`)
-- Relative imports last
-- Blank lines between groups
-
-## Critical Files to Understand
-
-- `packages/page-agent/src/PageAgent.ts` - Core AI agent class with DOM manipulation
-- `packages/page-agent/src/dom/dom_tree/index.js` - DOM extraction engine
-- `packages/page-agent/src/utils/bus.ts` - Type-safe event bus system
-- `packages/page-agent/src/entry.ts` - Library entry point for CDN usage
-- `packages/page-agent/vite.config.js` - Library build configuration
-
-- `packages/website/src/router.tsx` - Central routing definition (manual registration required)
-- `packages/website/src/components/DocsLayout.tsx` - Navigation structure
-- `packages/website/vite.config.js` - Website build configuration
-
-## Debugging Common Issues
-
-### Blank Documentation Pages
-
-1. Verify route exists in `packages/website/src/router.tsx`
-2. Check component import path
-3. Verify CSS isn't hiding content (check dark mode classes)
-4. Test with minimal component first
-
-### Library Integration Issues
-
-1. Check `packages/page-agent/dist/lib/page-agent.umd.js` builds correctly
-2. Test CDN injection with query params
-3. Verify event bus communications are properly typed
-4. Use `packages/website/src/test-pages/` for isolated testing

CONTRIBUTING.md

@@ -7,16 +7,14 @@ Thank you for your interest in contributing to Page-Agent! We welcome contributi
 ### Development Setup
 
 1. **Prerequisites**
-   - Node.js 20+
+   - `node.js >= 20` with `npm >= 10`
-   - npm 10+
+   - An editor that supports `ts/eslint/prettier`
-   - typescript as required in package.json
+   - Make sure `eslint`, `prettier` and `commitlint` work well
-   - vscode or other editors that support ts/eslint/prettier
-   - make sure `eslint`, `auto-format` and `commit-lint` all work
 
 2. **Setup**
 
    ```bash
-   npm install
+   npm ci
    npm start          # Start demo and documentation site
    ```
 
@@ -27,7 +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. 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 `IIFE` and `Website`. Bundle everything including local packages.
 
 ## 🤝 How to Contribute
 
@@ -59,10 +61,9 @@ We use a simplified monorepo solution with native npm-workspace. No fancy toolin
    - 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**
 
@@ -92,52 +93,52 @@ We use a simplified monorepo solution with native npm-workspace. No fancy toolin
 - 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`
-
-### Core Library (`src/`)
-
-- **No React dependencies** - Pure JavaScript/TypeScript only
-- Use event bus for component communication
-- Follow browser-use patterns for DOM operations
-
-### Doc&demo Site (`pages/`)
-
-- Use React 19 + TypeScript
-- Follow hash routing patterns (`useHashLocation`)
-- Use Tailwind CSS for styling
-- Add new docs pages to both router and sidebar
 
 ## 🔧 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
 
-- Config your LLM API
+- Start and serve a local `iife` script
-- Start a local script
 
-   ```bash
+  ```bash
-   npm run build:lib:watch    # Auto-rebuild on changes
+  npm run dev:iife # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.js
-   ```
+  ```
 
-- Add a new bookmark enable it on other website
+- Add a new bookmark
 
-   ```
+  ```javascript
-   javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5173/dist/lib/page-agent.umd.cjs?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
+  javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.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
+
+> Warning: AK in your local `.env` will be inlined in the iife script.
 
 ### Adding Documentation
 
-1. Create `pages/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 `pages/router.tsx`
+
-3. Add navigation link to `pages/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
 
@@ -152,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

@@ -8,7 +8,7 @@
 
 🌐 [English](./README.md) | **中文**
 
-👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a> 
+👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a>
 
 <video id="demo-video" src="https://github.com/user-attachments/assets/141bbb01-8022-4d1f-919d-9efc9a1dc1cf" width="640" crossorigin muted autoplay loop></video>
 
@@ -24,22 +24,26 @@
 
 ## 🗺️ Roadmap
 
-👉 [**Roadmap**](./ROADMAP.md)
+👉 [**Roadmap**](https://github.com/alibaba/page-agent/issues/96)
 
 ## 🚀 快速开始
 
-### CDN 集成
+### 快速体验 (Demo CDN)
+
+最快的体验方式：
 
 ```html
-<!-- 临时 CDN URL. 未来会变更 -->
+<script src="https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js" crossorigin="true"></script>
-<script
-	src="https://hwcxiuzfylggtcktqgij.supabase.co/storage/v1/object/public/demo-public/v0.0.4/page-agent.js"
-	crossorigin="true"
-	type="text/javascript"
-></script>
 ```
 
-### NPM 安装
+> ⚠️ **仅用于技术评估。** 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
@@ -48,35 +52,49 @@ npm install page-agent
 ```javascript
 import { PageAgent } from 'page-agent'
 
-// 测试接口
-// @note: 限流，限制 prompt 内容，限制来源，随时变更，请替换成你自己的
-// @note: 使用 DeepSeek-chat(3.2) 官方版本，使用协议和隐私策略见 DeepSeek 网站
-const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
 const agent = new PageAgent({
-	modelName: DEMO_MODEL,
+	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 引入
+
+适用于无法使用 NPM 的环境，用法与 NPM 一致：
+
+```html
+<script src="https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.js" crossorigin="true"></script>
+<script>
+const agent = new PageAgent({
+	model: 'deepseek-chat',
+	baseURL: 'https://api.deepseek.com',
+	apiKey: 'YOUR_API_KEY',
+})
+await agent.execute('点击登录按钮')
+</script>
+```
+
+| 位置   | URL                                                                                 |
+| ------ | ----------------------------------------------------------------------------------- |
+| 全球   | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.js                     |
+| 中国   | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.js      |
+
 ## 🏗️ 架构设计
 
-PageAgent 采用清晰的模块化架构：
+PageAgent adopts a simplified monorepo structure:
 
 ```
-src/
+packages/
-├── PageAgent.ts          # Agent 主流程
+├── page-agent/          # AI agent (npm: page-agent)
-├── dom/                  # DOM 理解
+├── llms/                # LLM 客户端 (npm: @page-agent/llms)
-├── tools/                # 代理交互工具
+├── page-controller/     # DOM 操作 & 蒙层 & 模拟鼠标 (npm: @page-agent/page-controller)
-├── ui/                   # UI 组件和面板
+├── ui/                  # 面板 & i18n (npm: @page-agent/ui)
-├── llms/                 # LLM 集成层
+├── cdn/                 # CDN IIFE builds (npm: @page-agent/cdn)
-└── utils/                # 事件总线和工具
+└── website/             # 文档站点
 ```
 
 ## 🤝 贡献

README.md

@@ -1,6 +1,6 @@
 # PageAgent 🤖🪄
 
-![banner](https://img.alicdn.com/imgextra/i1/O1CN01RY0Wvh26ATVeDIX7v_!!6000000007621-0-tps-1672-512.jpg)
+![banner](https://img.alicdn.com/imgextra/i3/O1CN01MyVCS21EoKkIHUT1s_!!6000000000398-49-tps-1280-353.webp)
 
 [![npm version](https://badge.fury.io/js/page-agent.svg)](https://badge.fury.io/js/page-agent) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) [![Downloads](https://img.shields.io/npm/dt/page-agent.svg)](https://www.npmjs.com/package/page-agent) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/page-agent)](https://bundlephobia.com/package/page-agent) [![GitHub stars](https://img.shields.io/github/stars/alibaba/page-agent.svg)](https://github.com/alibaba/page-agent)
 
@@ -8,7 +8,7 @@ The GUI Agent Living in Your Webpage. Control web interfaces with natural langua
 
 🌐 **English** | [中文](./README-zh.md)
 
-👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a> 
+👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a>
 
 <video id="demo-video" src="https://github.com/user-attachments/assets/de8d1964-8bde-494f-a52f-2975469557a5" width="640" crossorigin muted autoplay loop></video>
 
@@ -24,22 +24,26 @@ The GUI Agent Living in Your Webpage. Control web interfaces with natural langua
 
 ## 🗺️ Roadmap
 
-👉 [**Roadmap**](./ROADMAP.md)
+👉 [**Roadmap**](https://github.com/alibaba/page-agent/issues/96)
 
 ## 🚀 Quick Start
 
-### CDN Integration
+### Quick Try (Demo CDN)
+
+Fastest way to try PageAgent:
 
 ```html
-<!-- temporary CDN URL. May change in the future -->
+<script src="https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js" crossorigin="true"></script>
-<script
-	src="https://hwcxiuzfylggtcktqgij.supabase.co/storage/v1/object/public/demo-public/v0.0.4/page-agent.js"
-	crossorigin="true"
-	type="text/javascript"
-></script>
 ```
 
-### NPM Installation
+> ⚠️ **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
@@ -48,35 +52,49 @@ npm install page-agent
 ```javascript
 import { PageAgent } from 'page-agent'
 
-// test server
-// @note: rate limit. prompt limit. Origin limit. May change anytime. Use your own llm!
-// @note Using official DeepSeek-chat(3.2). Go to DeepSeek website for privacy policy.
-const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-
 const agent = new PageAgent({
-	modelName: DEMO_MODEL,
+	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 Build
+
+For environments where NPM is not available. Usage is identical to NPM:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.js" crossorigin="true"></script>
+<script>
+const agent = new PageAgent({
+	model: 'deepseek-chat',
+	baseURL: 'https://api.deepseek.com',
+	apiKey: 'YOUR_API_KEY',
+})
+await agent.execute('Click the login button')
+</script>
+```
+
+| Location | URL                                                                                 |
+| -------- | ----------------------------------------------------------------------------------- |
+| Global   | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.js                     |
+| China    | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.js      |
+
 ## 🏗️ Structure
 
-PageAgent follows a clean, modular architecture:
+PageAgent adopts a simplified monorepo structure:
 
 ```
-src/
+packages/
-├── PageAgent.ts          # Agent main loop
+├── page-agent/          # AI agent (npm: page-agent)
-├── dom/                  # DOM processing
+├── llms/                # LLM client (npm: @page-agent/llms)
-├── tools/                # Agent tools
+├── page-controller/     # DOM operations & Visual Mask (npm: @page-agent/page-controller)
-├── ui/                   # UI components & panels
+├── ui/                  # Panel & i18n (npm: @page-agent/ui)
-├── llms/                 # LLM integration layer
+├── cdn/                 # CDN IIFE builds (npm: @page-agent/cdn)
-└── utils/                # Event bus & utilities
+└── website/             # Demo & Documentation site
 ```
 
 ## 🤝 Contributing

ROADMAP.md

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

eslint.config.js

@@ -8,7 +8,7 @@ import globals from 'globals'
 import tseslint from 'typescript-eslint'
 
 export default defineConfig([
-	globalIgnores(['**/dist', '**/test-pages', '**/node_modules']),
+	globalIgnores(['**/dist', '**/node_modules', 'packages/website/src/components/ui']),
 	{
 		plugins: {
 			'react-hooks': reactHooks,
@@ -37,8 +37,10 @@ export default defineConfig([
 		],
 		languageOptions: {
 			parserOptions: {
-				project: ['./packages/*/tsconfig.json'],
+				// project: ['./tsconfig.json'],
-				tsconfigRootDir: import.meta.dirname,
+				// project: ['./packages/*/tsconfig.json'],
+				// tsconfigRootDir: import.meta.dirname,
+				projectService: true,
 			},
 			ecmaVersion: 2020,
 			globals: globals.browser,
@@ -67,6 +69,9 @@ export default defineConfig([
 			'react-dom/no-missing-button-type': 'off',
 			'react-x/no-nested-component-definitions': 'off',
 			'@typescript-eslint/prefer-optional-chain': 'off',
+
+			// 'require-await': 'off',
+			'@typescript-eslint/require-await': 'off',
 		},
 	},
 ])

package.json

@@ -1,10 +1,15 @@
 {
 	"name": "root",
 	"private": true,
-	"version": "0.0.5",
+	"version": "0.2.2",
 	"type": "module",
 	"workspaces": [
-		"packages/*"
+		"packages/page-controller",
+		"packages/ui",
+		"packages/llms",
+		"packages/page-agent",
+		"packages/cdn",
+		"packages/website"
 	],
 	"description": "AI-powered UI agent for web applications",
 	"author": "Simon<gaomeng1900>",
@@ -19,33 +24,43 @@
 		"npm": ">=10.0.0"
 	},
 	"scripts": {
-		"dev": "npm run dev --workspace=@page-agent/website",
+		"cleanup": "rm -rf packages/*/dist",
 		"start": "npm run dev --workspace=@page-agent/website",
-		"build": "npm run build --workspaces --if-present",
+		"build:website": "npm run build:website --workspace=@page-agent/website",
-		"build:lib": "npm run build --workspace=page-agent",
+		"build:libs": "npm run build --workspaces --if-present",
+		"build": "npm run build:libs && npm run build:website",
+		"dev:iife": "npm run dev:iife --workspace=page-agent",
 		"version": "node scripts/sync-version.js",
 		"lint": "eslint .",
 		"prepare": "husky"
 	},
 	"devDependencies": {
-		"@commitlint/cli": "^20.1.0",
+		"@commitlint/cli": "^20.3.1",
-		"@commitlint/config-conventional": "^20.0.0",
+		"@commitlint/config-conventional": "^20.3.1",
-		"@eslint/js": "^9.37.0",
+		"@eslint/js": "^9.39.2",
-		"@trivago/prettier-plugin-sort-imports": "^5.2.2",
+		"@microsoft/api-extractor": "^7.55.2",
+		"@trivago/prettier-plugin-sort-imports": "^6.0.2",
+		"@types/node": "^25.0.7",
+		"concurrently": "^9.2.1",
 		"dotenv": "^17.2.3",
-		"eslint": "^9.37.0",
+		"eslint": "^9.39.2",
 		"eslint-config-prettier": "^10.1.8",
-		"eslint-plugin-react-dom": "^2.3.9",
+		"eslint-plugin-react-dom": "^2.5.7",
 		"eslint-plugin-react-hooks": "^7.0.1",
-		"eslint-plugin-react-refresh": "^0.4.24",
+		"eslint-plugin-react-refresh": "^0.4.26",
-		"eslint-plugin-react-x": "^2.3.9",
+		"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.6.2",
+		"prettier": "^3.7.4",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.46.0",
+		"typescript-eslint": "^8.53.0",
-		"vite": "^7.1.9"
+		"unplugin-dts": "^1.0.0-beta.6",
+		"vite": "^7.3.1",
+		"vite-plugin-css-injected-by-js": "^3.5.2"
+	},
+	"overrides": {
+		"typescript": "^5.9.3"
 	},
 	"lint-staged": {
 		"*.{js,ts,cjs,cts,mjs,mts}": [

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/README.md

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

packages/llms/package.json

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

packages/llms/src/OpenAIClient.ts

@@ -0,0 +1,206 @@
+/**
+ * OpenAI Client implementation
+ */
+import { InvokeError, InvokeErrorType } from './errors'
+import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
+import { modelPatch, zodToOpenAITool } from './utils'
+
+/**
+ * Client for OpenAI compatible APIs
+ */
+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: Record<string, Tool>,
+		abortSignal?: AbortSignal,
+		options?: InvokeOptions
+	): Promise<InvokeResult> {
+		// 1. Convert tools to OpenAI format
+		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 this.fetch(`${this.config.baseURL}/chat/completions`, {
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/json',
+					Authorization: `Bearer ${this.config.apiKey}`,
+				},
+				body: JSON.stringify(modelPatch(requestBody)),
+				signal: abortSignal,
+			})
+		} catch (error: unknown) {
+			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
+			)
+		}
+
+		// 4. Parse and validate response
+		const data = await response.json()
+
+		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':
+			case 'function_call': // gemini
+			case 'stop': // some models use this even with tool calls
+				break
+			case 'length':
+				throw new InvokeError(
+					InvokeErrorType.CONTEXT_LENGTH,
+					'Response truncated: max tokens reached'
+				)
+			case 'content_filter':
+				throw new InvokeError(InvokeErrorType.CONTENT_FILTER, 'Content filtered by safety system')
+			default:
+				throw new InvokeError(
+					InvokeErrorType.UNKNOWN,
+					`Unexpected finish_reason: ${choice.finish_reason}`
+				)
+		}
+
+		// Apply normalizeResponse if provided (for fixing format issues automatically)
+		const normalizedData = options?.normalizeResponse ? options.normalizeResponse(data) : data
+		const normalizedChoice = (normalizedData as any).choices?.[0]
+
+		// Get tool name from response
+		const toolCallName = normalizedChoice?.message?.tool_calls?.[0]?.function?.name
+		if (!toolCallName) {
+			throw new InvokeError(
+				InvokeErrorType.NO_TOOL_CALL,
+				'No tool call found in response',
+				normalizedData
+			)
+		}
+
+		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(toolInput)
+		} catch (e) {
+			throw new InvokeError(
+				InvokeErrorType.TOOL_EXECUTION_ERROR,
+				`Tool execution failed: ${(e as Error).message}`,
+				e
+			)
+		}
+
+		// Return result
+		return {
+			toolCall: {
+				name: toolCallName,
+				args: toolInput,
+			},
+			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

@@ -0,0 +1,3 @@
+// Internal constants
+export const LLM_MAX_RETRIES = 2
+export const DEFAULT_TEMPERATURE = 0.7 // higher randomness helps auto-recovery

packages/llms/src/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

packages/llms/src/index.ts

@@ -0,0 +1,108 @@
+import { OpenAIClient } from './OpenAIClient'
+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,
+		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
+	}
+}
+
+export class LLM extends EventTarget {
+	config: Required<LLMConfig>
+	client: LLMClient
+
+	constructor(config: LLMConfig) {
+		super()
+		this.config = parseLLMConfig(config)
+
+		// Default to OpenAI client
+		this.client = new OpenAIClient(this.config)
+	}
+
+	/**
+	 * - call llm api *once*
+	 * - invoke tool call *once*
+	 * - return the result of the tool
+	 */
+	async invoke(
+		messages: Message[],
+		tools: Record<string, Tool>,
+		abortSignal: AbortSignal,
+		options?: InvokeOptions
+	): Promise<InvokeResult> {
+		return await withRetry(
+			async () => {
+				const result = await this.client.invoke(messages, tools, abortSignal, options)
+
+				return result
+			},
+			// retry settings
+			{
+				maxRetries: this.config.maxRetries,
+				onRetry: (current: number) => {
+					this.dispatchEvent(
+						new CustomEvent('retry', { detail: { current, max: this.config.maxRetries } })
+					)
+				},
+				onError: (error: Error) => {
+					this.dispatchEvent(new CustomEvent('error', { detail: { error } }))
+				},
+			}
+		)
+	}
+}
+
+async function withRetry<T>(
+	fn: () => Promise<T>,
+	settings: {
+		maxRetries: number
+		onRetry: (retries: number) => void
+		onError: (error: Error) => void
+	}
+): Promise<T> {
+	let retries = 0
+	let lastError: Error | null = null
+	while (retries <= settings.maxRetries) {
+		if (retries > 0) {
+			settings.onRetry(retries)
+			await new Promise((resolve) => setTimeout(resolve, 100))
+		}
+
+		try {
+			return await fn()
+		} catch (error: unknown) {
+			console.error(error)
+			settings.onError(error as Error)
+
+			// do not retry if aborted by user
+			if ((error as { name?: string })?.name === 'AbortError') throw error
+
+			// do not retry if error is not retryable (InvokeError)
+			if (error instanceof InvokeError && !error.retryable) throw error
+
+			lastError = error as Error
+			retries++
+
+			await new Promise((resolve) => setTimeout(resolve, 100))
+		}
+	}
+
+	throw lastError!
+}

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>
 }
 
@@ -65,13 +84,20 @@ export interface InvokeResult<TResult = unknown> {
 }
 
 /**
- * OpenAI Client config
+ * LLM configuration
  */
-export interface OpenAIClientConfig {
+export interface LLMConfig {
-	model: string
-	apiKey: string
 	baseURL: string
+	apiKey: string
+	model: string
+
 	temperature?: number
-	maxTokens?: number
 	maxRetries?: number
+
+	/**
+	 * Custom fetch function for LLM API requests.
+	 * Use this to customize headers, credentials, proxy, etc.
+	 * The response should follow OpenAI API format.
+	 */
+	customFetch?: typeof globalThis.fetch
 }

packages/llms/src/utils.ts

@@ -0,0 +1,120 @@
+/**
+ * Utility functions for LLM integration
+ */
+import chalk from 'chalk'
+import { z } from 'zod'
+
+import type { Tool } from './types'
+
+function debug(message: string) {
+	console.debug(chalk.gray('[LLM]'), message)
+}
+
+/**
+ * Convert Zod schema to OpenAI tool format
+ * Uses Zod 4 native z.toJSONSchema()
+ */
+export function zodToOpenAITool(name: string, tool: Tool) {
+	return {
+		type: 'function' as const,
+		function: {
+			name,
+			description: tool.description,
+			parameters: z.toJSONSchema(tool.inputSchema, { target: 'openapi-3.0' }),
+		},
+	}
+}
+
+/**
+ * Patch model specific parameters
+ */
+export function modelPatch(body: Record<string, any>) {
+	const model: string = body.model || ''
+	if (!model) return body
+
+	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: disable thinking')
+		body.thinking = { type: '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')) {
+		debug('Applying Grok patch: removing tool_choice')
+		delete body.tool_choice
+		debug('Applying Grok patch: disable reasoning and thinking')
+		body.thinking = { type: 'disabled', effort: 'minimal' }
+		body.reasoning = { enabled: false, effort: 'low' }
+	}
+
+	if (modelName.startsWith('gpt')) {
+		debug('Applying GPT patch: set verbosity to low')
+		body.verbosity = 'low'
+
+		if (modelName.startsWith('gpt-52')) {
+			debug('Applying GPT-52 patch: disable reasoning')
+			body.reasoning_effort = 'none'
+		} else if (modelName.startsWith('gpt-51')) {
+			debug('Applying GPT-51 patch: disable reasoning')
+			body.reasoning_effort = 'none'
+		} else if (modelName.startsWith('gpt-5')) {
+			debug('Applying GPT-5 patch: set reasoning effort to low')
+			body.reasoning_effort = 'low'
+		}
+	}
+
+	if (modelName.startsWith('gemini')) {
+		debug('Applying Gemini patch: set reasoning effort to minimal')
+		body.reasoning_effort = 'minimal'
+	}
+
+	return body
+}
+
+/**
+ * check if a given model ID fits a specific model name
+ *
+ * @note
+ * Different model providers may use different model IDs for the same model.
+ * For example, openai's `gpt-5.2` may called:
+ *
+ * - `gpt-5.2-version`
+ * - `gpt-5_2-date`
+ * - `GPT-52-version-date`
+ * - `openai/gpt-5.2-chat`
+ *
+ * They should be treated as the same model.
+ * Normalize them to `gpt-52`
+ */
+function normalizeModelName(modelName: string): string {
+	let normalizedName = modelName.toLowerCase()
+
+	// remove prefix before '/'
+	if (normalizedName.includes('/')) {
+		normalizedName = normalizedName.split('/')[1]
+	}
+
+	// remove '_'
+	normalizedName = normalizedName.replace(/_/g, '')
+
+	// remove '.'
+	normalizedName = normalizedName.replace(/\./g, '')
+
+	return normalizedName
+}

packages/llms/tsconfig.dts.json

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

packages/llms/tsconfig.json

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

packages/llms/vite.config.js

@@ -0,0 +1,36 @@
+// @ts-check
+import chalk from 'chalk'
+import { dirname, resolve } from 'path'
+import dts from 'unplugin-dts/vite'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+console.log(chalk.cyan(`📦 Building @page-agent/llms`))
+
+export default defineConfig({
+	clearScreen: false,
+	plugins: [dts({ tsconfigPath: './tsconfig.dts.json', bundleTypes: true })],
+	publicDir: false,
+	esbuild: {
+		keepNames: true,
+	},
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/index.ts'),
+			name: 'PageAgentLLMs',
+			fileName: 'page-agent-llms',
+			formats: ['es'],
+		},
+		outDir: resolve(__dirname, 'dist', 'lib'),
+		rollupOptions: {
+			external: ['chalk', 'zod'],
+		},
+		minify: false,
+		sourcemap: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})

packages/page-agent/package.json

@@ -1,59 +1,52 @@
 {
 	"name": "page-agent",
 	"private": false,
-	"version": "0.0.5",
+	"version": "0.2.2",
 	"type": "module",
-	"main": "./dist/lib/page-agent.js",
+	"main": "./dist/esm/page-agent.js",
-	"module": "./dist/lib/page-agent.js",
+	"module": "./dist/esm/page-agent.js",
-	"types": "./dist/lib/PageAgent.d.ts",
+	"types": "./dist/esm/PageAgent.d.ts",
 	"exports": {
 		".": {
-			"types": "./dist/lib/PageAgent.d.ts",
+			"types": "./dist/esm/PageAgent.d.ts",
-			"import": "./dist/lib/page-agent.js",
+			"import": "./dist/esm/page-agent.js",
-			"default": "./dist/lib/page-agent.js"
+			"default": "./dist/esm/page-agent.js"
 		}
 	},
 	"files": [
-		"dist/",
+		"dist/"
-		"README.md",
-		"README-zh.md",
-		"LICENSE"
 	],
-	"description": "AI-powered UI agent for web applications - add intelligent automation to any webpage with a single script tag",
+	"description": "GUI agent for web applications - add intelligent automation to any webpage with a single script",
 	"keywords": [
 		"ai",
 		"automation",
 		"ui-agent",
+		"GUI-agent",
 		"browser-automation",
 		"web-agent",
 		"llm",
 		"dom-interaction",
-		"intelligent-ui"
+		"web-automation",
+		"GUI-simulation"
 	],
 	"author": "Simon<gaomeng1900>",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/alibaba/page-agent.git",
+		"url": "https://github.com/alibaba/page-agent.git"
-		"directory": "packages/page-agent"
 	},
 	"homepage": "https://alibaba.github.io/page-agent/",
 	"scripts": {
-		"build": "MODE=lib vite build && MODE=umd vite build",
+		"build": "vite build",
-		"build:lib": "MODE=lib vite build",
+		"dev:iife": "concurrently \"vite build --config vite.iife.config.js --watch\" \"npx serve dist/iife -p 5174\"",
-		"build:umd": "MODE=umd vite build",
+		"prepublishOnly": "node -e \"const fs=require('fs');['README.md','LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
-		"build:watch": "MODE=lib vite build --watch",
+		"postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
-		"prepublishOnly": "node -e \"const fs=require('fs');['README.md','README-zh.md','LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
-		"postpublish": "node -e \"['README.md','README-zh.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
 	},
 	"dependencies": {
-		"ai-motion": "^0.4.7",
 		"chalk": "^5.6.2",
-		"zod": "^4.1.12"
+		"zod": "^4.3.5",
-	},
+		"@page-agent/llms": "0.2.2",
-	"devDependencies": {
+		"@page-agent/page-controller": "0.2.2",
-		"@microsoft/api-extractor": "^7.55.1",
+		"@page-agent/ui": "0.2.2"
-		"unplugin-dts": "^1.0.0-beta.6",
-		"vite-plugin-css-injected-by-js": "^3.5.2"
 	}
 }

packages/page-agent/src/PageAgent.ts

@@ -2,30 +2,28 @@
  * Copyright (C) 2025 Alibaba Group Holding Limited
  * All rights reserved.
  */
+import { LLM, type Tool } from '@page-agent/llms'
+import { PageController } from '@page-agent/page-controller'
+import { Panel } from '@page-agent/ui'
 import chalk from 'chalk'
 import zod from 'zod'
 
 import type { PageAgentConfig } from './config'
-import { MAX_STEPS, VIEWPORT_EXPANSION } from './config/constants'
+import { MAX_STEPS } from './config/constants'
-import * as dom from './dom'
-import { FlatDomTree, InteractiveElementDomNode } from './dom/dom_tree/type'
-import { getPageInfo } from './dom/getPageInfo'
-import { I18n } from './i18n'
-import { LLM, type Tool } from './llms'
-import { patchReact } from './patches/react'
 import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
 import { tools } from './tools'
-import { Panel, getToolCompletedText, getToolExecutingText } from './ui/Panel'
+import { normalizeResponse, trimLines, uid } from './utils'
-import { SimulatorMask } from './ui/SimulatorMask'
-import { trimLines, uid, waitUntil } from './utils'
 import { assert } from './utils/assert'
-import { getEventBus } from './utils/bus'
 
-export type { PageAgentConfig }
+/**
-export { tool, type PageAgentTool } from './tools'
+ * Agent reflection state - the reflection-before-action model
-
+ *
-export interface AgentBrain {
+ * Every tool call must first reflect on:
-	// thinking?: string
+ * - 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
@@ -33,11 +31,11 @@ export interface AgentBrain {
 
 /**
  * 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 {
+export interface MacroToolInput extends Partial<AgentReflection> {
-	evaluation_previous_goal?: string
-	memory?: string
-	next_goal?: string
 	action: Record<string, any>
 }
 
@@ -49,8 +47,15 @@ export interface MacroToolResult {
 	output: string
 }
 
-export interface AgentHistory {
+export type { PageAgentConfig }
-	brain: AgentBrain
+export { tool, type PageAgentTool } from './tools'
+
+/**
+ * A single agent step with reflection and action
+ */
+export interface AgentStep {
+	type: 'step'
+	reflection: Partial<AgentReflection>
 	action: {
 		name: string
 		input: any
@@ -65,56 +70,94 @@ 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 {
 	config: PageAgentConfig
 	id = uid()
-	bus = getEventBus(this.id)
-	i18n: I18n
 	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
+	#beforeUnloadListener: ((e: Event) => void) | null = null
 
-	/** Corresponds to eval_page in browser-use */
+	/** PageController for DOM operations */
-	flatTree: FlatDomTree | null = null
+	pageController: PageController
-	/**
-	 * All highlighted index-mapped interactive elements
-	 * Corresponds to DOMState.selector_map in browser-use
-	 */
-	selectorMap = new Map<number, InteractiveElementDomNode>()
-	/** highlight index -> element text */
-	elementTextMap = new Map<number, string>()
-	/** Corresponds to clickable_elements_to_string in browser-use */
-	simplifiedHTML = '<EMPTY>'
-	/** last time the tree was updated */
-	lastTimeUpdate = 0
 
-	/** 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
-		this.#llm = new LLM(this.config, this.id)
+		this.#llm = new LLM(this.config)
-		this.i18n = new I18n(this.config.language)
+		this.panel = new Panel({
-		this.panel = new Panel(this)
+			language: this.config.language,
+			onExecuteTask: (task) => this.execute(task),
+			onStop: () => this.dispose(),
+		})
 		this.tools = new Map(tools)
 
+		// Initialize PageController with config (mask enabled by default)
+		this.pageController = new PageController({
+			...this.config,
+			enableMask: this.config.enableMask ?? true,
+		})
+
+		// Listen to LLM events
+		this.#llmRetryListener = (e) => {
+			const { current, max } = (e as CustomEvent).detail
+			this.panel.update({ type: 'retry', current, max })
+		}
+		this.#llmErrorListener = (e) => {
+			const { error } = (e as CustomEvent).detail
+			this.panel.update({ type: 'error', message: `step failed: ${error.message}` })
+		}
+		this.#llm.addEventListener('retry', this.#llmRetryListener)
+		this.#llm.addEventListener('error', this.#llmErrorListener)
+
 		if (this.config.customTools) {
 			for (const [name, tool] of Object.entries(this.config.customTools)) {
 				if (tool === null) {
@@ -129,16 +172,21 @@ export class PageAgent extends EventTarget {
 			this.tools.delete('execute_javascript')
 		}
 
-		patchReact(this)
+		this.#beforeUnloadListener = (e) => {
-
-		window.addEventListener('beforeunload', (e) => {
 			if (!this.disposed) this.dispose('PAGE_UNLOADING')
-		})
+		}
+		window.addEventListener('beforeunload', this.#beforeUnloadListener)
 	}
 
 	/**
-	 * @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
@@ -152,15 +200,12 @@ export class PageAgent extends EventTarget {
 		await onBeforeTask.call(this)
 
 		// Show mask and panel
-		this.mask.show()
+		this.pageController.showMask()
 
-		this.bus.emit('panel:show')
+		this.panel.show()
-		this.bus.emit('panel:reset')
+		this.panel.reset()
 
-		this.bus.emit('panel:update', {
+		this.panel.update({ type: 'input', task: this.task })
-			type: 'input',
-			displayText: this.task,
-		})
 
 		if (this.#abortController) {
 			this.#abortController.abort()
@@ -169,25 +214,28 @@ export class PageAgent extends EventTarget {
 
 		this.history = []
 
+		// Reset states
+		this.states = {
+			totalWaitTime: 0,
+			lastURL: '',
+		}
+
 		try {
 			let step = 0
 
 			while (true) {
+				await this.#generateObservations(step)
+
 				await onBeforeStep.call(this, step)
 
-				console.group(`step: ${step + 1}`)
+				console.group(`step: ${step}`)
 
 				// abort
 				if (this.#abortController.signal.aborted) throw new Error('AbortError')
-				// pause
-				await waitUntil(() => !this.paused)
 
 				// Update status to thinking
 				console.log(chalk.blue('Thinking...'))
-				this.bus.emit('panel:update', {
+				this.panel.update({ type: 'thinking' })
-					type: 'thinking',
-					displayText: this.i18n.t('ui.panel.thinking'),
-				})
 
 				const result = await this.#llm.invoke(
 					[
@@ -197,33 +245,38 @@ export class PageAgent extends EventTarget {
 						},
 						{
 							role: 'user',
-							content: this.#assembleUserPrompt(),
+							content: await this.#assembleUserPrompt(),
 						},
 					],
 					{ 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()
@@ -281,9 +334,7 @@ export class PageAgent extends EventTarget {
 		const tools = this.tools
 
 		const actionSchemas = Array.from(tools.entries()).map(([toolName, tool]) => {
-			return zod.object({
+			return zod.object({ [toolName]: tool.inputSchema }).describe(tool.description)
-				[toolName]: tool.inputSchema,
-			})
 		})
 
 		const actionSchema = zod.union(
@@ -299,71 +350,60 @@ 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.bus.emit('panel:update', {
+				const reflectionLines: string[] = []
-					type: 'thinking',
+				if (input.evaluation_previous_goal)
-					displayText: brain,
+					reflectionLines.push(`✅: ${input.evaluation_previous_goal}`)
-				})
+				if (input.memory) reflectionLines.push(`💾: ${input.memory}`)
+				if (input.next_goal) reflectionLines.push(`🎯: ${input.next_goal}`)
+
+				const reflectionText = reflectionLines.length > 0 ? reflectionLines.join('\n') : ''
+
+				if (reflectionText) {
+					console.log(reflectionText)
+					this.panel.update({ type: 'thinking', text: reflectionText })
+				}
 
 				// Find the corresponding tool
 				const tool = tools.get(toolName)
 				assert(tool, `Tool ${toolName} not found. (@note should have been caught before this!!!)`)
 
 				console.log(chalk.blue.bold(`Executing tool: ${toolName}`), toolInput)
-				this.bus.emit('panel:update', {
+				this.panel.update({ type: 'toolExecuting', toolName, args: toolInput })
-					type: 'tool_executing',
-					toolName,
-					toolArgs: toolInput,
-					displayText: getToolExecutingText(toolName, toolInput, this.i18n),
-				})
 
 				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
-				const displayResult = getToolCompletedText(toolName, toolInput, this.i18n)
+				this.panel.update({
-				if (displayResult)
+					type: 'toolCompleted',
-					this.bus.emit('panel:update', {
+					toolName,
-						type: 'tool_executing',
+					args: toolInput,
-						toolName,
+					result,
-						toolArgs: toolInput,
+					duration,
-						toolResult: result,
+				})
-						displayText: displayResult,
-						duration,
-					})
 
 				// Wait a moment to let user see the result
 				await new Promise((resolve) => setTimeout(resolve, 100))
@@ -392,146 +432,190 @@ export class PageAgent extends EventTarget {
 		return systemPrompt
 	}
 
-	#assembleUserPrompt(): string {
+	/**
+	 * Get instructions from config and format as XML block
+	 */
+	async #getInstructions(): Promise<string> {
+		const { instructions } = this.config
+		if (!instructions) return ''
+
+		const systemInstructions = instructions.system?.trim()
+		const url = await this.pageController.getCurrentUrl()
+		let pageInstructions: string | undefined
+
+		if (instructions.getPageInstructions) {
+			try {
+				pageInstructions = instructions.getPageInstructions(url)?.trim()
+			} catch (error) {
+				console.error(
+					chalk.red('[PageAgent] Failed to execute getPageInstructions callback:'),
+					error
+				)
+			}
+		}
+		if (!systemInstructions && !pageInstructions) return ''
+
+		let result = '<instructions>\n'
+
+		if (systemInstructions) {
+			result += `<system_instructions>\n${systemInstructions}\n</system_instructions>\n`
+		}
+
+		if (pageInstructions) {
+			result += `<page_instructions>\n${pageInstructions}\n</page_instructions>\n`
+		}
+
+		result += '</instructions>\n\n'
+
+		return result
+	}
+
+	/**
+	 * Generate observations before each step
+	 * - URL change detection
+	 * - Too many steps warning
+	 * @todo loop detection
+	 * @todo console error
+	 */
+	async #generateObservations(stepCount: number): Promise<void> {
+		// Detect URL change
+		const currentURL = await this.pageController.getCurrentUrl()
+		if (currentURL !== this.states.lastURL) {
+			this.pushObservation(`Page navigated to → ${currentURL}`)
+			this.states.lastURL = currentURL
+		}
+
+		// Warn about remaining steps
+		const remaining = MAX_STEPS - stepCount
+		if (remaining === 5) {
+			this.pushObservation(
+				`⚠️ Only ${remaining} steps remaining. Consider wrapping up or calling done with partial results.`
+			)
+		} else if (remaining === 2) {
+			this.pushObservation(
+				`⚠️ Critical: Only ${remaining} steps left! You must finish the task or call done immediately.`
+			)
+		}
+	}
+
+	async #assembleUserPrompt(): Promise<string> {
 		let prompt = ''
 
-		// <agent_history>
+		// <instructions> (optional)
-		//  - <step_>
+		prompt += await this.#getInstructions()
-
-		prompt += '<agent_history>\n'
-
-		this.history.forEach((history, index) => {
-			prompt += `<step_${index + 1}>
-				Evaluation of Previous Step: ${history.brain.evaluation_previous_goal}
-				Memory: ${history.brain.memory}
-				Next Goal: ${history.brain.next_goal}
-				Action Results: ${history.action.output}
-				</step_${index + 1}>
-			`
-		})
-
-		prompt += '</agent_history>\n\n'
 
 		// <agent_state>
 		//  - <user_request>
 		//  - <step_info>
 		// <agent_state>
 
+		const stepCount = this.history.filter((e) => e.type === 'step').length
+
 		prompt += `<agent_state>
 			<user_request>
 			${this.task}
 			</user_request>
 			<step_info>
-			Step ${this.history.length + 1} of ${MAX_STEPS} max possible steps
+			Step ${stepCount + 1} of ${MAX_STEPS} max possible steps
 			Current date and time: ${new Date().toISOString()}
 			</step_info>
 			</agent_state>
 		`
 
+		// <agent_history>
+		//  - <step_N> for steps
+		//  - <sys> for observations and system messages
+
+		prompt += '\n<agent_history>\n'
+
+		let stepIndex = 0
+		for (const event of this.history) {
+			if (event.type === 'step') {
+				stepIndex++
+				prompt += `<step_${stepIndex}>
+				Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}
+				Memory: ${event.reflection.memory}
+				Next Goal: ${event.reflection.next_goal}
+				Action Results: ${event.action.output}
+				</step_${stepIndex}>
+			`
+			} else if (event.type === 'observation') {
+				prompt += `<sys>${event.content}</sys>\n`
+			} else if (event.type === 'user_takeover') {
+				prompt += `<sys>User took over control and made changes to the page.</sys>\n`
+			}
+		}
+
+		prompt += '</agent_history>\n\n'
+
 		// <browser_state>
 
-		prompt += this.#getBrowserState()
+		prompt += await this.#getBrowserState()
 
 		return trimLines(prompt)
 	}
 
 	#onDone(text: string, success = true) {
-		dom.cleanUpHighlights()
+		this.pageController.cleanUpHighlights()
 
 		// Update panel status
-		this.bus.emit('panel:update', {
+		if (success) {
-			type: success ? 'output' : 'error',
+			this.panel.update({ type: 'output', text })
-			displayText: text,
+		} else {
-		})
+			this.panel.update({ type: 'error', message: text })
+		}
 
 		// Task completed
-		this.bus.emit('panel:update', {
+		this.panel.update({ type: 'completed' })
-			type: 'completed',
-			displayText: this.i18n.t('ui.panel.taskCompleted'),
-		})
 
-		this.mask.hide()
+		this.pageController.hideMask()
 
 		this.#abortController.abort()
 	}
 
-	#getBrowserState(): string {
+	async #getBrowserState(): Promise<string> {
-		const pageUrl = window.location.href
+		const state = await this.pageController.getBrowserState()
-		const pageTitle = document.title
-		const pi = getPageInfo()
 
-		this.#updateTree()
+		let content = state.content
+		if (this.config.transformPageContent) {
+			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}
-			${VIEWPORT_EXPANSION === -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 && VIEWPORT_EXPANSION !== -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 += this.simplifiedHTML
-		prompt += `\n`
-
-		// Page footer info
-		const has_content_below = pi.pixels_below > 4
-		if (has_content_below && VIEWPORT_EXPANSION !== -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
-	}
-
-	/**
-	 * Update document tree
-	 */
-	#updateTree() {
-		this.dispatchEvent(new Event('beforeUpdate'))
-		this.lastTimeUpdate = Date.now()
-		dom.cleanUpHighlights()
-		this.mask.wrapper.style.pointerEvents = 'none'
-		this.flatTree = dom.getFlatTree({
-			...this.config,
-			interactiveBlacklist: [
-				...(this.config.interactiveBlacklist || []),
-				...document.querySelectorAll('[data-page-agent-not-interactive]').values(),
-			],
-		})
-		this.mask.wrapper.style.pointerEvents = 'auto'
-		this.simplifiedHTML = dom.flatTreeToString(this.flatTree, this.config.include_attributes)
-		this.selectorMap.clear()
-		this.selectorMap = dom.getSelectorMap(this.flatTree)
-		this.elementTextMap.clear()
-		this.elementTextMap = dom.getElementTextMap(this.simplifiedHTML)
-		this.dispatchEvent(new Event('afterUpdate'))
 	}
 
 	dispose(reason?: string) {
 		console.log('Disposing PageAgent...')
 		this.disposed = true
-		dom.cleanUpHighlights()
+		this.pageController.dispose()
-		this.flatTree = null
-		this.selectorMap.clear()
-		this.elementTextMap.clear()
 		this.panel.dispose()
-		this.mask.dispose()
 		this.history = []
 		this.#abortController.abort(reason ?? 'PageAgent disposed')
 
+		// Clean up LLM event listeners
+		if (this.#llmRetryListener) {
+			this.#llm.removeEventListener('retry', this.#llmRetryListener)
+			this.#llmRetryListener = null
+		}
+		if (this.#llmErrorListener) {
+			this.#llm.removeEventListener('error', this.#llmErrorListener)
+			this.#llmErrorListener = null
+		}
+
+		// Clean up window event listeners
+		if (this.#beforeUnloadListener) {
+			window.removeEventListener('beforeunload', this.#beforeUnloadListener)
+			this.#beforeUnloadListener = null
+		}
+
 		this.config.onDispose?.call(this, reason)
 	}
 }

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

@@ -1,29 +1,2 @@
-/**
+// Agent-specific constants (LLM constants moved to @page-agent/llms)
- * @note Since isTopElement depends on elementFromPoint,
- * it returns null when out of viewport, this feature has no practical use, only differ between -1 and 0
- */
-// export const VIEWPORT_EXPANSION = 100
-export const VIEWPORT_EXPANSION = -1
-
-// 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
-
-export const LLM_MAX_RETRIES = 2
 export const MAX_STEPS = 20
-export const DEFAULT_TEMPERATURE = 0.7 // higher randomness helps auto-recovery
-export const DEFAULT_MAX_TOKENS = 4096

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

@@ -1,24 +1,11 @@
-import type { AgentHistory, ExecutionResult, PageAgent } from '../PageAgent'
+import type { LLMConfig } from '@page-agent/llms'
-import type { DomConfig } from '../dom'
+import type { PageControllerConfig } from '@page-agent/page-controller'
-import type { SupportedLanguage } from '../i18n'
+import type { SupportedLanguage } from '@page-agent/ui'
-import type { PageAgentTool } from '../tools'
-import {
-	DEFAULT_API_KEY,
-	DEFAULT_BASE_URL,
-	DEFAULT_MAX_TOKENS,
-	DEFAULT_MODEL_NAME,
-	DEFAULT_TEMPERATURE,
-	LLM_MAX_RETRIES,
-} from './constants'
 
-export interface LLMConfig {
+import type { ExecutionResult, HistoryEvent, PageAgent } from '../PageAgent'
-	baseURL?: string
+import type { PageAgentTool } from '../tools'
-	apiKey?: string
+
-	model?: string
+export type { LLMConfig }
-	temperature?: number
-	maxTokens?: number
-	maxRetries?: number
-}
 
 export interface AgentConfig {
 	// theme?: 'light' | 'dark'
@@ -55,17 +42,37 @@ export interface AgentConfig {
 	 */
 	customTools?: Record<string, PageAgentTool | null>
 
+	/**
+	 * Instructions to guide the agent's behavior
+	 */
+	instructions?: {
+		/**
+		 * Global system-level instructions, applied to all tasks
+		 */
+		system?: string
+
+		/**
+		 * Dynamic page-level instructions callback
+		 * Called before each step to get instructions for the current page
+		 * @param url - Current page URL (window.location.href)
+		 * @returns Instructions string, or undefined/null to skip
+		 */
+		getPageInstructions?: (url: string) => string | undefined | null
+	}
+
 	// lifecycle hooks
 	// @todo: use event instead of hooks
+	// @todo: remove `this` binding, pass agent as explicit parameter instead
 
 	onBeforeStep?: (this: PageAgent, stepCnt: number) => Promise<void> | void
-	onAfterStep?: (this: PageAgent, stepCnt: number, history: AgentHistory[]) => Promise<void> | void
+	onAfterStep?: (this: PageAgent, stepCnt: number, history: HistoryEvent[]) => Promise<void> | void
 	onBeforeTask?: (this: PageAgent) => Promise<void> | void
 	onAfterTask?: (this: PageAgent, result: ExecutionResult) => Promise<void> | void
 
 	/**
 	 * @note this hook can block the disposal process
 	 * @note when dispose caused by page unload, reason will be 'PAGE_UNLOADING'. this method CANNOT block unloading. async operations may be cut.
+	 * @todo remove `this` binding, pass agent as explicit parameter instead
 	 */
 	onDispose?: (this: PageAgent, reason?: string) => void
 
@@ -79,10 +86,27 @@ export interface AgentConfig {
 	 */
 	experimentalScriptExecutionTool?: boolean
 
+	/**
+	 * Transform page content before sending to LLM.
+	 * Called after DOM extraction and simplification, before LLM invocation.
+	 * Use cases: inspect extraction results, modify page info, mask sensitive data.
+	 *
+	 * @param content - Simplified page content that will be sent to LLM
+	 * @returns Transformed content
+	 *
+	 * @example
+	 * // Mask phone numbers
+	 * transformPageContent: async (content) => {
+	 *   return content.replace(/1[3-9]\d{9}/g, '***********')
+	 * }
+	 */
+	transformPageContent?: (content: string) => Promise<string> | string
+
 	/**
 	 * TODO: @unimplemented
 	 * hook when action causes a new page to be opened
 	 * @note PageAgent will try to detect new pages and decide if it's caused by an action. But not very reliable.
+	 * @todo remove `this` binding, pass agent as explicit parameter instead
 	 */
 	onNewPageOpen?: (this: PageAgent, url: string) => Promise<void> | void
 
@@ -94,15 +118,4 @@ export interface AgentConfig {
 	experimentalPreventNewPage?: boolean
 }
 
-export type PageAgentConfig = LLMConfig & AgentConfig & DomConfig
+export type PageAgentConfig = LLMConfig & AgentConfig & PageControllerConfig
-
-export function parseLLMConfig(config: LLMConfig): Required<LLMConfig> {
-	return {
-		baseURL: config.baseURL ?? DEFAULT_BASE_URL,
-		apiKey: config.apiKey ?? DEFAULT_API_KEY,
-		model: config.model ?? DEFAULT_MODEL_NAME,
-		temperature: config.temperature ?? DEFAULT_TEMPERATURE,
-		maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS,
-		maxRetries: config.maxRetries ?? LLM_MAX_RETRIES,
-	}
-}

packages/page-agent/src/entry.ts

@@ -1,40 +0,0 @@
-/**
- * Auto-run entry for page-agent.js. Insert this script into your page to get page-agent functionality.
- */
-import { PageAgent, type PageAgentConfig } from './PageAgent'
-
-// 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 ES module usage
-// 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'
-
-const currentScript = document.currentScript as HTMLScriptElement | null
-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') as 'zh-CN' | 'en-US') || 'zh-CN'
-	const config: PageAgentConfig = { model, baseURL, apiKey, language }
-	window.pageAgent = new PageAgent(config)
-} else {
-	console.log('🚀 page-agent.js no current script detected, using default demo config')
-	window.pageAgent = new PageAgent()
-}
-
-console.log('🚀 page-agent.js initialized with config:', window.pageAgent.config)
-
-window.pageAgent.bus.emit('panel:show') // Show panel

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

@@ -1,5 +1,5 @@
 /// <reference types="vite/client" />
-import type { PageAgent } from './src/PageAgent'
+import type { PageAgent } from './PageAgent'
 
 declare module '*.module.css' {
 	const classes: Record<string, string>

packages/page-agent/src/iife.ts

@@ -0,0 +1,53 @@
+/**
+ * Auto-run entry for page-agent.js. Insert this script into your page to get page-agent functionality.
+ */
+import { PageAgent, type PageAgentConfig } from './PageAgent'
+
+// 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 ES module usage
+// 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'
+
+// in case document.x is not ready yet
+// @todo give a switch to disable auto-init
+setTimeout(() => {
+	const currentScript = document.currentScript as HTMLScriptElement | null
+	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') as 'zh-CN' | 'en-US') || 'zh-CN'
+		const config: PageAgentConfig = { 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: 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)
+
+	window.pageAgent.panel.show() // Show panel
+})

packages/page-agent/src/llms/OpenAIClient.ts

@@ -1,188 +0,0 @@
-/**
- * OpenAI Client implementation
- */
-import { InvokeError, InvokeErrorType } from './errors'
-import type { InvokeResult, LLMClient, Message, OpenAIClientConfig, Tool } from './types'
-import { modelPatch, zodToOpenAITool } from './utils'
-
-export class OpenAIClient implements LLMClient {
-	config: OpenAIClientConfig
-
-	constructor(config: OpenAIClientConfig) {
-		this.config = config
-	}
-
-	async invoke(
-		messages: Message[],
-		tools: Record<string, Tool>,
-		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 fetch(`${this.config.baseURL}/chat/completions`, {
-				method: 'POST',
-				headers: {
-					'Content-Type': 'application/json',
-					Authorization: `Bearer ${this.config.apiKey}`,
-				},
-				body: JSON.stringify(
-					modelPatch({
-						model: this.config.model,
-						temperature: this.config.temperature,
-						max_tokens: this.config.maxTokens,
-						messages,
-
-						tools: openaiTools,
-						// tool_choice: 'required',
-						tool_choice: { type: 'function', function: { name: 'AgentOutput' } },
-
-						// model specific params
-
-						// reasoning_effort: 'minimal',
-						// verbosity: 'low',
-						parallel_tool_calls: false,
-					})
-				),
-				signal: abortSignal,
-			})
-		} catch (error: unknown) {
-			// Network error
-			throw new InvokeError(InvokeErrorType.NETWORK_ERROR, 'Network request failed', error)
-		}
-
-		// 3. Handle HTTP errors
-		if (!response.ok) {
-			const errorData = await response.json().catch()
-			const errorMessage =
-				(errorData as { error?: { message?: string } }).error?.message || response.statusText
-
-			if (response.status === 401 || response.status === 403) {
-				throw new InvokeError(
-					InvokeErrorType.AUTH_ERROR,
-					`Authentication failed: ${errorMessage}`,
-					errorData
-				)
-			}
-			if (response.status === 429) {
-				throw new InvokeError(
-					InvokeErrorType.RATE_LIMIT,
-					`Rate limit exceeded: ${errorMessage}`,
-					errorData
-				)
-			}
-			if (response.status >= 500) {
-				throw new InvokeError(
-					InvokeErrorType.SERVER_ERROR,
-					`Server error: ${errorMessage}`,
-					errorData
-				)
-			}
-			throw new InvokeError(
-				InvokeErrorType.UNKNOWN,
-				`HTTP ${response.status}: ${errorMessage}`,
-				errorData
-			)
-		}
-
-		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)
-		}
-
-		switch (choice.finish_reason) {
-			case 'tool_calls':
-				// ✅ Normal
-				break
-			case 'length':
-				// ⚠️ Token limit reached
-				throw new InvokeError(
-					InvokeErrorType.CONTEXT_LENGTH,
-					'Response truncated: max tokens reached',
-					data
-				)
-			case 'content_filter':
-				// ❌ Content filtered
-				throw new InvokeError(
-					InvokeErrorType.CONTENT_FILTER,
-					'Content filtered by safety system',
-					data
-				)
-			case 'stop':
-				// ❌ Did not call tool (we require tool call)
-				throw new InvokeError(InvokeErrorType.NO_TOOL_CALL, 'Model did not call any tool', data)
-			default:
-				throw new InvokeError(
-					InvokeErrorType.UNKNOWN,
-					`Unexpected finish_reason: ${choice.finish_reason}`,
-					data
-				)
-		}
-
-		// 5. Parse tool call
-		const toolCall = choice.message?.tool_calls?.[0]
-		if (!toolCall) {
-			throw new InvokeError(InvokeErrorType.NO_TOOL_CALL, 'No tool call found in response', data)
-		}
-
-		const toolName = toolCall.function.name
-		const tool = tools[toolName]
-		if (!tool) {
-			throw new InvokeError(InvokeErrorType.UNKNOWN, `Tool ${toolName} not found`, data)
-		}
-
-		// 6. Parse and validate arguments
-		let toolArgs: unknown
-		try {
-			toolArgs = JSON.parse(toolCall.function.arguments)
-		} catch (e) {
-			throw new InvokeError(InvokeErrorType.INVALID_TOOL_ARGS, 'Invalid JSON in tool arguments', e)
-		}
-
-		// Validate against zod schema
-		const validation = tool.inputSchema.safeParse(toolArgs)
-		if (!validation.success) {
-			throw new InvokeError(
-				InvokeErrorType.INVALID_TOOL_ARGS,
-				`Tool arguments validation failed: ${validation.error.message}`,
-				validation.error
-			)
-		}
-
-		// 7. Execute tool
-		let toolResult: unknown
-		try {
-			toolResult = await tool.execute(validation.data)
-		} catch (e) {
-			throw new InvokeError(
-				InvokeErrorType.TOOL_EXECUTION_ERROR,
-				`Tool execution failed: ${(e as Error).message}`,
-				e
-			)
-		}
-
-		// 8. Return result (including cache tokens)
-		return {
-			toolCall: {
-				// id: toolCall.id,
-				name: toolName,
-				args: validation.data as Record<string, unknown>,
-			},
-			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/page-agent/src/llms/OpenAILenientClient.ts

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

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

@@ -1,137 +0,0 @@
-/**
- * @topic LLM 与主流程的隔离
- * @reasoning
- * 将 llm 的调用和主流程分开是复杂的，
- * 因为 agent 的 tool call 通常集成在 llm 模块中，而而先得到 llm 返回，然后处理工具调用
- * tools 和 llm 调用的逻辑不可避免地耦合在一起，tool 的执行又和主流程耦合在一起
- * 而 history 的维护和更新逻辑，又必须嵌入多轮 tool call 中
- * @reasoning
- * - 放弃框架提供的自动的多轮调用，每轮调用都由主流程发起
- * - 理想情况下，llm 调用应该获得 structured output，然后由额外的模块触发 tool call，目前模型和框架都无法实现
- * - 当前只能将 llm api 和 本地 tool call 耦合在一起，不关心其中的衔接方式
- * @conclusion
- * - @llm responsibility boundary:
- *   - call llm api with given messages and tools
- *   - invoke tool call and get the result of the tool
- *   - return the result to main loop
- * - @main_loop responsibility boundary:
- *   - maintain all behaviors of an **agent**
- * @conclusion
- * - 这里的 llm 模块不是 agent，只负责一轮 llm 调用和工具调用，无状态
- */
-/**
- * @topic 结构化输出
- * @facts
- * - 几乎所有模型都支持 tool call schema
- * - 几乎所有模型都支持返回 json
- *   - 只有 openAI/grok/gemini 支持 schema 并保证格式
- * - 主流模型都支持 tool_choice: required
- *   - 除了 qwen 必须指定一个函数名 (9月上新后支持)
- * @conclusion
- * - 永远使用 tool call 来返回结构化数据，禁止模型直接返回（视为出错）
- * - 不能假设 tool 参数合法，必须有修复机制，而且修复也应该使用 tool call 返回
- */
-import type { LLMConfig } from '../config'
-import { parseLLMConfig } from '../config'
-import { EventBus, getEventBus } from '../utils/bus'
-import { OpenAIClient } from './OpenAILenientClient'
-import { InvokeError } from './errors'
-import type { InvokeResult, LLMClient, Message, Tool } from './types'
-
-export type { Message, Tool, InvokeResult, LLMClient }
-
-export class LLM {
-	config: Required<LLMConfig>
-	id: string
-	client: LLMClient
-	#bus: EventBus
-
-	constructor(config: LLMConfig, id: string) {
-		this.config = parseLLMConfig(config)
-		this.id = id
-
-		this.#bus = getEventBus(id)
-
-		// Default to OpenAI client
-		this.client = new OpenAIClient({
-			model: this.config.model,
-			apiKey: this.config.apiKey,
-			baseURL: this.config.baseURL,
-			temperature: this.config.temperature,
-			maxTokens: this.config.maxTokens,
-		})
-	}
-
-	/**
-	 * - call llm api *once*
-	 * - invoke tool call *once*
-	 * - return the result of the tool
-	 */
-	async invoke(
-		messages: Message[],
-		tools: Record<string, Tool>,
-		abortSignal: AbortSignal
-	): Promise<InvokeResult> {
-		return await withRetry(
-			async () => {
-				const result = await this.client.invoke(messages, tools, abortSignal)
-
-				return result
-			},
-			// retry settings
-			{
-				maxRetries: this.config.maxRetries,
-				onRetry: (retries: number) => {
-					this.#bus.emit('panel:update', {
-						type: 'retry',
-						displayText: `retry-ing (${retries} / ${this.config.maxRetries})`,
-					})
-				},
-				onError: (error: Error, withRetry: boolean) => {
-					this.#bus.emit('panel:update', {
-						type: 'error',
-						displayText: `step failed: ${(error as Error).message}`,
-					})
-				},
-			}
-		)
-	}
-}
-
-async function withRetry<T>(
-	fn: () => Promise<T>,
-	settings: {
-		maxRetries: number
-		onRetry: (retries: number) => void
-		onError: (error: Error, withRetry: boolean) => void
-	}
-): Promise<T> {
-	let retries = 0
-	let lastError: Error | null = null
-	while (retries <= settings.maxRetries) {
-		if (retries > 0) {
-			settings.onRetry(retries)
-			await new Promise((resolve) => setTimeout(resolve, 100))
-		}
-
-		try {
-			return await fn()
-		} catch (error: unknown) {
-			console.error(error)
-			settings.onError(error as Error, retries < settings.maxRetries)
-
-			// do not retry if aborted by user
-			if ((error as { name?: string })?.name === 'AbortError') throw error
-
-			// do not retry if error is not retryable (InvokeError)
-			if (error instanceof InvokeError && !error.retryable) throw error
-
-			lastError = error as Error
-			retries++
-
-			await new Promise((resolve) => setTimeout(resolve, 100))
-		}
-	}
-
-	throw lastError!
-}

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

@@ -1,214 +0,0 @@
-/**
- * Utility functions for LLM integration
- */
-import chalk from 'chalk'
-import { z } from 'zod'
-
-import type { MacroToolInput } from '../PageAgent'
-import { InvokeError, InvokeErrorType } from './errors'
-import type { Tool } from './types'
-
-/**
- * Convert Zod schema to OpenAI tool format
- * Uses Zod 4 native z.toJSONSchema()
- */
-export function zodToOpenAITool(name: string, tool: Tool) {
-	return {
-		type: 'function' as const,
-		function: {
-			name,
-			description: tool.description,
-			parameters: z.toJSONSchema(tool.inputSchema, { target: 'openapi-3.0' }),
-		},
-	}
-}
-
-/**
- * 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
-		)
-	}
-}
-
-export function modelPatch(body: Record<string, any>) {
-	const model: string = body.model || ''
-
-	if (model.toLowerCase().startsWith('claude')) {
-		body.tool_choice = { type: 'tool', name: 'AgentOutput' }
-		body.thinking = { type: 'disabled' }
-		// body.reasoning = { enabled: 'disabled' }
-	}
-
-	if (model.toLowerCase().includes('grok')) {
-		console.log('Applying Grok patch: removing tool_choice')
-		delete body.tool_choice
-		console.log('Applying Grok patch: disable reasoning and thinking')
-		body.thinking = { type: 'disabled', effort: 'minimal' }
-		body.reasoning = { enabled: false, effort: 'low' }
-	}
-
-	return body
-}

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

@@ -5,21 +5,7 @@
 import zod, { type z } from 'zod'
 
 import type { PageAgent } from '../PageAgent'
-import {
+import { waitFor } from '../utils'
-	clickElement,
-	getElementByIndex,
-	getSystemInfo,
-	inputTextElement,
-	scrollHorizontally,
-	scrollVertically,
-	selectOptionElement,
-	waitFor,
-} from './actions'
-// debug
-import * as utils from './actions'
-
-// @ts-expect-error debug only
-window.utils = utils
 
 /**
  * Internal tool definition that has access to PageAgent `this` context
@@ -41,18 +27,6 @@ export function tool<TParams>(options: PageAgentTool<TParams>): PageAgentTool<TP
  */
 export const tools = new Map<string, PageAgentTool>()
 
-// tools.set(
-// 	'get_current_html',
-// 	tool({
-// 		description: 'Get the current (updated) simplified HTML of the page',
-// 		inputSchema: zod.object({}),
-// 		execute: function (this: PageAgent) {
-// 			this.updateTree()
-// 			return this.simplifiedHTML
-// 		},
-// 	})
-// )
-
 tools.set(
 	'done',
 	tool({
@@ -79,11 +53,20 @@ tools.set(
 			seconds: zod.number().min(1).max(10).default(1),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const lastTimeUpdate = this.lastTimeUpdate
+			const lastTimeUpdate = await this.pageController.getLastUpdateTime()
 			const actualWaitTime = Math.max(0, input.seconds - (Date.now() - lastTimeUpdate) / 1000)
 			console.log(`actualWaitTime: ${actualWaitTime} seconds`)
 			await waitFor(actualWaitTime)
-			return `✅ Waited for ${input.seconds} seconds.` + (await getSystemInfo())
+
+			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.`
 		},
 	})
 )
@@ -98,7 +81,7 @@ tools.set(
 		}),
 		execute: async function (this: PageAgent, input) {
 			const answer = await this.panel.askUser(input.question)
-			return `✅ Received user answer: ${answer}` + (await getSystemInfo())
+			return `✅ Received user answer: ${answer}`
 		},
 	})
 )
@@ -111,16 +94,8 @@ tools.set(
 			index: zod.int().min(0),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const element = getElementByIndex(this, input.index)
+			const result = await this.pageController.clickElement(input.index)
-			const elemText = this.elementTextMap.get(input.index)
+			return result.message
-			await clickElement(element)
-
-			// @workaround: Handle links that open in new tabs
-			if (element instanceof HTMLAnchorElement && element.target === '_blank') {
-				return `⚠️ Clicked link that opens in a new tab (${elemText ? elemText : input.index}). You are not capable of reading new tabs.`
-			}
-
-			return `✅ Clicked element (${elemText ? elemText : input.index}).` + (await getSystemInfo())
 		},
 	})
 )
@@ -134,13 +109,8 @@ tools.set(
 			text: zod.string(),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const element = getElementByIndex(this, input.index)
+			const result = await this.pageController.inputText(input.index, input.text)
-			const elemText = this.elementTextMap.get(input.index)
+			return result.message
-			await inputTextElement(element, input.text)
-			return (
-				`✅ Input text (${input.text}) into element (${elemText ? elemText : input.index}).` +
-				(await getSystemInfo())
-			)
 		},
 	})
 )
@@ -155,13 +125,8 @@ tools.set(
 			text: zod.string(),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const element = getElementByIndex(this, input.index)
+			const result = await this.pageController.selectOption(input.index, input.text)
-			const elemText = this.elementTextMap.get(input.index)
+			return result.message
-			await selectOptionElement(element as HTMLSelectElement, input.text)
-			return (
-				`✅ Selected option (${input.text}) in element (${elemText ? elemText : input.index}).` +
-				(await getSystemInfo())
-			)
 		},
 	})
 )
@@ -181,13 +146,11 @@ tools.set(
 			index: zod.number().int().min(0).optional(),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const { down, num_pages, index, pixels } = input
+			const result = await this.pageController.scroll({
-
+				...input,
-			const scroll_amount = pixels ? pixels : num_pages * (down ? 1 : -1) * window.innerHeight
+				numPages: input.num_pages,
-
+			})
-			const element = index !== undefined ? getElementByIndex(this, index) : null
+			return result.message
-
-			return (await scrollVertically(down, scroll_amount, element)) + (await getSystemInfo())
 		},
 	})
 )
@@ -203,13 +166,8 @@ tools.set(
 			index: zod.number().int().min(0).optional(),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const { right, pixels, index } = input
+			const result = await this.pageController.scrollHorizontally(input)
-
+			return result.message
-			const scroll_amount = pixels * (right ? 1 : -1)
-
-			const element = index !== undefined ? getElementByIndex(this, index) : null
-
-			return (await scrollHorizontally(right, scroll_amount, element)) + (await getSystemInfo())
 		},
 	})
 )
@@ -223,14 +181,8 @@ tools.set(
 			script: zod.string(),
 		}),
 		execute: async function (this: PageAgent, input) {
-			try {
+			const result = await this.pageController.executeJavascript(input.script)
-				// Wrap script in async function to support await
+			return result.message
-				const asyncFunction = eval(`(async () => { ${input.script} })`)
-				const result = await asyncFunction()
-				return `✅ Executed JavaScript. Result: ${result}` + (await getSystemInfo())
-			} catch (error) {
-				return `❌ Error executing JavaScript: ${error}` + (await getSystemInfo())
-			}
 		},
 	})
 )

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

@@ -1,40 +1,16 @@
-/**
- * Type-safe event bus for decoupling PageAgent and Panel
- */
-import type { Step } from '../ui/UIState'
-
 /**
  * Event mapping definitions
  * @note Event bus callbacks must be repeatable without errors
  */
 export interface PageAgentEventMap {
-	// Panel control events
-	// call panel.show()
-	'panel:show': { params: undefined }
-	// call panel.hide()
-	'panel:hide': { params: undefined }
-	// call panel.reset()
-	'panel:reset': { params: undefined }
-	// call panel.update()
-	'panel:update': { params: Omit<Step, 'id' | 'stepNumber' | 'timestamp'> }
-	// call panel.expand()
-	'panel:expand': { params: undefined }
-	// call panel.collapse()
-	'panel:collapse': { params: undefined }
-
 	// PageAgent status events
-	// 'agent:beforeUpdate': { params: undefined }
-	// 'agent:afterUpdate': { params: undefined }
 	// '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 } }
 
 	// Task status change events
-	// 'task:start': { params: { task: string } }
+	'task:start': { params: { task: string } }
-	// 'task:step': { params: Omit<AgentStep, 'id' | 'stepNumber' | 'timestamp'> }
 	// 'task:complete': { params: { text: string; success: boolean } }
 	// 'task: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
@@ -20,6 +22,10 @@ export async function waitUntil(check: () => boolean, timeout = 60 * 60_1000): P
 	})
 }
 
+export async function waitFor(seconds: number): Promise<void> {
+	await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
+}
+
 //
 
 export function truncate(text: string, maxLength: number): string {

packages/page-agent/tsconfig.dts.json

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

packages/page-agent/tsconfig.json

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

packages/page-agent/vite.config.js

@@ -1,7 +1,4 @@
 // @ts-check
-import chalk from 'chalk'
-import 'dotenv/config'
-import process from 'node:process'
 import { dirname, resolve } from 'path'
 import dts from 'unplugin-dts/vite'
 import { fileURLToPath } from 'url'
@@ -10,14 +7,11 @@ import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
-// ============================================================================
+// ES Module for NPM Package
-// Library Config (ES Module for NPM Package)
+export default defineConfig({
-// ============================================================================
-/** @type {import('vite').UserConfig} */
-const libConfig = {
 	clearScreen: false,
 	plugins: [
-		dts({ tsconfigPath: './tsconfig.json', bundleTypes: true }),
+		dts({ tsconfigPath: './tsconfig.dts.json', bundleTypes: true }),
 		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
 	],
 	publicDir: false,
@@ -31,9 +25,14 @@ const libConfig = {
 			fileName: 'page-agent',
 			formats: ['es'],
 		},
-		outDir: resolve(__dirname, 'dist', 'lib'),
+		outDir: resolve(__dirname, 'dist', 'esm'),
 		rollupOptions: {
-			external: ['ai', 'ai-motion', 'chalk', 'zod'],
+			external: [
+				'chalk',
+				'zod',
+				// all the internal packages
+				/^@page-agent\//,
+			],
 		},
 		minify: false,
 		sourcemap: true,
@@ -42,44 +41,4 @@ const libConfig = {
 	define: {
 		'process.env.NODE_ENV': '"production"',
 	},
-}
+})
-
-// ============================================================================
-// UMD Config (Browser Bundle for CDN)
-// ============================================================================
-/** @type {import('vite').UserConfig} */
-const umdConfig = {
-	plugins: [cssInjectedByJsPlugin({ relativeCSSInjection: true })],
-	publicDir: false,
-	esbuild: {
-		keepNames: true,
-	},
-	build: {
-		lib: {
-			entry: resolve(__dirname, 'src/entry.ts'),
-			name: 'PageAgent',
-			fileName: 'page-agent',
-			formats: ['umd'],
-		},
-		outDir: resolve(__dirname, 'dist', 'umd'),
-		cssCodeSplit: true,
-	},
-	define: {
-		'process.env.NODE_ENV': '"production"',
-	},
-}
-
-// ============================================================================
-
-const MODE = process.env.MODE
-
-console.log(chalk.cyan(`📦 Build mode: ${chalk.bold(MODE || 'lib')}`))
-
-let config
-if (MODE === 'umd') {
-	config = umdConfig
-} else {
-	config = libConfig
-}
-
-export default defineConfig(config)

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

@@ -0,0 +1,56 @@
+// @ts-check
+import { config as dotenvConfig } from 'dotenv'
+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))
+
+// 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(({ mode }) => ({
+	plugins: [cssInjectedByJsPlugin({ relativeCSSInjection: true })],
+	publicDir: false,
+	esbuild: {
+		keepNames: true,
+	},
+	resolve: {
+		alias: {
+			'@page-agent/page-controller': resolve(__dirname, '../page-controller/src/PageController.ts'),
+			'@page-agent/llms': resolve(__dirname, '../llms/src/index.ts'),
+			'@page-agent/ui': resolve(__dirname, '../ui/src/index.ts'),
+		},
+	},
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/iife.ts'),
+			name: 'PageAgent',
+			fileName: 'page-agent',
+			formats: ['iife'],
+		},
+		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)
+			},
+		},
+	},
+	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),
+	},
+}))

packages/page-controller/package.json

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

packages/page-controller/src/PageController.ts

@@ -0,0 +1,393 @@
+/**
+ * Copyright (C) 2025 Alibaba Group Holding Limited
+ * All rights reserved.
+ *
+ * PageController - Manages DOM operations and element interactions.
+ * Designed to be independent of LLM and can be tested in unit tests.
+ * All public methods are async for potential remote calling support.
+ */
+import {
+	clickElement,
+	getElementByIndex,
+	inputTextElement,
+	scrollHorizontally,
+	scrollVertically,
+	selectOptionElement,
+} from './actions'
+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 {
+	success: boolean
+	message: string
+}
+
+/**
+ * PageController manages DOM state and element interactions.
+ * It provides async methods for all DOM operations, keeping state isolated.
+ *
+ * @lifecycle
+ * - beforeUpdate: Emitted before the DOM tree is updated.
+ * - afterUpdate: Emitted after the DOM tree is updated.
+ */
+export class PageController extends EventTarget {
+	private config: PageControllerConfig
+
+	/** Corresponds to eval_page in browser-use */
+	private flatTree: FlatDomTree | null = null
+
+	/**
+	 * All highlighted index-mapped interactive elements
+	 * Corresponds to DOMState.selector_map in browser-use
+	 */
+	private selectorMap = new Map<number, InteractiveElementDomNode>()
+
+	/** Index -> element text description mapping */
+	private elementTextMap = new Map<number, string>()
+
+	/**
+	 * Simplified HTML for LLM consumption.
+	 * Corresponds to clickable_elements_to_string in browser-use
+	 */
+	private simplifiedHTML = '<EMPTY>'
+
+	/** 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 =======
+
+	/**
+	 * Get current page URL
+	 */
+	async getCurrentUrl(): Promise<string> {
+		return window.location.href
+	}
+
+	/**
+	 * Get last tree update timestamp
+	 */
+	async getLastUpdateTime(): Promise<number> {
+		return this.lastTimeUpdate
+	}
+
+	/**
+	 * Get structured browser state for LLM consumption.
+	 * Automatically calls updateTree() to refresh the DOM state.
+	 */
+	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 =======
+
+	/**
+	 * 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 = [
+			...(this.config.interactiveBlacklist || []),
+			...document.querySelectorAll('[data-page-agent-not-interactive]').values(),
+		]
+
+		this.flatTree = dom.getFlatTree({
+			...this.config,
+			interactiveBlacklist: blacklist,
+		})
+
+		this.simplifiedHTML = dom.flatTreeToString(this.flatTree, this.config.include_attributes)
+
+		this.selectorMap.clear()
+		this.selectorMap = dom.getSelectorMap(this.flatTree)
+
+		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
+	}
+
+	/**
+	 * Clean up all element highlights
+	 */
+	async cleanUpHighlights(): Promise<void> {
+		dom.cleanUpHighlights()
+	}
+
+	// ======= Element Actions =======
+
+	/**
+	 * Click element by index
+	 */
+	async clickElement(index: number): Promise<ActionResult> {
+		try {
+			const element = getElementByIndex(this.selectorMap, index)
+			const elemText = this.elementTextMap.get(index)
+			await clickElement(element)
+
+			// Handle links that open in new tabs
+			if (element instanceof HTMLAnchorElement && element.target === '_blank') {
+				return {
+					success: true,
+					message: `✅ Clicked element (${elemText ?? index}). ⚠️ Link opens in a new tab. You are not capable of reading new tabs.`,
+				}
+			}
+
+			return {
+				success: true,
+				message: `✅ Clicked element (${elemText ?? index}).`,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to click element: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Input text into element by index
+	 */
+	async inputText(index: number, text: string): Promise<ActionResult> {
+		try {
+			const element = getElementByIndex(this.selectorMap, index)
+			const elemText = this.elementTextMap.get(index)
+			await inputTextElement(element, text)
+
+			return {
+				success: true,
+				message: `✅ Input text (${text}) into element (${elemText ?? index}).`,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to input text: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Select dropdown option by index and option text
+	 */
+	async selectOption(index: number, optionText: string): Promise<ActionResult> {
+		try {
+			const element = getElementByIndex(this.selectorMap, index)
+			const elemText = this.elementTextMap.get(index)
+			await selectOptionElement(element as HTMLSelectElement, optionText)
+
+			return {
+				success: true,
+				message: `✅ Selected option (${optionText}) in element (${elemText ?? index}).`,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to select option: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Scroll vertically
+	 */
+	async scroll(options: {
+		down: boolean
+		numPages: number
+		pixels?: number
+		index?: number
+	}): Promise<ActionResult> {
+		try {
+			const { down, numPages, pixels, index } = options
+
+			const scrollAmount = pixels ?? numPages * (down ? 1 : -1) * window.innerHeight
+
+			const element = index !== undefined ? getElementByIndex(this.selectorMap, index) : null
+
+			const message = await scrollVertically(down, scrollAmount, element)
+
+			return {
+				success: true,
+				message,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to scroll: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Scroll horizontally
+	 */
+	async scrollHorizontally(options: {
+		right: boolean
+		pixels: number
+		index?: number
+	}): Promise<ActionResult> {
+		try {
+			const { right, pixels, index } = options
+
+			const scrollAmount = pixels * (right ? 1 : -1)
+
+			const element = index !== undefined ? getElementByIndex(this.selectorMap, index) : null
+
+			const message = await scrollHorizontally(right, scrollAmount, element)
+
+			return {
+				success: true,
+				message,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to scroll horizontally: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Execute arbitrary JavaScript on the page
+	 */
+	async executeJavascript(script: string): Promise<ActionResult> {
+		try {
+			// Wrap script in async function to support await
+			const asyncFunction = eval(`(async () => { ${script} })`)
+			const result = await asyncFunction()
+			return {
+				success: true,
+				message: `✅ Executed JavaScript. Result: ${result}`,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Error executing JavaScript: ${error}`,
+			}
+		}
+	}
+
+	// ======= 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
+	 */
+	dispose(): void {
+		dom.cleanUpHighlights()
+		this.flatTree = null
+		this.selectorMap.clear()
+		this.elementTextMap.clear()
+		this.simplifiedHTML = '<EMPTY>'
+		this.mask?.dispose()
+		this.mask = null
+	}
+}

packages/page-controller/src/actions.ts

@@ -2,26 +2,14 @@
  * Copyright (C) 2025 Alibaba Group Holding Limited
  * All rights reserved.
  */
-import type { PageAgent } from '../PageAgent'
+import type { InteractiveElementDomNode } from './dom/dom_tree/type'
 
 // ======= general utils =======
 
-export async function waitFor(seconds: number): Promise<void> {
+async function waitFor(seconds: number): Promise<void> {
 	await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
 }
 
-let currentUrl = window.location.href
-export async function getSystemInfo() {
-	// If current URL is already up to date, no need to add message
-	if (currentUrl === window.location.href) return ''
-
-	await waitFor(0.3) // Wait a bit longer for page to load
-
-	currentUrl = window.location.href
-
-	return `\n<sys> Current URL changed to: ${currentUrl} </sys>`
-}
-
 // ======= dom utils =======
 
 export async function movePointerToElement(element: HTMLElement) {
@@ -35,10 +23,13 @@ export async function movePointerToElement(element: HTMLElement) {
 }
 
 /**
- * Get the HTMLElement by index from the selectorMap in PageAgent.
+ * Get the HTMLElement by index from a selectorMap.
  */
-export function getElementByIndex(pageAgent: PageAgent, index: number): HTMLElement {
+export function getElementByIndex(
-	const interactiveNode = pageAgent.selectorMap.get(index)
+	selectorMap: Map<number, InteractiveElementDomNode>,
+	index: number
+): HTMLElement {
+	const interactiveNode = selectorMap.get(index)
 	if (!interactiveNode) {
 		throw new Error(`No interactive element found at index ${index}`)
 	}
@@ -170,7 +161,6 @@ export async function selectOptionElement(selectElement: HTMLSelectElement, opti
 	await waitFor(0.1) // Wait to ensure change event processing completes
 }
 
-// eslint-disable-next-line @typescript-eslint/require-await
 export async function scrollIntoViewIfNeeded(element: HTMLElement) {
 	const el = element as any
 	if (el.scrollIntoViewIfNeeded) {
@@ -297,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.`
 	}
 }
 
@@ -420,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/constants.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (C) 2025 Alibaba Group Holding Limited
+ * All rights reserved.
+ */
+
+/**
+ * Viewport expansion for DOM tree extraction.
+ * -1 means full page (no viewport restriction)
+ * 0 means viewport only
+ * positive values expand the viewport by that many pixels
+ *
+ * @note Since isTopElement depends on elementFromPoint,
+ * it returns null when out of viewport, this feature has no practical use, only differ between -1 and 0
+ */
+// export const VIEWPORT_EXPANSION = 100
+export const VIEWPORT_EXPANSION = -1

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/dom/index.ts

@@ -1,5 +1,5 @@
-import { VIEWPORT_EXPANSION } from '../config/constants'
+import { VIEWPORT_EXPANSION } from '../constants'
-import domTree from './dom_tree/index'
+import domTree from './dom_tree/index.js'
 import {
 	ElementDomNode,
 	FlatDomTree,

packages/page-controller/src/mask/SimulatorMask.ts

@@ -1,6 +1,6 @@
 import { Motion } from 'ai-motion'
 
-import { isPageDark } from '../utils/checkDarkMode'
+import { isPageDark } from './checkDarkMode'
 
 import styles from './SimulatorMask.module.css'
 import cursorStyles from './cursor.module.css'

packages/page-controller/src/mask/checkDarkMode.ts

@@ -3,14 +3,14 @@
  * @returns {boolean} - True if a common dark mode class is found.
  */
 function hasDarkModeClass() {
-	const DFEAULT_DARK_MODE_CLASSES = ['dark', 'dark-mode', 'theme-dark', 'night', 'night-mode']
+	const DEFAULT_DARK_MODE_CLASSES = ['dark', 'dark-mode', 'theme-dark', 'night', 'night-mode']
 
 	const htmlElement = document.documentElement
-	const bodyElement = document.body
+	const bodyElement = document.body || document.documentElement // can be null in some cases
 
 	// Check class names on <html> and <body>
-	for (const className of DFEAULT_DARK_MODE_CLASSES) {
+	for (const className of DEFAULT_DARK_MODE_CLASSES) {
-		if (htmlElement.classList.contains(className) || bodyElement.classList.contains(className)) {
+		if (htmlElement.classList.contains(className) || bodyElement?.classList.contains(className)) {
 			return true
 		}
 	}
@@ -70,7 +70,7 @@ function isColorDark(colorString: string, threshold = 128) {
 function isBackgroundDark() {
 	// We check both <html> and <body> because some pages set the color on <html>
 	const htmlStyle = window.getComputedStyle(document.documentElement)
-	const bodyStyle = window.getComputedStyle(document.body)
+	const bodyStyle = window.getComputedStyle(document.body || document.documentElement)
 
 	// Get background colors
 	const htmlBgColor = htmlStyle.backgroundColor
@@ -93,18 +93,23 @@ function isBackgroundDark() {
  * @returns {boolean} - True if the page is likely dark.
  */
 export function isPageDark() {
-	// Strategy 1: Check for common dark mode classes
+	try {
-	if (hasDarkModeClass()) {
+		// Strategy 1: Check for common dark mode classes
-		return true
+		if (hasDarkModeClass()) {
+			return true
+		}
+
+		// Strategy 2: Analyze the computed background color
+		if (isBackgroundDark()) {
+			return true
+		}
+
+		// @TODO add more checks here, e.g., analyzing text color,
+		// or checking the background of major layout elements like <main> or #app.
+
+		return false
+	} catch (error) {
+		console.warn('Error determining if page is dark:', error)
+		return false
 	}
-
-	// Strategy 2: Analyze the computed background color
-	if (isBackgroundDark()) {
-		return true
-	}
-
-	// @TODO add more checks here, e.g., analyzing text color,
-	// or checking the background of major layout elements like <main> or #app.
-
-	return false
 }

packages/page-controller/src/patches/antd.ts

@@ -1,4 +1,4 @@
-import type { PageAgent } from '../PageAgent'
+import type { PageController } from '../PageController'
 
 const clearFunctions = [] as (() => void)[]
 
@@ -11,9 +11,9 @@ function fixAntdSelect() {
 	// for (const select of selects) {}
 }
 
-export function patchAntd(pageAgent: PageAgent) {
+export function patchAntd(pageController: PageController) {
-	pageAgent.addEventListener('beforeUpdate', fixAntdSelect)
+	pageController.addEventListener('beforeUpdate', fixAntdSelect)
-	pageAgent.addEventListener('afterUpdate', () => {
+	pageController.addEventListener('afterUpdate', () => {
 		for (const fn of clearFunctions) fn()
 		clearFunctions.length = 0
 	})

packages/page-controller/src/patches/react.ts

@@ -1,7 +1,7 @@
-import type { PageAgent } from '../PageAgent'
+import type { PageController } from '../PageController'
 
 // Find common React root elements and add data-page-agent-not-interactive attribute
-export function patchReact(pageAgent: PageAgent) {
+export function patchReact(pageController: PageController) {
 	const reactRootElements = document.querySelectorAll(
 		'[data-reactroot], [data-reactid], [data-react-checksum], #root, #app, [id^="root-"], [id^="app-"], #adex-wrapper, #adex-root'
 	)

packages/page-controller/tsconfig.dts.json

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

packages/page-controller/tsconfig.json

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

packages/page-controller/vite.config.js

@@ -0,0 +1,45 @@
+// @ts-check
+import chalk from 'chalk'
+import { dirname, resolve } from 'path'
+import dts from 'unplugin-dts/vite'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+console.log(chalk.cyan(`📦 Building @page-agent/page-controller`))
+
+export default defineConfig({
+	clearScreen: false,
+	plugins: [
+		dts({ tsconfigPath: './tsconfig.dts.json', bundleTypes: true }),
+		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
+	],
+	publicDir: false,
+	esbuild: {
+		keepNames: true,
+	},
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/PageController.ts'),
+			name: 'PageController',
+			fileName: 'page-controller',
+			formats: ['es'],
+		},
+		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,
+		cssCodeSplit: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})

packages/ui/package.json

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

packages/ui/src/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,11 +1,34 @@
-import type { PageAgent } from '../PageAgent'
-import type { I18n } from '../i18n'
-import { truncate } from '../utils'
-import type { EventBus } from '../utils/bus'
 import { type Step, UIState } from './UIState'
+import { I18n, type SupportedLanguage } from './i18n'
+import { escapeHtml, truncate } from './utils'
 
 import styles from './Panel.module.css'
 
+/**
+ * Panel configuration
+ */
+export interface PanelConfig {
+	language?: SupportedLanguage
+	onExecuteTask: (task: string) => void
+	onStop: () => void
+}
+
+/**
+ * Semantic update types - Panel handles i18n internally
+ */
+export type PanelUpdate =
+	| { type: 'thinking'; text?: string } // text is optional, defaults to i18n thinking text
+	| { type: 'input'; task: string }
+	| { type: 'question'; question: string }
+	| { type: 'userAnswer'; input: string }
+	| { type: 'retry'; current: number; max: number }
+	| { type: 'error'; message: string }
+	| { type: 'output'; text: string }
+	| { type: 'completed' }
+	| { type: 'toolExecuting'; toolName: string; args: any }
+	| { type: 'toolCompleted'; toolName: string; args: any; result?: string; duration?: number }
+	| { type: 'observation'; content: string }
+
 /**
  * Agent control panel
  */
@@ -15,15 +38,14 @@ export class Panel {
 	#statusText: HTMLElement
 	#historySection: HTMLElement
 	#expandButton: HTMLElement
-	#pauseButton: HTMLElement
 	#stopButton: HTMLElement
 	#inputSection: HTMLElement
 	#taskInput: HTMLInputElement
-	#bus: EventBus
 
 	#state = new UIState()
 	#isExpanded = false
-	#pageAgent: PageAgent
+	#config: PanelConfig
+	#i18n: I18n
 	#userAnswerResolver: ((input: string) => void) | null = null
 	#isWaitingForUserAnswer: boolean = false
 	#headerUpdateTimer: ReturnType<typeof setInterval> | null = null
@@ -34,31 +56,24 @@ export class Panel {
 		return this.#wrapper
 	}
 
-	constructor(pageAgent: PageAgent) {
+	constructor(config: PanelConfig) {
-		this.#pageAgent = pageAgent
+		this.#config = config
-		this.#bus = pageAgent.bus
+		this.#i18n = new I18n(config.language ?? 'en-US')
 		this.#wrapper = this.#createWrapper()
 		this.#indicator = this.#wrapper.querySelector(`.${styles.indicator}`)!
 		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}`)!
 
 		this.#setupEventListeners()
 		this.#startHeaderUpdateLoop()
-		// this.#expand() // debug
 
 		this.#showInputArea()
 
-		this.#bus.on('panel:show', () => this.#show())
+		this.hide() // Start hidden
-		this.#bus.on('panel:hide', () => this.#hide())
-		this.#bus.on('panel:reset', () => this.#reset())
-		this.#bus.on('panel:update', (stepData) => this.#update(stepData))
-		this.#bus.on('panel:expand', () => this.#expand())
-		this.#bus.on('panel:collapse', () => this.#collapse())
 	}
 
 	/**
@@ -71,18 +86,62 @@ export class Panel {
 			this.#userAnswerResolver = resolve
 
 			// Update state to `running`
-			this.#update({
+			this.#updateInternal({
 				type: 'output',
-				displayText: this.#pageAgent.i18n.t('ui.panel.question', { question }),
+				displayText: this.#i18n.t('ui.panel.question', { question }),
 			}) // Expand history panel
 			if (!this.#isExpanded) {
 				this.#expand()
 			}
 
-			this.#showInputArea(this.#pageAgent.i18n.t('ui.panel.userAnswerPrompt'))
+			this.#showInputArea(this.#i18n.t('ui.panel.userAnswerPrompt'))
 		})
 	}
 
+	// ========== Public control methods ==========
+
+	show(): void {
+		this.wrapper.style.display = 'block'
+		void this.wrapper.offsetHeight
+		this.wrapper.style.opacity = '1'
+		this.wrapper.style.transform = 'translateX(-50%) translateY(0)'
+	}
+
+	hide(): void {
+		this.wrapper.style.opacity = '0'
+		this.wrapper.style.transform = 'translateX(-50%) translateY(20px)'
+		this.wrapper.style.display = 'none'
+	}
+
+	reset(): void {
+		this.#state.reset()
+		this.#statusText.textContent = this.#i18n.t('ui.panel.ready')
+		this.#updateStatusIndicator('thinking')
+		this.#updateHistory()
+		this.#collapse()
+		// Reset user input state
+		this.#isWaitingForUserAnswer = false
+		this.#userAnswerResolver = null
+		// Show input area
+		this.#showInputArea()
+	}
+
+	expand(): void {
+		this.#expand()
+	}
+
+	collapse(): void {
+		this.#collapse()
+	}
+
+	/**
+	 * Update panel with semantic data - i18n handled internally
+	 */
+	update(data: PanelUpdate): void {
+		const stepData = this.#toStepData(data)
+		this.#updateInternal(stepData)
+	}
+
 	/**
 	 * Dispose panel
 	 */
@@ -92,10 +151,104 @@ export class Panel {
 		this.wrapper.remove()
 	}
 
+	// ========== Private methods ==========
+
 	/**
-	 * Update status
+	 * Convert semantic update to step data with i18n
 	 */
-	#update(stepData: Omit<Step, 'id' | 'stepNumber' | 'timestamp'>): void {
+	#toStepData(data: PanelUpdate): Omit<Step, 'id' | 'stepNumber' | 'timestamp'> {
+		switch (data.type) {
+			case 'thinking':
+				return { type: 'thinking', displayText: data.text ?? this.#i18n.t('ui.panel.thinking') }
+			case 'input':
+				return { type: 'input', displayText: data.task }
+			case 'question':
+				return {
+					type: 'output',
+					displayText: this.#i18n.t('ui.panel.question', { question: data.question }),
+				}
+			case 'userAnswer':
+				return {
+					type: 'input',
+					displayText: this.#i18n.t('ui.panel.userAnswer', { input: data.input }),
+				}
+			case 'retry':
+				return { type: 'retry', displayText: `retry-ing (${data.current} / ${data.max})` }
+			case 'error':
+				return { type: 'error', displayText: data.message }
+			case 'output':
+				return { type: 'output', displayText: data.text }
+			case 'completed':
+				return { type: 'completed', displayText: this.#i18n.t('ui.panel.taskCompleted') }
+			case 'toolExecuting':
+				return {
+					type: 'tool_executing',
+					toolName: data.toolName,
+					toolArgs: data.args,
+					displayText: this.#getToolExecutingText(data.toolName, data.args),
+				}
+			case 'toolCompleted': {
+				const displayText = this.#getToolCompletedText(data.toolName, data.args)
+				if (!displayText) return { type: 'tool_executing', displayText: '' } // will be filtered
+				return {
+					type: 'tool_executing',
+					toolName: data.toolName,
+					toolArgs: data.args,
+					toolResult: data.result,
+					displayText,
+					duration: data.duration,
+				}
+			}
+			case 'observation':
+				return { type: 'observation', displayText: data.content }
+		}
+	}
+
+	#getToolExecutingText(toolName: string, args: any): string {
+		switch (toolName) {
+			case 'click_element_by_index':
+				return this.#i18n.t('ui.tools.clicking', { index: args.index })
+			case 'input_text':
+				return this.#i18n.t('ui.tools.inputting', { index: args.index })
+			case 'select_dropdown_option':
+				return this.#i18n.t('ui.tools.selecting', { text: args.text })
+			case 'scroll':
+				return this.#i18n.t('ui.tools.scrolling')
+			case 'wait':
+				return this.#i18n.t('ui.tools.waiting', { seconds: args.seconds })
+			case 'done':
+				return this.#i18n.t('ui.tools.done')
+			default:
+				return this.#i18n.t('ui.tools.executing', { toolName })
+		}
+	}
+
+	#getToolCompletedText(toolName: string, args: any): string | null {
+		switch (toolName) {
+			case 'click_element_by_index':
+				return this.#i18n.t('ui.tools.clicked', { index: args.index })
+			case 'input_text':
+				return this.#i18n.t('ui.tools.inputted', { text: args.text })
+			case 'select_dropdown_option':
+				return this.#i18n.t('ui.tools.selected', { text: args.text })
+			case 'scroll':
+				return this.#i18n.t('ui.tools.scrolled')
+			case 'wait':
+				return this.#i18n.t('ui.tools.waited')
+			case 'done':
+				return null
+			default:
+				return null
+		}
+	}
+
+	/**
+	 * Update status (internal)
+	 */
+	#updateInternal(stepData: Omit<Step, 'id' | 'stepNumber' | 'timestamp'>): void {
+		// Skip empty displayText (filtered toolCompleted for 'done')
+		if (!stepData.displayText) return
+
 		const step = this.#state.addStep(stepData)
 
 		// Queue header text update (will be processed by periodic check)
@@ -120,88 +273,17 @@ export class Panel {
 		}
 	}
 
-	/**
-	 * Show panel
-	 */
-	#show(): void {
-		this.wrapper.style.display = 'block'
-		// Force reflow to trigger animation
-		void this.wrapper.offsetHeight
-		this.wrapper.style.opacity = '1'
-		this.wrapper.style.transform = 'translateX(-50%) translateY(0)'
-	}
-
-	/**
-	 * Hide panel
-	 */
-	#hide(): void {
-		this.wrapper.style.opacity = '0'
-		this.wrapper.style.transform = 'translateX(-50%) translateY(20px)'
-		this.wrapper.style.display = 'none'
-	}
-
-	/**
-	 * Reset state
-	 */
-	#reset(): void {
-		this.#state.reset()
-		this.#statusText.textContent = this.#pageAgent.i18n.t('ui.panel.ready')
-		this.#updateStatusIndicator('thinking')
-		this.#updateHistory()
-		this.#collapse()
-		// Reset pause state
-		this.#pageAgent.paused = false
-		this.#updatePauseButton()
-		// Reset user input state
-		this.#isWaitingForUserAnswer = false
-		this.#userAnswerResolver = null
-		// Show input area
-		this.#showInputArea()
-	}
-
-	/**
-	 * Toggle pause state
-	 */
-	#togglePause(): void {
-		this.#pageAgent.paused = !this.#pageAgent.paused
-		this.#updatePauseButton()
-
-		// Update status display
-		if (this.#pageAgent.paused) {
-			this.#statusText.textContent = this.#pageAgent.i18n.t('ui.panel.paused')
-			this.#updateStatusIndicator('thinking') // Use existing thinking state
-		} else {
-			this.#statusText.textContent = this.#pageAgent.i18n.t('ui.panel.continueExecution')
-			this.#updateStatusIndicator('tool_executing') // Restore to execution state
-		}
-	}
-
-	/**
-	 * Update pause button state
-	 */
-	#updatePauseButton(): void {
-		if (this.#pageAgent.paused) {
-			this.#pauseButton.textContent = '▶'
-			this.#pauseButton.title = this.#pageAgent.i18n.t('ui.panel.continue')
-			this.#pauseButton.classList.add(styles.paused)
-		} else {
-			this.#pauseButton.textContent = '⏸︎'
-			this.#pauseButton.title = this.#pageAgent.i18n.t('ui.panel.pause')
-			this.#pauseButton.classList.remove(styles.paused)
-		}
-	}
-
 	/**
 	 * Stop Agent
 	 */
 	#stopAgent(): void {
 		// Update status display
-		this.#update({
+		this.#updateInternal({
 			type: 'error',
-			displayText: this.#pageAgent.i18n.t('ui.panel.taskTerminated'),
+			displayText: this.#i18n.t('ui.panel.taskTerminated'),
 		})
 
-		this.#pageAgent.dispose()
+		this.#config.onStop()
 	}
 
 	/**
@@ -218,7 +300,7 @@ export class Panel {
 			// Handle user input mode
 			this.#handleUserAnswer(input)
 		} else {
-			this.#pageAgent.execute(input)
+			this.#config.onExecuteTask(input)
 		}
 	}
 
@@ -227,9 +309,9 @@ export class Panel {
 	 */
 	#handleUserAnswer(input: string): void {
 		// Add user input to history
-		this.#update({
+		this.#updateInternal({
 			type: 'input',
-			displayText: this.#pageAgent.i18n.t('ui.panel.userAnswer', { input }),
+			displayText: this.#i18n.t('ui.panel.userAnswer', { input }),
 		})
 
 		// Reset state
@@ -248,7 +330,7 @@ export class Panel {
 	#showInputArea(placeholder?: string): void {
 		// Clear input field
 		this.#taskInput.value = ''
-		this.#taskInput.placeholder = placeholder || this.#pageAgent.i18n.t('ui.panel.taskInput')
+		this.#taskInput.placeholder = placeholder || this.#i18n.t('ui.panel.taskInput')
 		this.#inputSection.classList.remove(styles.hidden)
 		// Focus on input field
 		setTimeout(() => {
@@ -282,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 = `
@@ -294,23 +376,20 @@ export class Panel {
 						stepNumber: 0,
 						timestamp: new Date(),
 						type: 'thinking',
-						displayText: this.#pageAgent.i18n.t('ui.panel.waitingPlaceholder'),
+						displayText: this.#i18n.t('ui.panel.waitingPlaceholder'),
 					})}
 				</div>
 			</div>
 			<div class="${styles.header}">
 				<div class="${styles.statusSection}">
 					<div class="${styles.indicator} ${styles.thinking}"></div>
-					<div class="${styles.statusText}">${this.#pageAgent.i18n.t('ui.panel.ready')}</div>
+					<div class="${styles.statusText}">${this.#i18n.t('ui.panel.ready')}</div>
 				</div>
 				<div class="${styles.controls}">
-					<button class="${styles.controlButton} ${styles.expandButton}" title="${this.#pageAgent.i18n.t('ui.panel.expand')}">
+					<button class="${styles.controlButton} ${styles.expandButton}" title="${this.#i18n.t('ui.panel.expand')}">
 						▼
 					</button>
-					<button class="${styles.controlButton} ${styles.pauseButton}" title="${this.#pageAgent.i18n.t('ui.panel.pause')}">
+					<button class="${styles.controlButton} ${styles.stopButton}" title="${this.#i18n.t('ui.panel.stop')}">
-						⏸︎
-					</button>
-					<button class="${styles.controlButton} ${styles.stopButton}" title="${this.#pageAgent.i18n.t('ui.panel.stop')}">
 						X
 					</button>
 				</div>
@@ -347,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()
@@ -384,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 = '▲'
 	}
@@ -392,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 = '▼'
 	}
 
@@ -471,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()
 	}
 
@@ -501,8 +569,8 @@ export class Panel {
 			// Check if this is a result from done tool
 			if (step.toolName === 'done') {
 				// Judge success or failure based on result
-				const failureKeyword = this.#pageAgent.i18n.t('ui.tools.resultFailure')
+				const failureKeyword = this.#i18n.t('ui.tools.resultFailure')
-				const errorKeyword = this.#pageAgent.i18n.t('ui.tools.resultError')
+				const errorKeyword = this.#i18n.t('ui.tools.resultError')
 				const isSuccess =
 					!step.toolResult ||
 					(!step.toolResult.includes(failureKeyword) && !step.toolResult.includes(errorKeyword))
@@ -516,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 = '🤖'
@@ -526,12 +594,15 @@ export class Panel {
 		} else if (step.type === 'retry') {
 			typeClass = styles.retry
 			statusIcon = '🔄'
+		} else if (step.type === 'observation') {
+			typeClass = styles.observation
+			statusIcon = '👁️'
 		} else {
 			statusIcon = '🧠'
 		}
 
 		const durationText = step.duration ? ` · ${step.duration}ms` : ''
-		const stepLabel = this.#pageAgent.i18n.t('ui.panel.step', {
+		const stepLabel = this.#i18n.t('ui.panel.step', {
 			number: step.stepNumber.toString(),
 			time,
 			duration: durationText || '', // Explicitly pass empty string to replace template
@@ -541,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}
@@ -550,47 +621,3 @@ export class Panel {
 		`
 	}
 }
-
-/**
- * Get display text for tool execution
- */
-export function getToolExecutingText(toolName: string, args: any, i18n: I18n): string {
-	switch (toolName) {
-		case 'click_element_by_index':
-			return i18n.t('ui.tools.clicking', { index: args.index })
-		case 'input_text':
-			return i18n.t('ui.tools.inputting', { index: args.index })
-		case 'select_dropdown_option':
-			return i18n.t('ui.tools.selecting', { text: args.text })
-		case 'scroll':
-			return i18n.t('ui.tools.scrolling')
-		case 'wait':
-			return i18n.t('ui.tools.waiting', { seconds: args.seconds })
-		case 'done':
-			return i18n.t('ui.tools.done')
-		default:
-			return i18n.t('ui.tools.executing', { toolName })
-	}
-}
-
-/**
- * Get display text for tool completion
- */
-export function getToolCompletedText(toolName: string, args: any, i18n: I18n): string | null {
-	switch (toolName) {
-		case 'click_element_by_index':
-			return i18n.t('ui.tools.clicked', { index: args.index })
-		case 'input_text':
-			return i18n.t('ui.tools.inputted', { text: args.text })
-		case 'select_dropdown_option':
-			return i18n.t('ui.tools.selected', { text: args.text })
-		case 'scroll':
-			return i18n.t('ui.tools.scrolled')
-		case 'wait':
-			return i18n.t('ui.tools.waited')
-		case 'done':
-			return null
-		default:
-			return null
-	}
-}

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/env.d.ts

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

packages/ui/src/i18n/index.ts

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

packages/ui/src/i18n/locales.ts

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

packages/ui/src/index.ts

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

packages/ui/src/utils.ts

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

packages/ui/tsconfig.dts.json

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

packages/ui/tsconfig.json

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

packages/ui/vite.config.js

@@ -0,0 +1,41 @@
+// @ts-check
+import chalk from 'chalk'
+import { dirname, resolve } from 'path'
+import dts from 'unplugin-dts/vite'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+console.log(chalk.cyan(`📦 Building @page-agent/ui`))
+
+export default defineConfig({
+	clearScreen: false,
+	plugins: [
+		dts({ tsconfigPath: './tsconfig.dts.json', bundleTypes: true }),
+		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
+	],
+	publicDir: false,
+	esbuild: {
+		keepNames: true,
+	},
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/index.ts'),
+			name: 'PageAgentUI',
+			fileName: 'page-agent-ui',
+			formats: ['es'],
+		},
+		outDir: resolve(__dirname, 'dist', 'lib'),
+		rollupOptions: {
+			external: [],
+		},
+		minify: false,
+		sourcemap: true,
+		cssCodeSplit: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})

packages/website/AGENTS.md

@@ -0,0 +1,110 @@
+# Website Package - Instructions for Coding Assistants
+
+## Tech Stack
+
+- **React** with TypeScript
+- **Vite** for dev server and build
+- **Tailwind CSS** for styling
+- **shadcn/ui** (new-york style) for UI components
+- **Magic UI** for animations and effects
+- **wouter** with hash routing for static hosting
+- **lucide-react** for icons
+
+## Component Guidelines
+
+### Use shadcn/ui Components First
+
+**ALWAYS prefer shadcn/ui components over custom implementations.**
+
+Before creating any UI component, check if shadcn already provides it:
+
+```bash
+# IMPORTANT: Run from packages/website/, NOT from repo root
+cd packages/website
+
+# Add a new shadcn component
+npx shadcn@latest add <component-name>
+
+# Add a Magic UI component
+npx shadcn@latest add "@magicui/<component-name>"
+```
+
+Available shadcn components: https://ui.shadcn.com/docs/components
+Available Magic UI components: https://magicui.design/docs/components
+
+### Current UI Components
+
+Located in `src/components/ui/`:
+
+**From shadcn/ui:**
+
+- `alert`, `badge`, `button`, `separator`, `sonner`, `switch`, `tooltip`
+
+**From Magic UI:**
+
+- `animated-gradient-text`, `animated-shiny-text`, `aurora-text`
+- `hyper-text`, `magic-card`, `neon-gradient-card`, `particles`
+- `sparkles-text`, `text-animate`, `typing-animation`
+
+**Custom:**
+
+- `highlighter`, `kbd`, `spinner`
+
+### Styling Rules
+
+1. **Prefer Tailwind classes** over custom CSS
+2. Use CSS modules only for complex component-specific styles
+3. Support dark mode via `dark:` classes
+4. Use CSS variables from `src/index.css` for theme colors
+
+## Project Structure
+
+```
+src/
+├── pages/
+│   ├── Home.tsx         # Homepage
+│   └── docs/
+│       ├── Layout.tsx   # Documentation sidebar
+│       └── [section]/[topic]/page.tsx
+├── components/
+│   ├── ui/              # shadcn/ui + Magic UI components
+│   ├── Header.tsx       # Site header
+│   └── Footer.tsx       # Site footer
+├── i18n/                # Internationalization
+├── router.tsx           # Central routing
+└── main.tsx             # App entry
+```
+
+## Adding New Pages
+
+### Documentation Page
+
+1. Create `src/pages/docs/<section>/<slug>/page.tsx`
+2. Add route to `src/router.tsx` with `<Header /> + <DocsLayout>` wrapper
+3. Add navigation item to `pages/docs/Layout.tsx`
+
+## Routing
+
+Uses hash-based routing for static hosting:
+
+```tsx
+import { Router } from 'wouter'
+import { useHashLocation } from 'wouter/use-hash-location'
+
+;<Router hook={useHashLocation}>{/* routes */}</Router>
+```
+
+## Configuration Files
+
+| File              | Purpose                 |
+| ----------------- | ----------------------- |
+| `components.json` | shadcn/ui configuration |
+| `vite.config.js`  | Vite build settings     |
+| `tsconfig.json`   | TypeScript config       |
+
+## Commands
+
+```bash
+npm start        # Dev server (from root)
+npm run build:website    # Build website (from root)
+```

packages/website/components.json

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

packages/website/package.json

@@ -1,28 +1,42 @@
 {
 	"name": "@page-agent/website",
 	"private": true,
-	"version": "0.0.5",
+	"version": "0.2.2",
 	"type": "module",
 	"scripts": {
-		"dev": "vite",
+		"dev": "vite --host 0.0.0.0",
-		"build": "vite build",
+		"build:website": "vite build",
 		"preview": "vite preview",
 		"typecheck": "tsc --noEmit"
 	},
-	"dependencies": {
-		"page-agent": "*"
-	},
 	"devDependencies": {
-		"@tailwindcss/vite": "^4.1.14",
+		"@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.6.0",
+		"i18next": "^25.7.4",
 		"i18next-browser-languagedetector": "^8.2.0",
-		"react": "^19.2.0",
+		"react": "^19.2.3",
-		"react-dom": "^19.2.0",
+		"react-dom": "^19.2.3",
-		"react-i18next": "^16.1.4",
+		"react-i18next": "^16.5.2",
 		"tailwindcss": "^4.1.14",
-		"wouter": "^3.7.1"
+		"tw-animate-css": "^1.4.0",
+		"wouter": "^3.9.0"
+	},
+	"dependencies": {
+		"@radix-ui/react-icons": "^1.3.2",
+		"@radix-ui/react-separator": "^1.1.8",
+		"@radix-ui/react-slot": "^1.2.4",
+		"@radix-ui/react-switch": "^1.2.6",
+		"@radix-ui/react-tooltip": "^1.2.8",
+		"class-variance-authority": "^0.7.1",
+		"clsx": "^2.1.1",
+		"lucide-react": "^0.562.0",
+		"motion": "^12.26.1",
+		"next-themes": "^0.4.6",
+		"rough-notation": "^0.5.1",
+		"simple-icons": "^16.5.0",
+		"sonner": "^2.0.7",
+		"tailwind-merge": "^3.4.0"
 	}
 }

packages/website/src/components/Footer.tsx

@@ -1,4 +1,5 @@
 import { useTranslation } from 'react-i18next'
+import { siGithub } from 'simple-icons'
 
 export default function Footer() {
 	const { t } = useTranslation('common')
@@ -19,8 +20,13 @@ export default function Footer() {
 							className="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-white transition-colors duration-200"
 							aria-label={t('footer.github_label')}
 						>
-							<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+							<svg
-								<path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z" />
+								role="img"
+								viewBox="0 0 24 24"
+								className="w-5 h-5 fill-current"
+								aria-hidden="true"
+							>
+								<path d={siGithub.path} />
 							</svg>
 						</a>
 					</div>

packages/website/src/components/Header.tsx

@@ -1,10 +1,12 @@
+import { BookOpen, Menu, X } from 'lucide-react'
 import { useState } from 'react'
 import { useTranslation } from 'react-i18next'
+import { siGithub } from 'simple-icons'
 import { Link } from 'wouter'
 
 import LanguageSwitcher from './LanguageSwitcher'
 import ThemeSwitcher from './ThemeSwitcher'
-import { BookIcon, CloseIcon, GithubIcon, MenuIcon } from './icons'
+import { HyperText } from './ui/hyper-text'
 
 export default function Header() {
 	const { t } = useTranslation('common')
@@ -34,9 +36,15 @@ export default function Header() {
 								<span className="text-base sm:text-xl font-bold text-gray-900 dark:text-white block leading-tight">
 									page-agent
 								</span>
-								<p className="hidden sm:block text-xs text-gray-600 dark:text-gray-300">
+								<HyperText
+									as="p"
+									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')}
-								</p>
+								</HyperText>
 							</div>
 						</Link>
 
@@ -51,7 +59,7 @@ export default function Header() {
 								className="p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200 shrink-0"
 								aria-label={t('header.nav_docs')}
 							>
-								<BookIcon className="w-5 h-5" />
+								<BookOpen className="w-5 h-5" />
 							</Link>
 							<a
 								href="https://github.com/alibaba/page-agent"
@@ -60,7 +68,14 @@ export default function Header() {
 								className="p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200 shrink-0"
 								aria-label={t('header.nav_source')}
 							>
-								<GithubIcon className="w-5 h-5" />
+								<svg
+									role="img"
+									viewBox="0 0 24 24"
+									className="w-5 h-5 fill-current"
+									aria-hidden="true"
+								>
+									<path d={siGithub.path} />
+								</svg>
 							</a>
 						</nav>
 
@@ -70,11 +85,14 @@ 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"
 							>
-								<BookIcon />
+								<BookOpen className="w-4 h-4" />
 								{t('header.nav_docs')}
 							</Link>
 							<a
@@ -84,7 +102,14 @@ export default function Header() {
 								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"
 								aria-label={t('header.nav_source')}
 							>
-								<GithubIcon />
+								<svg
+									role="img"
+									viewBox="0 0 24 24"
+									className="w-4 h-4 fill-current"
+									aria-hidden="true"
+								>
+									<path d={siGithub.path} />
+								</svg>
 								{t('header.nav_source')}
 							</a>
 							<ThemeSwitcher />
@@ -100,7 +125,7 @@ export default function Header() {
 							aria-controls="mobile-menu"
 							onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
 						>
-							{mobileMenuOpen ? <CloseIcon /> : <MenuIcon />}
+							{mobileMenuOpen ? <X className="w-6 h-6" /> : <Menu className="w-6 h-6" />}
 						</button>
 					</div>
 
@@ -116,7 +141,7 @@ export default function Header() {
 								className="flex items-center gap-2 px-3 py-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
 								onClick={() => setMobileMenuOpen(false)}
 							>
-								<BookIcon className="w-5 h-5" />
+								<BookOpen className="w-5 h-5" />
 								{t('header.nav_docs')}
 							</Link>
 							<a
@@ -126,7 +151,14 @@ export default function Header() {
 								className="flex items-center gap-2 px-3 py-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
 								aria-label={t('header.nav_source')}
 							>
-								<GithubIcon className="w-5 h-5" />
+								<svg
+									role="img"
+									viewBox="0 0 24 24"
+									className="w-5 h-5 fill-current"
+									aria-hidden="true"
+								>
+									<path d={siGithub.path} />
+								</svg>
 								{t('header.nav_source')}
 							</a>
 							<div className="flex items-center gap-3 px-3 py-2">

packages/website/src/components/icons.tsx

@@ -1,75 +0,0 @@
-// SVG图标组件集合，用于Header等地方复用
-
-interface IconProps {
-	className?: string
-	'aria-hidden'?: boolean
-}
-
-export function BookIcon({ className = 'w-4 h-4', ...props }: IconProps) {
-	return (
-		<svg
-			className={className}
-			fill="none"
-			stroke="currentColor"
-			viewBox="0 0 24 24"
-			aria-hidden="true"
-			{...props}
-		>
-			<path
-				strokeLinecap="round"
-				strokeLinejoin="round"
-				strokeWidth={2}
-				d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 5c1.747 0 3.332.477 4.5 1.253v13C19.832 18.477 18.247 18 16.5 18c-1.746 0-3.332.477-4.5 1.253"
-			/>
-		</svg>
-	)
-}
-
-export function GithubIcon({ className = 'w-4 h-4', ...props }: IconProps) {
-	return (
-		<svg
-			className={className}
-			fill="currentColor"
-			viewBox="0 0 24 24"
-			aria-hidden="true"
-			{...props}
-		>
-			<path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z" />
-		</svg>
-	)
-}
-
-export function MenuIcon({ className = 'w-6 h-6', ...props }: IconProps) {
-	return (
-		<svg
-			className={className}
-			fill="none"
-			stroke="currentColor"
-			viewBox="0 0 24 24"
-			aria-hidden="true"
-			{...props}
-		>
-			<path
-				strokeLinecap="round"
-				strokeLinejoin="round"
-				strokeWidth={2}
-				d="M4 6h16M4 12h16M4 18h16"
-			/>
-		</svg>
-	)
-}
-
-export function CloseIcon({ className = 'w-6 h-6', ...props }: IconProps) {
-	return (
-		<svg
-			className={className}
-			fill="none"
-			stroke="currentColor"
-			viewBox="0 0 24 24"
-			aria-hidden="true"
-			{...props}
-		>
-			<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-		</svg>
-	)
-}

packages/website/src/components/ui/alert.tsx

@@ -0,0 +1,60 @@
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+const alertVariants = cva(
+	'relative w-full rounded-lg border px-4 py-3 text-sm grid has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] grid-cols-[0_1fr] has-[>svg]:gap-x-3 gap-y-0.5 items-start [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current',
+	{
+		variants: {
+			variant: {
+				default: 'bg-card text-card-foreground',
+				destructive:
+					'text-destructive bg-card [&>svg]:text-current *:data-[slot=alert-description]:text-destructive/90',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+		},
+	}
+)
+
+function Alert({
+	className,
+	variant,
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof alertVariants>) {
+	return (
+		<div
+			data-slot="alert"
+			role="alert"
+			className={cn(alertVariants({ variant }), className)}
+			{...props}
+		/>
+	)
+}
+
+function AlertTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="alert-title"
+			className={cn('col-start-2 line-clamp-1 min-h-4 font-medium tracking-tight', className)}
+			{...props}
+		/>
+	)
+}
+
+function AlertDescription({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="alert-description"
+			className={cn(
+				'text-muted-foreground col-start-2 grid justify-items-start gap-1 text-sm [&_p]:leading-relaxed',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export { Alert, AlertTitle, AlertDescription }

packages/website/src/components/ui/animated-gradient-text.tsx

@@ -0,0 +1,37 @@
+import { ComponentPropsWithoutRef } from 'react'
+
+import { cn } from '@/lib/utils'
+
+export interface AnimatedGradientTextProps extends ComponentPropsWithoutRef<'div'> {
+	speed?: number
+	colorFrom?: string
+	colorTo?: string
+}
+
+export function AnimatedGradientText({
+	children,
+	className,
+	speed = 1,
+	colorFrom = '#ffaa40',
+	colorTo = '#9c40ff',
+	...props
+}: AnimatedGradientTextProps) {
+	return (
+		<span
+			style={
+				{
+					'--bg-size': `${speed * 300}%`,
+					'--color-from': colorFrom,
+					'--color-to': colorTo,
+				} as React.CSSProperties
+			}
+			className={cn(
+				`animate-gradient inline bg-gradient-to-r from-[var(--color-from)] via-[var(--color-to)] to-[var(--color-from)] bg-[length:var(--bg-size)_100%] bg-clip-text text-transparent`,
+				className
+			)}
+			{...props}
+		>
+			{children}
+		</span>
+	)
+}

packages/website/src/components/ui/animated-shiny-text.tsx

@@ -0,0 +1,38 @@
+import { CSSProperties, ComponentPropsWithoutRef, FC } from 'react'
+
+import { cn } from '@/lib/utils'
+
+export interface AnimatedShinyTextProps extends ComponentPropsWithoutRef<'span'> {
+	shimmerWidth?: number
+}
+
+export const AnimatedShinyText: FC<AnimatedShinyTextProps> = ({
+	children,
+	className,
+	shimmerWidth = 100,
+	...props
+}) => {
+	return (
+		<span
+			style={
+				{
+					'--shiny-width': `${shimmerWidth}px`,
+				} as CSSProperties
+			}
+			className={cn(
+				'mx-auto max-w-md text-neutral-600/70 dark:text-neutral-400/70',
+
+				// Shine effect
+				'animate-shiny-text [background-size:var(--shiny-width)_100%] bg-clip-text [background-position:0_0] bg-no-repeat [transition:background-position_1s_cubic-bezier(.6,.6,0,1)_infinite]',
+
+				// Shine gradient
+				'bg-gradient-to-r from-transparent via-black/80 via-50% to-transparent dark:via-white/80',
+
+				className
+			)}
+			{...props}
+		>
+			{children}
+		</span>
+	)
+}

packages/website/src/components/ui/aurora-text.tsx

@@ -0,0 +1,39 @@
+import React, { memo } from 'react'
+
+interface AuroraTextProps {
+	children: React.ReactNode
+	className?: string
+	colors?: string[]
+	speed?: number
+}
+
+export const AuroraText = memo(
+	({
+		children,
+		className = '',
+		colors = ['#FF0080', '#7928CA', '#0070F3', '#38bdf8'],
+		speed = 1,
+	}: AuroraTextProps) => {
+		const gradientStyle = {
+			backgroundImage: `linear-gradient(135deg, ${colors.join(', ')}, ${colors[0]})`,
+			WebkitBackgroundClip: 'text',
+			WebkitTextFillColor: 'transparent',
+			animationDuration: `${10 / speed}s`,
+		}
+
+		return (
+			<span className={`relative inline-block ${className}`}>
+				<span className="sr-only">{children}</span>
+				<span
+					className="animate-aurora relative bg-[length:200%_auto] bg-clip-text text-transparent"
+					style={gradientStyle}
+					aria-hidden="true"
+				>
+					{children}
+				</span>
+			</span>
+		)
+	}
+)
+
+AuroraText.displayName = 'AuroraText'

packages/website/src/components/ui/badge.tsx

@@ -0,0 +1,37 @@
+import { Slot } from '@radix-ui/react-slot'
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+const badgeVariants = cva(
+	'inline-flex items-center justify-center rounded-full border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden',
+	{
+		variants: {
+			variant: {
+				default: 'border-transparent bg-primary text-primary-foreground [a&]:hover:bg-primary/90',
+				secondary:
+					'border-transparent bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90',
+				destructive:
+					'border-transparent bg-destructive text-white [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60',
+				outline: 'text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+		},
+	}
+)
+
+function Badge({
+	className,
+	variant,
+	asChild = false,
+	...props
+}: React.ComponentProps<'span'> & VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
+	const Comp = asChild ? Slot : 'span'
+
+	return <Comp data-slot="badge" className={cn(badgeVariants({ variant }), className)} {...props} />
+}
+
+export { Badge, badgeVariants }

packages/website/src/components/ui/bento-grid.tsx

@@ -0,0 +1,91 @@
+import { ArrowRightIcon } from '@radix-ui/react-icons'
+import { ComponentPropsWithoutRef, ReactNode } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { cn } from '@/lib/utils'
+
+interface BentoGridProps extends ComponentPropsWithoutRef<'div'> {
+	children: ReactNode
+	className?: string
+}
+
+interface BentoCardProps extends ComponentPropsWithoutRef<'div'> {
+	name: string
+	className: string
+	background: ReactNode
+	Icon: React.ElementType
+	description: string
+	href: string
+	cta: string
+}
+
+const BentoGrid = ({ children, className, ...props }: BentoGridProps) => {
+	return (
+		<div className={cn('grid w-full auto-rows-[22rem] grid-cols-3 gap-4', className)} {...props}>
+			{children}
+		</div>
+	)
+}
+
+const BentoCard = ({
+	name,
+	className,
+	background,
+	Icon,
+	description,
+	href,
+	cta,
+	...props
+}: BentoCardProps) => (
+	<div
+		key={name}
+		className={cn(
+			'group relative col-span-3 flex flex-col justify-between overflow-hidden rounded-xl',
+			// light styles
+			'bg-background [box-shadow:0_0_0_1px_rgba(0,0,0,.03),0_2px_4px_rgba(0,0,0,.05),0_12px_24px_rgba(0,0,0,.05)]',
+			// dark styles
+			'dark:bg-background transform-gpu dark:[box-shadow:0_-20px_80px_-20px_#ffffff1f_inset] dark:[border:1px_solid_rgba(255,255,255,.1)]',
+			className
+		)}
+		{...props}
+	>
+		<div>{background}</div>
+		<div className="p-4">
+			<div className="pointer-events-none z-10 flex transform-gpu flex-col gap-1 transition-all duration-300 lg:group-hover:-translate-y-10">
+				<Icon className="h-12 w-12 origin-left transform-gpu text-neutral-700 transition-all duration-300 ease-in-out group-hover:scale-75" />
+				<h3 className="text-xl font-semibold text-neutral-700 dark:text-neutral-300">{name}</h3>
+				<p className="max-w-lg text-neutral-400">{description}</p>
+			</div>
+
+			<div
+				className={cn(
+					'pointer-events-none flex w-full translate-y-0 transform-gpu flex-row items-center transition-all duration-300 group-hover:translate-y-0 group-hover:opacity-100 lg:hidden'
+				)}
+			>
+				<Button variant="link" asChild size="sm" className="pointer-events-auto p-0">
+					<a href={href}>
+						{cta}
+						<ArrowRightIcon className="ms-2 h-4 w-4 rtl:rotate-180" />
+					</a>
+				</Button>
+			</div>
+		</div>
+
+		<div
+			className={cn(
+				'pointer-events-none absolute bottom-0 hidden w-full translate-y-10 transform-gpu flex-row items-center p-4 opacity-0 transition-all duration-300 group-hover:translate-y-0 group-hover:opacity-100 lg:flex'
+			)}
+		>
+			<Button variant="link" asChild size="sm" className="pointer-events-auto p-0">
+				<a href={href}>
+					{cta}
+					<ArrowRightIcon className="ms-2 h-4 w-4 rtl:rotate-180" />
+				</a>
+			</Button>
+		</div>
+
+		<div className="pointer-events-none absolute inset-0 transform-gpu transition-all duration-300 group-hover:bg-black/[.03] group-hover:dark:bg-neutral-800/10" />
+	</div>
+)
+
+export { BentoCard, BentoGrid }

packages/website/src/components/ui/blur-fade.tsx

@@ -0,0 +1,79 @@
+import {
+	AnimatePresence,
+	MotionProps,
+	UseInViewOptions,
+	Variants,
+	motion,
+	useInView,
+} from 'motion/react'
+import { useRef } from 'react'
+
+type MarginType = UseInViewOptions['margin']
+
+interface BlurFadeProps extends MotionProps {
+	children: React.ReactNode
+	className?: string
+	variant?: {
+		hidden: { y: number }
+		visible: { y: number }
+	}
+	duration?: number
+	delay?: number
+	offset?: number
+	direction?: 'up' | 'down' | 'left' | 'right'
+	inView?: boolean
+	inViewMargin?: MarginType
+	blur?: string
+}
+
+export function BlurFade({
+	children,
+	className,
+	variant,
+	duration = 0.4,
+	delay = 0,
+	offset = 6,
+	direction = 'down',
+	inView = false,
+	inViewMargin = '-50px',
+	blur = '6px',
+	...props
+}: BlurFadeProps) {
+	const ref = useRef(null)
+	const inViewResult = useInView(ref, { once: true, margin: inViewMargin })
+	const isInView = !inView || inViewResult
+	const defaultVariants: Variants = {
+		hidden: {
+			[direction === 'left' || direction === 'right' ? 'x' : 'y']:
+				direction === 'right' || direction === 'down' ? -offset : offset,
+			opacity: 0,
+			filter: `blur(${blur})`,
+		},
+		visible: {
+			[direction === 'left' || direction === 'right' ? 'x' : 'y']: 0,
+			opacity: 1,
+			filter: `blur(0px)`,
+		},
+	}
+	const combinedVariants = variant || defaultVariants
+	return (
+		<AnimatePresence>
+			<motion.div
+				ref={ref}
+				initial="hidden"
+				animate={isInView ? 'visible' : 'hidden'}
+				exit="hidden"
+				variants={combinedVariants}
+				transition={{
+					delay: 0.04 + delay,
+					duration,
+					ease: 'easeOut',
+				}}
+				className={className}
+				{...props}
+			>
+				{children}
+			</motion.div>
+		</AnimatePresence>
+	)
+}

packages/website/src/components/ui/button.tsx

@@ -0,0 +1,60 @@
+import { Slot } from '@radix-ui/react-slot'
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+const buttonVariants = cva(
+	"inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+	{
+		variants: {
+			variant: {
+				default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+				destructive:
+					'bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60',
+				outline:
+					'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50',
+				secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+				ghost: 'hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50',
+				link: 'text-primary underline-offset-4 hover:underline',
+			},
+			size: {
+				default: 'h-9 px-4 py-2 has-[>svg]:px-3',
+				sm: 'h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5',
+				lg: 'h-10 rounded-md px-6 has-[>svg]:px-4',
+				icon: 'size-9',
+				'icon-sm': 'size-8',
+				'icon-lg': 'size-10',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+			size: 'default',
+		},
+	}
+)
+
+function Button({
+	className,
+	variant = 'default',
+	size = 'default',
+	asChild = false,
+	...props
+}: React.ComponentProps<'button'> &
+	VariantProps<typeof buttonVariants> & {
+		asChild?: boolean
+	}) {
+	const Comp = asChild ? Slot : 'button'
+
+	return (
+		<Comp
+			data-slot="button"
+			data-variant={variant}
+			data-size={size}
+			className={cn(buttonVariants({ variant, size, className }))}
+			{...props}
+		/>
+	)
+}
+
+export { Button, buttonVariants }

packages/website/src/components/ui/highlighter.tsx

@@ -0,0 +1,92 @@
+import { useInView } from 'motion/react'
+import { useEffect, useRef } from 'react'
+import type React from 'react'
+import { annotate } from 'rough-notation'
+import { type RoughAnnotation } from 'rough-notation/lib/model'
+
+type AnnotationAction =
+	| 'highlight'
+	| 'underline'
+	| 'box'
+	| 'circle'
+	| 'strike-through'
+	| 'crossed-off'
+	| 'bracket'
+
+interface HighlighterProps {
+	children: React.ReactNode
+	action?: AnnotationAction
+	color?: string
+	strokeWidth?: number
+	animationDuration?: number
+	iterations?: number
+	padding?: number
+	multiline?: boolean
+	isView?: boolean
+}
+
+export function Highlighter({
+	children,
+	action = 'highlight',
+	color = '#ffd1dc',
+	strokeWidth = 1.5,
+	animationDuration = 600,
+	iterations = 2,
+	padding = 2,
+	multiline = true,
+	isView = false,
+}: HighlighterProps) {
+	const elementRef = useRef<HTMLSpanElement>(null)
+	const annotationRef = useRef<RoughAnnotation | null>(null)
+
+	const isInView = useInView(elementRef, {
+		once: true,
+		margin: '-10%',
+	})
+
+	// If isView is false, always show. If isView is true, wait for inView
+	const shouldShow = !isView || isInView
+
+	useEffect(() => {
+		if (!shouldShow) return
+
+		const element = elementRef.current
+		if (!element) return
+
+		const annotationConfig = {
+			type: action,
+			color,
+			strokeWidth,
+			animationDuration,
+			iterations,
+			padding,
+			multiline,
+		}
+
+		const annotation = annotate(element, annotationConfig)
+
+		annotationRef.current = annotation
+		annotationRef.current.show()
+
+		const resizeObserver = new ResizeObserver(() => {
+			annotation.hide()
+			annotation.show()
+		})
+
+		resizeObserver.observe(element)
+		resizeObserver.observe(document.body)
+
+		return () => {
+			if (element) {
+				annotate(element, { type: action }).remove()
+				resizeObserver.disconnect()
+			}
+		}
+	}, [shouldShow, action, color, strokeWidth, animationDuration, iterations, padding, multiline])
+
+	return (
+		<span ref={elementRef} className="relative inline-block bg-transparent">
+			{children}
+		</span>
+	)
+}

packages/website/src/components/ui/hyper-text.tsx

@@ -0,0 +1,140 @@
+import { AnimatePresence, MotionProps, motion } from 'motion/react'
+import { useEffect, useRef, useState } from 'react'
+
+import { cn } from '@/lib/utils'
+
+type CharacterSet = string[] | readonly string[]
+
+interface HyperTextProps extends MotionProps {
+	/** The text content to be animated */
+	children: string
+	/** Optional className for styling */
+	className?: string
+	/** Duration of the animation in milliseconds */
+	duration?: number
+	/** Delay before animation starts in milliseconds */
+	delay?: number
+	/** Component to render as - defaults to div */
+	as?: React.ElementType
+	/** Whether to start animation when element comes into view */
+	startOnView?: boolean
+	/** Whether to trigger animation on hover */
+	animateOnHover?: boolean
+	/** Custom character set for scramble effect. Defaults to uppercase alphabet */
+	characterSet?: CharacterSet
+}
+
+const DEFAULT_CHARACTER_SET = Object.freeze(
+	'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('')
+) as readonly string[]
+
+const getRandomInt = (max: number): number => Math.floor(Math.random() * max)
+
+export function HyperText({
+	children,
+	className,
+	duration = 800,
+	delay = 0,
+	as: Component = 'div',
+	startOnView = false,
+	animateOnHover = true,
+	characterSet = DEFAULT_CHARACTER_SET,
+	...props
+}: HyperTextProps) {
+	const MotionComponent = motion.create(Component, {
+		forwardMotionProps: true,
+	})
+
+	const [displayText, setDisplayText] = useState<string[]>(() => children.split(''))
+	const [isAnimating, setIsAnimating] = useState(false)
+	const iterationCount = useRef(0)
+	const elementRef = useRef<HTMLElement>(null)
+
+	const handleAnimationTrigger = () => {
+		if (animateOnHover && !isAnimating) {
+			iterationCount.current = 0
+			setIsAnimating(true)
+		}
+	}
+
+	// Handle animation start based on view or delay
+	useEffect(() => {
+		if (!startOnView) {
+			const startTimeout = setTimeout(() => {
+				setIsAnimating(true)
+			}, delay)
+			return () => clearTimeout(startTimeout)
+		}
+
+		const observer = new IntersectionObserver(
+			([entry]) => {
+				if (entry.isIntersecting) {
+					setTimeout(() => {
+						setIsAnimating(true)
+					}, delay)
+					observer.disconnect()
+				}
+			},
+			{ threshold: 0.1, rootMargin: '-30% 0px -30% 0px' }
+		)
+
+		if (elementRef.current) {
+			observer.observe(elementRef.current)
+		}
+
+		return () => observer.disconnect()
+	}, [delay, startOnView])
+
+	// Handle scramble animation
+	useEffect(() => {
+		if (!isAnimating) return
+
+		const maxIterations = children.length
+		const startTime = performance.now()
+		let animationFrameId: number
+
+		const animate = (currentTime: number) => {
+			const elapsed = currentTime - startTime
+			const progress = Math.min(elapsed / duration, 1)
+
+			iterationCount.current = progress * maxIterations
+
+			setDisplayText((currentText) =>
+				currentText.map((letter, index) =>
+					letter === ' '
+						? letter
+						: index <= iterationCount.current
+							? children[index]
+							: characterSet[getRandomInt(characterSet.length)]
+				)
+			)
+
+			if (progress < 1) {
+				animationFrameId = requestAnimationFrame(animate)
+			} else {
+				setIsAnimating(false)
+			}
+		}
+
+		animationFrameId = requestAnimationFrame(animate)
+
+		return () => cancelAnimationFrame(animationFrameId)
+	}, [children, duration, isAnimating, characterSet])
+
+	return (
+		<MotionComponent
+			ref={elementRef}
+			className={cn('overflow-hidden py-2 text-4xl font-bold', className)}
+			onMouseEnter={handleAnimationTrigger}
+			{...props}
+		>
+			<AnimatePresence>
+				{displayText.map((letter, index) => (
+					<motion.span key={index} className={cn('font-mono', letter === ' ' ? 'w-3' : '')}>
+						{letter.toUpperCase()}
+					</motion.span>
+				))}
+			</AnimatePresence>
+		</MotionComponent>
+	)
+}