chore(version): bump version to 0.0.19

feat: custom instructions

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -6,32 +6,11 @@ body:
   - type: markdown
     attributes:
       value: |
-        Please follow our community communication guidelines when filing issues.
-        - Be polite and respectful.
-        - Prefer constructive, actionable feedback over venting.
-        - Include clear reproduction steps and environment details.
-        - Consider contributing a fix if possible — PRs are welcome.
+        Thanks for your interest in improving the project! Before submitting, please read our guidelines.
+        感谢您对改进项目的兴趣！提交前请阅读我们的指南。
 
-        提交 Issue 时请遵守社区沟通规范：
-        - 保持礼貌与尊重。
-        - 提供建设性、可行动的反馈，避免情绪化表达。
-        - 请包含清晰的复现步骤与环境信息。
-        - 如果可以，欢迎直接提交修复 PR。
-
-        See: CODE_OF_CONDUCT.md / CODE_OF_CONDUCT_zh.md, CONTRIBUTING.md
-
-  - type: checkboxes
-    id: community
-    attributes:
-      label: Community Communication / 社区沟通
-      description: Confirm you will communicate respectfully and constructively / 确认将以礼貌、建设性的方式沟通
-      options:
-        - label: I will be polite and respectful. / 我会保持礼貌与尊重。
-          required: true
-        - label: I will share constructive, actionable details. / 我会提供建设性、可行动的细节。
-          required: true
-        - label: I have read the Code of Conduct. / 我已阅读行为准则。
-          required: true
+        - [Code of Conduct](https://github.com/alibaba/page-agent/blob/main/CODE_OF_CONDUCT.md)
+        - [Contributing Guide](https://github.com/alibaba/page-agent/blob/main/CONTRIBUTING.md)
 
   - type: textarea
     id: description
@@ -48,7 +27,7 @@ body:
       render: typescript
       placeholder: Minimal reproduction code
     validations:
-      required: true
+      required: false
 
   - type: input
     id: browser
@@ -56,7 +35,7 @@ body:
       label: Browser
       placeholder: 'Chrome 120, Firefox 119, etc.'
     validations:
-      required: true
+      required: false
 
   - type: input
     id: version
@@ -64,4 +43,19 @@ body:
       label: version
       placeholder: '0.0.0'
     validations:
-      required: true
+      required: false
+
+  - type: checkboxes
+    id: community
+    attributes:
+      label: Community Communication / 社区沟通
+      description: Confirm you will communicate respectfully and constructively / 确认将以礼貌、建设性的方式沟通
+      options:
+        - label: I will be polite and respectful. / 我会保持礼貌与尊重。
+          required: true
+        - label: I will share constructive, actionable suggestions. / 我会提供建设性、可行动的建议。
+          required: true
+        - label: I have read the Code of Conduct. / 我已阅读行为准则。
+          required: true
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -12,6 +12,3 @@ contact_links:
   - name: Code of Conduct / 行为准则
     url: https://github.com/alibaba/page-agent/blob/main/CODE_OF_CONDUCT.md
     about: Community expectations and standards. 社区行为期望与标准。
-  - name: 行为准则（中文）
-    url: https://github.com/alibaba/page-agent/blob/main/CODE_OF_CONDUCT_zh.md
-    about: 中文版社区行为准则。

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -6,19 +6,30 @@ body:
   - type: markdown
     attributes:
       value: |
-        Please follow our community communication guidelines when proposing features.
-        - Be polite and respectful.
-        - Explain the problem first, then propose solutions.
-        - Prefer constructive, actionable suggestions.
-        - Contributions are encouraged — consider opening a PR.
+        Thanks for your interest in improving the project! Before submitting, please read our guidelines.
+        感谢您对改进项目的兴趣！提交前请阅读我们的指南。
 
-        提交功能建议时请遵守社区沟通规范：
-        - 保持礼貌与尊重。
-        - 先阐述问题，再提出解决方案。
-        - 提供建设性、可行动的建议。
-        - 鼓励代码贡献，欢迎直接提交 PR。
+        - [Code of Conduct](https://github.com/alibaba/page-agent/blob/main/CODE_OF_CONDUCT.md)
+        - [Contributing Guide](https://github.com/alibaba/page-agent/blob/main/CONTRIBUTING.md)
 
-        See: CODE_OF_CONDUCT.md / CODE_OF_CONDUCT_zh.md, CONTRIBUTING.md
+  - type: textarea
+    id: description
+    attributes:
+      label: Feature Description / 功能描述
+      description: Describe the problem, solution, and any API changes. / 描述问题、解决方案以及 API 变更。
+      placeholder: |
+        **Problem**:
+        What problem does this solve?
+
+        **Solution**:
+        How should this work?
+
+        **Proposed API**:
+        ```typescript
+        // code here
+        ```
+    validations:
+      required: true
 
   - type: checkboxes
     id: community
@@ -32,27 +43,5 @@ body:
           required: true
         - label: I have read the CODE_OF_CONDUCT.md and CONTRIBUTING.md. / 我已阅读行为准则。
           required: true
-
-  - type: textarea
-    id: problem
-    attributes:
-      label: Problem
-      placeholder: What problem does this solve?
     validations:
-      required: true
-
-  - type: textarea
-    id: solution
-    attributes:
-      label: Solution
-      placeholder: How should this work?
-    validations:
-      required: true
-
-  - type: textarea
-    id: api
-    attributes:
-      label: Proposed API
-      render: typescript
-    validations:
-      required: false
+      required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,9 +5,12 @@ Brief description of changes.
 ## Type
 
 - [ ] Bug fix
-- [ ] New feature
-- [ ] Breaking change
+- [ ] Feature / Improvement
+- [ ] Refactor
 - [ ] Documentation
+- [ ] Website
+- [ ] Demo / Testing
+- [ ] Breaking change
 
 ## Testing
 
@@ -19,10 +22,4 @@ Closes #(issue)
 
 ## Requirements / 要求
 
-- [ ] I will be polite and respectful. / 我会保持礼貌与尊重。
-- [ ] My comments and replies are constructive and actionable. / 我的评论与回复具有建设性。
 - [ ] I have read and follow the [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing Guide](CONTRIBUTING.md) . / 我已阅读并遵守行为准则。
-
-## Contributing / 贡献
-
-Constructive suggestions and code contributions are encouraged. If this PR originated from a discussion or issue, please link it above. 欢迎建设性意见与代码贡献；如源自讨论或 Issue，请在上方关联链接。

.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
@@ -33,7 +33,7 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v4
         with:
-          path: './dist'
+          path: './packages/website/dist'
 
       - name: Deploy to GitHub Pages
         id: deployment

.github/workflows/release.yml

@@ -13,20 +13,23 @@ 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
-          cache: 'npm'
+          node-version: 24
           registry-url: 'https://registry.npmjs.org'
 
+      # Ensure npm 11.5.1 or later is installed
+      - name: Update npm
+        run: npm install -g npm@latest
+        
       - name: Install dependencies
         run: npm ci
 
       - name: Build
-        run: npm run build:lib
+        run: npm run build:libs
 
-      - name: Publish to npm
-        run: npm publish
+      - name: Publish all public packages
+        run: npm publish --workspaces --access public

.gitignore

@@ -23,7 +23,13 @@ dist-ssr
 *.njsproj
 *.sln
 *.sw?
+.qoder
 
 
 # 
-.env
+.env
+
+# Copied files for npm publish (generated by prepublishOnly)
+packages/page-agent/README.md
+packages/page-agent/README-zh.md
+packages/page-agent/LICENSE

.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,16 @@
 {
 	"editor.fontLigatures": true,
-	"cSpell.words": ["HITL", "opensource", "retryable"],
+	"cSpell.words": [
+		"deepseek",
+		"HITL",
+		"innerhtml",
+		"llms",
+		"opensource",
+		"qwen",
+		"retryable",
+		"shadcn",
+		"wouter"
+	],
 	"markdownlint.config": {
 		// "comment": "Relaxed rules",
 		"default": true,

AGENTS.md

@@ -1,161 +1,126 @@
-# Instructions for coding assistants
+# Instructions for Coding Assistants
 
 ## Project Overview
 
-This is a dual-architecture project with **two separate parts**:
+This is a **monorepo** with npm workspaces:
 
-1. **Core Library** (`src/`) - Pure JavaScript/TypeScript AI agent library for browser DOM automation
-2. **Demo&docs Website** (`pages/`) - React documentation and landing page
+- **Core Library** (`packages/page-agent/`) - AI agent for browser DOM automation, published as `page-agent` on npm
+- **Website** (`packages/website/`) - React docs and landing page. **When working on website, follow `packages/website/AGENTS.md`**
+
+Internal packages:
+
+- **LLMs** (`packages/llms/`) - LLM client with reflection-before-action mental model
+- **Page Controller** (`packages/page-controller/`) - DOM operations, independent of LLM
+- **UI** (`packages/ui/`) - Panel, SimulatorMask, i18n. Decoupled from PageAgent
 
 ## Development Commands
 
-### Core Commands
-
 ```bash
-npm start                    # Start React website development server
-npm run build                # Build both library AND website
-npm run build:lib            # Build pure JS library only (src/ → dist/lib/)
-npm run build:lib:watch      # Library development with auto-rebuild
+npm start                    # Start website dev server
+npm run build                # Build all packages
+npm run build:libs           # Build all libraries
 npm run lint                 # ESLint with TypeScript strict rules
 ```
 
-## Architecture & Critical Patterns
+## Architecture
 
-### Dual Build System
+### Monorepo Structure
 
-- **Website build**: `vite.config.js` → React SPA with hash routing → `dist/`
-- **Library build**: `vite.lib.config.js` → UMD/ES modules → `dist/lib/`
-- **Entry points**: `src/entry.ts` (library), `pages/main.tsx` (website)
+Simple monorepo solution: TypeScript references + Vite aliases. Update tsconfig and vite config when adding/removing packages.
 
-### Module Boundaries (Critical)
+```
+packages/
+├── page-agent/              # npm: "page-agent" ⭐ MAIN
+├── website/                 # @page-agent/website (private)
+├── llms/                    # @page-agent/llms
+├── page-controller/         # @page-agent/page-controller
+└── ui/                      # @page-agent/ui
+```
 
-- **Core library** (`src/`): NEVER import from `pages/` - must remain pure JavaScript
-- **Website** (`pages/`): CAN import from `src/` via `@/` alias for demos
-- **Import aliases**: `@/` → `src/`, `@pages/` → `pages/`
+`workspaces` in `package.json` must be in topological order.
+
+### Module Boundaries
+
+- **Page Agent**: Core lib. Imports from `@page-agent/llms`, `@page-agent/page-controller`, `@page-agent/ui`
+- **LLMs**: LLM client with MacroToolInput contract. No dependency on page-agent
+- **UI**: Panel, Mask, i18n. No dependency on page-agent
+- **Page Controller**: Pure DOM operations. No LLM or UI dependency
+
+### 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/`
-2. **Dehydration**: DOM tree → simplified text for LLM processing
-3. **LLM Processing**: AI model returns action plans
-4. **Indexed Operations**: Map LLM responses back to specific DOM elements
+1. **DOM Extraction**: Live DOM → `FlatDomTree` via `page-controller/src/dom/dom_tree/`
+2. **Dehydration**: DOM tree → simplified text for LLM
+3. **LLM Processing**: AI returns action plans (page-agent)
+4. **Indexed Operations**: PageAgent calls PageController by element index
 
-### Event Bus Communication
+### CDN Auto-Injection
 
-Use `src/utils/bus.ts` for decoupled PageAgent ↔ UI communication:
-
-```typescript
-// Emit from PageAgent
-getEventBus().emit('panel:show')
-getEventBus().emit('panel:update', { status: 'thinking' })
-
-// Listen in UI components
-getEventBus().on('panel:show', () => panel.show())
-```
-
-### Hash Routing Requirement
-
-Uses wouter with `useHashLocation` for static hosting:
-
-```tsx
-<Router hook={useHashLocation}>  // Always hash-based routes
-```
-
-### CDN Auto-Injection Pattern
-
-Library auto-initializes when injected via script tag:
+Library auto-initializes via script tag:
 
 ```html
 <script src="page-agent.js?model=gpt-4"></script>
 ```
 
-Query params configure `PageAgentConfig` automatically in `src/entry.ts`.
+Query params configure `PageAgentConfig` in `src/umd.ts`.
 
-## File Organization
+## Key Files Reference
 
-### Core Library (`src/`)
+### Page Agent (`packages/page-agent/`)
 
-- `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
+| File | Description |
+|------|-------------|
+| `src/PageAgent.ts` | ⭐ Main AI agent class |
+| `src/umd.ts` | CDN/UMD entry with auto-init |
+| `src/tools/` | Tool definitions calling PageController |
 
-### Website (`pages/`)
+### LLMs (`packages/llms/`)
 
-- `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
+| File | Description |
+|------|-------------|
+| `src/index.ts` | ⭐ LLM class with retry logic |
+| `src/types.ts` | MacroToolInput, AgentBrain, LLMConfig |
+| `src/OpenAILenientClient.ts` | OpenAI-compatible client |
+
+### Page Controller (`packages/page-controller/`)
+
+| File | Description |
+|------|-------------|
+| `src/PageController.ts` | ⭐ Main controller class |
+| `src/actions.ts` | Element interactions (click, input, scroll) |
+| `src/dom/dom_tree/index.js` | Core DOM extraction engine |
 
 ## Adding New Features
 
-### New Documentation Page
-
-1. Create `pages/docs/<section>/<slug>/page.tsx`
-2. Add route to `pages/router.tsx` with `<Header /> + <DocsLayout>` wrapper
-3. Add navigation item to `DocsLayout.tsx`
-
 ### New Agent Tool
 
-1. Implement under `src/tools/`
-2. Export via `src/tools/index.ts`
-3. Wire into `PageAgent.ts` if needed
+1. Implement in `packages/page-agent/src/tools/index.ts`
+2. If tool needs DOM ops, add method to PageController first
+3. Tool calls `this.pageController.methodName()` for DOM interactions
 
-### New UI Component
+### New PageController Action
 
-1. Create in `src/ui/` with colocated CSS modules
-2. Use event bus for PageAgent communication
-3. Test via `pages/test-pages/`
+1. Add implementation in `packages/page-controller/src/actions.ts`
+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
-
-### CSS & Styling
-
-- **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
-
-- `pages/router.tsx` - Central routing definition (manual registration required)
-- `pages/components/DocsLayout.tsx` - Navigation structure
-- `src/PageAgent.ts` - Core AI agent class with DOM manipulation
-- `src/dom/dom_tree/index.js` - DOM extraction engine
-- `src/utils/bus.ts` - Type-safe event bus system
-- `src/entry.ts` - Library entry point for CDN usage
-- `vite.config.js` / `vite.lib.config.js` - Dual build configuration
-
-## Debugging Common Issues
-
-### Blank Documentation Pages
-
-1. Verify route exists in `pages/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 `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 `pages/test-pages/` for isolated testing
+- All code and comments must be in English.

CONTRIBUTING.md

@@ -7,11 +7,9 @@ Thank you for your interest in contributing to Page-Agent! We welcome contributi
 ### Development Setup
 
 1. **Prerequisites**
-   - Node.js 20+
-   - npm 10+
-   - typescript as required in package.json
-   - vscode or other editors that support ts/eslint/prettier
-   - make sure `eslint`, `auto-format` and `commit-lint` all work
+   - `node.js >= 20` with `npm >= 10`
+   - An editor that supports `ts/eslint/prettier`
+   - Make sure `eslint`, `prettier` and `commitlint` work well
 
 2. **Setup**
 
@@ -22,10 +20,16 @@ Thank you for your interest in contributing to Page-Agent! We welcome contributi
 
 ### Project Structure
 
-This project has **two separate parts**:
+This is a **monorepo** with npm workspaces containing **two main packages**:
 
-- **Core Library** (`src/`) - Pure JavaScript AI agent library
-- **Documentation Website** (`pages/`) - React web app for landing page and docs
+1. **Core Library** (`packages/page-agent/`) - Pure JavaScript/TypeScript AI agent library for browser DOM automation, published as `page-agent` on npm
+2. **Website** (`packages/website/`) - React documentation and landing page. Also as demo and test page for the core lib. private package `@page-agent/website`
+
+We use a simplified monorepo solution with `native npm-workspace + ts reference + vite alias`. No fancy tooling. Hoisting is required. 
+
+- When developing. Use alias so that we don't have to pre-build.
+- When bundling. Use external and disable ts `paths` alias to leave deps out.
+- When bundling `UMD` and `Website`. Bundle everything including local packages.
 
 ## 🤝 How to Contribute
 
@@ -95,19 +99,6 @@ This project has **two separate parts**:
    - 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
 
 ### Website Development
@@ -118,24 +109,26 @@ npm start                # React development server
 
 ### Core Lib Development and Testing
 
+> @TODO this part is outdated. Update this.
+
 - Config your LLM API
-- Start a local script
+- Start and serve a local umd script
 
    ```bash
-   npm run build:lib:watch    # Auto-rebuild on changes
+   npm run dev:umd # Serving UMD with auto rebuild at http://localhost:5173/page-agent.umd.cjs
    ```
 
 - Add a new bookmark enable it on other website
 
    ```
-   javascript:(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:5173/page-agent.umd.cjs?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
    ```
 
 ### Adding Documentation
 
-1. Create `pages/docs/section/page-name/page.tsx`
-2. Add route to `pages/router.tsx`
-3. Add navigation link to `pages/components/DocsLayout.tsx`
+1. Create `website/src/docs/section/page-name/page.tsx`
+2. Add route to `website/src/router.tsx`
+3. Add navigation link to `website/src/components/DocsLayout.tsx`
 
 ## 🎯 Contribution Areas
 

README-zh.md

@@ -4,13 +4,13 @@
 
 [![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)
 
-**让你的网页支持 AI 自动化。**
-
-运行在页面内的 UI agent. 使用自然语言操作 Web 应用。
+纯 JS 实现的 GUI agent。使用自然语言操作你的 Web 应用。无须后端、客户端、浏览器插件。
 
 🌐 [English](./README.md) | **中文**
 
-👉 [🚀 **Demo**](https://alibaba.github.io/page-agent/) | [📖 **Documentation**](https://alibaba.github.io/page-agent/#/docs/introduction/overview)
+👉 <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>
 
 ---
 
@@ -31,10 +31,11 @@
 ### CDN 集成
 
 ```html
-<!-- 临时 CDN URL. 未来会变更 -->
-<script
-	src="https://hwcxiuzfylggtcktqgij.supabase.co/storage/v1/object/public/demo-public/v0.0.2/page-agent.js"
-	crossorigin="true"
+// CDN        - https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js
+// Mirror(CN) - https://registry.npmmirror.com/page-agent/latest/files/dist/umd/page-agent.js
+<script 
+	src="https://registry.npmmirror.com/page-agent/latest/files/dist/umd/page-agent.js" 
+	crossorigin="true" 
 	type="text/javascript"
 ></script>
 ```
@@ -56,7 +57,7 @@ const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm
 const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
 
 const agent = new PageAgent({
-	modelName: DEMO_MODEL,
+	model: DEMO_MODEL,
 	baseURL: DEMO_BASE_URL,
 	apiKey: DEMO_API_KEY,
 	language: 'zh-CN',
@@ -67,16 +68,15 @@ await agent.execute('点击登录按钮')
 
 ## 🏗️ 架构设计
 
-PageAgent 采用清晰的模块化架构：
+PageAgent adopts a simplified monorepo structure:
 
 ```
-src/
-├── PageAgent.ts          # Agent 主流程
-├── dom/                  # DOM 理解
-├── tools/                # 代理交互工具
-├── ui/                   # UI 组件和面板
-├── llms/                 # LLM 集成层
-└── utils/                # 事件总线和工具
+packages/
+├── page-agent/          # AI agent (npm: page-agent)
+├── llms/                # LLM 客户端 (npm: @page-agent/llms)
+├── page-controller/     # DOM 操作 (npm: @page-agent/page-controller)
+├── ui/                  # 面板 & 蒙层 & 模拟鼠标 (npm: @page-agent/ui)
+└── website/             # 文档站点
 ```
 
 ## 🤝 贡献

README.md

@@ -1,22 +1,22 @@
 # 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)
 
-**Transform your webpage into an AI-powered application with a single script tag.**
-
-An in-page UI agent in javascript. Control web interfaces with natural language.
+The GUI Agent Living in Your Webpage. Control web interfaces with natural language.
 
 🌐 **English** | [中文](./README-zh.md)
 
-👉 [🚀 **Demo**](https://alibaba.github.io/page-agent/) | [📖 **Documentation**](https://alibaba.github.io/page-agent/#/docs/introduction/overview)
+👉 <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>
 
 ---
 
 ## ✨ Features
 
-- **🎯 Easy Integration**
+- **🎯 Easy Integration** - Transform your webpage into an agent with a single script tag.
 - **🔐 Client-Side Processing**
 - **🧠 DOM Extraction**
 - **💬 Natural Language Interface**
@@ -31,10 +31,11 @@ An in-page UI agent in javascript. Control web interfaces with natural language.
 ### CDN Integration
 
 ```html
-<!-- temporary CDN URL. May change in the future -->
-<script
-	src="https://hwcxiuzfylggtcktqgij.supabase.co/storage/v1/object/public/demo-public/v0.0.2/page-agent.js"
-	crossorigin="true"
+// CDN        - https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js
+// Mirror(CN) - https://registry.npmmirror.com/page-agent/latest/files/dist/umd/page-agent.js
+<script 
+	src="https://cdn.jsdelivr.net/npm/page-agent@latest/dist/umd/page-agent.js" 
+	crossorigin="true" 
 	type="text/javascript"
 ></script>
 ```
@@ -56,7 +57,7 @@ const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm
 const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
 
 const agent = new PageAgent({
-	modelName: DEMO_MODEL,
+	model: DEMO_MODEL,
 	baseURL: DEMO_BASE_URL,
 	apiKey: DEMO_API_KEY,
 	language: 'en-US',
@@ -67,16 +68,15 @@ await agent.execute('Click the login button')
 
 ## 🏗️ Structure
 
-PageAgent follows a clean, modular architecture:
+PageAgent adopts a simplified monorepo structure:
 
 ```
-src/
-├── PageAgent.ts          # Agent main loop
-├── dom/                  # DOM processing
-├── tools/                # Agent tools
-├── ui/                   # UI components & panels
-├── llms/                 # LLM integration layer
-└── utils/                # Event bus & utilities
+packages/
+├── page-agent/          # AI agent (npm: page-agent)
+├── llms/                # LLM client (npm: @page-agent/llms)
+├── page-controller/     # DOM operations (npm: @page-agent/page-controller)
+├── ui/                  # Panel & Mask & Mouse Animation (npm: @page-agent/ui)
+└── website/             # Demo & Documentation site
 ```
 
 ## 🤝 Contributing

ROADMAP.md

@@ -4,39 +4,58 @@ The development progress and future plans for PageAgent.
 
 ## 🚀 Current Works
 
-- [x] **MVP** - Core functionality implemented
-- [x] **SPA interaction** - Single Page Application support
+- [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
+- [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 is being used
+- [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] **Free evaluation plan**
 - [x] **Custom actions and HITL**
 - [ ] **Hooks and Events**
   - [x] **lifecycle hooks**
   - [ ] **lifecycle events**
-- [ ] **❗Pause and intervene**
+- [ ] **User takeover** 
+  - [#64](https://github.com/alibaba/page-agent/issues/64)
 - [ ] **❗Hijack `page_open/page_change/page_unload` behavior**
 - [ ] **Custom knowledge base and instructions**
+  - [#45](https://github.com/alibaba/page-agent/issues/45)
 - [ ] **Black/white-list safeguard**
 - [ ] **Data-masking**
+  - [#44](https://github.com/alibaba/page-agent/issues/44)
+- [ ] **Improve Memory**
+  - [#66](https://github.com/alibaba/page-agent/issues/66)
+  - [#65](https://github.com/alibaba/page-agent/issues/65)
 - [ ] **Optimize for popular UI frameworks**
-- [ ] **Testing suits**
-- [ ] **Support custom llm fetch**
-- [ ] **Refactor: Separate Agent and Page-Controller** - Agent should run w/o dom
+- [x] **i18n of the website**
+  - [x] Chinese version
+  - [x] English version
+- [x] **Refactor: Separate `Agent` and `PageController`** 
+- [ ] **Chrome-ext wrapper for multi-page tasks**
 
-♻️ Following browser-use's update and contribute back
+♻️ Following browser-use's update and contribute back.
 
 ## 📋 Pending Features
 
-- [ ] **Chrome-ext wrapper**
+- [ ] **Tools for more complex tasks**
+  - todo list
+  - file sys
+- [x] **Support custom llm fetch**
+- [ ] **Testing suits**
 - [ ] **Same-origin multi-page-app rally**
 - [ ] **Local MCP proxy**
 
 ## 🤔 To Be Decided
 
-- [ ] **Cross-origin multi-page?** - Tricky
+- [ ] **Cross-origin multi-page?** 
+  - Tricky
+  - Need some kind of "memory rally"

eslint.config.js

@@ -8,7 +8,12 @@ import globals from 'globals'
 import tseslint from 'typescript-eslint'
 
 export default defineConfig([
-	globalIgnores(['dist', 'test-pages']),
+	globalIgnores([
+		'**/dist',
+		'**/test-pages',
+		'**/node_modules',
+		'packages/website/src/components/ui',
+	]),
 	{
 		plugins: {
 			'react-hooks': reactHooks,
@@ -37,8 +42,10 @@ export default defineConfig([
 		],
 		languageOptions: {
 			parserOptions: {
-				project: ['./tsconfig.json'],
-				tsconfigRootDir: import.meta.dirname,
+				// project: ['./tsconfig.json'],
+				// project: ['./packages/*/tsconfig.json'],
+				// tsconfigRootDir: import.meta.dirname,
+				projectService: true,
 			},
 			ecmaVersion: 2020,
 			globals: globals.browser,
@@ -67,6 +74,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',
 		},
 	},
 ])

index.html

@@ -1,32 +0,0 @@
-<!doctype html>
-<html lang="zh-CN">
-	<head>
-		<meta charset="UTF-8" />
-		<link
-			rel="icon"
-			type="image/svg+xml"
-			href="https://img.alicdn.com/imgextra/i3/O1CN01uo9VaC20mamWNM2Zn_!!6000000006892-55-tps-64-64.svg"
-		/>
-		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
-		<title>PageAgent - 网页内的交互助手</title>
-		<meta
-			name="description"
-			content="PageAgent.js：一行 CDN 引入，为任何网站添加智能 UI Agent。现代网页 AI 自动化，极简集成，开发者专用。"
-		/>
-		<meta
-			name="keywords"
-			content="PageAgent, AI Agent, Web Automation, UI 自动化, 前端, CDN, JavaScript, React, Vite"
-		/>
-		<meta name="theme-color" content="#58c0fc" />
-		<meta name="color-scheme" content="light dark" />
-		<meta name="author" content="PageAgent.js Team" />
-		<meta property="og:title" content="PageAgent.js" />
-		<meta property="og:description" content="一行 CDN 引入，为任何网站添加智能 UI Agent。" />
-		<meta property="og:type" content="website" />
-		<meta property="og:locale" content="zh_CN" />
-	</head>
-	<body>
-		<div id="root"></div>
-		<script type="module" src="./pages/main.tsx"></script>
-	</body>
-</html>

package.json

@@ -1,89 +1,62 @@
 {
-	"name": "page-agent",
-	"private": false,
-	"version": "0.0.3",
+	"name": "root",
+	"private": true,
+	"version": "0.0.19",
 	"type": "module",
-	"main": "./dist/lib/page-agent.js",
-	"module": "./dist/lib/page-agent.js",
-	"types": "./dist/lib/PageAgent.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/lib/PageAgent.d.ts",
-			"import": "./dist/lib/page-agent.js",
-			"default": "./dist/lib/page-agent.js"
-		}
-	},
-	"files": [
-		"dist/lib/",
-		"README.md",
-		"LICENSE",
-		"NOTICE"
-	],
-	"description": "AI-powered UI agent for web applications - add intelligent automation to any webpage with a single script tag",
-	"keywords": [
-		"ai",
-		"automation",
-		"ui-agent",
-		"browser-automation",
-		"web-agent",
-		"llm",
-		"dom-interaction",
-		"intelligent-ui"
+	"workspaces": [
+		"packages/page-controller",
+		"packages/ui",
+		"packages/llms",
+		"packages/page-agent",
+		"packages/website"
 	],
+	"description": "AI-powered UI agent for web applications",
 	"author": "Simon<gaomeng1900>",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/alibaba/page-agent.git"
 	},
+	"homepage": "https://alibaba.github.io/page-agent/",
 	"engines": {
-		"node": ">=20.0.0"
+		"node": ">=20.0.0",
+		"npm": ">=10.0.0"
 	},
 	"scripts": {
-		"dev": "vite",
-		"start": "vite",
-		"build": "tsc -b && vite build && npm run build:lib && npm run build:umd",
-		"build:lib": "MODE=lib vite build",
-		"build:lib:watch": "MODE=lib vite build --watch",
-		"build:umd": "MODE=umd vite build",
+		"cleanup": "rm -rf packages/*/dist",
+		"start": "npm run dev --workspace=@page-agent/website",
+		"build:website": "npm run build:website --workspace=@page-agent/website",
+		"build:libs": "npm run build --workspaces --if-present",
+		"build": "npm run build:libs && npm run build:website",
+		"dev:umd": "npm run dev:umd --workspace=page-agent",
+		"version": "node scripts/sync-version.js",
 		"lint": "eslint .",
 		"prepare": "husky"
 	},
-	"dependencies": {
-		"ai-motion": "^0.4.7",
-		"chalk": "^5.6.2",
-		"zod": "^4.1.12"
-	},
 	"devDependencies": {
-		"@commitlint/cli": "^20.1.0",
-		"@commitlint/config-conventional": "^20.0.0",
-		"@eslint/js": "^9.37.0",
-		"@microsoft/api-extractor": "^7.53.1",
-		"@tailwindcss/vite": "^4.1.14",
-		"@trivago/prettier-plugin-sort-imports": "^5.2.2",
-		"@types/react": "^19.2.2",
-		"@types/react-dom": "^19.2.1",
-		"@vitejs/plugin-react-swc": "^4.1.0",
+		"@commitlint/cli": "^20.3.0",
+		"@commitlint/config-conventional": "^20.3.0",
+		"@eslint/js": "^9.39.2",
+		"@microsoft/api-extractor": "^7.55.2",
+		"@trivago/prettier-plugin-sort-imports": "^6.0.1",
+		"@types/node": "^25.0.3",
+		"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.0.6",
-		"eslint-plugin-react-hooks": "^7.0.0",
-		"eslint-plugin-react-refresh": "^0.4.23",
-		"eslint-plugin-react-x": "^2.0.6",
+		"eslint-plugin-react-dom": "^2.5.1",
+		"eslint-plugin-react-hooks": "^7.0.1",
+		"eslint-plugin-react-refresh": "^0.4.26",
+		"eslint-plugin-react-x": "^2.5.1",
 		"globals": "^16.4.0",
 		"husky": "^9.1.7",
 		"lint-staged": "^16.2.4",
-		"prettier": "^3.6.2",
-		"react": "^19.2.0",
-		"react-dom": "^19.2.0",
-		"tailwindcss": "^4.1.14",
+		"prettier": "^3.7.4",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.46.0",
+		"typescript-eslint": "^8.52.0",
 		"unplugin-dts": "^1.0.0-beta.6",
-		"vite": "^7.1.9",
-		"vite-plugin-css-injected-by-js": "^3.5.2",
-		"wouter": "^3.7.1"
+		"vite": "^7.3.0",
+		"vite-plugin-css-injected-by-js": "^3.5.2"
 	},
 	"lint-staged": {
 		"*.{js,ts,cjs,cts,mjs,mts}": [

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.0.19",
+	"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

@@ -1,14 +1,19 @@
 /**
  * OpenAI Client implementation
+ * @note This client is only for demonstrating how to implement a LLM client.
+ * @note Use OpenAILenientClient instead.
  */
 import { InvokeError, InvokeErrorType } from './errors'
-import type { InvokeResult, LLMClient, Message, OpenAIClientConfig, Tool } from './types'
+import type { InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
 import { modelPatch, zodToOpenAITool } from './utils'
 
+/**
+ * @deprecated Use OpenAILenientClient instead.
+ */
 export class OpenAIClient implements LLMClient {
-	config: OpenAIClientConfig
+	config: LLMConfig
 
-	constructor(config: OpenAIClientConfig) {
+	constructor(config: LLMConfig) {
 		this.config = config
 	}
 
@@ -33,7 +38,6 @@ export class OpenAIClient implements LLMClient {
 					modelPatch({
 						model: this.config.model,
 						temperature: this.config.temperature,
-						max_tokens: this.config.maxTokens,
 						messages,
 
 						tools: openaiTools,

packages/llms/src/OpenAILenientClient.ts

@@ -1,17 +1,17 @@
 /**
  * OpenAI Client implementation
  */
-import type { MacroToolInput } from '@/PageAgent'
-
 import { InvokeError, InvokeErrorType } from './errors'
-import type { InvokeResult, LLMClient, Message, OpenAIClientConfig, Tool } from './types'
+import type { InvokeResult, LLMClient, LLMConfig, MacroToolInput, Message, Tool } from './types'
 import { lenientParseMacroToolCall, modelPatch, zodToOpenAITool } from './utils'
 
 export class OpenAIClient implements LLMClient {
-	config: OpenAIClientConfig
+	config: Required<LLMConfig>
+	private fetch: typeof globalThis.fetch
 
-	constructor(config: OpenAIClientConfig) {
+	constructor(config: Required<LLMConfig>) {
 		this.config = config
+		this.fetch = config.customFetch
 	}
 
 	async invoke(
@@ -25,7 +25,7 @@ export class OpenAIClient implements LLMClient {
 		// 2. Call API
 		let response: Response
 		try {
-			response = await fetch(`${this.config.baseURL}/chat/completions`, {
+			response = await this.fetch(`${this.config.baseURL}/chat/completions`, {
 				method: 'POST',
 				headers: {
 					'Content-Type': 'application/json',
@@ -35,17 +35,11 @@ export class OpenAIClient implements LLMClient {
 					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,
 					})
 				),
@@ -53,6 +47,7 @@ export class OpenAIClient implements LLMClient {
 			})
 		} catch (error: unknown) {
 			// Network error
+			console.error(error)
 			throw new InvokeError(InvokeErrorType.NETWORK_ERROR, 'Network request failed', error)
 		}
 

packages/llms/src/constants.ts

@@ -1,10 +1,3 @@
-/**
- * @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
@@ -24,6 +17,4 @@ export const DEFAULT_BASE_URL: string =
 // 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/llms/src/env.d.ts

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

packages/llms/src/index.ts

@@ -31,36 +31,58 @@
  * - 永远使用 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 {
+	DEFAULT_API_KEY,
+	DEFAULT_BASE_URL,
+	DEFAULT_MODEL_NAME,
+	DEFAULT_TEMPERATURE,
+	LLM_MAX_RETRIES,
+} from './constants'
 import { InvokeError } from './errors'
-import type { InvokeResult, LLMClient, Message, Tool } from './types'
+import type {
+	AgentBrain,
+	InvokeResult,
+	LLMClient,
+	LLMConfig,
+	MacroToolInput,
+	MacroToolResult,
+	Message,
+	Tool,
+} from './types'
 
-export type { Message, Tool, InvokeResult, LLMClient }
+export type {
+	AgentBrain,
+	InvokeResult,
+	LLMClient,
+	LLMConfig,
+	MacroToolInput,
+	MacroToolResult,
+	Message,
+	Tool,
+}
 
-export class LLM {
+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,
+		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>
-	id: string
 	client: LLMClient
-	#bus: EventBus
 
-	constructor(config: LLMConfig, id: string) {
+	constructor(config: LLMConfig) {
+		super()
 		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,
-		})
+		this.client = new OpenAIClient(this.config)
 	}
 
 	/**
@@ -82,17 +104,13 @@ export class LLM {
 			// retry settings
 			{
 				maxRetries: this.config.maxRetries,
-				onRetry: (retries: number) => {
-					this.#bus.emit('panel:update', {
-						type: 'retry',
-						displayText: `retry-ing (${retries} / ${this.config.maxRetries})`,
-					})
+				onRetry: (current: number) => {
+					this.dispatchEvent(
+						new CustomEvent('retry', { detail: { current, max: this.config.maxRetries } })
+					)
 				},
-				onError: (error: Error, withRetry: boolean) => {
-					this.#bus.emit('panel:update', {
-						type: 'error',
-						displayText: `step failed: ${(error as Error).message}`,
-					})
+				onError: (error: Error) => {
+					this.dispatchEvent(new CustomEvent('error', { detail: { error } }))
 				},
 			}
 		)
@@ -104,7 +122,7 @@ async function withRetry<T>(
 	settings: {
 		maxRetries: number
 		onRetry: (retries: number) => void
-		onError: (error: Error, withRetry: boolean) => void
+		onError: (error: Error) => void
 	}
 ): Promise<T> {
 	let retries = 0
@@ -119,7 +137,7 @@ async function withRetry<T>(
 			return await fn()
 		} catch (error: unknown) {
 			console.error(error)
-			settings.onError(error as Error, retries < settings.maxRetries)
+			settings.onError(error as Error)
 
 			// do not retry if aborted by user
 			if ((error as { name?: string })?.name === 'AbortError') throw error

packages/llms/src/types.ts

@@ -65,13 +65,53 @@ export interface InvokeResult<TResult = unknown> {
 }
 
 /**
- * OpenAI Client config
+ * LLM configuration
  */
-export interface OpenAIClientConfig {
-	model: string
-	apiKey: string
-	baseURL: string
+export interface LLMConfig {
+	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
+}
+
+/**
+ * Agent brain state - the reflection-before-action model
+ *
+ * Every tool call must first reflect on:
+ * - evaluation_previous_goal: How well did the previous action achieve its goal?
+ * - memory: Key information to remember for future steps
+ * - next_goal: What should be accomplished in the next action?
+ */
+export interface AgentBrain {
+	// thinking?: string
+	evaluation_previous_goal: string
+	memory: string
+	next_goal: string
+}
+
+/**
+ * MacroTool input structure
+ *
+ * This is the core abstraction that enforces the "reflection-before-action" mental model.
+ * Before executing any action, the LLM must output its reasoning state.
+ */
+export interface MacroToolInput extends AgentBrain {
+	action: Record<string, any>
+}
+
+/**
+ * MacroTool output structure
+ */
+export interface MacroToolResult {
+	input: MacroToolInput
+	output: string
 }

packages/llms/src/utils.ts

@@ -4,10 +4,12 @@
 import chalk from 'chalk'
 import { z } from 'zod'
 
-import type { MacroToolInput } from '@/PageAgent'
-
 import { InvokeError, InvokeErrorType } from './errors'
-import type { Tool } from './types'
+import type { MacroToolInput, Tool } from './types'
+
+function debug(message: string) {
+	console.debug(chalk.gray('[LLM]'), message)
+}
 
 /**
  * Convert Zod schema to OpenAI tool format
@@ -42,6 +44,7 @@ export function lenientParseMacroToolCall(
 	// check
 	switch (choice.finish_reason) {
 		case 'tool_calls':
+		case 'function_call': // gemini
 		case 'stop': // will try a robust parse
 			// ✅ Normal
 			break
@@ -193,22 +196,82 @@ export function lenientParseMacroToolCall(
 	}
 }
 
+/**
+ * Patch model specific parameters
+ */
 export function modelPatch(body: Record<string, any>) {
 	const model: string = body.model || ''
+	if (!model) return body
 
-	if (model.toLowerCase().startsWith('claude')) {
+	const modelName = normalizeModelName(model)
+
+	if (modelName.startsWith('claude')) {
+		debug('Applying Claude patch: change tool_choice and disable thinking')
 		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')
+	if (modelName.startsWith('grok')) {
+		debug('Applying Grok patch: removing tool_choice')
 		delete body.tool_choice
-		console.log('Applying Grok patch: disable reasoning and thinking')
+		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,37 @@
+// @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

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

packages/page-agent/src/PageAgent.ts

@@ -2,52 +2,28 @@
  * Copyright (C) 2025 Alibaba Group Holding Limited
  * All rights reserved.
  */
+import {
+	type AgentBrain,
+	LLM,
+	type MacroToolInput,
+	type MacroToolResult,
+	type Tool,
+} from '@page-agent/llms'
+import { PageController } from '@page-agent/page-controller'
+import { Panel, SimulatorMask } from '@page-agent/ui'
 import chalk from 'chalk'
 import zod from 'zod'
 
 import type { PageAgentConfig } from './config'
-import { MAX_STEPS, VIEWPORT_EXPANSION } 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 { MAX_STEPS } from './config/constants'
 import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
 import { tools } from './tools'
-import { Panel, getToolCompletedText, getToolExecutingText } from './ui/Panel'
-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'
-
-export interface AgentBrain {
-	// thinking?: string
-	evaluation_previous_goal: string
-	memory: string
-	next_goal: string
-}
-
-/**
- * MacroTool input structure
- */
-export interface MacroToolInput {
-	evaluation_previous_goal?: string
-	memory?: string
-	next_goal?: string
-	action: Record<string, any>
-}
-
-/**
- * MacroTool output structure
- */
-export interface MacroToolResult {
-	input: MacroToolInput
-	output: string
-}
+export type { AgentBrain, MacroToolInput, MacroToolResult }
 
 export interface AgentHistory {
 	brain: AgentBrain
@@ -74,8 +50,6 @@ export interface ExecutionResult {
 export class PageAgent extends EventTarget {
 	config: PageAgentConfig
 	id = uid()
-	bus = getEventBus(this.id)
-	i18n: I18n
 	panel: Panel
 	tools: typeof tools
 	paused = false
@@ -86,20 +60,12 @@ export class PageAgent extends EventTarget {
 	#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 */
-	flatTree: FlatDomTree | null = null
-	/**
-	 * 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
+	/** PageController for DOM operations */
+	pageController: PageController
 
 	/** Fullscreen mask */
 	mask = new SimulatorMask()
@@ -110,11 +76,34 @@ export class PageAgent extends EventTarget {
 		super()
 
 		this.config = config
-		this.#llm = new LLM(this.config, this.id)
-		this.i18n = new I18n(this.config.language)
-		this.panel = new Panel(this)
+		this.#llm = new LLM(this.config)
+		this.panel = new Panel({
+			language: this.config.language,
+			onExecuteTask: (task) => this.execute(task),
+			onStop: () => this.dispose(),
+			onPauseToggle: () => {
+				this.paused = !this.paused
+				return this.paused
+			},
+			getPaused: () => this.paused,
+		})
 		this.tools = new Map(tools)
 
+		// Initialize PageController with config
+		this.pageController = new PageController(this.config)
+
+		// 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) {
@@ -125,11 +114,14 @@ export class PageAgent extends EventTarget {
 			}
 		}
 
-		patchReact(this)
+		if (!this.config.experimentalScriptExecutionTool) {
+			this.tools.delete('execute_javascript')
+		}
 
-		window.addEventListener('beforeunload', (e) => {
+		this.#beforeUnloadListener = (e) => {
 			if (!this.disposed) this.dispose('PAGE_UNLOADING')
-		})
+		}
+		window.addEventListener('beforeunload', this.#beforeUnloadListener)
 	}
 
 	/**
@@ -150,13 +142,10 @@ export class PageAgent extends EventTarget {
 		// Show mask and panel
 		this.mask.show()
 
-		this.bus.emit('panel:show')
-		this.bus.emit('panel:reset')
+		this.panel.show()
+		this.panel.reset()
 
-		this.bus.emit('panel:update', {
-			type: 'input',
-			displayText: this.task,
-		})
+		this.panel.update({ type: 'input', task: this.task })
 
 		if (this.#abortController) {
 			this.#abortController.abort()
@@ -171,7 +160,7 @@ export class PageAgent extends EventTarget {
 			while (true) {
 				await onBeforeStep.call(this, step)
 
-				console.group(`step: ${step + 1}`)
+				console.group(`step: ${step}`)
 
 				// abort
 				if (this.#abortController.signal.aborted) throw new Error('AbortError')
@@ -180,10 +169,7 @@ export class PageAgent extends EventTarget {
 
 				// Update status to thinking
 				console.log(chalk.blue('Thinking...'))
-				this.bus.emit('panel:update', {
-					type: 'thinking',
-					displayText: this.i18n.t('ui.panel.thinking'),
-				})
+				this.panel.update({ type: 'thinking' })
 
 				const result = await this.#llm.invoke(
 					[
@@ -193,7 +179,7 @@ export class PageAgent extends EventTarget {
 						},
 						{
 							role: 'user',
-							content: this.#assembleUserPrompt(),
+							content: await this.#assembleUserPrompt(),
 						},
 					],
 					{ AgentOutput: this.#packMacroTool() },
@@ -277,9 +263,7 @@ export class PageAgent extends EventTarget {
 		const tools = this.tools
 
 		const actionSchemas = Array.from(tools.entries()).map(([toolName, tool]) => {
-			return zod.object({
-				[toolName]: tool.inputSchema,
-			})
+			return zod.object({ [toolName]: tool.inputSchema }).describe(tool.description)
 		})
 
 		const actionSchema = zod.union(
@@ -313,22 +297,14 @@ export class PageAgent extends EventTarget {
 					`)
 
 				console.log(brain)
-				this.bus.emit('panel:update', {
-					type: 'thinking',
-					displayText: brain,
-				})
+				this.panel.update({ type: 'thinking', text: brain })
 
 				// 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', {
-					type: 'tool_executing',
-					toolName,
-					toolArgs: toolInput,
-					displayText: getToolExecutingText(toolName, toolInput, this.i18n),
-				})
+				this.panel.update({ type: 'toolExecuting', toolName, args: toolInput })
 
 				const startTime = Date.now()
 
@@ -350,16 +326,13 @@ export class PageAgent extends EventTarget {
 				}
 
 				// Briefly display execution result
-				const displayResult = getToolCompletedText(toolName, toolInput, this.i18n)
-				if (displayResult)
-					this.bus.emit('panel:update', {
-						type: 'tool_executing',
-						toolName,
-						toolArgs: toolInput,
-						toolResult: result,
-						displayText: displayResult,
-						duration,
-					})
+				this.panel.update({
+					type: 'toolCompleted',
+					toolName,
+					args: toolInput,
+					result,
+					duration,
+				})
 
 				// Wait a moment to let user see the result
 				await new Promise((resolve) => setTimeout(resolve, 100))
@@ -388,25 +361,49 @@ 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
+	}
+
+	async #assembleUserPrompt(): Promise<string> {
 		let prompt = ''
 
-		// <agent_history>
-		//  - <step_>
-
-		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'
+		// <instructions> (optional)
+		prompt += await this.#getInstructions()
 
 		// <agent_state>
 		//  - <user_request>
@@ -424,64 +421,84 @@ export class PageAgent extends EventTarget {
 			</agent_state>
 		`
 
+		// <agent_history>
+		//  - <step_>
+
+		prompt += '\n<agent_history>\n'
+
+		this.history.forEach((history, index) => {
+			prompt += `<step_${index + 1}>
+				Evaluation of Previous Step: ${history.brain.evaluation_previous_goal}
+				Memory: ${history.brain.memory}
+				Next Goal: ${history.brain.next_goal}
+				Action Results: ${history.action.output}
+				</step_${index + 1}>
+			`
+		})
+
+		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', {
-			type: success ? 'output' : 'error',
-			displayText: text,
-		})
+		if (success) {
+			this.panel.update({ type: 'output', text })
+		} else {
+			this.panel.update({ type: 'error', message: text })
+		}
 
 		// Task completed
-		this.bus.emit('panel:update', {
-			type: 'completed',
-			displayText: this.i18n.t('ui.panel.taskCompleted'),
-		})
+		this.panel.update({ type: 'completed' })
 
 		this.mask.hide()
 
 		this.#abortController.abort()
 	}
 
-	#getBrowserState(): string {
-		const pageUrl = window.location.href
-		const pageTitle = document.title
-		const pi = getPageInfo()
+	async #getBrowserState(): Promise<string> {
+		const pageUrl = await this.pageController.getCurrentUrl()
+		const pageTitle = await this.pageController.getPageTitle()
+		const pi = await this.pageController.getPageInfo()
+		const viewportExpansion = await this.pageController.getViewportExpansion()
 
-		this.#updateTree()
+		this.mask.wrapper.style.pointerEvents = 'none'
+		await this.pageController.updateTree()
+		this.mask.wrapper.style.pointerEvents = 'auto'
+
+		const simplifiedHTML = await this.pageController.getSimplifiedHTML()
 
 		let prompt = trimLines(`<browser_state>
 			Current Page: [${pageTitle}](${pageUrl})
 
 			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
 
-			${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:'}
+			${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:'}
 
 		`)
 
 		// Page header info
 		const has_content_above = pi.pixels_above > 4
-		if (has_content_above && VIEWPORT_EXPANSION !== -1) {
+		if (has_content_above && viewportExpansion !== -1) {
 			prompt += `... ${pi.pixels_above} pixels above (${pi.pages_above.toFixed(1)} pages) - scroll to see more ...\n`
 		} else {
 			prompt += `[Start of page]\n`
 		}
 
 		// Current viewport info
-		prompt += this.simplifiedHTML
+		prompt += simplifiedHTML
 		prompt += `\n`
 
 		// Page footer info
 		const has_content_below = pi.pixels_below > 4
-		if (has_content_below && VIEWPORT_EXPANSION !== -1) {
+		if (has_content_below && viewportExpansion !== -1) {
 			prompt += `... ${pi.pixels_below} pixels below (${pi.pages_below.toFixed(1)} pages) - scroll to see more ...\n`
 		} else {
 			prompt += `[End of page]\n`
@@ -492,42 +509,31 @@ export class PageAgent extends EventTarget {
 		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.flatTree = null
-		this.selectorMap.clear()
-		this.elementTextMap.clear()
+		this.pageController.dispose()
 		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

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

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

@@ -1,25 +1,11 @@
-import type { AgentHistory, ExecutionResult, PageAgent } from '@/PageAgent'
-import type { DomConfig } from '@/dom'
-import type { SupportedLanguage } from '@/i18n'
-import type { PageAgentTool } from '@/tools'
+import type { LLMConfig } from '@page-agent/llms'
+import type { PageControllerConfig } from '@page-agent/page-controller'
+import type { SupportedLanguage } from '@page-agent/ui'
 
-import {
-	DEFAULT_API_KEY,
-	DEFAULT_BASE_URL,
-	DEFAULT_MAX_TOKENS,
-	DEFAULT_MODEL_NAME,
-	DEFAULT_TEMPERATURE,
-	LLM_MAX_RETRIES,
-} from './constants'
+import type { AgentHistory, ExecutionResult, PageAgent } from '../PageAgent'
+import type { PageAgentTool } from '../tools'
 
-export interface LLMConfig {
-	baseURL?: string
-	apiKey?: string
-	model?: string
-	temperature?: number
-	maxTokens?: number
-	maxRetries?: number
-}
+export type { LLMConfig }
 
 export interface AgentConfig {
 	// theme?: 'light' | 'dark'
@@ -56,6 +42,24 @@ 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
 
@@ -72,6 +76,14 @@ export interface AgentConfig {
 
 	// page behavior hooks
 
+	/**
+	 * @experimental
+	 * Enable the experimental script execution tool that allows executing generated JavaScript code on the page.
+	 * @note Can cause unpredictable side effects.
+	 * @note May bypass some safe guards and data-masking mechanisms.
+	 */
+	experimentalScriptExecutionTool?: boolean
+
 	/**
 	 * TODO: @unimplemented
 	 * hook when action causes a new page to be opened
@@ -87,15 +99,4 @@ export interface AgentConfig {
 	experimentalPreventNewPage?: boolean
 }
 
-export type PageAgentConfig = LLMConfig & AgentConfig & DomConfig
-
-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,
-	}
-}
+export type PageAgentConfig = LLMConfig & AgentConfig & PageControllerConfig

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>
@@ -11,15 +11,10 @@ declare module '*.md?raw' {
 	export default content
 }
 
-/**
- * for local dev and umd demo
- */
-
 declare global {
 	interface Window {
 		pageAgent?: PageAgent
 		PageAgent: typeof PageAgent
-
 		__PAGE_AGENT_IDS__: string[]
 	}
 }

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

@@ -4,23 +4,8 @@
  */
 import zod, { type z } from 'zod'
 
-import type { PageAgent } from '@/PageAgent'
-
-import {
-	clickElement,
-	getElementByIndex,
-	getSystemInfo,
-	inputTextElement,
-	scrollHorizontally,
-	scrollVertically,
-	selectOptionElement,
-	waitFor,
-} from './actions'
-// debug
-import * as utils from './actions'
-
-// @ts-expect-error debug only
-window.utils = utils
+import type { PageAgent } from '../PageAgent'
+import { waitFor } from '../utils'
 
 /**
  * Internal tool definition that has access to PageAgent `this` context
@@ -42,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({
@@ -80,11 +53,11 @@ 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())
+			return `✅ Waited for ${input.seconds} seconds.`
 		},
 	})
 )
@@ -99,7 +72,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}`
 		},
 	})
 )
@@ -112,16 +85,8 @@ tools.set(
 			index: zod.int().min(0),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const element = getElementByIndex(this, input.index)
-			const elemText = this.elementTextMap.get(input.index)
-			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())
+			const result = await this.pageController.clickElement(input.index)
+			return result.message
 		},
 	})
 )
@@ -135,13 +100,8 @@ tools.set(
 			text: zod.string(),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const element = getElementByIndex(this, input.index)
-			const elemText = this.elementTextMap.get(input.index)
-			await inputTextElement(element, input.text)
-			return (
-				`✅ Input text (${input.text}) into element (${elemText ? elemText : input.index}).` +
-				(await getSystemInfo())
-			)
+			const result = await this.pageController.inputText(input.index, input.text)
+			return result.message
 		},
 	})
 )
@@ -156,13 +116,8 @@ tools.set(
 			text: zod.string(),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const element = getElementByIndex(this, input.index)
-			const elemText = this.elementTextMap.get(input.index)
-			await selectOptionElement(element as HTMLSelectElement, input.text)
-			return (
-				`✅ Selected option (${input.text}) in element (${elemText ? elemText : input.index}).` +
-				(await getSystemInfo())
-			)
+			const result = await this.pageController.selectOption(input.index, input.text)
+			return result.message
 		},
 	})
 )
@@ -182,13 +137,11 @@ tools.set(
 			index: zod.number().int().min(0).optional(),
 		}),
 		execute: async function (this: PageAgent, input) {
-			const { down, num_pages, index, pixels } = input
-
-			const scroll_amount = pixels ? pixels : num_pages * (down ? 1 : -1) * window.innerHeight
-
-			const element = index !== undefined ? getElementByIndex(this, index) : null
-
-			return (await scrollVertically(down, scroll_amount, element)) + (await getSystemInfo())
+			const result = await this.pageController.scroll({
+				...input,
+				numPages: input.num_pages,
+			})
+			return result.message
 		},
 	})
 )
@@ -204,13 +157,23 @@ 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())
+tools.set(
+	'execute_javascript',
+	tool({
+		description:
+			'Execute JavaScript code on the current page. Supports async/await syntax. Use with caution!',
+		inputSchema: zod.object({
+			script: zod.string(),
+		}),
+		execute: async function (this: PageAgent, input) {
+			const result = await this.pageController.executeJavascript(input.script)
+			return result.message
 		},
 	})
 )

packages/page-agent/src/umd.ts

@@ -0,0 +1,44 @@
+/**
+ * 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')
+		window.pageAgent = new PageAgent()
+	}
+
+	console.log('🚀 page-agent.js initialized with config:', window.pageAgent.config)
+
+	window.pageAgent.panel.show() // Show panel
+})

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

@@ -1,30 +1,9 @@
-/**
- * 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 }
@@ -33,8 +12,7 @@ export interface PageAgentEventMap {
 	// 'agent:error': { params: { error: string | Error } }
 
 	// Task status change events
-	// 'task:start': { params: { task: string } }
-	// 'task:step': { params: Omit<AgentStep, 'id' | 'stepNumber' | 'timestamp'> }
+	'task:start': { params: { task: string } }
 	// 'task:complete': { params: { text: string; success: boolean } }
 	// 'task:error': { params: { error: string | Error } }
 
@@ -69,10 +47,7 @@ class EventBus extends EventTarget {
 	/**
 	 * Listen to built-in events
 	 */
-	on<T extends keyof PageAgentEventMap>(
-		event: T,
-		handler: EventHandler<T & keyof PageAgentEventMap>
-	): void {
+	on<T extends keyof PageAgentEventMap>(event: T, handler: EventHandler<T>): void {
 		const wrappedHandler = (e: Event) => {
 			const customEvent = e as CustomEvent
 			const params = customEvent.detail?.[0]
@@ -84,10 +59,7 @@ class EventBus extends EventTarget {
 	/**
 	 * Listen to built-in events (one-time)
 	 */
-	once<T extends keyof PageAgentEventMap>(
-		event: T,
-		handler: EventHandler<T & keyof PageAgentEventMap>
-	): void {
+	once<T extends keyof PageAgentEventMap>(event: T, handler: EventHandler<T>): void {
 		const wrappedHandler = (e: Event) => {
 			const customEvent = e as CustomEvent
 			const params = customEvent.detail?.[0]

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

@@ -20,6 +20,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

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

packages/page-agent/vite.config.js

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

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

@@ -0,0 +1,45 @@
+// @ts-check
+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))
+
+// 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({
+	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/umd.ts'),
+			name: 'PageAgent',
+			fileName: 'page-agent',
+			formats: ['umd'],
+		},
+		outDir: resolve(__dirname, 'dist', 'umd'),
+		rollupOptions: {
+			output: {
+				// force use .js as extension
+				entryFileNames: 'page-agent.js',
+			},
+		},
+		cssCodeSplit: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})

packages/page-controller/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@page-agent/page-controller",
+	"version": "0.0.19",
+	"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{}})\""
+	}
+}

packages/page-controller/src/PageController.ts

@@ -0,0 +1,339 @@
+/**
+ * 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 { patchReact } from './patches/react'
+
+/**
+ * Configuration for PageController
+ */
+export interface PageControllerConfig extends dom.DomConfig {
+	viewportExpansion?: number
+}
+
+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
+
+	constructor(config: PageControllerConfig = {}) {
+		super()
+
+		this.config = config
+
+		patchReact(this)
+	}
+
+	// ======= State Queries =======
+
+	/**
+	 * Get current page URL
+	 */
+	async getCurrentUrl(): Promise<string> {
+		return window.location.href
+	}
+
+	/**
+	 * Get current page title
+	 */
+	async getPageTitle(): Promise<string> {
+		return document.title
+	}
+
+	/**
+	 * Get page scroll and size info
+	 */
+	async getPageInfo() {
+		return getPageInfo()
+	}
+
+	/**
+	 * Get the simplified HTML representation of the page.
+	 * This is used by LLM to understand the page structure.
+	 */
+	async getSimplifiedHTML(): Promise<string> {
+		return this.simplifiedHTML
+	}
+
+	/**
+	 * Get text description for an element by index
+	 */
+	async getElementText(index: number): Promise<string | undefined> {
+		return this.elementTextMap.get(index)
+	}
+
+	/**
+	 * Get total number of indexed interactive elements
+	 */
+	async getElementCount(): Promise<number> {
+		return this.selectorMap.size
+	}
+
+	/**
+	 * Get last tree update timestamp
+	 */
+	async getLastUpdateTime(): Promise<number> {
+		return this.lastTimeUpdate
+	}
+
+	/**
+	 * Get the viewport expansion setting
+	 */
+	async getViewportExpansion(): Promise<number> {
+		return this.config.viewportExpansion ?? VIEWPORT_EXPANSION
+	}
+
+	// ======= DOM Tree Operations =======
+
+	/**
+	 * Update DOM tree, returns simplified HTML for LLM.
+	 * This is the main method to refresh the page state.
+	 */
+	async updateTree(): Promise<string> {
+		this.dispatchEvent(new Event('beforeUpdate'))
+
+		this.lastTimeUpdate = Date.now()
+
+		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)
+
+		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}`,
+			}
+		}
+	}
+
+	/**
+	 * Dispose and clean up resources
+	 */
+	dispose(): void {
+		dom.cleanUpHighlights()
+		this.flatTree = null
+		this.selectorMap.clear()
+		this.elementTextMap.clear()
+		this.simplifiedHTML = '<EMPTY>'
+	}
+}

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 {
-	const interactiveNode = pageAgent.selectorMap.get(index)
+export function getElementByIndex(
+	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) {

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

@@ -1,11 +1,11 @@
-import { VIEWPORT_EXPANSION } from '@/config/constants'
-import domTree from '@/dom/dom_tree/index'
+import { VIEWPORT_EXPANSION } from '../constants'
+import domTree from './dom_tree/index.js'
 import {
 	ElementDomNode,
 	FlatDomTree,
 	InteractiveElementDomNode,
 	TextDomNode,
-} from '@/dom/dom_tree/type'
+} from './dom_tree/type'
 
 export interface DomConfig {
 	interactiveBlacklist?: (Element | (() => Element))[]

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) {
-	pageAgent.addEventListener('beforeUpdate', fixAntdSelect)
-	pageAgent.addEventListener('afterUpdate', () => {
+export function patchAntd(pageController: PageController) {
+	pageController.addEventListener('beforeUpdate', fixAntdSelect)
+	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,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/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/*'],
+		},
+		minify: false,
+		sourcemap: true,
+		cssCodeSplit: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})

packages/ui/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@page-agent/ui",
+	"version": "0.0.19",
+	"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, SimulatorMask, 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{}})\""
+	},
+	"dependencies": {
+		"ai-motion": "^0.4.7"
+	}
+}

packages/ui/src/Panel.module.css

@@ -33,8 +33,7 @@
 	/* 响应式设计 */
 	@media (max-width: 480px) {
 		width: calc(100vw - 40px);
-		left: 20px;
-		transform: none;
+		--width: calc(100vw - 40px);
 	}
 
 	.background {

packages/ui/src/Panel.ts

@@ -1,12 +1,35 @@
-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 { truncate } from './utils'
 
 import styles from './Panel.module.css'
 
+/**
+ * Panel configuration
+ */
+export interface PanelConfig {
+	language?: SupportedLanguage
+	onExecuteTask: (task: string) => void
+	onStop: () => void
+	onPauseToggle: () => boolean // returns new paused state
+	getPaused: () => boolean
+}
+
+/**
+ * Semantic update types - Panel handles i18n internally
+ */
+export type PanelUpdate =
+	| { type: 'thinking'; text?: string } // text is optional, defaults to i18n thinking text
+	| { type: 'input'; task: string }
+	| { type: 'question'; question: string }
+	| { type: 'userAnswer'; input: string }
+	| { type: 'retry'; current: number; max: number }
+	| { type: 'error'; message: string }
+	| { type: 'output'; text: string }
+	| { type: 'completed' }
+	| { type: 'toolExecuting'; toolName: string; args: any }
+	| { type: 'toolCompleted'; toolName: string; args: any; result?: string; duration?: number }
+
 /**
  * Agent control panel
  */
@@ -20,11 +43,11 @@ export class Panel {
 	#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
@@ -35,9 +58,9 @@ export class Panel {
 		return this.#wrapper
 	}
 
-	constructor(pageAgent: PageAgent) {
-		this.#pageAgent = pageAgent
-		this.#bus = pageAgent.bus
+	constructor(config: PanelConfig) {
+		this.#config = config
+		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}`)!
@@ -50,16 +73,8 @@ export class Panel {
 
 		this.#setupEventListeners()
 		this.#startHeaderUpdateLoop()
-		// this.#expand() // debug
 
 		this.#showInputArea()
-
-		this.#bus.on('panel:show', () => this.#show())
-		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())
 	}
 
 	/**
@@ -72,18 +87,67 @@ 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 pause state via callback
+		if (this.#config.getPaused()) {
+			this.#config.onPauseToggle()
+		}
+		this.#updatePauseButton()
+		// 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
 	 */
@@ -93,10 +157,102 @@ 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,
+				}
+			}
+		}
+	}
+
+	#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)
@@ -121,59 +277,20 @@ 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
+		const paused = this.#config.onPauseToggle()
 		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
+		if (paused) {
+			this.#statusText.textContent = this.#i18n.t('ui.panel.paused')
+			this.#updateStatusIndicator('thinking')
 		} else {
-			this.#statusText.textContent = this.#pageAgent.i18n.t('ui.panel.continueExecution')
-			this.#updateStatusIndicator('tool_executing') // Restore to execution state
+			this.#statusText.textContent = this.#i18n.t('ui.panel.continueExecution')
+			this.#updateStatusIndicator('tool_executing')
 		}
 	}
 
@@ -181,13 +298,14 @@ export class Panel {
 	 * Update pause button state
 	 */
 	#updatePauseButton(): void {
-		if (this.#pageAgent.paused) {
+		const paused = this.#config.getPaused()
+		if (paused) {
 			this.#pauseButton.textContent = '▶'
-			this.#pauseButton.title = this.#pageAgent.i18n.t('ui.panel.continue')
+			this.#pauseButton.title = this.#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.title = this.#i18n.t('ui.panel.pause')
 			this.#pauseButton.classList.remove(styles.paused)
 		}
 	}
@@ -197,12 +315,12 @@ export class Panel {
 	 */
 	#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()
 	}
 
 	/**
@@ -219,7 +337,7 @@ export class Panel {
 			// Handle user input mode
 			this.#handleUserAnswer(input)
 		} else {
-			this.#pageAgent.execute(input)
+			this.#config.onExecuteTask(input)
 		}
 	}
 
@@ -228,9 +346,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
@@ -249,7 +367,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(() => {
@@ -295,23 +413,23 @@ 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.pauseButton}" title="${this.#i18n.t('ui.panel.pause')}">
 						⏸︎
 					</button>
-					<button class="${styles.controlButton} ${styles.stopButton}" title="${this.#pageAgent.i18n.t('ui.panel.stop')}">
+					<button class="${styles.controlButton} ${styles.stopButton}" title="${this.#i18n.t('ui.panel.stop')}">
 						X
 					</button>
 				</div>
@@ -502,8 +620,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 errorKeyword = this.#pageAgent.i18n.t('ui.tools.resultError')
+				const failureKeyword = this.#i18n.t('ui.tools.resultFailure')
+				const errorKeyword = this.#i18n.t('ui.tools.resultError')
 				const isSuccess =
 					!step.toolResult ||
 					(!step.toolResult.includes(failureKeyword) && !step.toolResult.includes(errorKeyword))
@@ -532,7 +650,7 @@ export class Panel {
 		}
 
 		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
@@ -551,47 +669,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/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/ui/src/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) {
-		if (htmlElement.classList.contains(className) || bodyElement.classList.contains(className)) {
+	for (const className of DEFAULT_DARK_MODE_CLASSES) {
+		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
-	if (hasDarkModeClass()) {
-		return true
+	try {
+		// Strategy 1: Check for common dark mode classes
+		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/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/index.ts

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

packages/ui/src/utils.ts

@@ -0,0 +1,6 @@
+export function truncate(text: string, maxLength: number): string {
+	if (text.length > maxLength) {
+		return text.substring(0, maxLength) + '...'
+	}
+	return text
+}

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: ['ai-motion'],
+		},
+		minify: false,
+		sourcemap: true,
+		cssCodeSplit: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})

packages/website/AGENTS.md

@@ -0,0 +1,115 @@
+# 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/
+├── components/
+│   ├── ui/              # shadcn/ui + Magic UI components
+│   ├── Header.tsx       # Site header
+│   ├── Footer.tsx       # Site footer
+│   └── DocsLayout.tsx   # Documentation sidebar
+├── docs/                # Documentation pages
+│   └── [section]/[topic]/page.tsx
+├── test-pages/          # Library integration tests
+├── i18n/                # Internationalization
+├── router.tsx           # Central routing
+├── page.tsx             # Homepage
+└── main.tsx             # App entry
+```
+
+## Adding New Pages
+
+### Documentation Page
+
+1. Create `src/docs/<section>/<slug>/page.tsx`
+2. Add route to `src/router.tsx` with `<Header /> + <DocsLayout>` wrapper
+3. Add navigation item to `DocsLayout.tsx`
+
+### Test Page
+
+1. Create `src/test-pages/<name>.tsx`
+2. Add route to `src/test-pages/router.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/README.md

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

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/index.html

@@ -0,0 +1,60 @@
+<!doctype html>
+<html lang="zh-CN">
+	<head>
+		<meta charset="UTF-8" />
+		<link
+			rel="icon"
+			type="image/svg+xml"
+			href="https://img.alicdn.com/imgextra/i2/O1CN012eGDRI1X6nnMt9clU_!!6000000002875-49-tps-64-64.webp"
+		/>
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>PageAgent - The GUI Agent Living in Your Webpage</title>
+		<meta
+			name="description"
+			content="PageAgent.js: Intelligent GUI Agent for any website. Modern web AI automation with minimal integration."
+		/>
+		<meta
+			name="keywords"
+			content="PageAgent, AI Agent, GUI Agent, Web Automation, GUI Automation, Frontend, CDN, JavaScript, React, Vite, LLM"
+		/>
+		<meta
+			property="og:image"
+			content="https://img.alicdn.com/imgextra/i3/O1CN01JPT4Fj1FJTfmHfNxO_!!6000000000466-49-tps-512-512.webp"
+		/>
+		<meta property="og:url" content="https://alibaba.github.io/page-agent" />
+		<meta property="og:type" content="website" />
+		<meta name="theme-color" content="#58c0fc" />
+		<meta name="color-scheme" content="light dark" />
+		<meta name="author" content="PageAgent.js Team" />
+		<meta property="og:title" content="PageAgent.js - AI-powered GUI Agent" />
+		<meta property="og:description" content="The GUI Agent living in your website." />
+		<meta property="og:type" content="website" />
+		<meta property="og:locale" content="en_US" />
+		<meta property="og:locale:alternate" content="zh_CN" />
+
+		<!-- Google tag (gtag.js) -->
+		<script async src="https://www.googletagmanager.com/gtag/js?id=G-HCGRJTN3HM"></script>
+		<script>
+			window.dataLayer = window.dataLayer || []
+			function gtag() {
+				dataLayer.push(arguments)
+			}
+			gtag('js', new Date())
+
+			gtag('config', 'G-HCGRJTN3HM')
+		</script>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="./src/main.tsx"></script>
+		<script>
+			// Dynamically update html lang attribute based on i18n detection
+			const updateHtmlLang = () => {
+				const lang = localStorage.getItem('i18nextLng') || navigator.language || 'zh-CN'
+				document.documentElement.lang = lang
+			}
+			updateHtmlLang()
+			window.addEventListener('storage', updateHtmlLang)
+		</script>
+	</body>
+</html>

packages/website/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@page-agent/website",
+	"private": true,
+	"version": "0.0.19",
+	"type": "module",
+	"scripts": {
+		"dev": "vite",
+		"build:website": "vite build",
+		"preview": "vite preview",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@tailwindcss/vite": "^4.1.18",
+		"@types/react": "^19.2.2",
+		"@types/react-dom": "^19.2.1",
+		"@vitejs/plugin-react-swc": "^4.1.0",
+		"i18next": "^25.7.3",
+		"i18next-browser-languagedetector": "^8.2.0",
+		"react": "^19.2.3",
+		"react-dom": "^19.2.3",
+		"react-i18next": "^16.5.1",
+		"tailwindcss": "^4.1.14",
+		"tw-animate-css": "^1.4.0",
+		"wouter": "^3.9.0"
+	},
+	"dependencies": {
+		"@radix-ui/react-icons": "^1.3.2",
+		"@radix-ui/react-separator": "^1.1.8",
+		"@radix-ui/react-slot": "^1.2.4",
+		"@radix-ui/react-switch": "^1.2.6",
+		"@radix-ui/react-tooltip": "^1.2.8",
+		"class-variance-authority": "^0.7.1",
+		"clsx": "^2.1.1",
+		"lucide-react": "^0.562.0",
+		"motion": "^12.24.0",
+		"next-themes": "^0.4.6",
+		"rough-notation": "^0.5.1",
+		"simple-icons": "^16.4.0",
+		"sonner": "^2.0.7",
+		"tailwind-merge": "^3.4.0"
+	}
+}

packages/website/src/components/BetaNotice.tsx

@@ -1,17 +1,19 @@
+import { useTranslation } from 'react-i18next'
+
 export default function BetaNotice() {
+	const { t } = useTranslation('common')
+
 	return (
 		<div className="bg-orange-50 dark:bg-orange-900/20 border border-orange-200 dark:border-orange-800 rounded-lg p-4 mb-8">
 			<div className="flex items-start">
-				<div className="flex-shrink-0">
+				<div className="shrink-0">
 					<span className="text-xl">🚧</span>
 				</div>
 				<div className="ml-3">
 					<h3 className="text-sm font-medium text-orange-800 dark:text-orange-200 mb-1">
-						Beta 阶段
+						{t('beta_notice.title')}
 					</h3>
-					<p className="text-sm text-orange-700 dark:text-orange-300">
-						当前功能未完成，接口可能随时变更。正式版本发布前请勿用于生产环境。
-					</p>
+					<p className="text-sm text-orange-700 dark:text-orange-300">{t('beta_notice.content')}</p>
 				</div>
 			</div>
 		</div>

packages/website/src/components/CodeEditor.tsx

@@ -28,7 +28,7 @@ const CodeEditor: React.FC<CodeEditorProps> = ({
 
 	// 使用 Tailwind 的 dark: 前缀实现自动主题切换
 	const containerClasses =
-		'bg-gradient-to-br from-gray-50 to-gray-100 dark:from-gray-900 dark:to-gray-800 border-gray-300 dark:border-gray-700'
+		'bg-linear-to-br from-gray-50 to-gray-100 dark:from-gray-900 dark:to-gray-800 border-gray-300 dark:border-gray-700'
 	const headerClasses = 'bg-gray-100 dark:bg-gray-800 border-gray-300 dark:border-gray-700'
 	const headerTextClasses = 'text-gray-700 dark:text-gray-300'
 	const languageTextClasses = 'text-gray-600 dark:text-gray-400'
@@ -72,7 +72,7 @@ const CodeEditor: React.FC<CodeEditorProps> = ({
 				<div className="flex">
 					{/* 行号 */}
 					{showLineNumbers && (
-						<div className={`flex-shrink-0 px-4 py-4 ${lineNumbersClasses} border-r select-none`}>
+						<div className={`shrink-0 px-4 py-4 ${lineNumbersClasses} border-r select-none`}>
 							<div className="text-xs font-mono leading-6">
 								{lines.map((line, lineIdx) => {
 									const lineNum = lineIdx + 1

packages/website/src/components/DocsLayout.tsx

@@ -0,0 +1,98 @@
+import { ReactNode } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Link, useLocation } from 'wouter'
+
+interface DocsLayoutProps {
+	children: ReactNode
+}
+
+interface NavItem {
+	title: string
+	path: string
+}
+
+interface NavSection {
+	title: string
+	items: NavItem[]
+}
+
+export default function DocsLayout({ children }: DocsLayoutProps) {
+	const { t } = useTranslation('common')
+	const [location] = useLocation()
+
+	const navigationSections: NavSection[] = [
+		{
+			title: t('nav.introduction'),
+			items: [
+				{ title: t('nav.overview'), path: '/docs/introduction/overview' },
+				{ title: t('nav.quick_start'), path: '/docs/introduction/quick-start' },
+				{ title: t('nav.limitations'), path: '/docs/introduction/limitations' },
+			],
+		},
+		{
+			title: t('nav.features'),
+			items: [
+				{ title: t('nav.model_integration'), path: '/docs/features/model-integration' },
+				{ title: t('nav.custom_tools'), path: '/docs/features/custom-tools' },
+				{ title: t('nav.knowledge_injection'), path: '/docs/features/custom-instructions' },
+				{ title: t('nav.security_permissions'), path: '/docs/features/security-permissions' },
+				{ title: t('nav.data_masking'), path: '/docs/features/data-masking' },
+			],
+		},
+		{
+			title: t('nav.integration'),
+			items: [
+				{ title: t('nav.cdn_setup'), path: '/docs/integration/cdn-setup' },
+				{ title: t('nav.configuration'), path: '/docs/integration/configuration' },
+				{ title: t('nav.best_practices'), path: '/docs/integration/best-practices' },
+				{ title: t('nav.third_party_agent'), path: '/docs/integration/third-party-agent' },
+			],
+		},
+	]
+
+	return (
+		<div className="max-w-7xl mx-auto px-6 py-8 overflow-x-auto">
+			<div className="flex gap-8 min-w-[900px]">
+				{/* Sidebar */}
+				<aside className="w-64 shrink-0" role="complementary" aria-label="文档导航">
+					<div className="sticky top-8">
+						<nav className="space-y-8" role="navigation" aria-label="文档章节">
+							{navigationSections.map((section) => (
+								<section key={section.title}>
+									<h3 className="font-semibold text-gray-600 dark:text-gray-400 uppercase tracking-wider mb-3">
+										{section.title}
+									</h3>
+									<ul className="space-y-2" role="list">
+										{section.items.map((item) => {
+											const isActive = location === item.path
+											return (
+												<li key={item.path}>
+													<Link
+														href={item.path}
+														className={`block px-3 py-2 rounded-lg transition-colors duration-200 ${
+															isActive
+																? 'bg-blue-100 dark:bg-blue-900/30 text-blue-700 dark:text-blue-300 font-medium'
+																: 'text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-white hover:bg-gray-100 dark:hover:bg-gray-800'
+														}`}
+														aria-current={isActive ? 'page' : undefined}
+													>
+														{item.title}
+													</Link>
+												</li>
+											)
+										})}
+									</ul>
+								</section>
+							))}
+						</nav>
+					</div>
+				</aside>
+
+				{/* Main Content */}
+				<main className="flex-1 min-w-0" id="main-content" role="main">
+					<div className="prose prose-lg dark:prose-invert max-w-none">{children}</div>
+				</main>
+			</div>
+		</div>
+	)
+}

packages/website/src/components/Footer.tsx

@@ -0,0 +1,37 @@
+import { useTranslation } from 'react-i18next'
+import { siGithub } from 'simple-icons'
+
+export default function Footer() {
+	const { t } = useTranslation('common')
+
+	return (
+		<footer
+			className="bg-gray-50 dark:bg-gray-900 border-t border-gray-200 dark:border-gray-700"
+			role="contentinfo"
+		>
+			<div className="max-w-7xl mx-auto px-6 py-6">
+				<div className="flex flex-col md:flex-row justify-between items-center space-y-4 md:space-y-0">
+					<p className="text-gray-600 dark:text-gray-300 text-sm">{t('footer.copyright')}</p>
+					<div className="flex items-center space-x-6">
+						<a
+							href="https://github.com/alibaba/page-agent"
+							target="_blank"
+							rel="noopener noreferrer"
+							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
+								role="img"
+								viewBox="0 0 24 24"
+								className="w-5 h-5 fill-current"
+								aria-hidden="true"
+							>
+								<path d={siGithub.path} />
+							</svg>
+						</a>
+					</div>
+				</div>
+			</div>
+		</footer>
+	)
+}

packages/website/src/components/Header.tsx

@@ -0,0 +1,170 @@
+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 { HyperText } from './ui/hyper-text'
+
+export default function Header() {
+	const { t } = useTranslation('common')
+	const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
+
+	return (
+		<>
+			<header
+				className="relative z-50 bg-white/80 dark:bg-gray-900/80 backdrop-blur-md border-b border-gray-200 dark:border-gray-700"
+				role="banner"
+			>
+				<div className="max-w-7xl mx-auto px-6 py-4">
+					<div className="flex items-center justify-between gap-2">
+						{/* Logo */}
+						<Link
+							href="/"
+							className="flex items-center gap-2 sm:gap-3 group shrink-0"
+							aria-label={t('header.logo_alt')}
+							onClick={() => setMobileMenuOpen(false)}
+						>
+							<img
+								src="https://img.alicdn.com/imgextra/i2/O1CN01HB8ylu1uozANEMZw2_!!6000000006085-49-tps-128-128.webp"
+								alt="PageAgent Logo"
+								className="w-10 h-10 rounded-xl group-hover:scale-110 transition-transform duration-200"
+							/>
+							<div>
+								<span className="text-base sm:text-xl font-bold text-gray-900 dark:text-white block leading-tight">
+									page-agent
+								</span>
+								<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}
+								>
+									{t('header.slogan')}
+								</HyperText>
+							</div>
+						</Link>
+
+						{/* Mobile Icon Navigation (横向滚动) */}
+						<nav
+							className="md:hidden flex items-center gap-1 overflow-x-auto scrollbar-hide flex-1"
+							role="navigation"
+							aria-label="Mobile navigation"
+						>
+							<Link
+								href="/docs/introduction/overview"
+								className="p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200 shrink-0"
+								aria-label={t('header.nav_docs')}
+							>
+								<BookOpen className="w-5 h-5" />
+							</Link>
+							<a
+								href="https://github.com/alibaba/page-agent"
+								target="_blank"
+								rel="noopener noreferrer"
+								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')}
+							>
+								<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>
+
+						{/* Desktop Navigation */}
+						<nav
+							className="hidden md:flex items-center space-x-6"
+							role="navigation"
+							aria-label={t('header.nav_docs')}
+						>
+							<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"
+							>
+								<BookOpen className="w-4 h-4" />
+								{t('header.nav_docs')}
+							</Link>
+							<a
+								href="https://github.com/alibaba/page-agent"
+								target="_blank"
+								rel="noopener noreferrer"
+								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')}
+							>
+								<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 />
+							<LanguageSwitcher />
+						</nav>
+
+						{/* Mobile menu button */}
+						<button
+							type="button"
+							className="md:hidden p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors duration-200 shrink-0"
+							aria-label={t('header.mobile_menu')}
+							aria-expanded={mobileMenuOpen}
+							aria-controls="mobile-menu"
+							onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
+						>
+							{mobileMenuOpen ? <X className="w-6 h-6" /> : <Menu className="w-6 h-6" />}
+						</button>
+					</div>
+
+					{/* Mobile Navigation */}
+					{mobileMenuOpen && (
+						<nav
+							id="mobile-menu"
+							className="md:hidden pt-4 pb-2 space-y-3 border-t border-gray-200 dark:border-gray-700 mt-4"
+							role="navigation"
+						>
+							<Link
+								href="/docs/introduction/overview"
+								className="flex items-center gap-2 px-3 py-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
+								onClick={() => setMobileMenuOpen(false)}
+							>
+								<BookOpen className="w-5 h-5" />
+								{t('header.nav_docs')}
+							</Link>
+							<a
+								href="https://github.com/alibaba/page-agent"
+								target="_blank"
+								rel="noopener noreferrer"
+								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')}
+							>
+								<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">
+								<ThemeSwitcher />
+								<LanguageSwitcher />
+							</div>
+						</nav>
+					)}
+				</div>
+			</header>
+		</>
+	)
+}

packages/website/src/components/HighlightSyntax.module.css

@@ -0,0 +1,126 @@
+.syntax {
+	white-space: pre-wrap;
+	word-break: break-word;
+	overflow-wrap: break-word;
+	font-family: monospace;
+	color: #171717;
+}
+
+:global(.dark) .syntax {
+	color: #e0e0e0;
+}
+
+/* JavaScript/TypeScript 关键字 */
+.keyword {
+	color: #d73a49;
+	font-weight: 600;
+}
+
+:global(.dark) .keyword {
+	color: #ff6b6b;
+}
+
+/* TypeScript 特定关键字 (interface, type, enum, etc.) */
+.tsKeyword {
+	color: #af00db;
+	font-weight: 600;
+}
+
+:global(.dark) .tsKeyword {
+	color: #c792ea;
+}
+
+/* TypeScript 内置类型 */
+.type {
+	color: #267f99;
+	font-weight: 500;
+}
+
+:global(.dark) .type {
+	color: #4ec9b0;
+}
+
+/* 字符串 */
+.string {
+	color: #1d6eca;
+}
+
+:global(.dark) .string {
+	color: #4fc3f7;
+}
+
+/* 数字 */
+.number {
+	color: #00c583;
+}
+
+:global(.dark) .number {
+	color: #66bb6a;
+}
+
+/* 布尔值和字面量 (true, false, null, undefined) */
+.literal {
+	color: #0000ff;
+	font-weight: 500;
+}
+
+:global(.dark) .literal {
+	color: #569cd6;
+}
+
+/* 注释 */
+.comment {
+	color: #6a737d;
+	font-style: italic;
+}
+
+:global(.dark) .comment {
+	color: #9e9e9e;
+}
+
+/* 装饰器 (@decorator) */
+.decorator {
+	color: #e0aa00;
+	font-weight: 500;
+}
+
+:global(.dark) .decorator {
+	color: #dcdcaa;
+}
+
+/* 箭头函数 (=>) */
+.arrow {
+	color: #d73a49;
+	font-weight: bold;
+}
+
+:global(.dark) .arrow {
+	color: #ff6b6b;
+}
+
+/* 标识符（变量名、函数名等） */
+.identifier {
+	color: #171717;
+}
+
+:global(.dark) .identifier {
+	color: #e0e0e0;
+}
+
+/* 属性访问 (.property) */
+.property {
+	color: #0550ae;
+}
+
+:global(.dark) .property {
+	color: #9cdcfe;
+}
+
+/* 运算符 */
+.operator {
+	color: #5a5a5a;
+}
+
+:global(.dark) .operator {
+	color: #d4d4d4;
+}

packages/website/src/components/HighlightSyntax.tsx

@@ -0,0 +1,176 @@
+/**
+ * js 语法高亮组件，适合在文章中演示代码片段
+ */
+import React from 'react'
+
+import styles from './HighlightSyntax.module.css'
+
+interface HighlightSyntaxProps {
+	code: string
+}
+
+// JavaScript/TypeScript 关键字
+const keywords =
+	'async|await|function|const|let|var|if|else|for|while|return|try|catch|finally|class|extends|from|import|export|default|undefined|throw|break|continue|switch|case|do|with|yield|delete|typeof|void|static|get|set|super|debugger'
+
+// TypeScript 特定关键字
+const tsKeywords =
+	'interface|type|enum|namespace|module|declare|abstract|implements|public|private|protected|readonly|as|satisfies|infer|keyof|is'
+
+// 布尔值和空值
+const literals = 'true|false|null|undefined|NaN|Infinity'
+
+// TypeScript 内置类型
+const tsTypes =
+	'string|number|boolean|any|unknown|never|void|object|symbol|bigint|Array|Promise|Record|Partial|Required|Readonly|Pick|Omit|Exclude|Extract|NonNullable|ReturnType|Parameters|ConstructorParameters|InstanceType|ThisType|Uppercase|Lowercase|Capitalize|Uncapitalize'
+
+// 辅助函数：转义 HTML 特殊字符
+function escapeHtml(text: string): string {
+	return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+// 语法高亮函数，先提取 token 再转义和高亮
+function highlightSyntax(code: string): string {
+	// 构建正则模式，包含更多 token 类型（在原始文本上匹配）
+	const pattern = new RegExp(
+		'(' +
+			// 1. 字符串（双引号、单引号、模板字符串）
+			'"([^"\\\\]|\\\\.)*"|' +
+			"'([^'\\\\]|\\\\.)*'|" +
+			'`([^`\\\\]|\\\\.)*`|' +
+			// 2. 注释（单行和多行）
+			'//[^\\n]*|' +
+			'/\\*[\\s\\S]*?\\*/|' +
+			// 3. 装饰器
+			'@[a-zA-Z_$][\\w$]*|' +
+			// 4. 数字（包括小数、十六进制、科学计数法）
+			'\\b0[xX][0-9a-fA-F]+\\b|' +
+			'\\b\\d+\\.?\\d*(?:[eE][+-]?\\d+)?\\b|' +
+			// 5. TypeScript/JavaScript 关键字
+			'\\b(?:' +
+			keywords +
+			'|' +
+			tsKeywords +
+			'|' +
+			literals +
+			')\\b|' +
+			// 6. TypeScript 内置类型
+			'\\b(?:' +
+			tsTypes +
+			')\\b|' +
+			// 7. 箭头函数
+			'=>|' +
+			// 8. 函数调用（函数名后跟括号）
+			'\\b[a-zA-Z_$][\\w$]*(?=\\()|' +
+			// 9. 属性访问
+			'\\.[a-zA-Z_$][\\w$]*|' +
+			// 10. 运算符和特殊符号
+			'[+\\-*/%&|^!~<>=?:]+|' +
+			'[{}\\[\\]();,.]' +
+			')',
+		'g'
+	)
+
+	const tokens: string[] = []
+	let lastIndex = 0
+	let match: RegExpExecArray | null
+	while ((match = pattern.exec(code)) !== null) {
+		if (match.index > lastIndex) {
+			const gap = code.slice(lastIndex, match.index)
+			// 将间隙按空白符分割，保留空白符
+			tokens.push(...gap.split(/(\s+)/))
+		}
+		tokens.push(match[0])
+		lastIndex = pattern.lastIndex
+	}
+	if (lastIndex < code.length) {
+		tokens.push(...code.slice(lastIndex).split(/(\s+)/))
+	}
+
+	const highlighted = tokens
+		.map((token) => {
+			// 空白符直接返回
+			if (/^\s+$/.test(token)) {
+				return token
+			}
+
+			// 1. 注释（单行和多行）
+			if (/^\/\/.*$/.test(token) || /^\/\*[\s\S]*?\*\/$/.test(token)) {
+				return `<span class="${styles.comment}">${escapeHtml(token)}</span>`
+			}
+
+			// 2. 字符串
+			if (
+				/^"([^"\\]|\\.)*"$/.test(token) ||
+				/^'([^'\\]|\\.)*'$/.test(token) ||
+				/^`([^`\\]|\\.)*`$/.test(token)
+			) {
+				return `<span class="${styles.string}">${escapeHtml(token)}</span>`
+			}
+
+			// 3. 数字
+			if (/^(0[xX][0-9a-fA-F]+|\d+\.?\d*(?:[eE][+-]?\d+)?)$/.test(token)) {
+				return `<span class="${styles.number}">${escapeHtml(token)}</span>`
+			}
+
+			// 4. 布尔值和特殊字面量
+			if (new RegExp(`^(?:${literals})$`).test(token)) {
+				return `<span class="${styles.literal}">${escapeHtml(token)}</span>`
+			}
+
+			// 5. JavaScript/TypeScript 关键字
+			if (new RegExp(`^(?:${keywords})$`).test(token)) {
+				return `<span class="${styles.keyword}">${escapeHtml(token)}</span>`
+			}
+
+			// 6. TypeScript 特定关键字
+			if (new RegExp(`^(?:${tsKeywords})$`).test(token)) {
+				return `<span class="${styles.tsKeyword}">${escapeHtml(token)}</span>`
+			}
+
+			// 7. TypeScript 内置类型
+			if (new RegExp(`^(?:${tsTypes})$`).test(token)) {
+				return `<span class="${styles.type}">${escapeHtml(token)}</span>`
+			}
+
+			// 8. 装饰器
+			if (/^@[a-zA-Z_$][\w$]*$/.test(token)) {
+				return `<span class="${styles.decorator}">${escapeHtml(token)}</span>`
+			}
+
+			// 9. 箭头函数
+			if (token === '=>') {
+				return `<span class="${styles.arrow}">${escapeHtml(token)}</span>`
+			}
+
+			// 10. 函数调用和标识符
+			if (/^[a-zA-Z_$][\w$]*$/.test(token)) {
+				return `<span class="${styles.identifier}">${escapeHtml(token)}</span>`
+			}
+
+			// 11. 属性访问
+			if (/^\.[a-zA-Z_$][\w$]*$/.test(token)) {
+				return `<span class="${styles.property}">${escapeHtml(token)}</span>`
+			}
+
+			// 12. 运算符
+			if (/^[+\-*/%&|^!~<>=?:]+$/.test(token)) {
+				return `<span class="${styles.operator}">${escapeHtml(token)}</span>`
+			}
+
+			// 13. 其他符号，需要转义
+			return escapeHtml(token)
+		})
+		.join('')
+
+	return highlighted
+}
+
+const HighlightSyntaxClient: React.FC<HighlightSyntaxProps> = ({ code }) => {
+	const htmlContent = highlightSyntax(code)
+
+	// eslint-disable-next-line react-dom/no-dangerously-set-innerhtml
+	return <code className={styles.syntax} dangerouslySetInnerHTML={{ __html: htmlContent }} />
+}
+
+export default HighlightSyntaxClient

packages/website/src/components/LanguageSwitcher.tsx

@@ -0,0 +1,115 @@
+import { useEffect, useRef, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+
+export default function LanguageSwitcher() {
+	const { i18n, t } = useTranslation('common')
+	const [isOpen, setIsOpen] = useState(false)
+	const dropdownRef = useRef<HTMLDivElement>(null)
+
+	const currentLang = i18n.language
+
+	const languages = [
+		{ code: 'zh-CN', label: '中文' },
+		{ code: 'en-US', label: 'English' },
+	]
+
+	const currentLanguage = languages.find((lang) => lang.code === currentLang) || languages[0]
+
+	const handleLanguageChange = (langCode: string) => {
+		i18n.changeLanguage(langCode)
+		setIsOpen(false)
+	}
+
+	// Close dropdown when clicking outside
+	useEffect(() => {
+		const handleClickOutside = (event: MouseEvent) => {
+			if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+				setIsOpen(false)
+			}
+		}
+
+		if (isOpen) {
+			document.addEventListener('mousedown', handleClickOutside)
+		}
+
+		return () => {
+			document.removeEventListener('mousedown', handleClickOutside)
+		}
+	}, [isOpen])
+
+	return (
+		<div className="relative" ref={dropdownRef}>
+			<button
+				onClick={() => setIsOpen(!isOpen)}
+				className="flex items-center gap-2 px-3 py-1.5 rounded-lg bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 transition-colors text-sm font-medium border border-gray-200 dark:border-gray-700 text-gray-700 dark:text-gray-300"
+				aria-label={t('language.switch_label')}
+				aria-expanded={isOpen}
+				aria-haspopup="true"
+			>
+				<svg
+					className="w-4 h-4"
+					fill="none"
+					stroke="currentColor"
+					viewBox="0 0 24 24"
+					aria-hidden="true"
+				>
+					<path
+						strokeLinecap="round"
+						strokeLinejoin="round"
+						strokeWidth={2}
+						d="M3 5h12M9 3v2m1.048 9.5A18.022 18.022 0 016.412 9m6.088 9h7M11 21l5-10 5 10M12.751 5C11.783 10.77 8.07 15.61 3 18.129"
+					/>
+				</svg>
+				<span>{currentLanguage.label}</span>
+				<svg
+					className={`w-4 h-4 transition-transform duration-200 ${isOpen ? 'rotate-180' : ''}`}
+					fill="none"
+					stroke="currentColor"
+					viewBox="0 0 24 24"
+					aria-hidden="true"
+				>
+					<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
+				</svg>
+			</button>
+
+			{isOpen && (
+				<div
+					className="absolute right-0 mt-2 w-40 bg-white dark:bg-gray-800 rounded-lg shadow-lg border border-gray-200 dark:border-gray-700 py-1 z-50"
+					role="menu"
+					aria-orientation="vertical"
+				>
+					{languages.map((lang) => (
+						<button
+							key={lang.code}
+							onClick={() => handleLanguageChange(lang.code)}
+							className={`w-full flex items-center gap-2 px-4 py-2 text-sm text-left hover:bg-gray-100 dark:hover:bg-gray-700 transition-colors ${
+								currentLang === lang.code
+									? 'bg-blue-50 dark:bg-blue-900/20 text-blue-700 dark:text-blue-300'
+									: 'text-gray-700 dark:text-gray-300'
+							}`}
+							role="menuitem"
+						>
+							<span>{lang.label}</span>
+							{currentLang === lang.code && (
+								<svg
+									className="w-4 h-4 ml-auto"
+									fill="none"
+									stroke="currentColor"
+									viewBox="0 0 24 24"
+									aria-hidden="true"
+								>
+									<path
+										strokeLinecap="round"
+										strokeLinejoin="round"
+										strokeWidth={2}
+										d="M5 13l4 4L19 7"
+									/>
+								</svg>
+							)}
+						</button>
+					))}
+				</div>
+			)}
+		</div>
+	)
+}

packages/website/src/components/ThemeSwitcher.tsx

@@ -0,0 +1,133 @@
+import { useEffect, useState } from 'react'
+
+type Theme = 'light' | 'dark'
+
+export default function ThemeSwitcher() {
+	const [theme, setTheme] = useState<Theme>(() => {
+		// 初始化时读取保存的主题
+		if (typeof window !== 'undefined') {
+			const savedTheme = localStorage.getItem('theme') as Theme | null
+			if (savedTheme === 'light' || savedTheme === 'dark') {
+				return savedTheme
+			}
+			// 默认跟随系统
+			return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+		}
+		return 'light'
+	})
+
+	useEffect(() => {
+		// 应用主题
+		if (theme === 'dark') {
+			document.documentElement.classList.add('dark')
+			document.documentElement.style.colorScheme = 'dark'
+		} else {
+			document.documentElement.classList.remove('dark')
+			document.documentElement.style.colorScheme = 'light'
+		}
+		// 保存到 localStorage
+		localStorage.setItem('theme', theme)
+	}, [theme])
+
+	// 监听系统主题变化
+	useEffect(() => {
+		const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+
+		const handleSystemThemeChange = (e: MediaQueryListEvent) => {
+			// 只有在用户未手动设置时才自动跟随系统
+			const savedTheme = localStorage.getItem('theme')
+			if (!savedTheme) {
+				setTheme(e.matches ? 'dark' : 'light')
+			}
+		}
+
+		mediaQuery.addEventListener('change', handleSystemThemeChange)
+		return () => mediaQuery.removeEventListener('change', handleSystemThemeChange)
+	}, [])
+
+	const toggleTheme = () => {
+		setTheme((prev) => (prev === 'light' ? 'dark' : 'light'))
+	}
+
+	return (
+		<button
+			onClick={toggleTheme}
+			className="relative inline-flex items-center h-8 w-16 rounded-full transition-colors duration-300 ease-in-out focus:outline-none"
+			style={{
+				backgroundColor: theme === 'dark' ? '#1e293b' : '#e0f2fe',
+			}}
+			aria-label={theme === 'light' ? 'Switch to dark mode' : 'Switch to light mode'}
+			role="switch"
+			aria-checked={theme === 'dark'}
+		>
+			{/* 滑块 */}
+			<span
+				className="inline-block h-6 w-6 transform rounded-full transition-all duration-300 ease-in-out shadow-md"
+				style={{
+					backgroundColor: theme === 'dark' ? '#475569' : '#fbbf24',
+					transform: theme === 'dark' ? 'translateX(2.25rem)' : 'translateX(0.25rem)',
+				}}
+			>
+				{/* 图标 */}
+				<span className="flex items-center justify-center h-full w-full">
+					{theme === 'light' ? (
+						// 太阳图标
+						<svg
+							className="w-4 h-4 text-white"
+							fill="currentColor"
+							viewBox="0 0 20 20"
+							aria-hidden="true"
+						>
+							<path
+								fillRule="evenodd"
+								d="M10 2a1 1 0 011 1v1a1 1 0 11-2 0V3a1 1 0 011-1zm4 8a4 4 0 11-8 0 4 4 0 018 0zm-.464 4.95l.707.707a1 1 0 001.414-1.414l-.707-.707a1 1 0 00-1.414 1.414zm2.12-10.607a1 1 0 010 1.414l-.706.707a1 1 0 11-1.414-1.414l.707-.707a1 1 0 011.414 0zM17 11a1 1 0 100-2h-1a1 1 0 100 2h1zm-7 4a1 1 0 011 1v1a1 1 0 11-2 0v-1a1 1 0 011-1zM5.05 6.464A1 1 0 106.465 5.05l-.708-.707a1 1 0 00-1.414 1.414l.707.707zm1.414 8.486l-.707.707a1 1 0 01-1.414-1.414l.707-.707a1 1 0 011.414 1.414zM4 11a1 1 0 100-2H3a1 1 0 000 2h1z"
+								clipRule="evenodd"
+							/>
+						</svg>
+					) : (
+						// 月亮图标
+						<svg
+							className="w-4 h-4 text-slate-200"
+							fill="currentColor"
+							viewBox="0 0 20 20"
+							aria-hidden="true"
+						>
+							<path d="M17.293 13.293A8 8 0 016.707 2.707a8.001 8.001 0 1010.586 10.586z" />
+						</svg>
+					)}
+				</span>
+			</span>
+
+			{/* 背景装饰 */}
+			<span
+				className="absolute inset-0 flex items-center justify-between px-2 pointer-events-none"
+				aria-hidden="true"
+			>
+				{/* 左侧太阳（浅色模式时显示） */}
+				<span
+					className={`transition-opacity duration-300 ${
+						theme === 'light' ? 'opacity-0' : 'opacity-40'
+					}`}
+				>
+					<svg className="w-4 h-4 text-sky-400" fill="currentColor" viewBox="0 0 20 20">
+						<path
+							fillRule="evenodd"
+							d="M10 2a1 1 0 011 1v1a1 1 0 11-2 0V3a1 1 0 011-1zm4 8a4 4 0 11-8 0 4 4 0 018 0zm-.464 4.95l.707.707a1 1 0 001.414-1.414l-.707-.707a1 1 0 00-1.414 1.414zm2.12-10.607a1 1 0 010 1.414l-.706.707a1 1 0 11-1.414-1.414l.707-.707a1 1 0 011.414 0zM17 11a1 1 0 100-2h-1a1 1 0 100 2h1zm-7 4a1 1 0 011 1v1a1 1 0 11-2 0v-1a1 1 0 011-1zM5.05 6.464A1 1 0 106.465 5.05l-.708-.707a1 1 0 00-1.414 1.414l.707.707zm1.414 8.486l-.707.707a1 1 0 01-1.414-1.414l.707-.707a1 1 0 011.414 1.414zM4 11a1 1 0 100-2H3a1 1 0 000 2h1z"
+							clipRule="evenodd"
+						/>
+					</svg>
+				</span>
+				{/* 右侧月亮（深色模式时显示） */}
+				<span
+					className={`transition-opacity duration-300 ${
+						theme === 'dark' ? 'opacity-0' : 'opacity-40'
+					}`}
+				>
+					<svg className="w-4 h-4 text-slate-400" fill="currentColor" viewBox="0 0 20 20">
+						<path d="M17.293 13.293A8 8 0 016.707 2.707a8.001 8.001 0 1010.586 10.586z" />
+					</svg>
+				</span>
+			</span>
+		</button>
+	)
+}

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'