chore(version): bump version to 1.4.2

fix(actions): remove debug console.log statements

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -9,7 +9,7 @@ body:
         Thanks for your interest in improving the project! Before submitting, please read our guidelines.
         感谢您对改进项目的兴趣！提交前请阅读我们的指南。
 
-        - [Code of Conduct](https://github.com/alibaba/page-agent/blob/main/CODE_OF_CONDUCT.md)
+        - [Code of Conduct](https://github.com/alibaba/page-agent/blob/main/docs/CODE_OF_CONDUCT.md)
         - [Contributing Guide](https://github.com/alibaba/page-agent/blob/main/CONTRIBUTING.md)
 
   - type: textarea

.github/ISSUE_TEMPLATE/config.yml

@@ -10,5 +10,5 @@ contact_links:
     url: https://github.com/alibaba/page-agent/blob/main/CONTRIBUTING.md
     about: How to contribute code and ideas. 如何进行贡献与提交代码。
   - name: Code of Conduct / 行为准则
-    url: https://github.com/alibaba/page-agent/blob/main/CODE_OF_CONDUCT.md
+    url: https://github.com/alibaba/page-agent/blob/main/docs/CODE_OF_CONDUCT.md
     about: Community expectations and standards. 社区行为期望与标准。

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -9,7 +9,7 @@ body:
         Thanks for your interest in improving the project! Before submitting, please read our guidelines.
         感谢您对改进项目的兴趣！提交前请阅读我们的指南。
 
-        - [Code of Conduct](https://github.com/alibaba/page-agent/blob/main/CODE_OF_CONDUCT.md)
+        - [Code of Conduct](https://github.com/alibaba/page-agent/blob/main/docs/CODE_OF_CONDUCT.md)
         - [Contributing Guide](https://github.com/alibaba/page-agent/blob/main/CONTRIBUTING.md)
 
   - type: textarea

.github/PULL_REQUEST_TEMPLATE.md

@@ -22,4 +22,4 @@ Closes #(issue)
 
 ## Requirements / 要求
 
-- [ ] I have read and follow the [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing Guide](CONTRIBUTING.md) . / 我已阅读并遵守行为准则。
+- [ ] I have read and follow the [Code of Conduct](../docs/CODE_OF_CONDUCT.md) and [Contributing Guide](../CONTRIBUTING.md) . / 我已阅读并遵守行为准则。

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20, 24, 25]
+        node-version: [24]
 
     steps:
       - uses: actions/checkout@v6

.gitignore

@@ -29,11 +29,6 @@ dist-ssr
 .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
-
 # extension
 .output
 .wxt

.vscode/settings.json

@@ -18,7 +18,7 @@
         "wouter"
     ],
     "files.exclude": {
-        "packages/*/node_modules": true,
+        "packages/*/node_modules": true
     },
     "markdownlint.config": {
         // "comment": "Relaxed rules",
@@ -32,6 +32,7 @@
         "first-line-h1": false,
         "block-spacing": false,
         "blanks-around-lists": false,
-        "ol-prefix": false
+        "ol-prefix": false,
+        "no-duplicate-heading": false
     }
 }

AGENTS.md

@@ -22,6 +22,7 @@ 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
+npm run zip -w @page-agent/ext # Zip the extension package
 ```
 
 ## Architecture
@@ -36,7 +37,7 @@ packages/
 ├── page-agent/              # npm: "page-agent" entry class (with UI + controller + demo builds)
 ├── website/                 # @page-agent/website (private)
 ├── llms/                    # @page-agent/llms
-├── extension/               # 🚧 WIP: Browser extension (WXT + React)
+├── extension/               # Browser extension (WXT + React)
 ├── page-controller/         # @page-agent/page-controller
 └── ui/                      # @page-agent/ui
 ```

CHANGELOG.md

@@ -1,94 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.0.0] - 2026-01-19
-
-### 🎉 First Stable Release
-
-PageAgent is now ready for production use. The API is stable and breaking changes will follow semantic versioning.
-
-### Features
-
-#### Core
-
-- **PageAgent** - Main entry class with built-in UI Panel
-- **PageAgentCore** - Headless agent class for custom UI or programmatic use
-- **DOM Analysis** - Text-based DOM extraction with high-intensity dehydration
-- **LLM Support** - Works with OpenAI, Claude, DeepSeek, Qwen, and other OpenAI-compatible APIs
-- **Tool System** - Built-in tools for click, input, scroll, select, and more
-- **Custom Tools** - Extend agent capabilities with your own tools (experimental)
-- **Lifecycle Hooks** - Hook into agent execution (experimental)
-- **Instructions System** - System-level and page-level instructions to guide agent behavior
-- **Data Masking** - Transform page content before sending to LLM
-
-#### Page Controller
-
-- **Element Interactions** - Click, input text, select options, scroll
-- **Visual Mask** - Blocks user interaction during automation
-- **DOM Tree Extraction** - Efficient page structure extraction for LLM consumption
-
-#### UI
-
-- **Interactive Panel** - Real-time task progress and agent thinking display
-- **Ask User Tool** - Agent can ask users for clarification
-- **i18n Support** - English and Chinese localization
-
-### Configuration
-
-```typescript
-interface PageAgentConfig {
-    // LLM Configuration (required)
-    baseURL: string
-    apiKey: string
-    model: string
-    temperature?: number
-    maxRetries?: number
-    customFetch?: typeof fetch
-
-    // Agent Configuration
-    language?: 'en-US' | 'zh-CN'
-    maxSteps?: number // default: 20
-    customTools?: Record<string, PageAgentTool> // experimental
-    instructions?: InstructionsConfig
-    transformPageContent?: (content: string) => string | Promise<string>
-    experimentalScriptExecutionTool?: boolean // default: false
-
-    // Lifecycle Hooks (experimental)
-    onBeforeTask?: (agent, result) => void
-    onAfterTask?: (agent, result) => void
-    onBeforeStep?: (agent, stepCount) => void
-    onAfterStep?: (agent, history) => void
-    onDispose?: (agent, reason?) => void
-
-    // Page Controller Configuration
-    enableMask?: boolean // default: true
-    viewportExpansion?: number
-    interactiveBlacklist?: Element[]
-    interactiveWhitelist?: Element[]
-}
-```
-
-### Packages
-
-| Package                       | Description                        |
-| ----------------------------- | ---------------------------------- |
-| `page-agent`                  | Main entry with UI Panel           |
-| `@page-agent/core`            | Core agent logic without UI        |
-| `@page-agent/llms`            | LLM client with retry logic        |
-| `@page-agent/page-controller` | DOM operations and visual feedback |
-| `@page-agent/ui`              | Panel and i18n                     |
-
-### Known Limitations
-
-- Single-page application only (cannot navigate across pages)
-- No visual recognition (relies on DOM structure)
-- Limited interaction support (no hover, drag-drop, canvas operations)
-- See [Limitations](https://alibaba.github.io/page-agent/#/docs/introduction/limitations) for details
-
-### Acknowledgments
-
-This project builds upon the excellent work of [browser-use](https://github.com/browser-use/browser-use). DOM processing components and prompts are adapted from browser-use (MIT License).

CONTRIBUTING.md

@@ -20,10 +20,11 @@ Thank you for your interest in contributing to Page-Agent! We welcome contributi
 
 ### Project Structure
 
-This is a **monorepo** with npm workspaces containing **3 main packages**:
+This is a **monorepo** with npm workspaces containing **4 main packages**:
 
 - **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel, published as `page-agent` on npm
 - **Core** (`packages/core/`) - Core agent logic without UI (npm: `@page-agent/core`)
+- **Extension** (`packages/extension/`) - Chrome extension for multi-page tasks and browser-level automation
 - **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.
@@ -126,6 +127,16 @@ If your lame AI assistant does not support [AGENTS.md](https://agents.md/). Add
     LLM_BASE_URL=https://api.your-llm-provider.com/v1
     ```
 
+- **Ollama example** (tested on 0.15 + qwen3:14b, RTX3090 24GB):
+
+    ```env
+    LLM_BASE_URL="http://localhost:11434/v1"
+    LLM_API_KEY="NA"
+    LLM_MODEL_NAME="qwen3:14b"
+    ```
+
+    > ⚠️ Add `*` to `OLLAMA_ORIGINS` (403). Models < 10B unlikely strong enough. Requires tool_call support. Set context length > 15k (default 4k will NOT work): `$env:OLLAMA_CONTEXT_LENGTH=64000; ollama serve`
+
 - Restart the dev server to load new env vars
 - If not provided, the demo will the free testing proxy by default
 
@@ -135,6 +146,16 @@ If your lame AI assistant does not support [AGENTS.md](https://agents.md/). Add
 npm start
 ```
 
+### Extension Development
+
+```bash
+npm run dev -w @page-agent/ext
+npm run zip -w @page-agent/ext
+```
+
+- Load extension in Chrome via `chrome://extensions` -> **Load unpacked**
+- Use `packages/extension/docs/extension_api.md` (EN) or `packages/extension/docs/extension_api_zh.md` (ZH) for API integration details
+
 ### Testing on Other Websites
 
 - Start and serve a local `iife` script
@@ -183,14 +204,6 @@ By contributing to this project, you agree that your contributions will be licen
 
 > You may need to sign a github CLA before you create a PR.
 
-### Browser-Use Attribution
-
-Parts of this project are derived from the [browser-use](https://github.com/browser-use/browser-use) project (MIT License). When contributing to DOM-related functionality:
-
-- Maintain existing attribution comments
-- Follow similar patterns for consistency
-- Credit browser-use for derived concepts
-
 ## 💬 Questions?
 
 - Open a GitHub issue for technical questions

README.md

@@ -1,4 +1,4 @@
-# PageAgent 🤖🪄
+# Page Agent
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://img.alicdn.com/imgextra/i4/O1CN01qKig1P1FnhpFKNdi6_!!6000000000532-2-tps-1280-256.png">
@@ -9,28 +9,33 @@
 
 The GUI Agent Living in Your Webpage. Control web interfaces with natural language.
 
-🌐 **English** | [中文](./README-zh.md)
+🌐 **English** | [中文](./docs/README-zh.md)
 
-👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a>
+👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a>
 
-<video id="demo-video" src="https://github.com/user-attachments/assets/34d8444d-cbfb-44a3-a24e-fd5c167bb0bf" controls crossorigin muted></video>
+<video id="demo-video" src="https://github.com/user-attachments/assets/11aed429-b69c-49d5-8982-fa99b4a0e9a8" controls crossorigin muted></video>
 
 ---
 
 ## ✨ Features
 
-- **🎯 Easy Integration**
-    - No python. No headless browser. No browser extension. Just in-page scripts.
-- **🔐 Client-Side Processing**
-- **🧠 DOM Extraction**
-- **💬 Natural Language Interface**
-- **🎨 UI with Human in the loop**
+- **🎯 Easy integration**
+    - No need for `browser extension` / `python` / `headless browser`.
+    - Just in-page javascript. Everything happens in your web page.
+    - The best tool for your agent to control web pages.
+- **📖 Text-based DOM manipulation**
+    - No screenshots. No OCR or multi-modal LLMs needed.
+    - No special permissions required.
+- **🧠 Bring your own LLMs**
+- **🎨 Pretty UI with human-in-the-loop**
+- **🐙 Optional [chrome extension](https://alibaba.github.io/page-agent/docs/features/chrome-extension) for multi-page tasks.**
 
-And 😉
+## 💡 Use Cases
 
-- **🧪 `cross-page` control with an experimental chrome extension** - `packages/extension`
-
-👉 [**🗺️ Roadmap**](https://github.com/alibaba/page-agent/issues/96)
+- **SaaS AI Copilot** — Ship an AI copilot in your product in lines of code. No backend rewrite needed.
+- **Smart Form Filling** — Turn 20-click workflows into one sentence. Perfect for ERP, CRM, and admin systems.
+- **Accessibility** — Make any web app accessible through natural language. Voice commands, screen readers, zero barrier.
+- **Multi-page Agent** — Extend your agent's reach across browser tabs with the optional [chrome extension](https://alibaba.github.io/page-agent/docs/features/chrome-extension).
 
 ## 🚀 Quick Start
 
@@ -39,19 +44,15 @@ And 😉
 Fastest way to try PageAgent with our free Demo LLM:
 
 ```html
-<script
-    src="https://cdn.jsdelivr.net/npm/page-agent@1.0.0/dist/iife/page-agent.demo.js"
-    crossorigin="true"
-></script>
+<script src="{URL}" crossorigin="true"></script>
 ```
 
-> - **⚠️ For technical evaluation only.** Demo LLM has rate limits and usage restrictions. May change without notice.
-> - **🌷 Bring your own LLM API.**
-
 | Mirrors | URL                                                                                |
 | ------- | ---------------------------------------------------------------------------------- |
-| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.0.0/dist/iife/page-agent.demo.js         |
-| China   | https://registry.npmmirror.com/page-agent/1.0.0/files/dist/iife/page-agent.demo.js |
+| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.4.2/dist/iife/page-agent.demo.js         |
+| China   | https://registry.npmmirror.com/page-agent/1.4.2/files/dist/iife/page-agent.demo.js |
+
+> **⚠️ For technical evaluation only.** This demo CDN uses our free [testing LLM API](https://alibaba.github.io/page-agent/docs/features/models#free-testing-api). By using it, you agree to its [terms](https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md).
 
 ### NPM Installation
 
@@ -63,8 +64,8 @@ npm install page-agent
 import { PageAgent } from 'page-agent'
 
 const agent = new PageAgent({
-    model: 'deepseek-chat',
-    baseURL: 'https://api.deepseek.com',
+    model: 'qwen3.5-plus',
+    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
     apiKey: 'YOUR_API_KEY',
     language: 'en-US',
 })
@@ -72,25 +73,13 @@ const agent = new PageAgent({
 await agent.execute('Click the login button')
 ```
 
-## 🏗️ Structure
-
-PageAgent adopts a simplified monorepo structure:
-
-```
-packages/
-├── core/                # ** Core agent logic without UI(npm: @page-agent/core) **
-├── page-agent/          # Exported agent and demo(npm: page-agent)
-├── llms/                # LLM client (npm: @page-agent/llms)
-├── page-controller/     # DOM operations & Visual Mask (npm: @page-agent/page-controller)
-├── ui/                  # Panel & i18n (npm: @page-agent/ui)
-└── website/             # Demo & Documentation site
-```
+For more programmatic usage, see [📖 Documentations](https://alibaba.github.io/page-agent/docs/introduction/overview).
 
 ## 🤝 Contributing
 
 We welcome contributions from the community! Follow our instructions in [CONTRIBUTING.md](CONTRIBUTING.md) for environment setup and local development.
 
-Please read [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
+Please read [Code of Conduct](docs/CODE_OF_CONDUCT.md) before contributing.
 
 ## 👏 Acknowledgments
 

docs/CHANGELOG.md

@@ -0,0 +1,179 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.0] - 2026-02-27
+
+### Features
+
+- Update Terms of Use and Privacy Policy
+- **Robust tool-call validation** - Action inputs are now validated against tool schemas individually, producing clear error messages (e.g. `Invalid input for action "click_element_by_index"`) instead of unreadable union parse errors
+- **Primitive action input coercion** - Small models that output `{"click_element_by_index": 2}` instead of `{"click_element_by_index": {"index": 2}}` are now auto-corrected using tool schemas
+- **Qwen model updates** - Added `qwen3.5-plus` as the default free testing model; disabled `enable_thinking` for Qwen models to avoid incompatible responses
+- **Updated default LLM endpoint** - Migrated demo and extension to a new testing endpoint with legacy endpoint auto-migration
+
+### Improvements
+
+- Unified zod imports (`* as z`) across all packages for consistency
+- Better Zod error formatting with `z.prettifyError()` in LLM client
+- Exported `InvokeError` and `InvokeErrorType` as values (not just types) from `@page-agent/llms`
+- Exported `SupportedLanguage` type from `@page-agent/core`
+
+### Extension v0.1.8
+
+- **Language setting** - Added language selector (System / English / 中文) in config panel
+- **UI makeover** - New empty state with breathing glow and typing animation; ai-motion glow overlay while running; refined focus styles
+- **Testing endpoint notice** - Shows terms of use notice when using the free testing API
+- **Legacy endpoint migration** - Auto-migrates old Supabase testing endpoint to new endpoint on startup
+
+---
+
+## [1.3.0] - 2026-02-13
+
+### Breaking Changes
+
+- **Lifecycle: `stop()` vs `dispose()`** - New `stop()` method to cancel the current task while keeping the agent reusable. `dispose()` is now terminal — a disposed agent cannot be reused. This affects both `PageAgentCore` and `PanelAgentAdapter`.
+
+### Features
+
+- **Panel action button** - The panel button now morphs between Stop (■) and Close (X) based on agent status
+- **Error history** - Errors and max-step failures are now recorded in `history` as `AgentErrorEvent`, making post-task analysis more complete
+
+### Bug Fixes
+
+- **AbortError handling** - `AbortError` is no longer retried by the LLM client, and shows a clean "Task stopped" message instead of a raw error stack
+
+---
+
+## [1.2.0] - 2026-02-11
+
+### Features
+
+- **Observe Phase** - Agent now observes the page before each action, improving decision accuracy on dynamic pages
+- **Better Abort Handling** - Improved `abortSignal` support for cleaner task cancellation
+
+### Improvements
+
+- Pruned system prompts for lower token usage and faster responses
+- Improved error handling during agent steps with better error messages
+- Zod tree-shaking for smaller bundle size
+
+### Bug Fixes
+
+- Fixed indentation lost in DOM extraction caused by `trimLines`
+- Fixed `gpt-5-mini` temperature configuration
+
+---
+
+## [1.1.0] - 2026-02-02
+
+### Features
+
+- **Custom System Prompt** - New `systemPrompt` config option to customize or extend the default system prompt
+- **Chrome Extension** - Extension with multi-tab control, main-world API with token auth, and tab lifecycle management
+
+### Improvements
+
+- Renamed `include_attributes` to `includeAttributes` in PageController config (camelCase consistency)
+- Lazy-loaded mask module for faster initialization
+- Better date formatting and error messages from LLM client
+- Added `rawRequest` to step history for easier debugging
+
+### Bug Fixes
+
+- Fixed CSP errors by using local SVGs for cursor mask instead of inline styles
+- Fixed `AbortError` being incorrectly retried and shown to users
+- Fixed mask not working correctly when starting a new task after stopping a previous one
+
+---
+
+## [1.0.0] - 2026-01-19
+
+### 🎉 First Stable Release
+
+PageAgent is now ready for production use. The API is stable and breaking changes will follow semantic versioning.
+
+### Features
+
+#### Core
+
+- **PageAgent** - Main entry class with built-in UI Panel
+- **PageAgentCore** - Headless agent class for custom UI or programmatic use
+- **DOM Analysis** - Text-based DOM extraction with high-intensity dehydration
+- **LLM Support** - Works with OpenAI, Claude, DeepSeek, Qwen, and other OpenAI-compatible APIs
+- **Tool System** - Built-in tools for click, input, scroll, select, and more
+- **Custom Tools** - Extend agent capabilities with your own tools (experimental)
+- **Lifecycle Hooks** - Hook into agent execution (experimental)
+- **Instructions System** - System-level and page-level instructions to guide agent behavior
+- **Data Masking** - Transform page content before sending to LLM
+
+#### Page Controller
+
+- **Element Interactions** - Click, input text, select options, scroll
+- **Visual Mask** - Blocks user interaction during automation
+- **DOM Tree Extraction** - Efficient page structure extraction for LLM consumption
+
+#### UI
+
+- **Interactive Panel** - Real-time task progress and agent thinking display
+- **Ask User Tool** - Agent can ask users for clarification
+- **i18n Support** - English and Chinese localization
+
+### Configuration
+
+```typescript
+interface PageAgentConfig {
+    // LLM Configuration (required)
+    baseURL: string
+    apiKey: string
+    model: string
+    temperature?: number
+    maxRetries?: number
+    customFetch?: typeof fetch
+
+    // Agent Configuration
+    language?: 'en-US' | 'zh-CN'
+    maxSteps?: number // default: 20
+    customTools?: Record<string, PageAgentTool> // experimental
+    instructions?: InstructionsConfig
+    transformPageContent?: (content: string) => string | Promise<string>
+    experimentalScriptExecutionTool?: boolean // default: false
+
+    // Lifecycle Hooks (experimental)
+    onBeforeTask?: (agent, result) => void
+    onAfterTask?: (agent, result) => void
+    onBeforeStep?: (agent, stepCount) => void
+    onAfterStep?: (agent, history) => void
+    onDispose?: (agent, reason?) => void
+
+    // Page Controller Configuration
+    enableMask?: boolean // default: true
+    viewportExpansion?: number
+    interactiveBlacklist?: Element[]
+    interactiveWhitelist?: Element[]
+}
+```
+
+### Packages
+
+| Package                       | Description                        |
+| ----------------------------- | ---------------------------------- |
+| `page-agent`                  | Main entry with UI Panel           |
+| `@page-agent/core`            | Core agent logic without UI        |
+| `@page-agent/llms`            | LLM client with retry logic        |
+| `@page-agent/page-controller` | DOM operations and visual feedback |
+| `@page-agent/ui`              | Panel and i18n                     |
+
+### Known Limitations
+
+- Single-page application only (cannot navigate across pages)
+- No visual recognition (relies on DOM structure)
+- Limited interaction support (no hover, drag-drop, canvas operations)
+- See [Limitations](https://alibaba.github.io/page-agent/docs/introduction/limitations) for details
+
+### Acknowledgments
+
+This project builds upon the excellent work of [browser-use](https://github.com/browser-use/browser-use). DOM processing components and prompts are adapted from browser-use (MIT License).

docs/README-zh.md

@@ -1,4 +1,4 @@
-# PageAgent 🤖🪄
+# Page Agent
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://img.alicdn.com/imgextra/i4/O1CN01qKig1P1FnhpFKNdi6_!!6000000000532-2-tps-1280-256.png">
@@ -9,28 +9,33 @@
 
 纯 JS 实现的 GUI agent。使用自然语言操作你的 Web 应用。无须后端、客户端、浏览器插件。
 
-🌐 [English](./README.md) | **中文**
+🌐 [English](../README.md) | **中文**
 
-👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/#/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a>
+👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a>
 
-<video id="demo-video" src="https://github.com/user-attachments/assets/34d8444d-cbfb-44a3-a24e-fd5c167bb0bf" controls crossorigin muted></video>
+<video id="demo-video" src="https://github.com/user-attachments/assets/11aed429-b69c-49d5-8982-fa99b4a0e9a8" controls crossorigin muted></video>
 
 ---
 
 ## ✨ Features
 
 - **🎯 轻松集成**
-    - 无需 Python，无需无头浏览器，无需浏览器插件。纯页面内脚本。
-- **🔐 端侧运行**
-- **🧠 HTML 脱水**
-- **💬 自然语言接口**
-- **🎨 HITL 交互界面**
+    - 无需 `浏览器插件` / `Python` / `无头浏览器`。
+    - 纯页面内 JavaScript，一切都在你的网页中完成。
+    - The best tool for your agent to control web pages.
+- **📖 基于文本的 DOM 操作**
+    - 无需截图，无需 OCR 或多模态模型。
+    - 无需特殊权限。
+- **🧠 用你自己的 LLM**
+- **🎨 精美 UI，支持人机协同**
+- **🐙 可选的 [Chrome 扩展](https://alibaba.github.io/page-agent/docs/features/chrome-extension)，支持跨页面任务。**
 
-以及 😉
+## 💡 应用场景
 
-- **🧪 实验性的 Chrome 扩展，支持跨页面控制** - `packages/extension`
-
-👉 [**🗺️ Roadmap**](https://github.com/alibaba/page-agent/issues/96)
+- **SaaS AI 副驾驶** — 几行代码为你的产品加上 AI 副驾驶，不需要重写后端。
+- **智能表单填写** — 把 20 次点击变成一句话。ERP、CRM、管理后台的最佳拍档。
+- **无障碍增强** — 用自然语言让任何网页无障碍。语音指令、屏幕阅读器，零门槛。
+- **跨页面 Agent** — 通过可选的 [Chrome 扩展](https://alibaba.github.io/page-agent/docs/features/chrome-extension)，让你的 Agent 跨标签页工作。
 
 ## 🚀 快速开始
 
@@ -39,19 +44,15 @@
 通过我们免费的 Demo LLM 快速体验 PageAgent：
 
 ```html
-<script
-    src="https://registry.npmmirror.com/page-agent/1.0.0/files/dist/iife/page-agent.demo.js"
-    crossorigin="true"
-></script>
+<script src="{URL}" crossorigin="true"></script>
 ```
 
-> - **⚠️ 仅用于技术评估。** Demo LLM 有速率和使用限制，可能随时变更。
-> - **🌷 建议使用自己的 LLM API。**
-
 | Mirrors | URL                                                                                |
 | ------- | ---------------------------------------------------------------------------------- |
-| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.0.0/dist/iife/page-agent.demo.js         |
-| China   | https://registry.npmmirror.com/page-agent/1.0.0/files/dist/iife/page-agent.demo.js |
+| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.4.2/dist/iife/page-agent.demo.js         |
+| China   | https://registry.npmmirror.com/page-agent/1.4.2/files/dist/iife/page-agent.demo.js |
+
+> **⚠️ 仅用于技术评估。** 该 Demo CDN 使用了免费的[测试 LLM API](https://alibaba.github.io/page-agent/docs/features/models#free-testing-api)，使用即表示您同意其[条款](https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md)。
 
 ### NPM 安装
 
@@ -63,8 +64,8 @@ npm install page-agent
 import { PageAgent } from 'page-agent'
 
 const agent = new PageAgent({
-    model: 'deepseek-chat',
-    baseURL: 'https://api.deepseek.com',
+    model: 'qwen3.5-plus',
+    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
     apiKey: 'YOUR_API_KEY',
     language: 'zh-CN',
 })
@@ -72,25 +73,11 @@ const agent = new PageAgent({
 await agent.execute('点击登录按钮')
 ```
 
-适用于无法使用 NPM 的环境，我们也提供了 IIFE 构建的 CDN 方式。[@see CDN Usage](https://alibaba.github.io/page-agent/#/docs/integration/cdn-setup)
-
-## 🏗️ 架构设计
-
-PageAgent adopts a simplified monorepo structure:
-
-```
-packages/
-├── core/                # ** Core agent logic without UI(npm: @page-agent/core) **
-├── page-agent/          # Exported agent and demo(npm: page-agent)
-├── llms/                # LLM 客户端 (npm: @page-agent/llms)
-├── page-controller/     # DOM 操作 & 蒙层 & 模拟鼠标 (npm: @page-agent/page-controller)
-├── ui/                  # 面板 & i18n (npm: @page-agent/ui)
-└── website/             # 文档站点
-```
+更多编程用法，请参阅 [📖 文档](https://alibaba.github.io/page-agent/docs/introduction/overview)。
 
 ## 🤝 贡献
 
-欢迎社区贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解环境配置和本地开发说明。
+欢迎社区贡献！请参阅 [CONTRIBUTING.md](../CONTRIBUTING.md) 了解环境配置和本地开发说明。
 
 请在贡献前阅读[行为准则](CODE_OF_CONDUCT.md)。
 
@@ -119,7 +106,7 @@ file and in the node_modules directory after installation.
 
 ## 📄 许可证
 
-[MIT License](LICENSE)
+[MIT License](../LICENSE)
 
 ---
 

docs/terms-and-privacy.md

@@ -0,0 +1,83 @@
+# Terms of Use & Privacy
+
+**Last updated:** February 2026
+
+"We" in this document refers to the maintainers of the open-source Page Agent project (https://github.com/alibaba/page-agent). This document covers the Page Agent software itself and the testing services we provide — **not** any third-party product or service built with it.
+
+---
+
+## 1. Open Source Software Privacy
+
+Page Agent (PageAgent.js and Page Agent Extension) is a **client-side only** tool with a "Bring Your Own Key" (BYOK) architecture. The software itself does **not** include any backend service. The software does **not** collect or transmit any user data on its own, and the maintainers do **not** have access to your browsing activity, page content, or task instructions through the software.
+
+All data transmission occurs **only** between your browser and the LLM provider you configure. You are in full control of which provider receives your data.
+
+- You choose which LLM provider to use
+- You may configure your own API endpoint at any time
+- The project is open source and can be audited: https://github.com/alibaba/page-agent
+
+---
+
+## 2. Testing API and Demo Disclaimer & Terms of Use
+
+To facilitate easy testing and technical evaluation, we provide a free testing LLM API. This API is used in the project homepage's live demo, the pre-built demo CDN bundles, and the browser extension's default configuration. Users may also use it independently for their own technical evaluation of page-agent.
+
+This free testing API is provided **strictly for technical evaluation and R&D purposes only**. It must not be used in any production environment. By using this service, you agree to the following terms:
+
+**No Sensitive Data**: You are strictly prohibited from inputting any Personal Identifiable Information (PII), confidential business data, financial/medical records, or using this agent on web pages containing such sensitive information.
+
+**Zero Data Retention**: We do not store, log, or use your prompts or webpage data (DOM) for model training. All data is processed in-transit and immediately discarded. However, we do temporarily process necessary, identity-agnostic network data (such as IP addresses) solely for rate-limiting and anti-abuse purposes.
+
+**Independent Infrastructure**: The `page-agent` open-source software is completely frontend-based with a "Bring Your Own Key" (BYOK) architecture and no built-in backend. To facilitate easy testing, the maintainers have independently purchased public cloud services from Alibaba Cloud China ([aliyun.com](https://www.aliyun.com) FC and BaiLian Qwen models). This project is not affiliated with, nor endorsed by, Alibaba Cloud.
+
+**No Guaranteed Availability**: This testing API may be rate-limited, degraded, or discontinued at any time without prior notice.
+
+**"AS IS" & Limitation of Liability**: This service is provided strictly on an "AS IS" and "AS AVAILABLE" basis, without any warranties. The maintainers bear no liability for any data loss, service interruption, or legal consequences arising from your use of this demo.
+
+**Recommendation for Real Usage**: For secure and continuous usage, we strongly advise using the default BYOK mode with your own legally compliant commercial LLM API keys, or connecting to local, offline models (e.g., Ollama).
+
+**Note**: This service processes data via servers located in Mainland China. If you are located in a region with strict data localization laws (such as the EU/EEA), please do not use this demo.
+
+---
+
+## 3. Browser Extension (Page Agent Ext)
+
+### Data Processing
+
+The extension performs DOM analysis and automation actions **locally in your browser**. Your browsing history, passwords, and form data are not accessed or collected by the extension developer.
+
+Data is transmitted to external servers **only when you initiate an automation task**. When this occurs:
+
+- Your task instructions (natural language commands)
+- Simplified page structure (cleaned DOM) of all pages under the extension's control
+
+are sent to the LLM API endpoint configured in **your settings**.
+
+> **Note:** The DOM cleaning process simplifies page structure for AI readability but **does not guarantee removal of sensitive information** (e.g., visible text, form values, or personal data on the page). Please be mindful of the page content when initiating tasks.
+
+**If you configure a third-party LLM provider** (e.g., OpenAI, Anthropic, or others), data is sent directly to that provider. Their privacy policies apply.
+
+**If you use the built-in testing API**, the terms in [Section 2](#2-testing-api-and-demo-disclaimer--terms-of-use) apply. By using the extension with the default testing API, you agree to those terms.
+
+### Data Storage
+
+- **Local storage only**: Your configuration (API endpoint, API key, model selection) is stored in your browser via `chrome.storage.local`
+- **No cloud sync**: Configuration is not synced to any external server
+- **No analytics**: The extension does not include any analytics or tracking code
+
+### Your Control
+
+- The extension is open source and can be audited by anyone
+- You choose which LLM provider to use
+- You may configure your own API endpoint at any time
+- You can clear all stored data by removing the extension
+
+---
+
+## Changes
+
+We may update these terms as the project evolves.
+
+## Contact
+
+https://github.com/alibaba/page-agent/issues

package.json

@@ -1,7 +1,7 @@
 {
     "name": "root",
     "private": true,
-    "version": "1.0.0",
+    "version": "1.4.2",
     "type": "module",
     "workspaces": [
         "packages/page-controller",
@@ -21,8 +21,7 @@
     },
     "homepage": "https://alibaba.github.io/page-agent/",
     "engines": {
-        "node": ">=20.0.0",
-        "npm": ">=10.0.0"
+        "node": "^20.19.0 || ^22.13.0 || >=24"
     },
     "scripts": {
         "cleanup": "rm -rf packages/*/dist",
@@ -36,29 +35,33 @@
         "prepare": "husky"
     },
     "devDependencies": {
-        "@commitlint/cli": "^20.3.1",
-        "@commitlint/config-conventional": "^20.3.1",
+        "@commitlint/cli": "^20.4.2",
+        "@commitlint/config-conventional": "^20.4.2",
         "@eslint/js": "^9.39.2",
-        "@microsoft/api-extractor": "^7.55.2",
+        "@microsoft/api-extractor": "^7.57.3",
+        "@tailwindcss/vite": "^4.2.1",
         "@trivago/prettier-plugin-sort-imports": "^6.0.2",
-        "@types/node": "^25.0.9",
+        "@types/node": "^25.3.0",
+        "@vitejs/plugin-react-swc": "^4.1.0",
+        "chalk": "^5.6.2",
         "concurrently": "^9.2.1",
-        "dotenv": "^17.2.3",
+        "dotenv": "^17.3.1",
         "eslint": "^9.39.2",
         "eslint-config-prettier": "^10.1.8",
-        "eslint-plugin-react-dom": "^2.7.2",
+        "eslint-plugin-react-dom": "^2.13.0",
         "eslint-plugin-react-hooks": "^7.0.1",
-        "eslint-plugin-react-refresh": "^0.4.26",
-        "eslint-plugin-react-x": "^2.7.2",
+        "eslint-plugin-react-refresh": "^0.5.2",
+        "eslint-plugin-react-x": "^2.13.0",
         "globals": "^17.0.0",
         "husky": "^9.1.7",
         "lint-staged": "^16.2.4",
         "prettier": "^3.8.0",
         "typescript": "^5.9.3",
-        "typescript-eslint": "^8.54.0",
+        "typescript-eslint": "^8.56.1",
         "unplugin-dts": "^1.0.0-beta.6",
         "vite": "^7.3.1",
-        "vite-plugin-css-injected-by-js": "^3.5.2"
+        "vite-plugin-css-injected-by-js": "^3.5.2",
+        "vite-bundle-analyzer": "^1.3.6"
     },
     "overrides": {
         "typescript": "^5.9.3"

packages/core/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@page-agent/core",
     "private": false,
-    "version": "1.0.0",
+    "version": "1.4.2",
     "type": "module",
     "main": "./dist/esm/page-agent-core.js",
     "module": "./dist/esm/page-agent-core.js",
@@ -45,7 +45,7 @@
     "dependencies": {
         "chalk": "^5.6.2",
         "zod": "^4.3.5",
-        "@page-agent/llms": "1.0.0",
-        "@page-agent/page-controller": "1.0.0"
+        "@page-agent/llms": "1.4.2",
+        "@page-agent/page-controller": "1.4.2"
     }
 }

packages/core/src/PageAgentCore.ts

@@ -3,15 +3,15 @@
  * All rights reserved.
  */
 import { InvokeError, LLM, type Tool } from '@page-agent/llms'
-import type { PageController } from '@page-agent/page-controller'
+import type { BrowserState, PageController } from '@page-agent/page-controller'
 import chalk from 'chalk'
-import zod from 'zod'
+import * as z from 'zod'
 
-import { type PageAgentConfig } from './config'
+import { type PageAgentConfig, type SupportedLanguage } from './config'
 import { DEFAULT_MAX_STEPS } from './config/constants'
 import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
 import { tools } from './tools'
-import {
+import type {
 	AgentActivity,
 	AgentReflection,
 	AgentStatus,
@@ -21,17 +21,26 @@ import {
 	MacroToolInput,
 	MacroToolResult,
 } from './types'
-import { normalizeResponse, trimLines, uid, waitFor } from './utils'
-import { assert } from './utils/assert'
+import { assert, normalizeResponse, uid, waitFor } from './utils'
 
 export { type PageAgentConfig }
+export type { SupportedLanguage }
 export { tool, type PageAgentTool } from './tools'
 export type * from './types'
 
 /**
- * AI agent for browser DOM automation.
+ * AI agent for browser automation.
  *
  * @remarks
+ * ## Re-act Agent Loop
+ * - step
+ *    - observe (gather information about current environment and context)
+ *    - think (LLM calling)
+ *      - reflection (evaluate history, generate memory, short-term planning)
+ *      - action (give the action to approach the next goal)
+ *    - act (execute the action)
+ * - loop
+ *
  * ## Event System
  * - `statuschange` - Agent status transitions (idle → running → completed/error)
  * - `historychange` - History events updated (persistent, part of agent memory)
@@ -50,14 +59,18 @@ export type * from './types'
  *    - Types: thinking, executing, executed, retrying, error
  */
 export class PageAgentCore extends EventTarget {
-	config: PageAgentConfig & { maxSteps: number }
-	id = uid()
-	tools: typeof tools
+	readonly id = uid()
+	readonly config: PageAgentConfig & { maxSteps: number }
+	readonly tools: typeof tools
+	/** PageController for DOM operations */
+	readonly pageController: PageController
+
 	task = ''
 	taskId = ''
-
-	/** Agent execution status */
-	#status: AgentStatus = 'idle'
+	/** History events */
+	history: HistoricalEvent[] = []
+	/** Whether this agent has been disposed */
+	disposed = false
 
 	/**
 	 * Callback for when agent needs user input (ask_user tool)
@@ -66,23 +79,21 @@ export class PageAgentCore extends EventTarget {
 	 */
 	onAskUser?: (question: string) => Promise<string>
 
+	#status: AgentStatus = 'idle'
 	#llm: LLM
 	#abortController = new AbortController()
+	#observations: string[] = []
 
-	/** PageController for DOM operations */
-	pageController: PageController
-
-	/** Runtime states for tracking across steps */
-	states = {
-		/** Accumulated wait time in seconds, used by wait tool */
+	/** internal states during a single task execution */
+	#states = {
+		/** Accumulated wait time in seconds */
 		totalWaitTime: 0,
-		/** Last known URL for detecting navigation */
+		/** For detecting navigation */
 		lastURL: '',
+		/** Browser state */
+		browserState: null as BrowserState | null,
 	}
 
-	/** History events */
-	history: HistoricalEvent[] = []
-
 	constructor(config: PageAgentConfig & { pageController: PageController }) {
 		super()
 
@@ -95,7 +106,7 @@ export class PageAgentCore extends EventTarget {
 		// Listen to LLM retry events
 		this.#llm.addEventListener('retry', (e) => {
 			const { attempt, maxAttempts } = (e as CustomEvent).detail
-			this.emitActivity({ type: 'retrying', attempt, maxAttempts })
+			this.#emitActivity({ type: 'retrying', attempt, maxAttempts })
 			// Also push to history for panel rendering
 			this.history.push({
 				type: 'retry',
@@ -109,7 +120,7 @@ export class PageAgentCore extends EventTarget {
 			const error = (e as CustomEvent).detail.error as Error | InvokeError
 			if ((error as any)?.rawError?.name === 'AbortError') return
 			const message = String(error)
-			this.emitActivity({ type: 'error', message })
+			this.#emitActivity({ type: 'error', message })
 			// Also push to history for panel rendering
 			this.history.push({
 				type: 'error',
@@ -153,7 +164,7 @@ export class PageAgentCore extends EventTarget {
 	 * Emit activity event - for transient UI feedback
 	 * @param activity - Current agent activity
 	 */
-	emitActivity(activity: AgentActivity): void {
+	#emitActivity(activity: AgentActivity): void {
 		this.dispatchEvent(new CustomEvent('activity', { detail: activity }))
 	}
 
@@ -166,15 +177,24 @@ export class PageAgentCore extends EventTarget {
 	}
 
 	/**
-	 * Push a persistent observation to the history event stream.
-	 * This will be visible in <agent_history> and remain in memory across steps.
+	 * Push a observation message to the history event stream.
+	 * This will be visible in <agent_history> and remain persistent in memory across steps.
+	 * @experimental @internal
+	 * @note history change will be emitted before next step starts
 	 */
 	pushObservation(content: string): void {
-		this.history.push({ type: 'observation', content })
-		this.#emitHistoryChange()
+		this.#observations.push(content)
+	}
+
+	/** Stop the current task. Agent remains reusable. */
+	stop() {
+		this.pageController.cleanUpHighlights()
+		this.pageController.hideMask()
+		this.#abortController.abort()
 	}
 
 	async execute(task: string): Promise<ExecutionResult> {
+		if (this.disposed) throw new Error('PageAgent has been disposed. Create a new instance.')
 		if (!task) throw new Error('Task is required')
 		this.task = task
 		this.taskId = uid()
@@ -203,44 +223,44 @@ export class PageAgentCore extends EventTarget {
 		this.#setStatus('running')
 		this.#emitHistoryChange()
 
-		// Reset states
-		this.states = {
-			totalWaitTime: 0,
-			lastURL: '',
-		}
+		// Reset internal states
+		this.#states = { totalWaitTime: 0, lastURL: '', browserState: null }
 
-		try {
-			let step = 0
+		let step = 0
 
-			while (true) {
-				await this.#generateObservations(step)
+		while (true) {
+			try {
+				console.group(`step: ${step}`)
 
 				await onBeforeStep?.(this, step)
 
-				console.group(`step: ${step}`)
+				// observe
 
-				// abort
-				if (this.#abortController.signal.aborted) throw new Error('AbortError')
+				console.log(chalk.blue.bold('👀 Observing...'))
 
-				// Thinking
-				console.log(chalk.blue('Thinking...'))
-				this.emitActivity({ type: 'thinking' })
+				this.#states.browserState = await this.pageController.getBrowserState()
+				await this.#handleObservations(step)
 
-				// invoke LLM
+				// assemble prompts
 
 				const messages = [
 					{ role: 'system' as const, content: this.#getSystemPrompt() },
 					{ role: 'user' as const, content: await this.#assembleUserPrompt() },
 				]
 
-				const tools = { AgentOutput: this.#packMacroTool() }
+				const macroTool = { AgentOutput: this.#packMacroTool() }
 
-				const result = await this.#llm.invoke(messages, tools, this.#abortController.signal, {
+				// invoke LLM
+
+				console.log(chalk.blue.bold('🧠 Thinking...'))
+				this.#emitActivity({ type: 'thinking' })
+
+				const result = await this.#llm.invoke(messages, macroTool, this.#abortController.signal, {
 					toolChoiceName: 'AgentOutput',
-					normalizeResponse,
+					normalizeResponse: (res) => normalizeResponse(res, this.tools),
 				})
 
-				// assemble history event
+				// assemble history
 
 				const macroResult = result.toolResult as MacroToolResult
 				const input = macroResult.input
@@ -270,22 +290,12 @@ export class PageAgentCore extends EventTarget {
 
 				//
 
-				console.log(chalk.green('Step finished:'), actionName)
-				console.groupEnd()
-
 				await onAfterStep?.(this, this.history)
 
-				step++
-				if (step > this.config.maxSteps) {
-					this.#onDone(false)
-					const result: ExecutionResult = {
-						success: false,
-						data: 'Step count exceeded maximum limit',
-						history: this.history,
-					}
-					await onAfterTask?.(this, result)
-					return result
-				}
+				console.groupEnd()
+
+				// finish task if done
+
 				if (actionName === 'done') {
 					const success = action.input?.success ?? false
 					const text = action.input?.text || 'no text provided'
@@ -299,19 +309,41 @@ export class PageAgentCore extends EventTarget {
 					await onAfterTask?.(this, result)
 					return result
 				}
+			} catch (error: unknown) {
+				console.groupEnd() // to prevent nested groups
+				const isAbortError = (error as any)?.rawError?.name === 'AbortError'
+
+				console.error('Task failed', error)
+				const errorMessage = isAbortError ? 'Task stopped' : String(error)
+				this.#emitActivity({ type: 'error', message: errorMessage })
+				this.history.push({ type: 'error', message: errorMessage, rawResponse: error })
+				this.#emitHistoryChange()
+				this.#onDone(false)
+				const result: ExecutionResult = {
+					success: false,
+					data: errorMessage,
+					history: this.history,
+				}
+				await onAfterTask?.(this, result)
+				return result
 			}
-		} catch (error: unknown) {
-			console.error('Task failed', error)
-			const errorMessage = String(error)
-			this.emitActivity({ type: 'error', message: errorMessage })
-			this.#onDone(false)
-			const result: ExecutionResult = {
-				success: false,
-				data: errorMessage,
-				history: this.history,
+
+			step++
+			if (step > this.config.maxSteps) {
+				const errorMessage = 'Step count exceeded maximum limit'
+				this.history.push({ type: 'error', message: errorMessage })
+				this.#emitHistoryChange()
+				this.#onDone(false)
+				const result: ExecutionResult = {
+					success: false,
+					data: errorMessage,
+					history: this.history,
+				}
+				await onAfterTask?.(this, result)
+				return result
 			}
-			await onAfterTask?.(this, result)
-			return result
+
+			await waitFor(0.4) // @TODO: configurable
 		}
 	}
 
@@ -328,29 +360,27 @@ export class PageAgentCore extends EventTarget {
 		const tools = this.tools
 
 		const actionSchemas = Array.from(tools.entries()).map(([toolName, tool]) => {
-			return zod.object({ [toolName]: tool.inputSchema }).describe(tool.description)
+			return z.object({ [toolName]: tool.inputSchema }).describe(tool.description)
 		})
 
-		const actionSchema = zod.union(
-			actionSchemas as unknown as [zod.ZodType, zod.ZodType, ...zod.ZodType[]]
-		)
+		const actionSchema = z.union(actionSchemas as unknown as [z.ZodType, z.ZodType, ...z.ZodType[]])
 
-		const macroToolSchema = zod.object({
-			// thinking: zod.string().optional(),
-			evaluation_previous_goal: zod.string().optional(),
-			memory: zod.string().optional(),
-			next_goal: zod.string().optional(),
+		const macroToolSchema = z.object({
+			// thinking: z.string().optional(),
+			evaluation_previous_goal: z.string().optional(),
+			memory: z.string().optional(),
+			next_goal: z.string().optional(),
 			action: actionSchema,
 		})
 
 		return {
-			description: 'You MUST call this tool every step. Outputs your reflections and next action.',
-			inputSchema: macroToolSchema as zod.ZodType<MacroToolInput>,
+			description: 'You MUST call this tool every step!',
+			inputSchema: macroToolSchema as z.ZodType<MacroToolInput>,
 			execute: async (input: MacroToolInput): Promise<MacroToolResult> => {
 				// abort
 				if (this.#abortController.signal.aborted) throw new Error('AbortError')
 
-				console.log(chalk.blue.bold('MacroTool execute'), input)
+				console.log(chalk.blue.bold('MacroTool input'), input)
 				const action = input.action
 
 				const toolName = Object.keys(action)[0]
@@ -371,12 +401,12 @@ export class PageAgentCore extends EventTarget {
 
 				// Find the corresponding tool
 				const tool = tools.get(toolName)
-				assert(tool, `Tool ${toolName} not found. (@note should have been caught before this!!!)`)
+				assert(tool, `Tool ${toolName} not found`)
 
 				console.log(chalk.blue.bold(`Executing tool: ${toolName}`), toolInput)
 
 				// Emit executing activity
-				this.emitActivity({ type: 'executing', tool: toolName, input: toolInput })
+				this.#emitActivity({ type: 'executing', tool: toolName, input: toolInput })
 
 				const startTime = Date.now()
 
@@ -387,7 +417,7 @@ export class PageAgentCore extends EventTarget {
 				console.log(chalk.green.bold(`Tool (${toolName}) executed for ${duration}ms`), result)
 
 				// Emit executed activity
-				this.emitActivity({
+				this.#emitActivity({
 					type: 'executed',
 					tool: toolName,
 					input: toolInput,
@@ -395,9 +425,11 @@ export class PageAgentCore extends EventTarget {
 					duration,
 				})
 
-				// Reset wait time for non-wait tools
-				if (toolName !== 'wait') {
-					this.states.totalWaitTime = 0
+				// counting wait time
+				if (toolName === 'wait') {
+					this.#states.totalWaitTime += toolInput?.seconds || 0
+				} else {
+					this.#states.totalWaitTime = 0
 				}
 
 				// Return structured result
@@ -417,10 +449,8 @@ export class PageAgentCore extends EventTarget {
 			return this.config.customSystemPrompt
 		}
 
-		let systemPrompt = SYSTEM_PROMPT
-
 		const targetLanguage = this.config.language === 'zh-CN' ? '中文' : 'English'
-		systemPrompt = systemPrompt.replace(
+		const systemPrompt = SYSTEM_PROMPT.replace(
 			/Default working language: \*\*.*?\*\*/,
 			`Default working language: **${targetLanguage}**`
 		)
@@ -429,17 +459,17 @@ export class PageAgentCore extends EventTarget {
 	}
 
 	/**
-	 * Get instructions from config and format as XML block
+	 * Get instructions from config
 	 */
 	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) {
+		const url = this.#states.browserState?.url || ''
+		if (instructions.getPageInstructions && url) {
 			try {
 				pageInstructions = instructions.getPageInstructions(url)?.trim()
 			} catch (error) {
@@ -467,23 +497,28 @@ export class PageAgentCore extends EventTarget {
 	}
 
 	/**
-	 * Generate observations before each step
-	 * - URL change detection
-	 * - Too many steps warning
+	 * Generate system observations before each step
 	 * @todo loop detection
 	 * @todo console error
 	 */
-	async #generateObservations(stepCount: number): Promise<void> {
+	async #handleObservations(step: number): Promise<void> {
+		// Accumulated wait time warning
+		if (this.#states.totalWaitTime >= 3) {
+			this.pushObservation(
+				`You have waited ${this.#states.totalWaitTime} seconds accumulatively. DO NOT wait any longer unless you have a good reason.`
+			)
+		}
+
 		// Detect URL change
-		const currentURL = await this.pageController.getCurrentUrl()
-		if (currentURL !== this.states.lastURL) {
+		const currentURL = this.#states.browserState?.url || ''
+		if (currentURL !== this.#states.lastURL) {
 			this.pushObservation(`Page navigated to → ${currentURL}`)
-			this.states.lastURL = currentURL
+			this.#states.lastURL = currentURL
 			await waitFor(0.5) // wait for page to stabilize
 		}
 
-		// Warn about remaining steps
-		const remaining = this.config.maxSteps - stepCount
+		// Remaining steps warning
+		const remaining = this.config.maxSteps - step
 		if (remaining === 5) {
 			this.pushObservation(
 				`⚠️ Only ${remaining} steps remaining. Consider wrapping up or calling done with partial results.`
@@ -493,12 +528,25 @@ export class PageAgentCore extends EventTarget {
 				`⚠️ Critical: Only ${remaining} steps left! You must finish the task or call done immediately.`
 			)
 		}
+
+		// Push observations to history and emit
+		if (this.#observations.length > 0) {
+			for (const content of this.#observations) {
+				this.history.push({ type: 'observation', content })
+				console.log(chalk.cyan('Observation:'), content)
+			}
+			this.#observations = []
+			this.#emitHistoryChange()
+		}
 	}
 
 	async #assembleUserPrompt(): Promise<string> {
+		const browserState = this.#states.browserState!
+
 		let prompt = ''
 
 		// <instructions> (optional)
+
 		prompt += await this.#getInstructions()
 
 		// <agent_state>
@@ -508,38 +556,36 @@ export class PageAgentCore extends EventTarget {
 
 		const stepCount = this.history.filter((e) => e.type === 'step').length
 
-		prompt += `<agent_state>
-			<user_request>
-			${this.task}
-			</user_request>
-			<step_info>
-			Step ${stepCount + 1} of ${this.config.maxSteps} max possible steps
-			Current date and time: ${new Date().toLocaleString()}
-			</step_info>
-			</agent_state>
-		`
+		prompt += '<agent_state>\n'
+		prompt += '<user_request>\n'
+		prompt += `${this.task}\n`
+		prompt += '</user_request>\n'
+		prompt += '<step_info>\n'
+		prompt += `Step ${stepCount + 1} of ${this.config.maxSteps} max possible steps\n`
+		prompt += `Current time: ${new Date().toLocaleString()}\n`
+		prompt += '</step_info>\n'
+		prompt += '</agent_state>\n\n'
 
 		// <agent_history>
 		//  - <step_N> for steps
 		//  - <sys> for observations and system messages
 
-		prompt += '\n<agent_history>\n'
+		prompt += '<agent_history>\n'
 
 		let stepIndex = 0
 		for (const event of this.history) {
 			if (event.type === 'step') {
 				stepIndex++
-				prompt += `<step_${stepIndex}>
-				Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}
-				Memory: ${event.reflection.memory}
-				Next Goal: ${event.reflection.next_goal}
-				Action Results: ${event.action.output}
-				</step_${stepIndex}>
-			`
+				prompt += `<step_${stepIndex}>\n`
+				prompt += `Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}\n`
+				prompt += `Memory: ${event.reflection.memory}\n`
+				prompt += `Next Goal: ${event.reflection.next_goal}\n`
+				prompt += `Action Results: ${event.action.output}\n`
+				prompt += `</step_${stepIndex}>\n`
 			} else if (event.type === 'observation') {
 				prompt += `<sys>${event.content}</sys>\n`
 			} else if (event.type === 'user_takeover') {
-				prompt += `<sys>User took over control and made changes to the page.</sys>\n`
+				prompt += `<sys>User took over control and made changes to the page</sys>\n`
 			} else if (event.type === 'error') {
 				// Error events are mainly for panel rendering, not included in LLM context
 				// to avoid polluting the agent's reasoning with transient errors
@@ -550,9 +596,18 @@ export class PageAgentCore extends EventTarget {
 
 		// <browser_state>
 
-		prompt += await this.#getBrowserState()
+		let pageContent = browserState.content
+		if (this.config.transformPageContent) {
+			pageContent = await this.config.transformPageContent(pageContent)
+		}
 
-		return trimLines(prompt)
+		prompt += '<browser_state>\n'
+		prompt += browserState.header + '\n'
+		prompt += pageContent + '\n'
+		prompt += browserState.footer + '\n\n'
+		prompt += '</browser_state>\n\n'
+
+		return prompt
 	}
 
 	#onDone(success = true) {
@@ -562,25 +617,9 @@ export class PageAgentCore extends EventTarget {
 		this.#abortController.abort()
 	}
 
-	async #getBrowserState(): Promise<string> {
-		const state = await this.pageController.getBrowserState()
-
-		let content = state.content
-		if (this.config.transformPageContent) {
-			content = await this.config.transformPageContent(content)
-		}
-
-		return trimLines(`<browser_state>
-			${state.header}
-			${content}
-			${state.footer}
-			
-			</browser_state>
-		`)
-	}
-
 	dispose() {
 		console.log('Disposing PageAgent...')
+		this.disposed = true
 		this.pageController.dispose()
 		// this.history = []
 		this.#abortController.abort()

packages/core/src/prompts/system_prompt.md

@@ -10,7 +10,7 @@ You excel at following tasks:
 </intro>
 
 <language_settings>
-- Default working language: **中文**
+- Default working language: **English**
 - Use the language that user is using. Return in user's language.
 </language_settings>
 
@@ -128,7 +128,6 @@ Exhibit the following reasoning patterns to successfully achieve the <user_reque
 Here are examples of good output patterns. Use them as reference but never copy them directly.
 
 <evaluation_examples>
-- Positive Examples:
 "evaluation_previous_goal": "Successfully navigated to the product page and found the target information. Verdict: Success"
 "evaluation_previous_goal": "Clicked the login button and user authentication form appeared. Verdict: Success"
 </evaluation_examples>
@@ -139,17 +138,16 @@ Here are examples of good output patterns. Use them as reference but never copy
 
 <next_goal_examples>
 "next_goal": "Click on the 'Add to Cart' button to proceed with the purchase flow."
-"next_goal": "Extract details from the first item on the page."
 </next_goal_examples>
 </examples>
 
 <output>
-You must ALWAYS respond with a valid JSON in this exact format:
-
 {
   "evaluation_previous_goal": "Concise one-sentence analysis of your last action. Clearly state success, failure, or uncertain.",
   "memory": "1-3 concise sentences of specific memory of this step and overall progress. You should put here everything that will help you track progress in future steps. Like counting pages visited, items found, etc.",
-  "next_goal": "State the next immediate goal and action to achieve it, in one clear sentence."
-  "action":{"one_action_name": {// action-specific parameter}}
+  "next_goal": "State the next immediate goal and action to achieve it, in one clear sentence.",
+  "action":{
+    "Action name": {// Action parameters}
+  }
 }
 </output>

packages/core/src/tools/index.ts

@@ -2,7 +2,7 @@
  * Internal tools for PageAgent.
  * @note Adapted from browser-use
  */
-import zod, { type z } from 'zod'
+import * as z from 'zod'
 
 import type { PageAgentCore } from '../PageAgentCore'
 import { waitFor } from '../utils'
@@ -31,14 +31,13 @@ tools.set(
 	'done',
 	tool({
 		description:
-			'Complete task - provide a summary of results for the user. Set success=True if task completed successfully, false otherwise. Text should be your response to the user summarizing results.',
-		inputSchema: zod.object({
-			text: zod.string(),
-			success: zod.boolean().default(true),
+			'Complete task. Text is your final response to the user — keep it concise unless the user explicitly asks for detail.',
+		inputSchema: z.object({
+			text: z.string(),
+			success: z.boolean().default(true),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			// @note main loop will handle this one
-			// this.onDone(input.text, input.success)
 			return Promise.resolve('Task completed')
 		},
 	})
@@ -47,25 +46,17 @@ tools.set(
 tools.set(
 	'wait',
 	tool({
-		description:
-			'Wait for x seconds. default 1s (max 10 seconds, min 1 second). This can be used to wait until the page or data is fully loaded.',
-		inputSchema: zod.object({
-			seconds: zod.number().min(1).max(10).default(1),
+		description: 'Wait for x seconds. Can be used to wait until the page or data is fully loaded.',
+		inputSchema: z.object({
+			seconds: z.number().min(1).max(10).default(1),
 		}),
 		execute: async function (this: PageAgentCore, input) {
+			// try to subtract LLM calling time from the actual wait time
 			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)
 
-			this.states.totalWaitTime += input.seconds
-
-			if (this.states.totalWaitTime >= 3) {
-				this.pushObservation(
-					`You have waited ${this.states.totalWaitTime} seconds accumulatively. Do NOT wait any longer unless you have a good reason.`
-				)
-			}
-
 			return `✅ Waited for ${input.seconds} seconds.`
 		},
 	})
@@ -76,8 +67,8 @@ tools.set(
 	tool({
 		description:
 			'Ask the user a question and wait for their answer. Use this if you need more information or clarification.',
-		inputSchema: zod.object({
-			question: zod.string(),
+		inputSchema: z.object({
+			question: z.string(),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			if (!this.onAskUser) {
@@ -93,8 +84,8 @@ tools.set(
 	'click_element_by_index',
 	tool({
 		description: 'Click element by index',
-		inputSchema: zod.object({
-			index: zod.int().min(0),
+		inputSchema: z.object({
+			index: z.int().min(0),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.clickElement(input.index)
@@ -106,10 +97,10 @@ tools.set(
 tools.set(
 	'input_text',
 	tool({
-		description: 'Click and input text into a input interactive element',
-		inputSchema: zod.object({
-			index: zod.int().min(0),
-			text: zod.string(),
+		description: 'Click and type text into an interactive input element',
+		inputSchema: z.object({
+			index: z.int().min(0),
+			text: z.string(),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.inputText(input.index, input.text)
@@ -123,9 +114,9 @@ tools.set(
 	tool({
 		description:
 			'Select dropdown option for interactive element index by the text of the option you want to select',
-		inputSchema: zod.object({
-			index: zod.int().min(0),
-			text: zod.string(),
+		inputSchema: z.object({
+			index: z.int().min(0),
+			text: z.string(),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.selectOption(input.index, input.text)
@@ -140,13 +131,12 @@ tools.set(
 tools.set(
 	'scroll',
 	tool({
-		description:
-			'Scroll the page by specified number of pages (set down=True to scroll down, down=False to scroll up, num_pages=number of pages to scroll like 0.5 for half page, 1.0 for one page, etc.). Optional index parameter to scroll within a specific element or its scroll container (works well for dropdowns and custom UI components). Optional pixels parameter to scroll by a specific number of pixels instead of pages.',
-		inputSchema: zod.object({
-			down: zod.boolean().default(true),
-			num_pages: zod.number().min(0).max(10).optional().default(0.1),
-			pixels: zod.number().int().min(0).optional(),
-			index: zod.number().int().min(0).optional(),
+		description: 'Scroll the page vertically. Use index for scroll elements (dropdowns/custom UI).',
+		inputSchema: z.object({
+			down: z.boolean().default(true),
+			num_pages: z.number().min(0).max(10).optional().default(0.1),
+			pixels: z.number().int().min(0).optional(),
+			index: z.number().int().min(0).optional(),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.scroll({
@@ -158,15 +148,18 @@ tools.set(
 	})
 )
 
+/**
+ * @todo Tables need a dedicated parser to extract structured data. This tool is useless.
+ */
 tools.set(
 	'scroll_horizontally',
 	tool({
 		description:
-			'Scroll the page or element horizontally (set right=True to scroll right, right=False to scroll left, pixels=number of pixels to scroll). Optional index parameter to scroll within a specific element or its scroll container (works well for wide tables).',
-		inputSchema: zod.object({
-			right: zod.boolean().default(true),
-			pixels: zod.number().int().min(0),
-			index: zod.number().int().min(0).optional(),
+			'Scroll the page horizontally, or within a specific element by index. Useful for wide tables.',
+		inputSchema: z.object({
+			right: z.boolean().default(true),
+			pixels: z.number().int().min(0),
+			index: z.number().int().min(0).optional(),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.scrollHorizontally(input)
@@ -180,8 +173,8 @@ tools.set(
 	tool({
 		description:
 			'Execute JavaScript code on the current page. Supports async/await syntax. Use with caution!',
-		inputSchema: zod.object({
-			script: zod.string(),
+		inputSchema: z.object({
+			script: z.string(),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			const result = await this.pageController.executeJavascript(input.script)
@@ -190,8 +183,6 @@ tools.set(
 	})
 )
 
-// @todo get_dropdown_options
-// @todo select_dropdown_option
 // @todo send_keys
 // @todo upload_file
 // @todo go_back

packages/core/src/utils/assert.ts

@@ -1,17 +0,0 @@
-import chalk from 'chalk'
-
-/**
- * Simple assertion function that throws an error if the condition is falsy
- * @param condition - The condition to assert
- * @param message - Optional error message
- * @throws Error if condition is falsy
- */
-export function assert(condition: unknown, message?: string, silent?: boolean): asserts condition {
-	if (!condition) {
-		const errorMessage = message ?? 'Assertion failed'
-
-		if (!silent) console.error(chalk.red(`❌ assert: ${errorMessage}`))
-
-		throw new Error(errorMessage)
-	}
-}

packages/core/src/utils/autoFixer.ts

@@ -1,4 +1,8 @@
+import { InvokeError, InvokeErrorType } from '@page-agent/llms'
 import chalk from 'chalk'
+import * as z from 'zod'
+
+import type { PageAgentTool } from '../tools'
 
 /**
  * Normalize LLM response and fix common format issues.
@@ -9,9 +13,10 @@ import chalk from 'chalk'
  * - Arguments wrapped as double JSON string
  * - Nested function call format
  * - Missing action field (fallback to wait)
+ * - Primitive action input for single-field tools (e.g. `{"click_element_by_index": 2}`)
  * - etc.
  */
-export function normalizeResponse(response: any): any {
+export function normalizeResponse(response: any, tools?: Map<string, PageAgentTool>): any {
 	let resolvedArguments = null as any
 
 	const choice = (response as { choices?: Choice[] }).choices?.[0]
@@ -78,6 +83,11 @@ export function normalizeResponse(response: any): any {
 		resolvedArguments.action = safeJsonParse(resolvedArguments.action)
 	}
 
+	// validate and fix action input using tool schemas
+	if (resolvedArguments.action && tools) {
+		resolvedArguments.action = validateAction(resolvedArguments.action, tools)
+	}
+
 	// fix incomplete formats
 	if (!resolvedArguments.action) {
 		console.log(chalk.yellow(`[normalizeResponse] #5: fixing tool_call`))
@@ -108,6 +118,55 @@ export function normalizeResponse(response: any): any {
 	}
 }
 
+/**
+ * Validate action against tool schemas. Provides clear error messages
+ * instead of letting the union schema produce unreadable errors.
+ *
+ * Also coerces primitive inputs for single-field tools:
+ * e.g. `{"click_element_by_index": 2}` → `{"click_element_by_index": {"index": 2}}`
+ */
+function validateAction(action: any, tools: Map<string, PageAgentTool>): any {
+	if (typeof action !== 'object' || action === null) return action
+
+	const toolName = Object.keys(action)[0]
+	if (!toolName) return action
+
+	const tool = tools.get(toolName)
+	if (!tool) {
+		const available = Array.from(tools.keys()).join(', ')
+		throw new InvokeError(
+			InvokeErrorType.INVALID_TOOL_ARGS,
+			`Unknown action "${toolName}". Available: ${available}`
+		)
+	}
+
+	let value = action[toolName]
+	const schema = tool.inputSchema
+
+	// coerce primitive input for single-field tools
+	if (schema instanceof z.ZodObject && value !== null && typeof value !== 'object') {
+		const requiredKey = Object.keys(schema.shape).find(
+			(k) => !(schema.shape as Record<string, z.ZodType>)[k].safeParse(undefined).success
+		)
+		if (requiredKey) {
+			console.log(
+				chalk.yellow(`[normalizeResponse] coercing primitive action input for "${toolName}"`)
+			)
+			value = { [requiredKey]: value }
+		}
+	}
+
+	const result = schema.safeParse(value)
+	if (!result.success) {
+		throw new InvokeError(
+			InvokeErrorType.INVALID_TOOL_ARGS,
+			`Invalid input for action "${toolName}": ${z.prettifyError(result.error)}`
+		)
+	}
+
+	return { [toolName]: result.data }
+}
+
 /**
  * Safely parse JSON, return original input if not json.
  */

packages/core/src/utils/index.ts

@@ -1,27 +1,7 @@
+import chalk from 'chalk'
+
 export { normalizeResponse } from './autoFixer'
 
-/**
- * Wait until condition becomes true
- * @returns Returns when condition becomes true, throws otherwise
- * @param timeout Timeout in milliseconds, default 0 means no timeout, throws error on timeout
- */
-export async function waitUntil(check: () => boolean, timeout = 60 * 60_1000): Promise<boolean> {
-	if (check()) return true
-
-	return new Promise((resolve, reject) => {
-		const start = Date.now()
-		const interval = setInterval(() => {
-			if (check()) {
-				clearInterval(interval)
-				resolve(true)
-			} else if (Date.now() - start > timeout) {
-				clearInterval(interval)
-				reject(new Error('Timeout waiting for condition to become true'))
-			}
-		}, 100)
-	})
-}
-
 export async function waitFor(seconds: number): Promise<void> {
 	await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
 }
@@ -37,15 +17,6 @@ export function truncate(text: string, maxLength: number): string {
 
 //
 
-export function trimLines(text: string): string {
-	return text
-		.split('\n')
-		.map((line) => line.trim())
-		.join('\n')
-}
-
-//
-
 export function randomID(existingIDs?: string[]): string {
 	let id = Math.random().toString(36).substring(2, 11)
 
@@ -85,3 +56,19 @@ export function uid() {
 	ids.push(id)
 	return id
 }
+
+/**
+ * Simple assertion function that throws an error if the condition is falsy
+ * @param condition - The condition to assert
+ * @param message - Optional error message
+ * @throws Error if condition is falsy
+ */
+export function assert(condition: unknown, message?: string, silent?: boolean): asserts condition {
+	if (!condition) {
+		const errorMessage = message ?? 'Assertion failed'
+
+		if (!silent) console.error(chalk.red(`❌ assert: ${errorMessage}`))
+
+		throw new Error(errorMessage)
+	}
+}

packages/extension/PRIVACY.md

@@ -1,57 +1,5 @@
 # Privacy Policy for Page Agent Extension
 
-**Last updated:** January 2026
+This document has moved. Please see our full **[Terms of Use & Privacy](../../docs/terms-and-privacy.md)**.
 
-## Overview
-
-Page Agent Extension is a browser automation tool that uses AI to help you interact with web pages. This policy explains what data is processed and under what circumstances.
-
-## Data Processing
-
-### Local Processing
-
-The extension performs DOM analysis and automation actions **locally in your browser**. Your browsing history, passwords, and form data are not accessed or collected by the extension itself.
-
-### Data Transmission
-
-Data is transmitted to external servers **only when you initiate an automation task**. When this occurs:
-
-- Your task instructions (natural language commands)
-- Sanitized page structure (simplified DOM, excluding sensitive form values)
-
-are sent to the LLM API endpoint configured in **your settings**.
-
-**If you configure a third-party LLM provider** (e.g., OpenAI, Anthropic, or others), data is sent directly to that provider. Their privacy policies apply.
-
-**If you use our testing endpoint**, your requests are proxied to [DeepSeek](https://deepseek.com) for AI processing. Regarding this test endpoint:
-
-- This endpoint is provided for evaluation purposes only and is not recommended for production or daily use
-- We do **not** store your task content, page content, or visited URLs
-- Minimal logging (timestamps, request metadata, IP addresses) may occur for abuse prevention and service stability
-- DeepSeek's [Privacy Policy](https://cdn.deepseek.com/policies/en-US/deepseek-privacy-policy.html) applies to their processing of your requests
-
-## Data Storage
-
-- **Local storage only**: Your configuration (API endpoint, API key, model selection) is stored in your browser via `chrome.storage.local`
-- **No cloud sync**: Configuration is not synced to any external server
-- **No analytics**: The extension does not include any analytics or tracking code
-
-## Your Control
-
-- The extension is open source and can be audited by anyone
-- You choose which LLM provider to use
-- You may configure your own API endpoint at any time
-- You can clear all stored data by removing the extension
-
-## Changes to This Policy
-
-We may update this policy as the extension evolves. Significant changes will be noted in the extension's release notes.
-
-## Contact
-
-For questions about this privacy policy:
-https://github.com/alibaba/page-agent/issues
-
----
-
-Source code: https://github.com/alibaba/page-agent
+Online: https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md

packages/extension/components.json

@@ -5,7 +5,7 @@
     "tsx": true,
     "tailwind": {
         "config": "",
-        "css": "src/index.css",
+        "css": "src/assets/index.css",
         "baseColor": "neutral",
         "cssVariables": true,
         "prefix": ""
@@ -16,7 +16,7 @@
         "utils": "@/lib/utils",
         "ui": "@/components/ui",
         "lib": "@/lib",
-        "hooks": "@/hooks"
+        "hooks": "@/lib/hooks"
     },
     "registries": {
         "@magicui": "https://magicui.design/r/{name}.json"

packages/extension/docs/extension_api.md

@@ -0,0 +1,226 @@
+# Page Agent Extension API
+
+Integrate the Page Agent extension into your web app and trigger multi-page browser tasks from page JavaScript.
+
+## Installation
+
+### 1. Install the browser extension
+
+Primary channel:
+
+- Chrome Web Store: https://chromewebstore.google.com/detail/page-agent-ext/akldabonmimlicnjlflnapfeklbfemhj
+
+Latest updates are often published earlier on:
+
+- GitHub Releases: https://github.com/alibaba/page-agent/releases
+
+### 2. Install type definitions (recommended)
+
+```bash
+npm install @page-agent/core --save-dev
+```
+
+### 3. Authorization (Token)
+
+The token allows your page JS to call the extension API (`window.PAGE_AGENT_EXT`) and execute multi-page tasks.
+
+Why token-based access is required:
+
+- The extension has broad browser permissions (page access, navigation, multi-tab control).
+- If abused, it can harm user privacy and security.
+- Users must explicitly provide the token only to applications they trust.
+
+Setup:
+
+1. Open the extension side panel and copy your auth token.
+2. Set the token in your page:
+
+```typescript
+localStorage.setItem('PageAgentExtUserAuthToken', 'your-token')
+```
+
+## Quick Start
+
+```typescript
+import type {
+  AgentActivity,
+  AgentStatus,
+  ExecutionResult,
+  HistoricalEvent,
+} from '@page-agent/core'
+
+// Wait for extension injection (up to 1 second)
+async function waitForExtension(timeout = 1000): Promise<boolean> {
+  const start = Date.now()
+  while (Date.now() - start < timeout) {
+    if (window.PAGE_AGENT_EXT) return true
+    await new Promise((r) => setTimeout(r, 100))
+  }
+  return false
+}
+
+// Usage
+if (await waitForExtension()) {
+  const result = await window.PAGE_AGENT_EXT!.execute('Click the login button', {
+    baseURL: 'https://api.openai.com/v1',
+    apiKey: 'your-api-key',
+    model: 'gpt-5.2',
+    onStatusChange: (status) => console.log('Status:', status),
+    onActivity: (activity) => console.log('Activity:', activity),
+  })
+  console.log('Result:', result)
+}
+```
+
+## Global API
+
+After token match, the extension injects APIs into `window`.
+
+### `window.PAGE_AGENT_EXT_VERSION`
+
+Extension version string (for capability checks before using the main API).
+
+### `window.PAGE_AGENT_EXT`
+
+Main namespace object.
+
+#### `PAGE_AGENT_EXT.execute(task, config)`
+
+Execute one agent task.
+
+Parameters:
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `task` | `string` | Yes | Task description |
+| `config` | `ExecuteConfig` | Yes | LLM settings, options, and callbacks |
+
+Returns: `Promise<ExecutionResult>`
+
+#### `PAGE_AGENT_EXT.stop()`
+
+Stop the current task.
+
+## Types
+
+Install `@page-agent/core` for complete types:
+
+```typescript
+import type {
+  AgentActivity,
+  AgentStatus,
+  ExecutionResult,
+  HistoricalEvent,
+} from '@page-agent/core'
+
+export interface ExecuteConfig {
+  baseURL: string
+  apiKey: string
+  model: string
+
+  // Include the initial tab where page JS starts. Default: true.
+  includeInitialTab?: boolean
+
+  onStatusChange?: (status: AgentStatus) => void
+  onActivity?: (activity: AgentActivity) => void
+  onHistoryUpdate?: (history: HistoricalEvent[]) => void
+}
+
+export type Execute = (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
+```
+
+`AgentStatus`
+
+```typescript
+type AgentStatus = 'idle' | 'running' | 'completed' | 'error'
+```
+
+`AgentActivity`
+
+```typescript
+type AgentActivity =
+  | { type: 'thinking' }
+  | { type: 'executing'; tool: string; input: unknown }
+  | { type: 'executed'; tool: string; input: unknown; output: string; duration: number }
+  | { type: 'retrying'; attempt: number; maxAttempts: number }
+  | { type: 'error'; message: string }
+```
+
+`HistoricalEvent`
+
+```typescript
+type HistoricalEvent =
+  | { type: 'step'; stepIndex: number; reflection: AgentReflection; action: Action }
+  | { type: 'observation'; content: string }
+  | { type: 'user_takeover' }
+  | { type: 'retry'; message: string; attempt: number; maxAttempts: number }
+  | { type: 'error'; message: string; rawResponse?: unknown }
+```
+
+`ExecutionResult`
+
+```typescript
+interface ExecutionResult {
+  success: boolean
+  data: string
+  history: HistoricalEvent[]
+}
+```
+
+## Usage Examples
+
+### Basic Execution
+
+```typescript
+const result = await window.PAGE_AGENT_EXT!.execute(
+  'Fill in the email field with test@example.com and click Submit',
+  {
+    baseURL: 'https://api.openai.com/v1',
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: 'gpt-5.2',
+    includeInitialTab: false, // Optional: exclude current tab
+    onStatusChange: (status) => console.log(status),
+    onActivity: (activity) => console.log(activity),
+  }
+)
+```
+
+### Stop the Current Task
+
+```typescript
+window.PAGE_AGENT_EXT!.stop()
+```
+
+## Window Type Declaration
+
+If you are not importing `@page-agent/core`, add:
+
+```typescript
+import type {
+  AgentActivity,
+  AgentStatus,
+  ExecutionResult,
+  HistoricalEvent,
+} from '@page-agent/core'
+
+interface ExecuteConfig {
+  baseURL: string
+  apiKey: string
+  model: string
+  includeInitialTab?: boolean
+  onStatusChange?: (status: AgentStatus) => void
+  onActivity?: (activity: AgentActivity) => void
+  onHistoryUpdate?: (history: HistoricalEvent[]) => void
+}
+
+declare global {
+  interface Window {
+    PAGE_AGENT_EXT_VERSION?: string
+    PAGE_AGENT_EXT?: {
+      version: string
+      execute: Execute
+      stop: () => void
+    }
+  }
+}
+```

packages/extension/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@page-agent/ext",
     "private": true,
-    "version": "0.1.0-b3",
+    "version": "0.1.8",
     "type": "module",
     "scripts": {
         "dev": "wxt",
@@ -10,27 +10,6 @@
         "postinstall": "wxt prepare"
     },
     "devDependencies": {
-        "@tailwindcss/vite": "^4.1.18",
-        "@types/chrome": "^0.1.34",
-        "@types/react": "^19.2.8",
-        "@types/react-dom": "^19.2.1",
-        "@vitejs/plugin-react-swc": "^4.1.0",
-        "@wxt-dev/module-react": "^1.1.5",
-        "i18next": "^25.7.4",
-        "i18next-browser-languagedetector": "^8.2.0",
-        "react": "^19.2.4",
-        "react-dom": "^19.2.4",
-        "react-i18next": "^16.5.2",
-        "tailwindcss": "^4.1.14",
-        "tw-animate-css": "^1.4.0",
-        "wouter": "^3.9.0",
-        "wxt": "^0.20.13"
-    },
-    "dependencies": {
-        "@page-agent/core": "1.0.0",
-        "@page-agent/llms": "1.0.0",
-        "@page-agent/page-controller": "1.0.0",
-        "@page-agent/ui": "1.0.0",
         "@radix-ui/react-hover-card": "^1.1.15",
         "@radix-ui/react-icons": "^1.3.2",
         "@radix-ui/react-label": "^2.1.8",
@@ -38,14 +17,33 @@
         "@radix-ui/react-slot": "^1.2.4",
         "@radix-ui/react-switch": "^1.2.6",
         "@radix-ui/react-tooltip": "^1.2.8",
+        "@types/chrome": "^0.1.37",
+        "@types/react": "^19.2.14",
+        "@types/react-dom": "^19.2.1",
+        "@wxt-dev/module-react": "^1.1.5",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
-        "lucide-react": "^0.563.0",
-        "motion": "^12.29.2",
+        "idb": "^8.0.3",
+        "lucide-react": "^0.575.0",
+        "motion": "^12.34.3",
         "next-themes": "^0.4.6",
+        "react": "^19.2.4",
+        "react-dom": "^19.2.4",
         "rough-notation": "^0.5.1",
-        "simple-icons": "^16.5.0",
+        "simple-icons": "^16.9.0",
         "sonner": "^2.0.7",
-        "tailwind-merge": "^3.4.0"
+        "tailwind-merge": "^3.5.0",
+        "tailwindcss": "^4.1.14",
+        "tw-animate-css": "^1.4.0",
+        "wxt": "^0.20.18"
+    },
+    "dependencies": {
+        "@page-agent/core": "1.4.2",
+        "@page-agent/llms": "1.4.2",
+        "@page-agent/page-controller": "1.4.2",
+        "@page-agent/ui": "1.4.2",
+        "ai-motion": "^0.4.8",
+        "chalk": "^5.6.2",
+        "zod": "^4.3.5"
     }
 }

packages/extension/public/_locales/en/messages.json

@@ -0,0 +1,11 @@
+{
+	"extName": {
+		"message": "Page Agent Ext"
+	},
+	"extDescription": {
+		"message": "AI-powered browser automation assistant. Control web pages with natural language."
+	},
+	"extActionTitle": {
+		"message": "Open Page Agent"
+	}
+}

packages/extension/public/_locales/zh_CN/messages.json

@@ -0,0 +1,11 @@
+{
+	"extName": {
+		"message": "Page Agent Ext"
+	},
+	"extDescription": {
+		"message": "AI 驱动的浏览器自动化助手，用自然语言控制网页。"
+	},
+	"extActionTitle": {
+		"message": "打开 Page Agent"
+	}
+}

packages/extension/src/agent/MultiPageAgent.ts

@@ -5,20 +5,58 @@ import { TabsController } from './TabsController'
 import SYSTEM_PROMPT from './system_prompt.md?raw'
 import { createTabTools } from './tabTools'
 
+/** Detect user language from browser settings */
+function detectLanguage(): 'en-US' | 'zh-CN' {
+	const lang = navigator.language || navigator.languages?.[0] || 'en-US'
+	return lang.startsWith('zh') ? 'zh-CN' : 'en-US'
+}
+
+/**
+ * MultiPageAgent
+ * - use with extension
+ * - can be used from a side panel or a content script
+ */
 export class MultiPageAgent extends PageAgentCore {
-	constructor(config: Omit<PageAgentConfig, 'pageController'>) {
+	constructor(config: Omit<PageAgentConfig, 'pageController'> & { includeInitialTab?: boolean }) {
+		// multi page controller
 		const tabsController = new TabsController()
 		const pageController = new RemotePageController(tabsController)
 		const customTools = createTabTools(tabsController)
 
+		// system prompt - auto-detect language if not specified
+		const language = config.language ?? detectLanguage()
+		const targetLanguage = language === 'zh-CN' ? '中文' : 'English'
+		const systemPrompt = SYSTEM_PROMPT.replace(
+			/Default working language: \*\*.*?\*\*/,
+			`Default working language: **${targetLanguage}**`
+		)
+
+		// include initial tab for controlling
+		const includeInitialTab = config.includeInitialTab ?? true
+
+		/**
+		 * When the agent is in side-panel and user closed the side-panel.
+		 * There is no chance for isAgentRunning to be set false.
+		 * (unload event doesn't work well in side panel.)
+		 * (I'm trying not to use long-lived connection because the lifecycle of a sw is hard to predict.)
+		 * This heartbeat mechanism acts as a backup.
+		 */
+		let heartBeatInterval: null | number = null
+
 		super({
 			...config,
 			pageController: pageController as any,
 			customTools: customTools,
-			customSystemPrompt: SYSTEM_PROMPT,
+			customSystemPrompt: systemPrompt,
 
 			onBeforeTask: async (agent) => {
-				await tabsController.init(agent.task)
+				await tabsController.init(agent.task, includeInitialTab)
+
+				heartBeatInterval = window.setInterval(() => {
+					chrome.storage.local.set({
+						agentHeartbeat: Date.now(),
+					})
+				}, 1_000)
 
 				await chrome.storage.local.set({
 					isAgentRunning: true,
@@ -26,18 +64,32 @@ export class MultiPageAgent extends PageAgentCore {
 			},
 
 			onAfterTask: async () => {
+				if (heartBeatInterval) {
+					window.clearInterval(heartBeatInterval)
+					heartBeatInterval = null
+				}
+
 				await chrome.storage.local.set({
 					isAgentRunning: false,
 				})
 			},
 
+			onBeforeStep: async (agent) => {
+				// make sure the current tab is loaded before the step starts
+				await tabsController.waitUntilTabLoaded(tabsController.currentTabId!)
+			},
+
 			onDispose: () => {
+				if (heartBeatInterval) {
+					window.clearInterval(heartBeatInterval)
+					heartBeatInterval = null
+				}
+
 				chrome.storage.local.set({
 					isAgentRunning: false,
 				})
 
-				// no need to dispose tabsController and pageController
-				// as they do not keep references
+				tabsController.dispose()
 			},
 		})
 	}

packages/extension/src/agent/RemotePageController.background.ts

@@ -8,13 +8,21 @@ export function handlePageControlMessage(
 	sender: chrome.runtime.MessageSender,
 	sendResponse: (response: unknown) => void
 ): true | undefined {
+	const PREFIX = '[RemotePageController.background]'
+
+	function debug(...messages: any[]) {
+		console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
+	}
+
 	const { action, payload, targetTabId } = message
 
 	if (action === 'get_my_tab_id') {
+		debug('get_my_tab_id', sender.tab?.id)
 		sendResponse({ tabId: sender.tab?.id || null })
 		return
 	}
 
+	// proxy to content script
 	chrome.tabs
 		.sendMessage(targetTabId, {
 			type: 'PAGE_CONTROL',
@@ -25,6 +33,7 @@ export function handlePageControlMessage(
 			sendResponse(result)
 		})
 		.catch((error) => {
+			console.error(PREFIX, error)
 			sendResponse({
 				success: false,
 				error: error instanceof Error ? error.message : String(error),

packages/extension/src/agent/RemotePageController.content.ts

@@ -12,26 +12,27 @@ export function initPageController() {
 		.then((response) => {
 			return (response as { tabId: number | null }).tabId
 		})
+		.catch((error) => {
+			console.error('[RemotePageController.ContentScript]: Failed to get my tab id', error)
+			return null
+		})
 
 	function getPC(): PageController {
 		if (!pageController) {
-			pageController = new PageController({ enableMask: false })
+			pageController = new PageController({ enableMask: false, viewportExpansion: 400 })
 		}
 		return pageController
 	}
 
 	intervalID = window.setInterval(async () => {
+		const agentHeartbeat = (await chrome.storage.local.get('agentHeartbeat')).agentHeartbeat
+		const now = Date.now()
+		const agentInTouch = typeof agentHeartbeat === 'number' && now - agentHeartbeat < 2_000
+
 		const isAgentRunning = (await chrome.storage.local.get('isAgentRunning')).isAgentRunning
 		const currentTabId = (await chrome.storage.local.get('currentTabId')).currentTabId
 
-		const shouldShowMask = isAgentRunning && currentTabId === (await myTabIdPromise)
-
-		// console.log('[RemotePageController] polling:', {
-		// 	isAgentRunning,
-		// 	currentTabId,
-		// 	myTabId: await myTabIdPromise,
-		// 	shouldShowMask,
-		// })
+		const shouldShowMask = isAgentRunning && agentInTouch && currentTabId === (await myTabIdPromise)
 
 		if (shouldShowMask) {
 			const pc = getPC()
@@ -45,13 +46,13 @@ export function initPageController() {
 			}
 		}
 
-		if (!isAgentRunning) {
+		if (!isAgentRunning && agentInTouch) {
 			if (pageController) {
 				pageController.dispose()
 				pageController = null
 			}
 		}
-	}, 1_000)
+	}, 500)
 
 	chrome.runtime.onMessage.addListener((message, sender, sendResponse): true | undefined => {
 		if (message.type !== 'PAGE_CONTROL') {

packages/extension/src/agent/RemotePageController.ts

@@ -2,13 +2,31 @@ import type { BrowserState } from '@page-agent/page-controller'
 
 import type { TabsController } from './TabsController'
 
+const PREFIX = '[RemotePageController]'
+
+function debug(...messages: any[]) {
+	console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
+}
+
+function sendMessage(message: {
+	type: 'PAGE_CONTROL'
+	action: string
+	targetTabId: number
+	payload?: any
+}): Promise<any> {
+	return chrome.runtime.sendMessage(message).catch((error) => {
+		console.error(PREFIX, message.action, error)
+		return null
+	})
+}
+
 /**
  * Agent side page controller.
  * - live in the agent env (extension page or content script)
  * - communicates with remote PageController via sw
  */
 export class RemotePageController {
-	private tabsController: TabsController
+	tabsController: TabsController
 
 	constructor(tabsController: TabsController) {
 		this.tabsController = tabsController
@@ -18,46 +36,46 @@ export class RemotePageController {
 		return this.tabsController.currentTabId
 	}
 
-	async getCurrentUrl(): Promise<string> {
+	private async getCurrentUrl(): Promise<string> {
 		if (!this.currentTabId) return ''
 		const { url } = await this.tabsController.getTabInfo(this.currentTabId)
 		return url || ''
 	}
 
-	async getCurrentTitle(): Promise<string> {
+	private async getCurrentTitle(): Promise<string> {
 		if (!this.currentTabId) return ''
 		const { title } = await this.tabsController.getTabInfo(this.currentTabId)
 		return title || ''
 	}
 
-	get currentTabTitle(): Promise<string> {
-		return this.getCurrentTitle()
-	}
-
 	async getLastUpdateTime(): Promise<number> {
 		if (!this.currentTabId) throw new Error('tabsController not initialized.')
-
-		return await chrome.runtime.sendMessage({
+		return sendMessage({
 			type: 'PAGE_CONTROL',
 			action: 'get_last_update_time',
 			targetTabId: this.currentTabId,
 		})
 	}
 
-	// getBrowserState
 	async getBrowserState(): Promise<BrowserState> {
-		let browserState = {} as BrowserState
+		if (!this.currentTabId) throw new Error('tabsController not initialized.')
 
-		if (!this.currentTabId || !isContentScriptAllowed(await this.currentTabUrl)) {
+		let browserState = {} as BrowserState
+		debug('getBrowserState', this.currentTabId)
+
+		const currentUrl = await this.getCurrentUrl()
+		const currentTitle = await this.getCurrentTitle()
+
+		if (!this.currentTabId || !isContentScriptAllowed(currentUrl)) {
 			browserState = {
-				url: await this.currentTabUrl,
-				title: await this.currentTabTitle,
+				url: currentUrl,
+				title: currentTitle,
 				header: '',
-				content: '(empty page)',
+				content: '(empty page. either current page is not readable or not loaded yet.)',
 				footer: '',
 			}
 		} else {
-			browserState = await chrome.runtime.sendMessage({
+			browserState = await sendMessage({
 				type: 'PAGE_CONTROL',
 				action: 'get_browser_state',
 				targetTabId: this.currentTabId,
@@ -67,61 +85,58 @@ export class RemotePageController {
 		const sum = await this.tabsController.summarizeTabs()
 		browserState.header = sum + '\n\n' + (browserState.header || '')
 
+		debug('getBrowserState: success', this.currentTabId, browserState)
+
 		return browserState
 	}
 
-	// updateTree
 	async updateTree(): Promise<void> {
-		if (!this.currentTabId || !isContentScriptAllowed(await this.currentTabUrl)) {
+		if (!this.currentTabId || !isContentScriptAllowed(await this.getCurrentUrl())) {
 			return
 		}
 
-		await chrome.runtime.sendMessage({
+		await sendMessage({
 			type: 'PAGE_CONTROL',
 			action: 'update_tree',
 			targetTabId: this.currentTabId,
 		})
 	}
 
-	// cleanUpHighlights
 	async cleanUpHighlights(): Promise<void> {
-		if (!this.currentTabId || !isContentScriptAllowed(await this.currentTabUrl)) {
+		if (!this.currentTabId || !isContentScriptAllowed(await this.getCurrentUrl())) {
 			return
 		}
 
-		await chrome.runtime.sendMessage({
+		await sendMessage({
 			type: 'PAGE_CONTROL',
 			action: 'clean_up_highlights',
 			targetTabId: this.currentTabId,
 		})
 	}
 
-	// clickElement
 	async clickElement(...args: any[]): Promise<DomActionReturn> {
-		return this.remoteCallDomAction('click_element', args)
+		const res = await this.remoteCallDomAction('click_element', args)
+		// @note may cause page navigation, wait for 1 second to ensure the page loading started
+		await new Promise((resolve) => setTimeout(resolve, 1000))
+		return res
 	}
 
-	// inputText
 	async inputText(...args: any[]): Promise<DomActionReturn> {
 		return this.remoteCallDomAction('input_text', args)
 	}
 
-	// selectOption
 	async selectOption(...args: any[]): Promise<DomActionReturn> {
 		return this.remoteCallDomAction('select_option', args)
 	}
 
-	// scroll
 	async scroll(...args: any[]): Promise<DomActionReturn> {
 		return this.remoteCallDomAction('scroll', args)
 	}
 
-	// scrollHorizontally
 	async scrollHorizontally(...args: any[]): Promise<DomActionReturn> {
 		return this.remoteCallDomAction('scroll_horizontally', args)
 	}
 
-	// executeJavascript
 	async executeJavascript(...args: any[]): Promise<DomActionReturn> {
 		return this.remoteCallDomAction('execute_javascript', args)
 	}
@@ -133,35 +148,26 @@ export class RemotePageController {
 	/** @note Managed by content script via storage polling. */
 	dispose(): void {}
 
-	private async preCheck() {
-		if (!this.currentTabId) {
-			return 'RemotePageController not initialized.'
-		}
-
-		if (!isContentScriptAllowed(await this.currentTabUrl)) {
-			return 'Operation not allowed on this page. Use open_new_tab to navigate to a web page first.'
-		}
-
-		return null
-	}
-
 	private async remoteCallDomAction(action: string, payload: any[]): Promise<DomActionReturn> {
-		const preCheckError = await this.preCheck()
-		if (preCheckError) {
-			return { success: false, message: preCheckError }
+		if (!this.currentTabId) {
+			return { success: false, message: 'RemotePageController not initialized.' }
 		}
 
-		return await chrome.runtime.sendMessage({
+		if (!isContentScriptAllowed(await this.getCurrentUrl())) {
+			return {
+				success: false,
+				message:
+					'Operation not allowed on this page. Use open_new_tab to navigate to a web page first.',
+			}
+		}
+
+		return sendMessage({
 			type: 'PAGE_CONTROL',
 			action: action,
 			targetTabId: this.currentTabId!,
 			payload,
 		})
 	}
-
-	private get currentTabUrl(): Promise<string> {
-		return this.getCurrentUrl()
-	}
 }
 
 interface DomActionReturn {

packages/extension/src/agent/TabsController.background.ts

@@ -3,6 +3,12 @@
  */
 import type { TabAction } from './TabsController'
 
+const PREFIX = '[TabsController.background]'
+
+function debug(...messages: any[]) {
+	console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
+}
+
 export function handleTabControlMessage(
 	message: { type: 'TAB_CONTROL'; action: TabAction; payload: any },
 	sender: chrome.runtime.MessageSender,
@@ -12,10 +18,12 @@ export function handleTabControlMessage(
 
 	switch (action as TabAction) {
 		case 'get_active_tab': {
+			debug('get_active_tab')
 			chrome.tabs
 				.query({ active: true, currentWindow: true })
 				.then((tabs) => {
 					const tabId = tabs.length > 0 ? tabs[0].id || null : null
+					debug('get_active_tab: success', tabId)
 					sendResponse({ success: true, tabId })
 				})
 				.catch((error) => {
@@ -25,11 +33,12 @@ export function handleTabControlMessage(
 		}
 
 		case 'get_tab_info': {
+			debug('get_tab_info', payload)
 			chrome.tabs
 				.get(payload.tabId)
 				.then((tab) => {
-					const result = { title: tab.title || '', url: tab.url || '' }
-					sendResponse(result)
+					debug('get_tab_info: success', tab)
+					sendResponse(tab)
 				})
 				.catch((error) => {
 					sendResponse({ error: error instanceof Error ? error.message : String(error) })
@@ -38,10 +47,11 @@ export function handleTabControlMessage(
 		}
 
 		case 'open_new_tab': {
+			debug('open_new_tab', payload)
 			chrome.tabs
 				.create({ url: payload.url, active: false })
 				.then((newTab) => {
-					// @todo: wait for tab to be fully loaded
+					debug('open_new_tab: success', newTab)
 					sendResponse({ success: true, tabId: newTab.id, windowId: newTab.windowId })
 				})
 				.catch((error) => {
@@ -51,20 +61,22 @@ export function handleTabControlMessage(
 		}
 
 		case 'create_tab_group': {
+			debug('create_tab_group', payload)
 			chrome.tabs
 				.group({ tabIds: payload.tabIds, createProperties: { windowId: payload.windowId } })
 				.then((groupId) => {
-					console.log('Created tab group', groupId)
+					debug('create_tab_group: success', groupId)
 					sendResponse({ success: true, groupId })
 				})
 				.catch((error) => {
-					console.error('Failed to create tab group', error)
+					console.error(PREFIX, 'Failed to create tab group', error)
 					sendResponse({ error: error instanceof Error ? error.message : String(error) })
 				})
 			return true // async response
 		}
 
 		case 'update_tab_group': {
+			debug('update_tab_group', payload)
 			chrome.tabGroups
 				.update(payload.groupId, payload.properties)
 				.then(() => {
@@ -77,6 +89,7 @@ export function handleTabControlMessage(
 		}
 
 		case 'add_tab_to_group': {
+			debug('add_tab_to_group', payload)
 			chrome.tabs
 				.group({ tabIds: payload.tabId, groupId: payload.groupId })
 				.then(() => {
@@ -89,6 +102,7 @@ export function handleTabControlMessage(
 		}
 
 		case 'close_tab': {
+			debug('close_tab', payload)
 			chrome.tabs
 				.remove(payload.tabId)
 				.then(() => {
@@ -105,3 +119,42 @@ export function handleTabControlMessage(
 			return
 	}
 }
+
+export function setupTabChangeEvents() {
+	console.log('[TabsController.background] setupTabChangeEvents')
+
+	chrome.tabs.onCreated.addListener((tab) => {
+		debug('onCreated', tab)
+		chrome.runtime
+			.sendMessage({ type: 'TAB_CHANGE', action: 'created', payload: { tab } })
+			.catch((error) => {
+				debug('onCreated error:', error)
+			})
+	})
+
+	chrome.tabs.onRemoved.addListener((tabId, removeInfo) => {
+		debug('onRemoved', tabId, removeInfo)
+		chrome.runtime
+			.sendMessage({
+				type: 'TAB_CHANGE',
+				action: 'removed',
+				payload: { tabId, removeInfo },
+			})
+			.catch((error) => {
+				debug('onRemoved error:', error)
+			})
+	})
+
+	chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
+		debug('onUpdated', tabId, changeInfo)
+		chrome.runtime
+			.sendMessage({
+				type: 'TAB_CHANGE',
+				action: 'updated',
+				payload: { tabId, changeInfo, tab },
+			})
+			.catch((error) => {
+				debug('onUpdated error:', error)
+			})
+	})
+}

packages/extension/src/agent/TabsController.ts

@@ -1,3 +1,20 @@
+const PREFIX = '[TabsController]'
+
+function debug(...messages: any[]) {
+	console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
+}
+
+function sendMessage(message: {
+	type: 'TAB_CONTROL'
+	action: TabAction
+	payload?: any
+}): Promise<any> {
+	return chrome.runtime.sendMessage(message).catch((error) => {
+		console.error(PREFIX, message.action, error)
+		return null
+	})
+}
+
 /**
  * Controller for managing browser tabs.
  * - live in the agent env (extension page or content script)
@@ -12,7 +29,9 @@ export class TabsController extends EventTarget {
 	private task: string = ''
 	private windowId: number | null = null
 
-	async init(task: string) {
+	async init(task: string, includeInitialTab: boolean = true) {
+		debug('init', task, includeInitialTab)
+
 		this.task = task
 		this.tabs = []
 		this.currentTabId = null
@@ -20,23 +39,36 @@ export class TabsController extends EventTarget {
 		this.initialTabId = null
 		this.windowId = null
 
-		const result = await chrome.runtime.sendMessage({
+		const result = await sendMessage({
 			type: 'TAB_CONTROL',
 			action: 'get_active_tab',
 		})
 
 		this.initialTabId = result.tabId
-		this.currentTabId = result.tabId
-
-		this.tabs.push({
-			id: result.tabId,
-			isInitial: true,
-		})
 
 		if (!this.initialTabId) {
 			throw new Error('Failed to get initial tab ID')
 		}
 
+		if (includeInitialTab) {
+			this.currentTabId = this.initialTabId
+
+			// update tab status immediately
+			const info = await sendMessage({
+				type: 'TAB_CONTROL',
+				action: 'get_tab_info',
+				payload: { tabId: this.initialTabId },
+			})
+
+			this.tabs.push({
+				id: result.tabId,
+				isInitial: true,
+				url: info.url,
+				title: info.title,
+				status: info.status,
+			})
+		}
+
 		await this.updateCurrentTabId(this.currentTabId)
 
 		const tabChangeHandler = (message: any): void => {
@@ -68,6 +100,14 @@ export class TabsController extends EventTarget {
 						}
 					}
 				}
+			} else if (message.action === 'updated') {
+				const { tabId, tab } = message.payload as { tabId: number; tab: chrome.tabs.Tab }
+				const targetTab = this.tabs.find((t) => t.id === tabId)
+				if (targetTab) {
+					targetTab.url = tab.url
+					targetTab.title = tab.title
+					targetTab.status = tab.status
+				}
 			}
 		}
 
@@ -78,8 +118,10 @@ export class TabsController extends EventTarget {
 		})
 	}
 
-	async openNewTab(url: string): Promise<{ success: boolean; tabId: number; message: string }> {
-		const result = await chrome.runtime.sendMessage({
+	async openNewTab(url: string): Promise<string> {
+		debug('openNewTab', url)
+
+		const result = await sendMessage({
 			type: 'TAB_CONTROL',
 			action: 'open_new_tab',
 			payload: { url },
@@ -102,7 +144,7 @@ export class TabsController extends EventTarget {
 		await this.switchToTab(tabId)
 
 		if (!this.tabGroupId) {
-			const result = await chrome.runtime.sendMessage({
+			const result = await sendMessage({
 				type: 'TAB_CONTROL',
 				action: 'create_tab_group',
 				payload: { tabIds: [tabId], windowId: this.windowId },
@@ -116,7 +158,7 @@ export class TabsController extends EventTarget {
 
 			this.tabGroupId = groupId
 
-			await chrome.runtime.sendMessage({
+			await sendMessage({
 				type: 'TAB_CONTROL',
 				action: 'update_tab_group',
 				payload: {
@@ -129,57 +171,43 @@ export class TabsController extends EventTarget {
 				},
 			})
 		} else {
-			await chrome.runtime.sendMessage({
+			await sendMessage({
 				type: 'TAB_CONTROL',
 				action: 'add_tab_to_group',
 				payload: { tabId: result.tabId, groupId: this.tabGroupId },
 			})
 		}
 
-		// wait for the new tab to be fully loaded
-		// @todo
-		await new Promise((resolve) => setTimeout(resolve, 500))
+		await this.waitUntilTabLoaded(tabId)
 
-		return {
-			success: true,
-			tabId,
-			message: `Opened new tab ID ${tabId} with URL ${url}`,
-		}
+		return `✅ Opened new tab ID ${tabId} with URL ${url}`
 	}
 
-	async switchToTab(tabId: number): Promise<{ success: boolean; message: string }> {
+	async switchToTab(tabId: number): Promise<string> {
+		debug('switchToTab', tabId)
+
 		const targetTab = this.tabs.find((t) => t.id === tabId)
 		if (!targetTab) {
-			return {
-				success: false,
-				message: `Tab ID ${tabId} not found in tab list.`,
-			}
+			throw new Error(`Tab ID ${tabId} not found in tab list.`)
 		}
 
 		await this.updateCurrentTabId(tabId)
 
-		return {
-			success: true,
-			message: `Switched to tab ID ${tabId}.`,
-		}
+		return `✅ Switched to tab ID ${tabId}.`
 	}
 
-	async closeTab(tabId: number): Promise<{ success: boolean; message: string }> {
+	async closeTab(tabId: number): Promise<string> {
+		debug('closeTab', tabId)
+
 		const targetTab = this.tabs.find((t) => t.id === tabId)
 		if (!targetTab) {
-			return {
-				success: false,
-				message: `Tab ID ${tabId} not found in tab list.`,
-			}
+			throw new Error(`Tab ID ${tabId} not found in tab list.`)
 		}
 		if (targetTab.isInitial) {
-			return {
-				success: false,
-				message: `Cannot close the initial tab ID ${tabId}.`,
-			}
+			throw new Error(`Cannot close the initial tab ID ${tabId}.`)
 		}
 
-		const result = await chrome.runtime.sendMessage({
+		const result = await sendMessage({
 			type: 'TAB_CONTROL',
 			action: 'close_tab',
 			payload: { tabId },
@@ -196,29 +224,39 @@ export class TabsController extends EventTarget {
 				}
 			}
 
-			return {
-				success: true,
-				message: `Closed tab ID ${tabId}.`,
-			}
+			return `✅ Closed tab ID ${tabId}.`
 		} else {
-			return {
-				success: false,
-				message: `Failed to close tab ID ${tabId}: ${result.error}`,
-			}
+			throw new Error(`Failed to close tab ID ${tabId}: ${result.error}`)
 		}
 	}
 
 	async updateCurrentTabId(tabId: number | null) {
+		debug('updateCurrentTabId', tabId)
+
 		this.currentTabId = tabId
 		await chrome.storage.local.set({ currentTabId: tabId })
 	}
 
 	async getTabInfo(tabId: number): Promise<{ title: string; url: string }> {
-		const result = await chrome.runtime.sendMessage({
+		// use cached tab info if available
+		const tabMeta = this.tabs.find((t) => t.id === tabId)
+		if (tabMeta && tabMeta.url && tabMeta.title) {
+			return { title: tabMeta.title, url: tabMeta.url }
+		}
+
+		// otherwise, pull the latest tab info from the background script
+		debug('getTabInfo: pulling from background script', tabId)
+		const result = await sendMessage({
 			type: 'TAB_CONTROL',
 			action: 'get_tab_info',
 			payload: { tabId },
 		})
+
+		if (tabMeta) {
+			tabMeta.url = result.url
+			tabMeta.title = result.title
+		}
+
 		return result
 	}
 
@@ -230,9 +268,24 @@ export class TabsController extends EventTarget {
 				`| ${tab.id} | ${url} | ${title} | ${this.currentTabId === tab.id ? '✅' : ''} |`
 			)
 		}
+		if (!this.tabs.length) {
+			summaries.push('\nNo tabs available. Open a tab if needed.')
+		}
+
 		return summaries.join('\n')
 	}
 
+	async waitUntilTabLoaded(tabId: number): Promise<void> {
+		const tab = this.tabs.find((t) => t.id === tabId)
+		if (!tab) throw new Error(`Tab ID ${tabId} not found in tab list.`)
+
+		if (tab.status === 'unloaded') throw new Error(`Tab ID ${tabId} is unloaded.`)
+		if (tab.status === 'complete') return
+
+		debug('waitUntilTabLoaded', tabId)
+		await waitUntil(() => tab.status === 'complete', 4_000)
+	}
+
 	dispose() {
 		this.dispatchEvent(new Event('dispose'))
 	}
@@ -251,6 +304,9 @@ export type TabAction =
 interface TabMeta {
 	id: number
 	isInitial: boolean
+	url?: string
+	title?: string
+	status?: 'loading' | 'unloaded' | 'complete'
 }
 
 const TAB_GROUP_COLORS = [
@@ -269,3 +325,33 @@ type TabGroupColor = (typeof TAB_GROUP_COLORS)[number]
 function randomColor(): TabGroupColor {
 	return TAB_GROUP_COLORS[Math.floor(Math.random() * TAB_GROUP_COLORS.length)]
 }
+
+/**
+ * Wait until condition becomes true
+ * @returns Returns when condition becomes true, throws otherwise
+ * @param timeoutMS Timeout in milliseconds, default 1 minutes, throws error on timeout
+ * @param error Error object to reject on timeout. If not provided, will resolve with false
+ */
+export async function waitUntil(
+	check: () => boolean | Promise<boolean>,
+	timeoutMS = 60_000,
+	error?: string
+): Promise<boolean> {
+	if (await check()) return true
+
+	return new Promise((resolve, reject) => {
+		const start = Date.now()
+		const poll = async () => {
+			if (await check()) return resolve(true)
+			if (Date.now() - start > timeoutMS) {
+				if (error) {
+					return reject(new Error(error))
+				} else {
+					return resolve(false)
+				}
+			}
+			setTimeout(poll, 100)
+		}
+		setTimeout(poll, 100)
+	})
+}

packages/extension/src/agent/constants.ts

@@ -1,13 +1,30 @@
 import type { LLMConfig } from '@page-agent/llms'
 
 // Demo LLM for testing
-export const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-export const DEMO_BASE_URL =
-	'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-export const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+export const DEMO_MODEL = 'qwen3.5-plus'
+export const DEMO_BASE_URL = 'https://page-ag-testing-ohftxirgbn.cn-shanghai.fcapp.run'
+export const DEMO_API_KEY = 'NA'
 
 export const DEMO_CONFIG: LLMConfig = {
 	apiKey: DEMO_API_KEY,
 	baseURL: DEMO_BASE_URL,
 	model: DEMO_MODEL,
 }
+
+/** Legacy testing endpoints that should be auto-migrated to DEMO_BASE_URL */
+export const LEGACY_TESTING_ENDPOINTS = [
+	'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy',
+]
+
+export function isTestingEndpoint(url: string): boolean {
+	const normalized = url.replace(/\/+$/, '')
+	return normalized === DEMO_BASE_URL || LEGACY_TESTING_ENDPOINTS.some((ep) => normalized === ep)
+}
+
+export function migrateLegacyEndpoint(config: LLMConfig): LLMConfig {
+	const normalized = config.baseURL.replace(/\/+$/, '')
+	if (LEGACY_TESTING_ENDPOINTS.some((ep) => normalized === ep)) {
+		return { ...DEMO_CONFIG }
+	}
+	return config
+}

packages/extension/src/agent/system_prompt.md

@@ -10,7 +10,7 @@ You excel at following tasks:
 </intro>
 
 <language_settings>
-- Default working language: **中文**
+- Default working language: **English**
 - Use the language that user is using. Return in user's language.
 </language_settings>
 
@@ -120,7 +120,6 @@ Exhibit the following reasoning patterns to successfully achieve the <user_reque
 Here are examples of good output patterns. Use them as reference but never copy them directly.
 
 <evaluation_examples>
-- Positive Examples:
 "evaluation_previous_goal": "Successfully navigated to the product page and found the target information. Verdict: Success"
 "evaluation_previous_goal": "Clicked the login button and user authentication form appeared. Verdict: Success"
 </evaluation_examples>
@@ -131,17 +130,16 @@ Here are examples of good output patterns. Use them as reference but never copy
 
 <next_goal_examples>
 "next_goal": "Click on the 'Add to Cart' button to proceed with the purchase flow."
-"next_goal": "Extract details from the first item on the page."
 </next_goal_examples>
 </examples>
 
 <output>
-You must ALWAYS respond with a valid JSON in this exact format:
-
 {
   "evaluation_previous_goal": "Concise one-sentence analysis of your last action. Clearly state success, failure, or uncertain.",
   "memory": "1-3 concise sentences of specific memory of this step and overall progress. You should put here everything that will help you track progress in future steps. Like counting pages visited, items found, etc.",
-  "next_goal": "State the next immediate goal and action to achieve it, in one clear sentence."
-  "action":{"one_action_name": {// action-specific parameter}}
+  "next_goal": "State the next immediate goal and action to achieve it, in one clear sentence.",
+  "action":{
+    "Action name": {// Action parameters}
+  }
 }
 </output>

packages/extension/src/agent/tabTools.ts

@@ -6,14 +6,14 @@
  * - switch_to_tab: Switch to an existing tab
  * - close_tab: Close a tab (optionally switch to another)
  */
-import zod from 'zod'
+import * as z from 'zod'
 
 import type { TabsController } from './TabsController'
 
 /** Tool definition compatible with PageAgentCore customTools */
 interface TabTool {
 	description: string
-	inputSchema: zod.ZodType
+	inputSchema: z.ZodType
 	execute: (input: unknown) => Promise<string>
 }
 
@@ -26,37 +26,48 @@ export function createTabTools(tabsController: TabsController): Record<string, T
 		open_new_tab: {
 			description:
 				'Open a new browser tab with the specified URL. The new tab becomes the current tab for all subsequent page operations.',
-			inputSchema: zod.object({
-				url: zod.string().describe('The URL to open in the new tab'),
+			inputSchema: z.object({
+				url: z.string().describe('The URL to open in the new tab'),
 			}),
 			execute: async (input: unknown) => {
 				const { url } = input as { url: string }
-				const result = await tabsController.openNewTab(url)
-				return result.message
+				try {
+					return await tabsController.openNewTab(url)
+				} catch (error) {
+					return `❌ Failed: ${error instanceof Error ? error.message : String(error)}`
+				}
 			},
 		},
 
 		switch_to_tab: {
 			description:
 				'Switch to an existing tab by its ID. After switching, all page operations will target the new current tab. You can only switch to tabs in the tab list shown in browser state.',
-			inputSchema: zod.object({
-				tab_id: zod.number().int().describe('The tab ID to switch to'),
+			inputSchema: z.object({
+				tab_id: z.number().int().describe('The tab ID to switch to'),
 			}),
 			execute: async (input: unknown) => {
 				const { tab_id } = input as { tab_id: number }
-				return (await tabsController.switchToTab(tab_id)).message
+				try {
+					return await tabsController.switchToTab(tab_id)
+				} catch (error) {
+					return `❌ Failed: ${error instanceof Error ? error.message : String(error)}`
+				}
 			},
 		},
 
 		close_tab: {
 			description:
 				'Close a tab by its ID. Cannot close the initial tab. Optionally specify which tab to switch to after closing.',
-			inputSchema: zod.object({
-				tab_id: zod.number().int().describe('The tab ID to close'),
+			inputSchema: z.object({
+				tab_id: z.number().int().describe('The tab ID to close'),
 			}),
 			execute: async (input: unknown) => {
 				const { tab_id } = input as { tab_id: number }
-				return (await tabsController.closeTab(tab_id)).message
+				try {
+					return await tabsController.closeTab(tab_id)
+				} catch (error) {
+					return `❌ Failed: ${error instanceof Error ? error.message : String(error)}`
+				}
 			},
 		},
 	}

packages/extension/src/agent/useAgent.ts

@@ -1,22 +1,34 @@
 /**
  * React hook for using AgentController
  */
-import type { AgentActivity, AgentStatus, HistoricalEvent } from '@page-agent/core'
+import type {
+	AgentActivity,
+	AgentStatus,
+	HistoricalEvent,
+	SupportedLanguage,
+} from '@page-agent/core'
 import type { LLMConfig } from '@page-agent/llms'
 import { useCallback, useEffect, useRef, useState } from 'react'
 
 import { MultiPageAgent } from './MultiPageAgent'
-import { DEMO_CONFIG } from './constants'
+import { DEMO_CONFIG, migrateLegacyEndpoint } from './constants'
+
+/** Language preference: undefined means follow system */
+export type LanguagePreference = SupportedLanguage | undefined
+
+export interface ExtConfig extends LLMConfig {
+	language?: LanguagePreference
+}
 
 export interface UseAgentResult {
 	status: AgentStatus
 	history: HistoricalEvent[]
 	activity: AgentActivity | null
 	currentTask: string
-	config: LLMConfig | null
+	config: ExtConfig | null
 	execute: (task: string) => Promise<void>
 	stop: () => void
-	configure: (config: LLMConfig) => Promise<void>
+	configure: (config: ExtConfig) => Promise<void>
 }
 
 export function useAgent(): UseAgentResult {
@@ -25,16 +37,23 @@ export function useAgent(): UseAgentResult {
 	const [history, setHistory] = useState<HistoricalEvent[]>([])
 	const [activity, setActivity] = useState<AgentActivity | null>(null)
 	const [currentTask, setCurrentTask] = useState('')
-	const [config, setConfig] = useState<LLMConfig | null>(null)
+	const [config, setConfig] = useState<ExtConfig | null>(null)
 
 	useEffect(() => {
-		chrome.storage.local.get('llmConfig').then((result) => {
-			if (result.llmConfig) {
-				setConfig(result.llmConfig as LLMConfig)
-			} else {
+		chrome.storage.local.get(['llmConfig', 'language']).then((result) => {
+			let llmConfig = (result.llmConfig as LLMConfig) ?? DEMO_CONFIG
+			const language = (result.language as SupportedLanguage) || undefined
+
+			// Auto-migrate legacy testing endpoints
+			const migrated = migrateLegacyEndpoint(llmConfig)
+			if (migrated !== llmConfig) {
+				llmConfig = migrated
+				chrome.storage.local.set({ llmConfig: migrated })
+			} else if (!result.llmConfig) {
 				chrome.storage.local.set({ llmConfig: DEMO_CONFIG })
-				setConfig(DEMO_CONFIG)
 			}
+
+			setConfig({ ...llmConfig, language })
 		})
 	}, [])
 
@@ -75,7 +94,7 @@ export function useAgent(): UseAgentResult {
 
 	const execute = useCallback(async (task: string) => {
 		const agent = agentRef.current
-		console.log('Fire task:', task, agent)
+		console.log('🚀 [useAgent] start executing task:', task)
 		if (!agent) throw new Error('Agent not initialized')
 
 		setCurrentTask(task)
@@ -84,11 +103,17 @@ export function useAgent(): UseAgentResult {
 	}, [])
 
 	const stop = useCallback(() => {
-		agentRef.current?.dispose()
+		agentRef.current?.stop()
 	}, [])
 
-	const configure = useCallback(async (newConfig: LLMConfig) => {
-		setConfig(newConfig)
+	const configure = useCallback(async ({ language, ...llmConfig }: ExtConfig) => {
+		await chrome.storage.local.set({ llmConfig })
+		if (language) {
+			await chrome.storage.local.set({ language })
+		} else {
+			await chrome.storage.local.remove('language')
+		}
+		setConfig({ ...llmConfig, language })
 	}, [])
 
 	return {

packages/extension/src/assets/index.css

@@ -40,7 +40,7 @@
 }
 
 .dark {
-	--background: oklch(0.145 0 0);
+	--background: oklch(0.19 0 0);
 	--foreground: oklch(0.985 0 0);
 	--card: oklch(0.145 0 0);
 	--card-foreground: oklch(0.985 0 0);
@@ -111,6 +111,41 @@
 	--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
 	--color-sidebar-border: var(--sidebar-border);
 	--color-sidebar-ring: var(--sidebar-ring);
+	--animate-blink-cursor: blink-cursor 1.2s step-end infinite;
+	@keyframes blink-cursor {
+		0%,
+		49% {
+			opacity: 1;
+		}
+		50%,
+		100% {
+			opacity: 0;
+		}
+	}
+}
+
+@keyframes glow-a {
+	0%,
+	100% {
+		opacity: 0.45;
+		transform: scale(1);
+	}
+	50% {
+		opacity: 0;
+		transform: scale(1.1);
+	}
+}
+
+@keyframes glow-b {
+	0%,
+	100% {
+		opacity: 0;
+		transform: scale(1.1);
+	}
+	50% {
+		opacity: 0.45;
+		transform: scale(1);
+	}
 }
 
 @layer base {

packages/extension/src/components/ui/input-group.tsx

@@ -21,8 +21,9 @@ function InputGroup({ className, ...props }: React.ComponentProps<'div'>) {
 				'has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>[data-align=block-start]]:[&>input]:pb-3',
 				'has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-end]]:[&>input]:pt-3',
 
-				// Focus state.
-				'has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-ring/50 has-[[data-slot=input-group-control]:focus-visible]:ring-[3px]',
+				// Focus state — soft multi-color glow matching ai-motion palette
+				'has-[[data-slot=input-group-control]:focus-visible]:border-blue-400/60',
+				'has-[[data-slot=input-group-control]:focus-visible]:shadow-[0_0_0_1px_rgba(57,182,255,0.2),0_0_8px_rgba(57,182,255,0.15),0_0_16px_rgba(189,69,251,0.1)]',
 
 				// Error state.
 				'has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[[data-slot][aria-invalid=true]]:border-destructive dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40',

packages/extension/src/components/ui/typing-animation.tsx

@@ -0,0 +1,164 @@
+import { MotionProps, motion, useInView } from 'motion/react'
+import { useEffect, useMemo, useRef, useState } from 'react'
+
+import { cn } from '@/lib/utils'
+
+interface TypingAnimationProps extends MotionProps {
+	children?: string
+	words?: string[]
+	className?: string
+	duration?: number
+	typeSpeed?: number
+	deleteSpeed?: number
+	delay?: number
+	pauseDelay?: number
+	loop?: boolean
+	as?: React.ElementType
+	startOnView?: boolean
+	showCursor?: boolean
+	blinkCursor?: boolean
+	cursorStyle?: 'line' | 'block' | 'underscore'
+}
+
+export function TypingAnimation({
+	children,
+	words,
+	className,
+	duration = 100,
+	typeSpeed,
+	deleteSpeed,
+	delay = 0,
+	pauseDelay = 1000,
+	loop = false,
+	as: Component = 'span',
+	startOnView = true,
+	showCursor = true,
+	blinkCursor = true,
+	cursorStyle = 'line',
+	...props
+}: TypingAnimationProps) {
+	const MotionComponent = motion.create(Component, {
+		forwardMotionProps: true,
+	})
+
+	const [displayedText, setDisplayedText] = useState<string>('')
+	const [currentWordIndex, setCurrentWordIndex] = useState(0)
+	const [currentCharIndex, setCurrentCharIndex] = useState(0)
+	const [phase, setPhase] = useState<'typing' | 'pause' | 'deleting'>('typing')
+	const elementRef = useRef<HTMLElement | null>(null)
+	const isInView = useInView(elementRef as React.RefObject<Element>, {
+		amount: 0.3,
+		once: true,
+	})
+
+	const wordsToAnimate = useMemo(() => words || (children ? [children] : []), [words, children])
+	const hasMultipleWords = wordsToAnimate.length > 1
+
+	const typingSpeed = typeSpeed || duration
+	const deletingSpeed = deleteSpeed || typingSpeed / 2
+
+	const shouldStart = startOnView ? isInView : true
+
+	useEffect(() => {
+		if (!shouldStart || wordsToAnimate.length === 0) return
+
+		const timeoutDelay =
+			delay > 0 && displayedText === ''
+				? delay
+				: phase === 'typing'
+					? typingSpeed
+					: phase === 'deleting'
+						? deletingSpeed
+						: pauseDelay
+
+		const timeout = setTimeout(() => {
+			const currentWord = wordsToAnimate[currentWordIndex] || ''
+			const graphemes = Array.from(currentWord)
+
+			switch (phase) {
+				case 'typing':
+					if (currentCharIndex < graphemes.length) {
+						setDisplayedText(graphemes.slice(0, currentCharIndex + 1).join(''))
+						setCurrentCharIndex(currentCharIndex + 1)
+					} else {
+						if (hasMultipleWords || loop) {
+							const isLastWord = currentWordIndex === wordsToAnimate.length - 1
+							if (!isLastWord || loop) {
+								setPhase('pause')
+							}
+						}
+					}
+					break
+
+				case 'pause':
+					setPhase('deleting')
+					break
+
+				case 'deleting':
+					if (currentCharIndex > 0) {
+						setDisplayedText(graphemes.slice(0, currentCharIndex - 1).join(''))
+						setCurrentCharIndex(currentCharIndex - 1)
+					} else {
+						const nextIndex = (currentWordIndex + 1) % wordsToAnimate.length
+						setCurrentWordIndex(nextIndex)
+						setPhase('typing')
+					}
+					break
+			}
+		}, timeoutDelay)
+
+		return () => clearTimeout(timeout)
+	}, [
+		shouldStart,
+		phase,
+		currentCharIndex,
+		currentWordIndex,
+		displayedText,
+		wordsToAnimate,
+		hasMultipleWords,
+		loop,
+		typingSpeed,
+		deletingSpeed,
+		pauseDelay,
+		delay,
+	])
+
+	const currentWordGraphemes = Array.from(wordsToAnimate[currentWordIndex] || '')
+	const isComplete =
+		!loop &&
+		currentWordIndex === wordsToAnimate.length - 1 &&
+		currentCharIndex >= currentWordGraphemes.length &&
+		phase !== 'deleting'
+
+	const shouldShowCursor =
+		showCursor &&
+		!isComplete &&
+		(hasMultipleWords || loop || currentCharIndex < currentWordGraphemes.length)
+
+	const getCursorChar = () => {
+		switch (cursorStyle) {
+			case 'block':
+				return '▌'
+			case 'underscore':
+				return '_'
+			case 'line':
+			default:
+				return '|'
+		}
+	}
+
+	return (
+		<MotionComponent
+			ref={elementRef}
+			className={cn('leading-[5rem] tracking-[-0.02em]', className)}
+			{...props}
+		>
+			{displayedText}
+			{shouldShowCursor && (
+				<span className={cn('inline-block', blinkCursor && 'animate-blink-cursor')}>
+					{getCursorChar()}
+				</span>
+			)}
+		</MotionComponent>
+	)
+}

packages/extension/src/entrypoints/background.ts

@@ -1,24 +1,13 @@
 import { handlePageControlMessage } from '@/agent/RemotePageController.background'
-import { handleTabControlMessage } from '@/agent/TabsController.background'
-
-chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
-	if (message.type === 'TAB_CONTROL') {
-		return handleTabControlMessage(message, sender, sendResponse)
-	} else if (message.type === 'PAGE_CONTROL') {
-		return handlePageControlMessage(message, sender, sendResponse)
-	} else {
-		sendResponse({ error: 'Unknown message type' })
-		return
-	}
-})
-
-// ============================================================================
-// Extension Setup
-// ============================================================================
+import { handleTabControlMessage, setupTabChangeEvents } from '@/agent/TabsController.background'
 
 export default defineBackground(() => {
 	console.log('[Background] Service Worker started')
 
+	// tab change events
+
+	setupTabChangeEvents()
+
 	// generate user auth token
 
 	chrome.storage.local.get('PageAgentExtUserAuthToken').then((result) => {
@@ -28,21 +17,20 @@ export default defineBackground(() => {
 		chrome.storage.local.set({ PageAgentExtUserAuthToken: userAuthToken })
 	})
 
+	// message proxy
+
+	chrome.runtime.onMessage.addListener((message, sender, sendResponse): true | undefined => {
+		if (message.type === 'TAB_CONTROL') {
+			return handleTabControlMessage(message, sender, sendResponse)
+		} else if (message.type === 'PAGE_CONTROL') {
+			return handlePageControlMessage(message, sender, sendResponse)
+		} else {
+			sendResponse({ error: 'Unknown message type' })
+			return
+		}
+	})
+
 	// setup
 
 	chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true }).catch(() => {})
-
-	// Tab change events
-
-	chrome.tabs.onCreated.addListener((tab) => {
-		chrome.runtime.sendMessage({ type: 'TAB_CHANGE', action: 'created', payload: { tab } })
-	})
-
-	chrome.tabs.onRemoved.addListener((tabId, removeInfo) => {
-		chrome.runtime.sendMessage({
-			type: 'TAB_CHANGE',
-			action: 'removed',
-			payload: { tabId, removeInfo },
-		})
-	})
 })

packages/extension/src/entrypoints/content.ts

@@ -6,7 +6,7 @@ const DEBUG_PREFIX = '[Content]'
 
 export default defineContentScript({
 	matches: ['<all_urls>'],
-	runAt: 'document_idle',
+	runAt: 'document_end',
 
 	main() {
 		console.debug(`${DEBUG_PREFIX} Loaded on ${window.location.href}`)
@@ -54,6 +54,7 @@ async function exposeAgentToPage() {
 
 		switch (action) {
 			case 'execute': {
+				// singleton check
 				if (multiPageAgent && multiPageAgent.status === 'running') {
 					window.postMessage(
 						{
@@ -68,9 +69,55 @@ async function exposeAgentToPage() {
 				}
 
 				try {
-					const { task, llmConfig } = payload
+					const { task, config } = payload
 
-					multiPageAgent = new MultiPageAgent(llmConfig)
+					// Dispose old instance before creating new one
+					multiPageAgent?.dispose()
+
+					multiPageAgent = new MultiPageAgent(config)
+
+					// events
+
+					multiPageAgent.addEventListener('statuschange', (event) => {
+						if (!multiPageAgent) return
+						window.postMessage(
+							{
+								channel: 'PAGE_AGENT_EXT_RESPONSE',
+								id,
+								action: 'status_change_event',
+								payload: multiPageAgent.status,
+							},
+							'*'
+						)
+					})
+
+					multiPageAgent.addEventListener('activity', (event) => {
+						if (!multiPageAgent) return
+						window.postMessage(
+							{
+								channel: 'PAGE_AGENT_EXT_RESPONSE',
+								id,
+								action: 'activity_event',
+								payload: (event as CustomEvent).detail,
+							},
+							'*'
+						)
+					})
+
+					multiPageAgent.addEventListener('historychange', (event) => {
+						if (!multiPageAgent) return
+						window.postMessage(
+							{
+								channel: 'PAGE_AGENT_EXT_RESPONSE',
+								id,
+								action: 'history_change_event',
+								payload: multiPageAgent.history,
+							},
+							'*'
+						)
+					})
+
+					// result
 
 					const result = await multiPageAgent.execute(task)
 
@@ -98,9 +145,8 @@ async function exposeAgentToPage() {
 				break
 			}
 
-			case 'dispose': {
-				// @note stop ongoing processes but can still be re-used later
-				multiPageAgent?.dispose()
+			case 'stop': {
+				multiPageAgent?.stop()
 				break
 			}
 

packages/extension/src/entrypoints/main-world.ts

@@ -1,32 +1,68 @@
-import type { LLMConfig } from '@page-agent/llms'
+import type { AgentActivity, AgentStatus, ExecutionResult, HistoricalEvent } from '@page-agent/core'
+
+export type Execute = (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
+
+export interface ExecuteConfig {
+	baseURL: string
+	apiKey: string
+	model: string
+
+	/**
+	 * Whether to include the initial tab (that holds this main world script) in the task.
+	 * @default true
+	 */
+	includeInitialTab?: boolean
+
+	onStatusChange?: (status: AgentStatus) => void
+	onActivity?: (activity: AgentActivity) => void
+	onHistoryUpdate?: (history: HistoricalEvent[]) => void
+}
 
 export default defineUnlistedScript(() => {
-	const w = window as any
-
 	let _lastId = 0
 	function getId() {
 		_lastId += 1
 		return _lastId
 	}
 
-	w.execute = async (task: string, llmConfig: LLMConfig) => {
+	const execute: Execute = async (task, config) => {
 		if (typeof task !== 'string') throw new Error('Task must be a string')
 		if (task.trim().length === 0) throw new Error('Task cannot be empty')
-		if (!llmConfig) throw new Error('LLM config is required')
-		if (!llmConfig.baseURL) throw new Error('LLM config must have a baseURL')
-		if (!llmConfig.apiKey) throw new Error('LLM config must have an apiKey')
-		if (!llmConfig.model) throw new Error('LLM config must have a model')
+		if (!config) throw new Error('Config is required')
+		if (!config.baseURL) throw new Error('Config must have a baseURL')
+		if (!config.apiKey) throw new Error('Config must have an apiKey')
+		if (!config.model) throw new Error('Config must have a model')
 
 		const id = getId()
 
-		const promise = new Promise((resolve, reject) => {
+		const promise = new Promise<ExecutionResult>((resolve, reject) => {
 			function handleMessage(e: MessageEvent) {
 				const data = e.data
 				if (typeof data !== 'object' || data === null) return
 				if (data.channel !== 'PAGE_AGENT_EXT_RESPONSE') return
-				if (data.action !== 'execute_result') return
 				if (data.id !== id) return
 
+				// events
+
+				if (data.action === 'status_change_event' && config.onStatusChange) {
+					config.onStatusChange(data.payload)
+					return
+				}
+
+				if (data.action === 'activity_event' && config.onActivity) {
+					config.onActivity(data.payload)
+					return
+				}
+
+				if (data.action === 'history_change_event' && config.onHistoryUpdate) {
+					config.onHistoryUpdate(data.payload)
+					return
+				}
+
+				if (data.action !== 'execute_result') return
+
+				// execute_result
+
 				window.removeEventListener('message', handleMessage)
 
 				if (data.error) {
@@ -36,6 +72,7 @@ export default defineUnlistedScript(() => {
 				}
 			}
 
+			// @note will be removed on dispose or result
 			window.addEventListener('message', handleMessage)
 		})
 
@@ -44,7 +81,15 @@ export default defineUnlistedScript(() => {
 				channel: 'PAGE_AGENT_EXT_REQUEST',
 				id,
 				action: 'execute',
-				payload: { task, llmConfig },
+				payload: {
+					task,
+					config: {
+						baseURL: config.baseURL,
+						apiKey: config.apiKey,
+						model: config.model,
+						includeInitialTab: config.includeInitialTab,
+					},
+				},
 			},
 			'*'
 		)
@@ -52,16 +97,23 @@ export default defineUnlistedScript(() => {
 		return promise
 	}
 
-	w.dispose = () => {
+	const stop = () => {
 		const id = getId()
 
 		window.postMessage(
 			{
 				channel: 'PAGE_AGENT_EXT_REQUEST',
 				id,
-				action: 'dispose',
+				action: 'stop',
 			},
 			'*'
 		)
 	}
+
+	;(window as any).PAGE_AGENT_EXT_VERSION = __EXT_VERSION__
+	;(window as any).PAGE_AGENT_EXT = {
+		version: __EXT_VERSION__,
+		execute,
+		stop,
+	}
 })

packages/extension/src/entrypoints/sidepanel/App.tsx

@@ -1,4 +1,4 @@
-import { Send, Settings, Square } from 'lucide-react'
+import { History, Send, Settings, Square } from 'lucide-react'
 import { useCallback, useEffect, useRef, useState } from 'react'
 
 import { Button } from '@/components/ui/button'
@@ -8,20 +8,47 @@ import {
 	InputGroupButton,
 	InputGroupTextarea,
 } from '@/components/ui/input-group'
+import { saveSession } from '@/lib/db'
 
 import { useAgent } from '../../agent/useAgent'
 import { ConfigPanel } from './components/ConfigPanel'
+import { HistoryDetail } from './components/HistoryDetail'
+import { HistoryList } from './components/HistoryList'
 import { ActivityCard, EventCard } from './components/cards'
-import { EmptyState, Logo, StatusDot } from './components/misc'
+import { EmptyState, Logo, MotionOverlay, StatusDot } from './components/misc'
+
+type View =
+	| { name: 'chat' }
+	| { name: 'config' }
+	| { name: 'history' }
+	| { name: 'history-detail'; sessionId: string }
 
 export default function App() {
-	const [showConfig, setShowConfig] = useState(false)
+	const [view, setView] = useState<View>({ name: 'chat' })
 	const [inputValue, setInputValue] = useState('')
 	const historyRef = useRef<HTMLDivElement>(null)
 	const textareaRef = useRef<HTMLTextAreaElement>(null)
 
 	const { status, history, activity, currentTask, config, execute, stop, configure } = useAgent()
 
+	// Persist session when task finishes
+	const prevStatusRef = useRef(status)
+	useEffect(() => {
+		const prev = prevStatusRef.current
+		prevStatusRef.current = status
+
+		if (
+			prev === 'running' &&
+			(status === 'completed' || status === 'error') &&
+			history.length > 0 &&
+			currentTask
+		) {
+			saveSession({ task: currentTask, history, status }).catch((err) =>
+				console.error('[SidePanel] Failed to save session:', err)
+			)
+		}
+	}, [status, history, currentTask])
+
 	// Auto-scroll to bottom on new events
 	useEffect(() => {
 		if (historyRef.current) {
@@ -30,7 +57,7 @@ export default function App() {
 	}, [history, activity])
 
 	const handleSubmit = useCallback(
-		(e?: React.FormEvent) => {
+		(e?: React.SyntheticEvent) => {
 			e?.preventDefault()
 			if (!inputValue.trim() || status === 'running') return
 
@@ -56,33 +83,64 @@ export default function App() {
 		}
 	}
 
-	if (showConfig) {
+	// --- View routing ---
+
+	if (view.name === 'config') {
 		return (
 			<ConfigPanel
 				config={config}
 				onSave={async (newConfig) => {
 					await configure(newConfig)
-					setShowConfig(false)
+					setView({ name: 'chat' })
 				}}
-				onClose={() => setShowConfig(false)}
+				onClose={() => setView({ name: 'chat' })}
 			/>
 		)
 	}
 
+	if (view.name === 'history') {
+		return (
+			<HistoryList
+				onSelect={(id) => setView({ name: 'history-detail', sessionId: id })}
+				onBack={() => setView({ name: 'chat' })}
+			/>
+		)
+	}
+
+	if (view.name === 'history-detail') {
+		return <HistoryDetail sessionId={view.sessionId} onBack={() => setView({ name: 'history' })} />
+	}
+
+	// --- Chat view ---
+
 	const isRunning = status === 'running'
 	const showEmptyState = !currentTask && history.length === 0 && !isRunning
 
 	return (
-		<div className="flex flex-col h-screen bg-background">
+		<div className="relative flex flex-col h-screen bg-background">
+			<MotionOverlay active={isRunning} />
 			{/* Header */}
 			<header className="flex items-center justify-between border-b px-3 py-2">
 				<div className="flex items-center gap-2">
 					<Logo className="size-5" />
 					<span className="text-sm font-medium">Page Agent Ext</span>
 				</div>
-				<div className="flex items-center gap-3">
+				<div className="flex items-center gap-1">
 					<StatusDot status={status} />
-					<Button variant="ghost" size="icon-sm" onClick={() => setShowConfig(true)}>
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						onClick={() => setView({ name: 'history' })}
+						className="cursor-pointer"
+					>
+						<History className="size-3.5" />
+					</Button>
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						onClick={() => setView({ name: 'config' })}
+						className="cursor-pointer"
+					>
 						<Settings className="size-3.5" />
 					</Button>
 				</div>
@@ -142,7 +200,7 @@ export default function App() {
 								variant="default"
 								onClick={() => handleSubmit()}
 								disabled={!inputValue.trim()}
-								className="size-7"
+								className="size-7 cursor-pointer"
 							>
 								<Send className="size-3" />
 							</InputGroupButton>

packages/extension/src/entrypoints/sidepanel/components/ConfigPanel.tsx

@@ -1,14 +1,15 @@
-import type { LLMConfig } from '@page-agent/llms'
-import { Copy, Loader2 } from 'lucide-react'
+import { Copy, CornerUpLeft, Eye, EyeOff, HatGlasses, Home, Loader2, Scale } from 'lucide-react'
 import { useEffect, useState } from 'react'
+import { siGithub } from 'simple-icons'
 
-import { DEMO_API_KEY, DEMO_BASE_URL, DEMO_MODEL } from '@/agent/constants'
+import { DEMO_API_KEY, DEMO_BASE_URL, DEMO_MODEL, isTestingEndpoint } from '@/agent/constants'
+import type { ExtConfig, LanguagePreference } from '@/agent/useAgent'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 
 interface ConfigPanelProps {
-	config: LLMConfig | null
-	onSave: (config: LLMConfig) => Promise<void>
+	config: ExtConfig | null
+	onSave: (config: ExtConfig) => Promise<void>
 	onClose: () => void
 }
 
@@ -16,15 +17,19 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 	const [apiKey, setApiKey] = useState(config?.apiKey || DEMO_API_KEY)
 	const [baseURL, setBaseURL] = useState(config?.baseURL || DEMO_BASE_URL)
 	const [model, setModel] = useState(config?.model || DEMO_MODEL)
+	const [language, setLanguage] = useState<LanguagePreference>(config?.language)
 	const [saving, setSaving] = useState(false)
 	const [userAuthToken, setUserAuthToken] = useState<string>('')
 	const [copied, setCopied] = useState(false)
+	const [showToken, setShowToken] = useState(false)
+	const [showApiKey, setShowApiKey] = useState(false)
 
 	// Update local state when config prop changes
 	useEffect(() => {
 		setApiKey(config?.apiKey || DEMO_API_KEY)
 		setBaseURL(config?.baseURL || DEMO_BASE_URL)
 		setModel(config?.model || DEMO_MODEL)
+		setLanguage(config?.language)
 	}, [config])
 
 	// Poll for user auth token every second until found
@@ -62,15 +67,42 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 	const handleSave = async () => {
 		setSaving(true)
 		try {
-			await onSave({ apiKey, baseURL, model })
+			await onSave({ apiKey, baseURL, model, language })
 		} finally {
 			setSaving(false)
 		}
 	}
 
 	return (
-		<div className="flex flex-col gap-4 p-4">
-			<h2 className="text-base font-semibold">Settings</h2>
+		<div className="flex flex-col gap-4 p-4 relative">
+			<div className="flex items-center justify-between">
+				<h2 className="text-base font-semibold">Settings</h2>
+				<Button
+					variant="ghost"
+					size="icon-sm"
+					onClick={onClose}
+					className="absolute top-2 right-3 cursor-pointer"
+				>
+					<CornerUpLeft className="size-3.5" />
+				</Button>
+			</div>
+
+			{/* Testing API notice */}
+			{isTestingEndpoint(baseURL) && (
+				<div className="p-2.5 rounded-md border border-amber-500/30 bg-amber-500/5 text-[10px] text-muted-foreground leading-relaxed">
+					<Scale className="size-3 inline-block mr-1 -mt-0.5 text-amber-600" />
+					You are using the free testing API. By using this service you agree to the{' '}
+					<a
+						href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="underline hover:text-foreground"
+					>
+						Terms of Use & Privacy Policy
+					</a>
+					. No sensitive data. No guaranteed availability.
+				</div>
+			)}
 
 			{/* User Auth Token Section */}
 			<div className="flex flex-col gap-1.5 p-3 bg-muted/50 rounded-md border">
@@ -81,9 +113,24 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 				<div className="flex gap-2 items-center">
 					<Input
 						readOnly
-						value={userAuthToken || 'Loading...'}
+						value={
+							userAuthToken
+								? showToken
+									? userAuthToken
+									: `${userAuthToken.slice(0, 4)}${'•'.repeat(userAuthToken.length - 8)}${userAuthToken.slice(-4)}`
+								: 'Loading...'
+						}
 						className="text-xs h-8 font-mono bg-background"
 					/>
+					<Button
+						variant="outline"
+						size="icon"
+						className="h-8 w-8 shrink-0 cursor-pointer"
+						onClick={() => setShowToken(!showToken)}
+						disabled={!userAuthToken}
+					>
+						{showToken ? <EyeOff className="size-3" /> : <Eye className="size-3" />}
+					</Button>
 					<Button
 						variant="outline"
 						size="icon"
@@ -109,7 +156,7 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 			<div className="flex flex-col gap-1.5">
 				<label className="text-xs text-muted-foreground">Model</label>
 				<Input
-					placeholder="gpt-4o"
+					placeholder="gpt-5.2"
 					value={model}
 					onChange={(e) => setModel(e.target.value)}
 					className="text-xs h-8"
@@ -118,23 +165,111 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 
 			<div className="flex flex-col gap-1.5">
 				<label className="text-xs text-muted-foreground">API Key</label>
-				<Input
-					type="password"
-					placeholder="sk-..."
-					value={apiKey}
-					onChange={(e) => setApiKey(e.target.value)}
-					className="text-xs h-8"
-				/>
+				<div className="flex gap-2 items-center">
+					<Input
+						type={showApiKey ? 'text' : 'password'}
+						placeholder="sk-..."
+						value={apiKey}
+						onChange={(e) => setApiKey(e.target.value)}
+						className="text-xs h-8"
+					/>
+					<Button
+						variant="outline"
+						size="icon"
+						className="h-8 w-8 shrink-0 cursor-pointer"
+						onClick={() => setShowApiKey(!showApiKey)}
+					>
+						{showApiKey ? <EyeOff className="size-3" /> : <Eye className="size-3" />}
+					</Button>
+				</div>
+			</div>
+
+			<div className="flex flex-col gap-1.5">
+				<label className="text-xs text-muted-foreground">Language</label>
+				<select
+					value={language ?? ''}
+					onChange={(e) => setLanguage((e.target.value || undefined) as LanguagePreference)}
+					className="h-8 text-xs rounded-md border border-input bg-background px-2 cursor-pointer"
+				>
+					<option value="">System</option>
+					<option value="en-US">English</option>
+					<option value="zh-CN">中文</option>
+				</select>
 			</div>
 
 			<div className="flex gap-2 mt-2">
-				<Button variant="outline" onClick={onClose} className="flex-1 h-8 text-xs">
+				<Button variant="outline" onClick={onClose} className="flex-1 h-8 text-xs cursor-pointer">
 					Cancel
 				</Button>
-				<Button onClick={handleSave} disabled={saving} className="flex-1 h-8 text-xs">
+				<Button
+					onClick={handleSave}
+					disabled={saving}
+					className="flex-1 h-8 text-xs cursor-pointer"
+				>
 					{saving ? <Loader2 className="size-3 animate-spin" /> : 'Save'}
 				</Button>
 			</div>
+
+			{/* Footer */}
+			<div className="mt-4 mb-4 pt-4 border-t border-border/50 flex gap-2 justify-between text-[10px] text-muted-foreground">
+				<div className="flex flex-col justify-between">
+					<a
+						href="https://github.com/alibaba/page-agent"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="flex items-center gap-1 hover:text-foreground"
+					>
+						<svg role="img" viewBox="0 0 24 24" className="size-3 fill-current">
+							<path d={siGithub.path} />
+						</svg>
+						<span>Source Code</span>
+					</a>
+
+					<a
+						href="https://alibaba.github.io/page-agent/"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="flex items-center gap-1 hover:text-foreground"
+					>
+						<Home className="size-3" />
+						<span>Home Page</span>
+					</a>
+
+					<a
+						href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="flex items-center gap-1 hover:text-foreground"
+					>
+						<HatGlasses className="size-3" />
+						<span>Privacy Policy</span>
+					</a>
+				</div>
+
+				<div className="flex flex-col items-end">
+					<span>
+						Extension <span className="font-mono">v{__EXT_VERSION__}</span>
+					</span>
+					<span>
+						PageAgent <span className="font-mono">v{__CORE_VERSION__}</span>
+					</span>
+				</div>
+			</div>
+
+			{/* attribute */}
+			<div className="text-[10px] text-muted-foreground bg-background fixed bottom-0 w-full flex justify-around">
+				<span className="leading-loose">
+					Built with ♥️ by{' '}
+					<a
+						href="https://github.com/gaomeng1900"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="underline hover:text-foreground"
+					>
+						@Simon
+					</a>
+				</span>
+			</div>
 		</div>
 	)
 }

packages/extension/src/entrypoints/sidepanel/components/HistoryDetail.tsx

@@ -0,0 +1,51 @@
+import { ArrowLeft } from 'lucide-react'
+import { useEffect, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { type SessionRecord, getSession } from '@/lib/db'
+
+import { EventCard } from './cards'
+
+export function HistoryDetail({ sessionId, onBack }: { sessionId: string; onBack: () => void }) {
+	const [session, setSession] = useState<SessionRecord | null>(null)
+
+	useEffect(() => {
+		getSession(sessionId).then((s) => setSession(s ?? null))
+	}, [sessionId])
+
+	if (!session) {
+		return (
+			<div className="flex items-center justify-center h-screen text-xs text-muted-foreground">
+				Loading...
+			</div>
+		)
+	}
+
+	return (
+		<div className="flex flex-col h-screen bg-background">
+			{/* Header */}
+			<header className="flex items-center gap-2 border-b px-3 py-2">
+				<Button variant="ghost" size="icon-sm" onClick={onBack} className="cursor-pointer">
+					<ArrowLeft className="size-3.5" />
+				</Button>
+				<span className="text-sm font-medium truncate">History</span>
+			</header>
+
+			{/* Task */}
+			<div className="border-b px-3 py-2 bg-muted/30">
+				<div className="text-[10px] text-muted-foreground uppercase tracking-wide">Task</div>
+				<div className="text-xs font-medium" title={session.task}>
+					{session.task}
+				</div>
+			</div>
+
+			{/* Events (read-only) */}
+			<div className="flex-1 overflow-y-auto p-3 space-y-2">
+				{session.history.map((event, index) => (
+					// eslint-disable-next-line react-x/no-array-index-key
+					<EventCard key={index} event={event} />
+				))}
+			</div>
+		</div>
+	)
+}

packages/extension/src/entrypoints/sidepanel/components/HistoryList.tsx

@@ -0,0 +1,119 @@
+import { ArrowLeft, CheckCircle, Trash2, XCircle } from 'lucide-react'
+import { useCallback, useEffect, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { type SessionRecord, clearSessions, deleteSession, listSessions } from '@/lib/db'
+
+function timeAgo(ts: number): string {
+	const seconds = Math.floor((Date.now() - ts) / 1000)
+	if (seconds < 60) return 'just now'
+	const minutes = Math.floor(seconds / 60)
+	if (minutes < 60) return `${minutes}m ago`
+	const hours = Math.floor(minutes / 60)
+	if (hours < 24) return `${hours}h ago`
+	const days = Math.floor(hours / 24)
+	return `${days}d ago`
+}
+
+export function HistoryList({
+	onSelect,
+	onBack,
+}: {
+	onSelect: (id: string) => void
+	onBack: () => void
+}) {
+	const [sessions, setSessions] = useState<SessionRecord[]>([])
+	const [loading, setLoading] = useState(true)
+
+	const load = useCallback(async () => {
+		setSessions(await listSessions())
+		setLoading(false)
+	}, [])
+
+	useEffect(() => {
+		// eslint-disable-next-line react-hooks/set-state-in-effect
+		load()
+	}, [load])
+
+	const handleDelete = async (e: React.MouseEvent, id: string) => {
+		e.stopPropagation()
+		await deleteSession(id)
+		setSessions((prev) => prev.filter((s) => s.id !== id))
+	}
+
+	return (
+		<div className="flex flex-col h-screen bg-background">
+			{/* Header */}
+			<header className="flex items-center gap-2 border-b px-3 py-2">
+				<Button variant="ghost" size="icon-sm" onClick={onBack} className="cursor-pointer">
+					<ArrowLeft className="size-3.5" />
+				</Button>
+				<span className="text-sm font-medium flex-1">History</span>
+				{sessions.length > 0 && (
+					<Button
+						variant="ghost"
+						size="sm"
+						onClick={async () => {
+							await clearSessions()
+							setSessions([])
+						}}
+						className="text-[10px] text-muted-foreground hover:text-destructive cursor-pointer h-6 px-2"
+					>
+						<Trash2 className="size-3 mr-1" />
+						Clear All
+					</Button>
+				)}
+			</header>
+
+			{/* List */}
+			<div className="flex-1 overflow-y-auto">
+				{loading && (
+					<div className="flex items-center justify-center h-32 text-xs text-muted-foreground">
+						Loading...
+					</div>
+				)}
+
+				{!loading && sessions.length === 0 && (
+					<div className="flex items-center justify-center h-32 text-xs text-muted-foreground">
+						No history yet
+					</div>
+				)}
+
+				{sessions.map((session) => (
+					<div
+						key={session.id}
+						role="button"
+						tabIndex={0}
+						onClick={() => onSelect(session.id)}
+						onKeyDown={(e) => e.key === 'Enter' && onSelect(session.id)}
+						className="w-full text-left px-3 py-2.5 border-b hover:bg-muted/50 transition-colors cursor-pointer flex items-start gap-2 group"
+					>
+						{/* Status icon */}
+						{session.status === 'completed' ? (
+							<CheckCircle className="size-3.5 text-green-500 shrink-0 mt-0.5" />
+						) : (
+							<XCircle className="size-3.5 text-destructive shrink-0 mt-0.5" />
+						)}
+
+						{/* Content */}
+						<div className="flex-1 min-w-0">
+							<p className="text-xs font-medium truncate">{session.task}</p>
+							<p className="text-[10px] text-muted-foreground mt-0.5">
+								{timeAgo(session.createdAt)} · {session.history.length} steps
+							</p>
+						</div>
+
+						{/* Delete */}
+						<button
+							type="button"
+							onClick={(e) => handleDelete(e, session.id)}
+							className="opacity-0 group-hover:opacity-100 transition-opacity p-1 hover:text-destructive cursor-pointer shrink-0"
+						>
+							<Trash2 className="size-3" />
+						</button>
+					</div>
+				))}
+			</div>
+		</div>
+	)
+}

packages/extension/src/entrypoints/sidepanel/components/cards.tsx

@@ -315,9 +315,7 @@ export function EventCard({ event }: { event: HistoricalEvent }) {
 				<ResultCard
 					success={input?.success ?? true}
 					text={input?.text || event.action.output || ''}
-				>
-					<RawSection rawRequest={event.rawRequest} rawResponse={event.rawResponse} />
-				</ResultCard>
+				/>
 			</>
 		)
 	}

packages/extension/src/entrypoints/sidepanel/components/misc.tsx

@@ -1,5 +1,10 @@
 import type { AgentStatus } from '@page-agent/core'
+import { Motion } from 'ai-motion'
+import { BookOpen, Globe } from 'lucide-react'
+import { useEffect, useRef } from 'react'
+import { siGithub } from 'simple-icons'
 
+import { TypingAnimation } from '@/components/ui/typing-animation'
 import { cn } from '@/lib/utils'
 
 // Status dot indicator
@@ -19,7 +24,7 @@ export function StatusDot({ status }: { status: AgentStatus }) {
 	}[status]
 
 	return (
-		<div className="flex items-center gap-1.5">
+		<div className="flex items-center gap-1.5 mr-2">
 			<span
 				className={cn('size-2 rounded-full', colorClass, status === 'running' && 'animate-pulse')}
 			/>
@@ -32,14 +37,111 @@ export function Logo({ className }: { className?: string }) {
 	return <img src="/assets/page-agent-256.webp" alt="Page Agent" className={cn('', className)} />
 }
 
-// Empty state with logo
+// Full-screen ai-motion glow overlay, shown only while running
+export function MotionOverlay({ active }: { active: boolean }) {
+	const containerRef = useRef<HTMLDivElement>(null)
+	const motionRef = useRef<Motion | null>(null)
+
+	useEffect(() => {
+		const mode = document.documentElement.classList.contains('dark') ? 'dark' : 'light'
+		const motion = new Motion({
+			mode,
+			borderWidth: 4,
+			borderRadius: 14,
+			glowWidth: mode === 'dark' ? 120 : 60,
+			styles: { position: 'absolute', inset: '0' },
+		})
+		motionRef.current = motion
+		containerRef.current!.appendChild(motion.element)
+		motion.autoResize(containerRef.current!)
+
+		return () => {
+			motion.dispose()
+			motionRef.current = null
+		}
+	}, [])
+
+	useEffect(() => {
+		const motion = motionRef.current
+		if (!motion) return
+
+		let disposed = false
+		if (active) {
+			motion.start()
+			motion.fadeIn()
+		} else {
+			motion.fadeOut().then(() => !disposed && motion.pause())
+		}
+		return () => {
+			disposed = true
+		}
+	}, [active])
+
+	return (
+		<div
+			ref={containerRef}
+			className="pointer-events-none absolute inset-0 z-10 opacity-60"
+			style={{ display: active ? undefined : 'none' }}
+		/>
+	)
+}
+
+// Empty state with logo and breathing glow
 export function EmptyState() {
 	return (
-		<div className="flex flex-col items-center justify-center h-full gap-3 text-center px-6">
-			<Logo className="size-20 opacity-80" />
+		<div className="flex flex-col items-center justify-center h-full gap-4 text-center px-6">
+			<div className="relative select-none pointer-events-none">
+				<div className="absolute inset-0 -m-6 rounded-full bg-[conic-gradient(from_180deg,oklch(0.55_0.2_280),oklch(0.5_0.15_230),oklch(0.6_0.18_310),oklch(0.55_0.2_280))] blur-2xl animate-[glow-a_5s_ease-in-out_infinite]" />
+				<div className="absolute inset-0 -m-6 rounded-full bg-[conic-gradient(from_0deg,oklch(0.55_0.18_160),oklch(0.5_0.2_200),oklch(0.6_0.15_120),oklch(0.55_0.18_160))] blur-2xl animate-[glow-b_5s_ease-in-out_infinite]" />
+				<Logo className="relative size-20 opacity-80" />
+			</div>
 			<div>
-				<h2 className="text-sm font-medium text-foreground">Page Agent Ext</h2>
-				<p className="text-xs text-muted-foreground mt-1">Enter a task to automate this page</p>
+				<h2 className="text-base font-medium text-foreground mb-1">Page Agent Ext</h2>
+				<TypingAnimation
+					className="text-sm text-muted-foreground"
+					words={[
+						'Enter a task to automate this page',
+						'Execute multi-page tasks',
+						'Call this extension from your web page',
+						'Use this extension in your own agents',
+					]}
+					cursorStyle="underscore"
+					loop
+					typeSpeed={20}
+					deleteSpeed={10}
+					pauseDelay={3000}
+				/>
+			</div>
+			<div className="flex items-center gap-3 mt-1 text-muted-foreground">
+				<a
+					href="https://github.com/alibaba/page-agent"
+					target="_blank"
+					rel="noopener noreferrer"
+					className="hover:text-foreground transition-colors"
+					title="GitHub"
+				>
+					<svg role="img" viewBox="0 0 24 24" className="size-4 fill-current">
+						<path d={siGithub.path} />
+					</svg>
+				</a>
+				<a
+					href="https://alibaba.github.io/page-agent/docs/features/chrome-extension"
+					target="_blank"
+					rel="noopener noreferrer"
+					className="hover:text-foreground transition-colors"
+					title="Documentation"
+				>
+					<BookOpen className="size-4" />
+				</a>
+				<a
+					href="https://alibaba.github.io/page-agent"
+					target="_blank"
+					rel="noopener noreferrer"
+					className="hover:text-foreground transition-colors"
+					title="Website"
+				>
+					<Globe className="size-4" />
+				</a>
 			</div>
 		</div>
 	)

packages/extension/src/entrypoints/sidepanel/main.tsx

@@ -6,6 +6,16 @@ import { ErrorBoundary } from './components/ErrorBoundary'
 
 import '@/assets/index.css'
 
+// Sync dark mode with system preference
+const syncDarkMode = () => {
+	document.documentElement.classList.toggle(
+		'dark',
+		matchMedia('(prefers-color-scheme: dark)').matches
+	)
+}
+syncDarkMode()
+matchMedia('(prefers-color-scheme: dark)').addEventListener('change', syncDarkMode)
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
 	<React.StrictMode>
 		<ErrorBoundary>

packages/extension/src/lib/db.ts

@@ -0,0 +1,70 @@
+import type { HistoricalEvent } from '@page-agent/core'
+import { type DBSchema, type IDBPDatabase, openDB } from 'idb'
+
+const DB_NAME = 'page-agent-ext'
+const DB_VERSION = 1
+
+export interface SessionRecord {
+	id: string
+	task: string
+	history: HistoricalEvent[]
+	status: 'completed' | 'error'
+	createdAt: number
+}
+
+interface PageAgentDB extends DBSchema {
+	sessions: {
+		key: string
+		value: SessionRecord
+		indexes: { 'by-created': number }
+	}
+}
+
+let dbPromise: Promise<IDBPDatabase<PageAgentDB>> | null = null
+
+function getDB() {
+	if (!dbPromise) {
+		dbPromise = openDB<PageAgentDB>(DB_NAME, DB_VERSION, {
+			upgrade(db) {
+				const store = db.createObjectStore('sessions', { keyPath: 'id' })
+				store.createIndex('by-created', 'createdAt')
+			},
+		})
+	}
+	return dbPromise
+}
+
+export async function saveSession(
+	session: Omit<SessionRecord, 'id' | 'createdAt'>
+): Promise<SessionRecord> {
+	const db = await getDB()
+	const record: SessionRecord = {
+		...session,
+		id: crypto.randomUUID(),
+		createdAt: Date.now(),
+	}
+	await db.put('sessions', record)
+	return record
+}
+
+/** List sessions, newest first */
+export async function listSessions(): Promise<SessionRecord[]> {
+	const db = await getDB()
+	const all = await db.getAllFromIndex('sessions', 'by-created')
+	return all.reverse()
+}
+
+export async function getSession(id: string): Promise<SessionRecord | undefined> {
+	const db = await getDB()
+	return db.get('sessions', id)
+}
+
+export async function deleteSession(id: string): Promise<void> {
+	const db = await getDB()
+	await db.delete('sessions', id)
+}
+
+export async function clearSessions(): Promise<void> {
+	const db = await getDB()
+	await db.clear('sessions')
+}

packages/extension/src/types/globals.d.ts

@@ -0,0 +1,2 @@
+declare const __EXT_VERSION__: string
+declare const __CORE_VERSION__: string

packages/extension/wxt.config.js

@@ -1,10 +1,12 @@
 import tailwindcss from '@tailwindcss/vite'
-import { mkdirSync } from 'node:fs'
+import { mkdirSync, readFileSync } from 'node:fs'
 import { defineConfig } from 'wxt'
 
 const chromeProfile = '.wxt/chrome-data'
 mkdirSync(chromeProfile, { recursive: true })
 
+const pkg = JSON.parse(readFileSync('./package.json', 'utf-8'))
+
 // See https://wxt.dev/api/config.html
 export default defineConfig({
 	srcDir: 'src',
@@ -16,6 +18,10 @@ export default defineConfig({
 	},
 	vite: () => ({
 		plugins: [tailwindcss()],
+		define: {
+			__EXT_VERSION__: JSON.stringify(pkg.version),
+			__CORE_VERSION__: JSON.stringify(pkg.dependencies['@page-agent/core']),
+		},
 		optimizeDeps: {
 			force: true,
 		},
@@ -32,9 +38,9 @@ export default defineConfig({
 		},
 	}),
 	manifest: {
-		name: 'Page Agent Ext',
-		description:
-			'AI-powered browser automation assistant. Control web pages with natural language.',
+		default_locale: 'en',
+		name: '__MSG_extName__',
+		description: '__MSG_extDescription__',
 		homepage_url: 'https://alibaba.github.io/page-agent/',
 		permissions: ['tabs', 'tabGroups', 'sidePanel', 'storage'],
 		host_permissions: ['<all_urls>'],
@@ -42,7 +48,7 @@ export default defineConfig({
 			64: 'assets/page-agent-64.png',
 		},
 		action: {
-			default_title: 'Open Page Agent',
+			default_title: '__MSG_extActionTitle__',
 		},
 		web_accessible_resources: [
 			{

packages/llms/package.json

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

packages/llms/src/OpenAIClient.ts

@@ -1,6 +1,8 @@
 /**
  * OpenAI Client implementation
  */
+import * as z from 'zod'
+
 import { InvokeError, InvokeErrorType } from './errors'
 import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
 import { modelPatch, zodToOpenAITool } from './utils'
@@ -54,8 +56,10 @@ export class OpenAIClient implements LLMClient {
 				signal: abortSignal,
 			})
 		} catch (error: unknown) {
-			console.error(error)
-			throw new InvokeError(InvokeErrorType.NETWORK_ERROR, 'Network request failed', error)
+			const isAbortError = (error as any)?.name === 'AbortError'
+			const errorMessage = isAbortError ? 'Network request aborted' : 'Network request failed'
+			if (!isAbortError) console.error(error)
+			throw new InvokeError(InvokeErrorType.NETWORK_ERROR, errorMessage, error)
 		}
 
 		// 3. Handle HTTP errors
@@ -180,7 +184,7 @@ export class OpenAIClient implements LLMClient {
 		// Validate with schema
 		const validation = tool.inputSchema.safeParse(parsedArgs)
 		if (!validation.success) {
-			console.error(validation.error)
+			console.error(z.prettifyError(validation.error))
 			throw new InvokeError(
 				InvokeErrorType.INVALID_TOOL_ARGS,
 				'Tool arguments validation failed',

packages/llms/src/env.d.ts

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

packages/llms/src/errors.ts

@@ -34,12 +34,15 @@ export class InvokeError extends Error {
 		super(message)
 		this.name = 'InvokeError'
 		this.type = type
-		this.retryable = this.isRetryable(type)
+		this.retryable = this.isRetryable(type, rawError)
 		this.rawError = rawError
 		this.rawResponse = rawResponse
 	}
 
-	private isRetryable(type: InvokeErrorType): boolean {
+	private isRetryable(type: InvokeErrorType, rawError?: unknown): boolean {
+		const isAbortError = (rawError as any)?.name === 'AbortError'
+		if (isAbortError) return false
+
 		const retryableTypes: InvokeErrorType[] = [
 			InvokeErrorType.NETWORK_ERROR,
 			InvokeErrorType.RATE_LIMIT,

packages/llms/src/index.ts

@@ -1,16 +1,17 @@
 import { OpenAIClient } from './OpenAIClient'
 import { DEFAULT_TEMPERATURE, LLM_MAX_RETRIES } from './constants'
-import { InvokeError } from './errors'
+import { InvokeError, InvokeErrorType } from './errors'
 import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
 
-export type { InvokeError, InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool }
+export { InvokeError, InvokeErrorType }
+export type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool }
 
 export function parseLLMConfig(config: LLMConfig): Required<LLMConfig> {
 	// Runtime validation as defensive programming (types already guarantee these)
 	if (!config.baseURL || !config.apiKey || !config.model) {
 		throw new Error(
 			'[PageAgent] LLM configuration required. Please provide: baseURL, apiKey, model. ' +
-				'See: https://alibaba.github.io/page-agent/#/docs/features/models'
+				'See: https://alibaba.github.io/page-agent/docs/features/models'
 		)
 	}
 
@@ -49,6 +50,9 @@ export class LLM extends EventTarget {
 	): Promise<InvokeResult> {
 		return await withRetry(
 			async () => {
+				// in case user aborted before invoking
+				if (abortSignal.aborted) throw new Error('AbortError')
+
 				const result = await this.client.invoke(messages, tools, abortSignal, options)
 
 				return result

packages/llms/src/types.ts

@@ -1,7 +1,7 @@
 /**
  * Core types for LLM integration
  */
-import type { z } from 'zod'
+import type * as z from 'zod'
 
 /**
  * Message format - OpenAI standard (industry standard)

packages/llms/src/utils.ts

@@ -2,7 +2,7 @@
  * Utility functions for LLM integration
  */
 import chalk from 'chalk'
-import { z } from 'zod'
+import * as z from 'zod'
 
 import type { Tool } from './types'
 
@@ -38,6 +38,7 @@ export function modelPatch(body: Record<string, any>) {
 	if (modelName.startsWith('qwen')) {
 		debug('Applying Qwen patch: use higher temperature for auto fixing')
 		body.temperature = Math.max(body.temperature || 0, 1.0)
+		body.enable_thinking = false
 	}
 
 	if (modelName.startsWith('claude')) {
@@ -74,6 +75,10 @@ export function modelPatch(body: Record<string, any>) {
 		} else if (modelName.startsWith('gpt-51')) {
 			debug('Applying GPT-51 patch: disable reasoning')
 			body.reasoning_effort = 'none'
+		} else if (modelName.startsWith('gpt-5-mini')) {
+			debug('Applying GPT-5-mini patch: set reasoning effort to low, temperature to 1')
+			body.reasoning_effort = 'low'
+			body.temperature = 1
 		} else if (modelName.startsWith('gpt-5')) {
 			debug('Applying GPT-5 patch: set reasoning effort to low')
 			body.reasoning_effort = 'low'

packages/page-agent/package.json

@@ -1,7 +1,7 @@
 {
     "name": "page-agent",
     "private": false,
-    "version": "1.0.0",
+    "version": "1.4.2",
     "type": "module",
     "main": "./dist/esm/page-agent.js",
     "module": "./dist/esm/page-agent.js",
@@ -44,11 +44,11 @@
         "postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
     },
     "dependencies": {
+        "@page-agent/core": "1.4.2",
+        "@page-agent/llms": "1.4.2",
+        "@page-agent/page-controller": "1.4.2",
+        "@page-agent/ui": "1.4.2",
         "chalk": "^5.6.2",
-        "zod": "^4.3.5",
-        "@page-agent/llms": "1.0.0",
-        "@page-agent/page-controller": "1.0.0",
-        "@page-agent/core": "1.0.0",
-        "@page-agent/ui": "1.0.0"
+        "zod": "^4.3.5"
     }
 }

packages/page-agent/src/demo.ts

@@ -13,9 +13,9 @@ window.PageAgent = PageAgent
 
 console.log('🚀 page-agent.js loaded!')
 
-const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+const DEMO_MODEL = 'qwen3.5-plus'
+const DEMO_BASE_URL = 'https://page-ag-testing-ohftxirgbn.cn-shanghai.fcapp.run'
+const DEMO_API_KEY = 'NA'
 
 // in case document.x is not ready yet
 setTimeout(() => {

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

@@ -3,6 +3,7 @@ import { config as dotenvConfig } from 'dotenv'
 import { dirname, resolve } from 'path'
 import { fileURLToPath } from 'url'
 import { defineConfig } from 'vite'
+// import { analyzer } from 'vite-bundle-analyzer'
 import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -14,8 +15,11 @@ dotenvConfig({ path: resolve(__dirname, '../../.env') })
 // - alias all local packages so that they can be build in
 // - no external
 // - no d.ts. dts does not work with monorepo aliasing
-export default defineConfig(({ mode }) => ({
-	plugins: [cssInjectedByJsPlugin({ relativeCSSInjection: true })],
+export default defineConfig(() => ({
+	plugins: [
+		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
+		// analyzer()
+	],
 	publicDir: false,
 	esbuild: {
 		keepNames: true,

packages/page-controller/package.json

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

packages/page-controller/src/PageController.ts

@@ -194,7 +194,7 @@ export class PageController extends EventTarget {
 			interactiveBlacklist: blacklist,
 		})
 
-		this.simplifiedHTML = dom.flatTreeToString(this.flatTree, this.config.include_attributes)
+		this.simplifiedHTML = dom.flatTreeToString(this.flatTree, this.config.includeAttributes)
 
 		this.selectorMap.clear()
 		this.selectorMap = dom.getSelectorMap(this.flatTree)
@@ -248,7 +248,7 @@ export class PageController extends EventTarget {
 			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.`,
+					message: `✅ Clicked element (${elemText ?? index}). ⚠️ Link opened in a new tab.`,
 				}
 			}
 

packages/page-controller/src/actions.ts

@@ -86,7 +86,7 @@ export async function clickElement(element: HTMLElement) {
 	// dispatch a click event
 	// element.click()
 
-	await waitFor(0.1) // Wait to ensure click event processing completes
+	await waitFor(0.2) // Wait to ensure click event processing completes
 }
 
 // eslint-disable-next-line @typescript-eslint/unbound-method
@@ -181,11 +181,6 @@ export async function scrollVertically(
 	// Element-specific scrolling if element is provided
 	if (element) {
 		const targetElement = element
-		console.log(
-			'[SCROLL DEBUG] Starting direct container scroll for element:',
-			targetElement.tagName
-		)
-
 		let currentElement = targetElement as HTMLElement | null
 		let scrollSuccess = false
 		let scrolledElement: HTMLElement | null = null
@@ -198,19 +193,6 @@ export async function scrollVertically(
 			const hasScrollableY = /(auto|scroll|overlay)/.test(computedStyle.overflowY)
 			const canScrollVertically = currentElement.scrollHeight > currentElement.clientHeight
 
-			console.log(
-				'[SCROLL DEBUG] Checking element:',
-				currentElement.tagName,
-				'hasScrollableY:',
-				hasScrollableY,
-				'canScrollVertically:',
-				canScrollVertically,
-				'scrollHeight:',
-				currentElement.scrollHeight,
-				'clientHeight:',
-				currentElement.clientHeight
-			)
-
 			if (hasScrollableY && canScrollVertically) {
 				const beforeScroll = currentElement.scrollTop
 				const maxScroll = currentElement.scrollHeight - currentElement.clientHeight
@@ -228,27 +210,10 @@ export async function scrollVertically(
 				const afterScroll = currentElement.scrollTop
 				const actualScrollDelta = afterScroll - beforeScroll
 
-				console.log(
-					'[SCROLL DEBUG] Scroll attempt:',
-					currentElement.tagName,
-					'before:',
-					beforeScroll,
-					'after:',
-					afterScroll,
-					'delta:',
-					actualScrollDelta
-				)
-
 				if (Math.abs(actualScrollDelta) > 0.5) {
 					scrollSuccess = true
 					scrolledElement = currentElement
 					scrollDelta = actualScrollDelta
-					console.log(
-						'[SCROLL DEBUG] Successfully scrolled container:',
-						currentElement.tagName,
-						'delta:',
-						actualScrollDelta
-					)
 					break
 				}
 			}
@@ -344,11 +309,6 @@ export async function scrollHorizontally(
 	// Element-specific scrolling if element is provided
 	if (element) {
 		const targetElement = element
-		console.log(
-			'[SCROLL DEBUG] Starting direct container scroll for element:',
-			targetElement.tagName
-		)
-
 		let currentElement = targetElement as HTMLElement | null
 		let scrollSuccess = false
 		let scrolledElement: HTMLElement | null = null
@@ -361,19 +321,6 @@ export async function scrollHorizontally(
 			const hasScrollableX = /(auto|scroll|overlay)/.test(computedStyle.overflowX)
 			const canScrollHorizontally = currentElement.scrollWidth > currentElement.clientWidth
 
-			console.log(
-				'[SCROLL DEBUG] Checking element:',
-				currentElement.tagName,
-				'hasScrollableX:',
-				hasScrollableX,
-				'canScrollHorizontally:',
-				canScrollHorizontally,
-				'scrollWidth:',
-				currentElement.scrollWidth,
-				'clientWidth:',
-				currentElement.clientWidth
-			)
-
 			if (hasScrollableX && canScrollHorizontally) {
 				const beforeScroll = currentElement.scrollLeft
 				const maxScroll = currentElement.scrollWidth - currentElement.clientWidth
@@ -391,27 +338,10 @@ export async function scrollHorizontally(
 				const afterScroll = currentElement.scrollLeft
 				const actualScrollDelta = afterScroll - beforeScroll
 
-				console.log(
-					'[SCROLL DEBUG] Scroll attempt:',
-					currentElement.tagName,
-					'before:',
-					beforeScroll,
-					'after:',
-					afterScroll,
-					'delta:',
-					actualScrollDelta
-				)
-
 				if (Math.abs(actualScrollDelta) > 0.5) {
 					scrollSuccess = true
 					scrolledElement = currentElement
 					scrollDelta = actualScrollDelta
-					console.log(
-						'[SCROLL DEBUG] Successfully scrolled container:',
-						currentElement.tagName,
-						'delta:',
-						actualScrollDelta
-					)
 					break
 				}
 			}

packages/page-controller/src/dom/index.ts

@@ -10,7 +10,7 @@ import {
 export interface DomConfig {
 	interactiveBlacklist?: (Element | (() => Element))[]
 	interactiveWhitelist?: (Element | (() => Element))[]
-	include_attributes?: string[]
+	includeAttributes?: string[]
 	highlightOpacity?: number
 	highlightLabelOpacity?: number
 }
@@ -117,7 +117,7 @@ interface TreeNode {
  *
  * @todo 数据脱敏过滤器
  */
-export function flatTreeToString(flatTree: FlatDomTree, include_attributes?: string[]): string {
+export function flatTreeToString(flatTree: FlatDomTree, includeAttributes?: string[]): string {
 	const DEFAULT_INCLUDE_ATTRIBUTES = [
 		'title',
 		'type',
@@ -146,7 +146,7 @@ export function flatTreeToString(flatTree: FlatDomTree, include_attributes?: str
 		'aria-owns',
 	]
 
-	const includeAttrs = [...(include_attributes || []), ...DEFAULT_INCLUDE_ATTRIBUTES]
+	const includeAttrs = [...(includeAttributes || []), ...DEFAULT_INCLUDE_ATTRIBUTES]
 
 	// Helper function to cap text length
 	const capTextLength = (text: string, maxLength: number): string => {

packages/ui/package.json

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

packages/ui/src/i18n/locales.ts

@@ -12,9 +12,10 @@ const enUS = {
 			question: 'Question: {{question}}',
 			waitingPlaceholder: 'Waiting for task to start...',
 			stop: 'Stop',
+			close: 'Close',
 			expand: 'Expand history',
 			collapse: 'Collapse history',
-			step: 'Step {{number}} · {{time}}{{duration}}',
+			step: 'Step {{number}}',
 		},
 		tools: {
 			clicking: 'Clicking element [{{index}}]...',
@@ -59,9 +60,10 @@ const zhCN = {
 			question: '询问: {{question}}',
 			waitingPlaceholder: '等待任务开始...',
 			stop: '终止',
+			close: '关闭',
 			expand: '展开历史',
 			collapse: '收起历史',
-			step: '步骤 {{number}} · {{time}}{{duration}}',
+			step: '步骤 {{number}}',
 		},
 		tools: {
 			clicking: '正在点击元素 [{{index}}]...',

packages/ui/src/index.ts

@@ -1,3 +1,2 @@
 export { Panel, type PanelConfig } from './panel/Panel'
-export type { AgentActivity, PanelAgentAdapter } from './panel/types'
 export { I18n, type SupportedLanguage, type TranslationKey } from './i18n'

packages/ui/src/panel/Panel.ts

@@ -1,6 +1,6 @@
 import { I18n, type SupportedLanguage } from '../i18n'
 import { truncate } from '../utils'
-import { createCard, createReflectionLines, formatTime } from './cards'
+import { createCard, createReflectionLines } from './cards'
 import type { AgentActivity, PanelAgentAdapter } from './types'
 
 import styles from './Panel.module.css'
@@ -33,7 +33,7 @@ export class Panel {
 	#statusText: HTMLElement
 	#historySection: HTMLElement
 	#expandButton: HTMLElement
-	#stopButton: HTMLElement
+	#actionButton: HTMLElement
 	#inputSection: HTMLElement
 	#taskInput: HTMLInputElement
 
@@ -76,7 +76,7 @@ export class Panel {
 		this.#statusText = this.#wrapper.querySelector(`.${styles.statusText}`)!
 		this.#historySection = this.#wrapper.querySelector(`.${styles.historySection}`)!
 		this.#expandButton = this.#wrapper.querySelector(`.${styles.expandButton}`)!
-		this.#stopButton = this.#wrapper.querySelector(`.${styles.stopButton}`)!
+		this.#actionButton = this.#wrapper.querySelector(`.${styles.stopButton}`)!
 		this.#inputSection = this.#wrapper.querySelector(`.${styles.inputSectionWrapper}`)!
 		this.#taskInput = this.#wrapper.querySelector(`.${styles.taskInput}`)!
 
@@ -105,6 +105,15 @@ export class Panel {
 			status === 'running' ? 'thinking' : status === 'idle' ? 'thinking' : status
 		this.#updateStatusIndicator(indicatorType)
 
+		// Morph action button: running = stop (■), not running = close (X)
+		if (status === 'running') {
+			this.#actionButton.textContent = '■'
+			this.#actionButton.title = this.#i18n.t('ui.panel.stop')
+		} else {
+			this.#actionButton.textContent = 'X'
+			this.#actionButton.title = this.#i18n.t('ui.panel.close')
+		}
+
 		// Show/hide based on status
 		if (status === 'running') {
 			this.show()
@@ -178,7 +187,6 @@ export class Panel {
 			tempCard.innerHTML = createCard({
 				icon: '❓',
 				content: `Question: ${question}`,
-				meta: formatTime(this.#config.language ?? 'en-US'),
 				type: 'question',
 			})
 			const cardElement = tempCard.firstElementChild as HTMLElement
@@ -266,10 +274,14 @@ export class Panel {
 	}
 
 	/**
-	 * Stop Agent
+	 * Action button handler: stop when running, close (dispose) when idle
 	 */
-	#stopAgent(): void {
-		this.#agent.dispose()
+	#handleActionButton(): void {
+		if (this.#agent.status === 'running') {
+			this.#agent.stop()
+		} else {
+			this.#agent.dispose()
+		}
 	}
 
 	/**
@@ -383,7 +395,7 @@ export class Panel {
 					<button class="${styles.controlButton} ${styles.expandButton}" title="${this.#i18n.t('ui.panel.expand')}">
 						▼
 					</button>
-					<button class="${styles.controlButton} ${styles.stopButton}" title="${this.#i18n.t('ui.panel.stop')}">
+					<button class="${styles.controlButton} ${styles.stopButton}" title="${this.#i18n.t('ui.panel.close')}">
 						X
 					</button>
 				</div>
@@ -420,10 +432,10 @@ export class Panel {
 			this.#toggle()
 		})
 
-		// Stop button
-		this.#stopButton.addEventListener('click', (e) => {
+		// Action button (stop / close)
+		this.#actionButton.addEventListener('click', (e) => {
 			e.stopPropagation()
-			this.#stopAgent()
+			this.#handleActionButton()
 		})
 
 		// Submit on Enter key in input field
@@ -578,15 +590,12 @@ export class Panel {
 	/** Create cards for a history event */
 	#createHistoryCards(event: PanelAgentAdapter['history'][number]): string[] {
 		const cards: string[] = []
-		const time = formatTime(this.#config.language ?? 'en-US')
 		const meta =
 			event.type === 'step' && event.stepIndex !== undefined
 				? this.#i18n.t('ui.panel.step', {
 						number: (event.stepIndex + 1).toString(),
-						time,
-						duration: '',
 					})
-				: time
+				: undefined
 
 		if (event.type === 'step') {
 			// Reflection card
@@ -623,7 +632,7 @@ export class Panel {
 	/** Create cards for an action */
 	#createActionCards(
 		action: { name: string; input: unknown; output: string },
-		meta: string
+		meta?: string
 	): string[] {
 		const cards: string[] = []
 

packages/ui/src/panel/cards.ts

@@ -32,16 +32,6 @@ export function createCard({ icon, content, meta, type }: CardOptions): string {
 	`
 }
 
-/** Format timestamp for cards */
-export function formatTime(locale: string = 'en-US'): string {
-	return new Date().toLocaleTimeString(locale, {
-		hour12: false,
-		hour: '2-digit',
-		minute: '2-digit',
-		second: '2-digit',
-	})
-}
-
 /** Create reflection lines from reflection object */
 export function createReflectionLines(reflection: {
 	evaluation_previous_goal?: string

packages/ui/src/panel/types.ts

@@ -68,6 +68,9 @@ export interface PanelAgentAdapter extends EventTarget {
 	/** Execute a task */
 	execute(task: string): Promise<unknown>
 
-	/** Dispose the agent */
+	/** Stop the current task (agent remains reusable) */
+	stop(): void
+
+	/** Dispose the agent (terminal, cannot be reused) */
 	dispose(): void
 }

packages/website/AGENTS.md

@@ -5,9 +5,9 @@
 - **React** with TypeScript
 - **Vite** for dev server and build
 - **Tailwind CSS** for styling
-- **shadcn/ui** (new-york style) for UI components
+- **shadcn/ui** (new-york style) for UI components — **do NOT hand-edit `src/components/ui/` files**
 - **Magic UI** for animations and effects
-- **wouter** with hash routing for static hosting
+- **wouter** with browser routing (`base: "/page-agent"`)
 - **lucide-react** for icons
 
 ## Component Guidelines
@@ -53,58 +53,74 @@ Located in `src/components/ui/`:
 ### 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
+2. Support dark mode via `dark:` classes
+3. Use CSS variables from `src/index.css` for theme colors
 
 ## Project Structure
 
 ```
 src/
 ├── pages/
-│   ├── Home.tsx         # Homepage
+│   ├── home/
+│   │   ├── HomeContent.tsx  # Homepage sections
+│   │   └── ...Section.tsx
 │   └── docs/
-│       ├── Layout.tsx   # Documentation sidebar
+│       ├── index.tsx    # Docs route switch
+│       ├── Layout.tsx   # Sidebar navigation
 │       └── [section]/[topic]/page.tsx
 ├── components/
-│   ├── ui/              # shadcn/ui + Magic UI components
+│   ├── ui/              # shadcn/ui + Magic UI (DO NOT hand-edit)
+│   ├── Heading.tsx      # Anchor heading for doc pages
 │   ├── Header.tsx       # Site header
 │   └── Footer.tsx       # Site footer
 ├── i18n/                # Internationalization
-├── router.tsx           # Central routing
+├── router.tsx           # Root layout + routing
 └── main.tsx             # App entry
 ```
 
+## Routing
+
+Uses wouter browser routing with base path for GitHub Pages deployment at `https://alibaba.github.io/page-agent/`.
+
+```tsx
+// main.tsx
+<Router base="/page-agent">
+  <PagesRouter />
+</Router>
+```
+
+**Key rules:**
+
+- Header and Footer live in `router.tsx` **outside** `<Switch>`, so they always see the root router context (`base="/page-agent"`)
+- Docs pages are nested via `<Route path="/docs" nest>`, which creates a child context (`base="/page-agent/docs"`)
+- Inside the docs nest, Link hrefs are relative to `/docs` (e.g. `href="/features/models"`, NOT `href="/docs/features/models"`)
+- **Never use `~` prefix** in Link hrefs — it bypasses the base path entirely
+- Doc page headings use `<Heading id="slug" level={2}>` for anchor links
+
+### SPA on GitHub Pages
+
+Instead of `404.html` redirects, the build copies `index.html` into every route directory. Add new routes to the `SPA_ROUTES` array in `vite.config.js`.
+
 ## Adding New Pages
 
 ### Documentation Page
 
 1. Create `src/pages/docs/<section>/<slug>/page.tsx`
-2. Add route to `src/router.tsx` with `<Header /> + <DocsLayout>` wrapper
-3. Add navigation item to `pages/docs/Layout.tsx`
-
-## Routing
-
-Uses hash-based routing for static hosting:
-
-```tsx
-import { Router } from 'wouter'
-import { useHashLocation } from 'wouter/use-hash-location'
-
-;<Router hook={useHashLocation}>{/* routes */}</Router>
-```
+2. Add route in `src/pages/docs/index.tsx`
+3. Add navigation item in `src/pages/docs/Layout.tsx`
+4. Add path to `SPA_ROUTES` in `vite.config.js`
 
 ## Configuration Files
 
 | File              | Purpose                 |
 | ----------------- | ----------------------- |
 | `components.json` | shadcn/ui configuration |
-| `vite.config.js`  | Vite build settings     |
+| `vite.config.js`  | Vite build + SPA routes |
 | `tsconfig.json`   | TypeScript config       |
 
 ## Commands
 
 ```bash
-npm start        # Dev server (from root)
+npm start            # Dev server (from root)
 npm run build:website    # Build website (from root)
 ```

packages/website/index.html

@@ -45,13 +45,24 @@
 		</script>
 	</head>
 	<body>
-		<div id="root"></div>
+		<div id="root">
+			<div id="sk">
+				<p class="sk-text" id="sk-text">Loading...</p>
+				<style>
+					#sk{display:flex;align-items:center;justify-content:center;min-height:100vh;background:linear-gradient(135deg,#eff6ff,#f5f3ff)}
+					@media(prefers-color-scheme:dark){#sk{background:linear-gradient(135deg,#111827,#1f2937)}}
+					.sk-text{font:400 14px/1 system-ui,sans-serif;color:#94a3b8;animation:skf 2s ease-in-out infinite}
+					@keyframes skf{0%,100%{opacity:.6}50%{opacity:.3}}
+				</style>
+			</div>
+		</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
+				const el = document.getElementById('sk-text')
+				if (el) el.textContent = lang.startsWith('zh') ? '加载中...' : 'Loading...'
 			}
 			updateHtmlLang()
 			window.addEventListener('storage', updateHtmlLang)

packages/website/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@page-agent/website",
     "private": true,
-    "version": "1.0.0",
+    "version": "1.4.2",
     "type": "module",
     "scripts": {
         "dev": "vite --host 0.0.0.0",
@@ -10,33 +10,26 @@
         "typecheck": "tsc --noEmit"
     },
     "devDependencies": {
-        "@tailwindcss/vite": "^4.1.18",
-        "@types/react": "^19.2.8",
-        "@types/react-dom": "^19.2.1",
-        "@vitejs/plugin-react-swc": "^4.1.0",
-        "i18next": "^25.7.4",
-        "i18next-browser-languagedetector": "^8.2.0",
-        "react": "^19.2.4",
-        "react-dom": "^19.2.4",
-        "react-i18next": "^16.5.3",
-        "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",
+        "@types/react": "^19.2.14",
+        "@types/react-dom": "^19.2.1",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
-        "lucide-react": "^0.563.0",
-        "motion": "^12.29.2",
+        "lucide-react": "^0.575.0",
+        "motion": "^12.34.3",
         "next-themes": "^0.4.6",
+        "react": "^19.2.4",
+        "react-dom": "^19.2.4",
         "rough-notation": "^0.5.1",
-        "simple-icons": "^16.6.0",
+        "simple-icons": "^16.9.0",
         "sonner": "^2.0.7",
-        "tailwind-merge": "^3.4.0"
+        "tailwind-merge": "^3.5.0",
+        "tailwindcss": "^4.1.14",
+        "tw-animate-css": "^1.4.0",
+        "wouter": "^3.9.0"
     }
 }

packages/website/src/components/BetaNotice.tsx

@@ -1,7 +1,7 @@
-import { useTranslation } from 'react-i18next'
+import { useLanguage } from '@/i18n/context'
 
 export default function BetaNotice() {
-	const { t } = useTranslation('common')
+	const { isZh } = useLanguage()
 
 	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">
@@ -11,9 +11,13 @@ export default function BetaNotice() {
 				</div>
 				<div className="ml-3">
 					<h3 className="text-sm font-medium text-orange-800 dark:text-orange-200 mb-1">
-						{t('beta_notice.title')}
+						{isZh ? 'Beta 阶段' : 'Beta Stage'}
 					</h3>
-					<p className="text-sm text-orange-700 dark:text-orange-300">{t('beta_notice.content')}</p>
+					<p className="text-sm text-orange-700 dark:text-orange-300">
+						{isZh
+							? '当前功能未完成，接口可能随时变更。正式版本发布前请勿用于生产环境。'
+							: 'Current features are incomplete and the API may change at any time. Please do not use in production environments before the official release.'}
+					</p>
 				</div>
 			</div>
 		</div>

packages/website/src/components/Footer.tsx

@@ -1,8 +1,9 @@
-import { useTranslation } from 'react-i18next'
 import { siGithub } from 'simple-icons'
 
+import { useLanguage } from '@/i18n/context'
+
 export default function Footer() {
-	const { t } = useTranslation('common')
+	const { isZh } = useLanguage()
 
 	return (
 		<footer
@@ -11,14 +12,24 @@ export default function Footer() {
 		>
 			<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>
+					<p className="text-gray-600 dark:text-gray-300 text-sm">
+						© 2026 page-agent. All rights reserved.
+					</p>
 					<div className="flex items-center space-x-6">
+						<a
+							href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md"
+							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 text-sm"
+						>
+							{isZh ? '使用条款与隐私' : 'Terms & Privacy'}
+						</a>
 						<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')}
+							aria-label={isZh ? '访问 GitHub 仓库' : 'Visit GitHub repository'}
 						>
 							<svg
 								role="img"

packages/website/src/components/Header.tsx

@@ -1,15 +1,16 @@
 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 { useLanguage } from '@/i18n/context'
+
 import LanguageSwitcher from './LanguageSwitcher'
 import ThemeSwitcher from './ThemeSwitcher'
 import { HyperText } from './ui/hyper-text'
 
 export default function Header() {
-	const { t } = useTranslation('common')
+	const { isZh } = useLanguage()
 	const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
 
 	return (
@@ -22,9 +23,9 @@ export default function Header() {
 					<div className="flex items-center justify-between gap-2">
 						{/* Logo */}
 						<Link
-							href="~/"
+							href="/"
 							className="flex items-center gap-2 sm:gap-3 group shrink-0"
-							aria-label={t('header.logo_alt')}
+							aria-label={isZh ? 'page-agent 首页' : 'page-agent home'}
 							onClick={() => setMobileMenuOpen(false)}
 						>
 							<img
@@ -43,7 +44,7 @@ export default function Header() {
 									animateOnHover={true}
 									aria-hidden="true"
 								>
-									{t('header.slogan')}
+									AI Agent In Your Webpage
 								</HyperText>
 							</div>
 						</Link>
@@ -55,9 +56,9 @@ export default function Header() {
 							aria-label="Mobile navigation"
 						>
 							<Link
-								href="~/docs/introduction/overview"
+								href="/docs/introduction/overview"
 								className="p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200 shrink-0"
-								aria-label={t('header.nav_docs')}
+								aria-label={isZh ? '文档' : 'Docs'}
 							>
 								<BookOpen className="w-5 h-5" />
 							</Link>
@@ -66,7 +67,7 @@ export default function Header() {
 								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')}
+								aria-label="GitHub"
 							>
 								<svg
 									role="img"
@@ -83,24 +84,24 @@ export default function Header() {
 						<nav
 							className="hidden md:flex items-center space-x-6"
 							role="navigation"
-							aria-label={t('header.nav_docs')}
+							aria-label={isZh ? '文档' : 'Docs'}
 						>
 							<span className="text-xs font-mono text-gray-400 dark:text-gray-500 tabular-nums before:content-['v']">
 								{import.meta.env.VERSION}
 							</span>
 							<Link
-								href="~/docs/introduction/overview"
+								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')}
+								{isZh ? '文档' : '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')}
+								aria-label="GitHub"
 							>
 								<svg
 									role="img"
@@ -110,7 +111,7 @@ export default function Header() {
 								>
 									<path d={siGithub.path} />
 								</svg>
-								{t('header.nav_source')}
+								GitHub
 							</a>
 							<ThemeSwitcher />
 							<LanguageSwitcher />
@@ -120,7 +121,7 @@ export default function Header() {
 						<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-label={isZh ? '打开导航栏' : 'Open navigation'}
 							aria-expanded={mobileMenuOpen}
 							aria-controls="mobile-menu"
 							onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
@@ -137,19 +138,19 @@ export default function Header() {
 							role="navigation"
 						>
 							<Link
-								href="~/docs/introduction/overview"
+								href="/docs/introduction/overview"
 								className="flex items-center gap-2 px-3 py-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
 								onClick={() => setMobileMenuOpen(false)}
 							>
 								<BookOpen className="w-5 h-5" />
-								{t('header.nav_docs')}
+								{isZh ? '文档' : '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')}
+								aria-label="GitHub"
 							>
 								<svg
 									role="img"
@@ -159,7 +160,7 @@ export default function Header() {
 								>
 									<path d={siGithub.path} />
 								</svg>
-								{t('header.nav_source')}
+								GitHub
 							</a>
 							<div className="flex items-center gap-3 px-3 py-2">
 								<ThemeSwitcher />

packages/website/src/components/Heading.tsx

@@ -0,0 +1,45 @@
+import { ComponentPropsWithoutRef, useEffect, useRef } from 'react'
+
+import { cn } from '@/lib/utils'
+
+type Level = 2 | 3
+
+interface HeadingProps extends Omit<ComponentPropsWithoutRef<'h2'>, 'children'> {
+	id: string
+	level?: Level
+	children: React.ReactNode
+}
+
+const levelStyles = {
+	2: { tag: 'h2', className: 'text-2xl font-semibold mb-4' },
+	3: { tag: 'h3', className: 'text-xl font-semibold mb-3' },
+} as const
+
+export function Heading({ id, level = 2, className, children, ...props }: HeadingProps) {
+	const ref = useRef<HTMLHeadingElement>(null)
+	const { tag: Tag, className: defaultClassName } = levelStyles[level]
+
+	useEffect(() => {
+		if (window.location.hash === `#${id}`) {
+			ref.current?.scrollIntoView({ behavior: 'smooth' })
+		}
+	}, [id])
+
+	return (
+		<Tag
+			ref={ref}
+			id={id}
+			className={cn('group relative scroll-mt-20', defaultClassName, className)}
+			{...props}
+		>
+			<a
+				href={`#${id}`}
+				className="absolute -left-5 top-1/2 -translate-y-1/2 opacity-0 group-hover:opacity-100 text-gray-400 hover:text-blue-500 transition-opacity no-underline"
+				aria-label={`Link to ${id}`}
+			>
+				#
+			</a>
+			{children}
+		</Tag>
+	)
+}

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

@@ -3,6 +3,8 @@
 	word-break: break-word;
 	overflow-wrap: break-word;
 	font-family: monospace;
+	font-size: 13px;
+	line-height: 1;
 	color: #171717;
 }
 

packages/website/src/components/LanguageSwitcher.tsx

@@ -1,22 +1,21 @@
 import { useEffect, useRef, useState } from 'react'
-import { useTranslation } from 'react-i18next'
+
+import { useLanguage } from '@/i18n/context'
 
 export default function LanguageSwitcher() {
-	const { i18n, t } = useTranslation('common')
+	const { language, isZh, setLanguage } = useLanguage()
 	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' },
+		{ code: 'zh-CN' as const, label: '中文' },
+		{ code: 'en-US' as const, label: 'English' },
 	]
 
-	const currentLanguage = languages.find((lang) => lang.code === currentLang) || languages[0]
+	const currentLanguage = languages.find((lang) => lang.code === language) || languages[0]
 
-	const handleLanguageChange = (langCode: string) => {
-		i18n.changeLanguage(langCode)
+	const handleLanguageChange = (langCode: 'zh-CN' | 'en-US') => {
+		setLanguage(langCode)
 		setIsOpen(false)
 	}
 
@@ -42,7 +41,7 @@ export default function LanguageSwitcher() {
 			<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-label={isZh ? '切换语言' : 'Switch language'}
 				aria-expanded={isOpen}
 				aria-haspopup="true"
 			>
@@ -83,14 +82,14 @@ export default function LanguageSwitcher() {
 							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
+								language === 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 && (
+							{language === lang.code && (
 								<svg
 									className="w-4 h-4 ml-auto"
 									fill="none"

packages/website/src/components/ui/magic-card.tsx

@@ -85,7 +85,7 @@ export function MagicCard({
           `,
 				}}
 			/>
-			<div className="bg-background absolute inset-px rounded-[inherit]" />
+			<div className="absolute inset-px rounded-[inherit] bg-white dark:bg-neutral-900" />
 			<motion.div
 				className="pointer-events-none absolute inset-px rounded-[inherit] opacity-0 transition-opacity duration-300 group-hover:opacity-100"
 				style={{

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

@@ -0,0 +1,74 @@
+import { ComponentPropsWithoutRef } from 'react'
+
+import { cn } from '@/lib/utils'
+
+interface MarqueeProps extends ComponentPropsWithoutRef<'div'> {
+	/**
+	 * Optional CSS class name to apply custom styles
+	 */
+	className?: string
+	/**
+	 * Whether to reverse the animation direction
+	 * @default false
+	 */
+	reverse?: boolean
+	/**
+	 * Whether to pause the animation on hover
+	 * @default false
+	 */
+	pauseOnHover?: boolean
+	/**
+	 * Content to be displayed in the marquee
+	 */
+	children: React.ReactNode
+	/**
+	 * Whether to animate vertically instead of horizontally
+	 * @default false
+	 */
+	vertical?: boolean
+	/**
+	 * Number of times to repeat the content
+	 * @default 4
+	 */
+	repeat?: number
+}
+
+export function Marquee({
+	className,
+	reverse = false,
+	pauseOnHover = false,
+	children,
+	vertical = false,
+	repeat = 4,
+	...props
+}: MarqueeProps) {
+	return (
+		<div
+			{...props}
+			className={cn(
+				'group flex [gap:var(--gap)] overflow-hidden p-2 [--duration:40s] [--gap:1rem]',
+				{
+					'flex-row': !vertical,
+					'flex-col': vertical,
+				},
+				className
+			)}
+		>
+			{Array(repeat)
+				.fill(0)
+				.map((_, i) => (
+					<div
+						key={i}
+						className={cn('flex shrink-0 justify-around [gap:var(--gap)]', {
+							'animate-marquee flex-row': !vertical,
+							'animate-marquee-vertical flex-col': vertical,
+							'group-hover:[animation-play-state:paused]': pauseOnHover,
+							'[animation-direction:reverse]': reverse,
+						})}
+					>
+						{children}
+					</div>
+				))}
+		</div>
+	)
+}

packages/website/src/constants.ts

@@ -1,11 +1,10 @@
 // Demo build (auto-init with demo LLM, for quick testing)
 export const CDN_DEMO_URL =
-	'https://cdn.jsdelivr.net/npm/page-agent@1.0.0/dist/iife/page-agent.demo.js'
+	'https://cdn.jsdelivr.net/npm/page-agent@1.4.2/dist/iife/page-agent.demo.js'
 export const CDN_DEMO_CN_URL =
-	'https://registry.npmmirror.com/page-agent/1.0.0/files/dist/iife/page-agent.demo.js'
+	'https://registry.npmmirror.com/page-agent/1.4.2/files/dist/iife/page-agent.demo.js'
 
-// Demo LLM for website testing
-export const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
-export const DEMO_BASE_URL =
-	'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
-export const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+// Demo LLM for website testing (homepage quick trial uses flash)
+export const DEMO_MODEL = 'qwen3.5-flash'
+export const DEMO_BASE_URL = 'https://page-ag-testing-ohftxirgbn.cn-shanghai.fcapp.run'
+export const DEMO_API_KEY = 'NA'

packages/website/src/i18n/README.md

@@ -1,73 +0,0 @@
-# 国际化配置说明
-
-本项目使用 `react-i18next` 实现国际化支持。
-
-## 目录结构
-
-```
-pages/i18n/
-├── config.ts              # i18next 配置和初始化
-├── types.ts               # TypeScript 类型声明
-├── locales/
-│   ├── zh-CN/             # 中文翻译
-│   │   ├── common.json    # 通用组件（Header, Footer等）
-│   │   ├── home.json      # 首页
-│   │   └── docs.json      # 文档页（待完善）
-│   └── en-US/             # 英文翻译
-│       ├── common.json
-│       ├── home.json
-│       └── docs.json
-└── README.md              # 本文件
-```
-
-## 使用方法
-
-### 在组件中使用
-
-```tsx
-import { useTranslation } from 'react-i18next'
-
-function MyComponent() {
-    const { t } = useTranslation('common') // 指定命名空间
-
-    return <h1>{t('header.nav_docs')}</h1>
-}
-```
-
-### 使用多个命名空间
-
-```tsx
-const { t } = useTranslation(['home', 'common'])
-
-// 使用时指定命名空间
-t('home:hero.title')
-t('common:header.nav_docs')
-```
-
-## 语言切换
-
-用户可以通过以下方式切换语言：
-
-1. **自动检测**：首次访问根据浏览器语言自动选择
-2. **手动切换**：点击页面右上角的语言切换按钮
-3. **持久化**：语言选择保存在 `localStorage` 中，刷新后保持
-
-## 添加新翻译
-
-1. 在对应的 JSON 文件中添加翻译条目（如 `zh-CN/home.json`）
-2. 在对应的英文文件中添加翻译（如 `en-US/home.json`）
-3. 在组件中使用 `t('namespace:key')` 获取翻译
-
-## TypeScript 支持
-
-`types.ts` 文件提供了类型声明，使得翻译 key 具有：
-
-- 自动补全
-- 编译期类型检查
-- 防止拼写错误
-
-## 待完成
-
-- [ ] 文档页翻译（`docs.json`）
-- [ ] DocsLayout 导航结构国际化
-- [ ] 404 页面国际化

packages/website/src/i18n/config.ts

@@ -1,45 +0,0 @@
-import i18n from 'i18next'
-import LanguageDetector from 'i18next-browser-languagedetector'
-import { initReactI18next } from 'react-i18next'
-
-import commonEn from './locales/en-US/common'
-import docsEn from './locales/en-US/docs'
-import homeEn from './locales/en-US/home'
-import commonZh from './locales/zh-CN/common'
-import docsZh from './locales/zh-CN/docs'
-import homeZh from './locales/zh-CN/home'
-
-const resources = {
-	'zh-CN': {
-		common: commonZh,
-		home: homeZh,
-		docs: docsZh,
-	},
-	'en-US': {
-		common: commonEn,
-		home: homeEn,
-		docs: docsEn,
-	},
-}
-
-i18n
-	.use(LanguageDetector)
-	.use(initReactI18next)
-	.init({
-		resources,
-		fallbackLng: 'en-US',
-		defaultNS: 'common',
-
-		// 语言检测配置
-		detection: {
-			// localStorage 优先（用户手动选择），其次检测浏览器语言
-			order: ['localStorage', 'navigator'],
-			caches: ['localStorage'],
-		},
-
-		interpolation: {
-			escapeValue: false, // React 已经做了 XSS 防护
-		},
-	})
-
-export default i18n

packages/website/src/i18n/context.tsx

@@ -0,0 +1,35 @@
+import { ReactNode, createContext, use, useState } from 'react'
+
+type Lang = 'en-US' | 'zh-CN'
+
+const LanguageContext = createContext<{
+	language: Lang
+	isZh: boolean
+	setLanguage: (lang: Lang) => void
+} | null>(null)
+
+export function LanguageProvider({ children }: { children: ReactNode }) {
+	const [language, setLang] = useState<Lang>(() => {
+		const stored = localStorage.getItem('language') as Lang
+		if (stored === 'zh-CN' || stored === 'en-US') return stored
+		return navigator.language.startsWith('zh') ? 'zh-CN' : 'en-US'
+	})
+
+	const setLanguage = (lang: Lang) => {
+		setLang(lang)
+		localStorage.setItem('language', lang)
+	}
+
+	return (
+		<LanguageContext value={{ language, isZh: language === 'zh-CN', setLanguage }}>
+			{children}
+		</LanguageContext>
+	)
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export function useLanguage() {
+	const ctx = use(LanguageContext)
+	if (!ctx) throw new Error('useLanguage must be used within LanguageProvider')
+	return ctx
+}

packages/website/src/i18n/locales/en-US/common.ts

@@ -1,43 +0,0 @@
-export default {
-	header: {
-		logo_alt: 'page-agent home',
-		slogan: 'GUI Agent in your webpage',
-		nav_docs: 'Docs',
-		nav_source: 'GitHub',
-		mobile_menu: 'Open navigation',
-	},
-	footer: {
-		copyright: '© 2025 page-agent. All rights reserved.',
-		github_label: 'Visit GitHub repository',
-	},
-	beta_notice: {
-		title: 'Beta Stage',
-		content:
-			'Current features are incomplete and the API may change at any time. Please do not use in production environments before the official release.',
-	},
-	language: {
-		zh: '中文',
-		en: 'English',
-		switch_label: 'Switch language',
-	},
-	nav: {
-		introduction: 'Introduction',
-		features: 'Features',
-		integration: 'Integration',
-		advanced: 'Advanced',
-		overview: 'Overview',
-		quick_start: 'Quick Start',
-		limitations: 'Limitations',
-		models: 'Models',
-		custom_tools: 'Custom Tools',
-		knowledge_injection: 'Instructions',
-		data_masking: 'Data Masking',
-		chrome_extension: 'Chrome Extension',
-		cdn_setup: 'CDN Setup',
-		best_practices: 'Best Practices',
-		third_party_agent: 'Third-party Agent',
-		security_permissions: 'Security & Permissions',
-		page_agent: 'PageAgent',
-		page_agent_core: 'PageAgentCore',
-	},
-}

packages/website/src/i18n/locales/en-US/docs.ts

@@ -1,157 +0,0 @@
-export default {
-	overview: {
-		title: 'Overview',
-		subtitle:
-			'page-agent is a purely web-based GUI Agent. Gives your website an AI operator in simple steps.',
-		what_is: 'What is page-agent?',
-		what_is_desc:
-			'page-agent is an embedded GUI Agent. Unlike traditional browser automation tools, page-agent is built for web developers and web applications first. Integrate it into your site to let users interact with pages through natural language.',
-		features_title: 'Core Features',
-		feature_dom: {
-			title: '🧠 Smart DOM Analysis',
-			desc: 'DOM-based analysis with high-intensity dehydration. No visual recognition needed. Pure text for fast and precise operations.',
-		},
-		feature_secure: {
-			title: '🔒 Secure & Controllable',
-			desc: 'Supports operation allowlists, data masking protection. Inject custom knowledge to make AI work by your rules.',
-		},
-		feature_backend: {
-			title: '⚡ Zero Backend',
-			desc: 'CDN or NPM import with custom LLM endpoints.',
-		},
-		feature_accessible: {
-			title: '♿ Accessible Intelligence',
-			desc: 'Provides natural language interface for complex B2B systems and admin panels. Makes software easy for everyone.',
-		},
-		vs_browser_use: 'vs. browser-use',
-		table_feature: 'Feature',
-		table_deployment: 'Deployment',
-		table_deployment_pa: 'Embedded component',
-		table_deployment_bu: 'External tool',
-		table_scope: 'Scope',
-		table_scope_pa: 'Current page',
-		table_scope_bu: 'Entire browser',
-		table_user: 'Target Users',
-		table_user_pa: 'Web developers',
-		table_user_bu: 'Scraper/Agent developers',
-		table_scenario: 'Use Case',
-		table_scenario_pa: 'UX enhancement',
-		table_scenario_bu: 'Automation tasks',
-		use_cases_title: 'Use Cases',
-		use_case1_title: 'Connect Support Bots:',
-		use_case1_desc:
-			"Turn your support assistant into a full agent. Customer service bots no longer just say 'Please click the settings button then click...'—they operate for users directly.",
-		use_case2_title: 'Modernize Legacy Apps:',
-		use_case2_desc:
-			'One line of code transforms old apps into agents. Product experts help users navigate complex B2B software. Reduce support costs and improve satisfaction.',
-		use_case3_title: 'Interactive Training:',
-		use_case3_desc:
-			"Demonstrate workflows in real-time. Let AI show the complete process of 'how to submit an expense report.'",
-		use_case4_title: 'Accessibility:',
-		use_case4_desc:
-			'Provide natural language interaction for visually impaired and elderly users. Connect screen readers or voice assistants to make software accessible to everyone.',
-		get_started_title: '🚀 Get Started',
-		get_started_desc:
-			'Ready to add an AI operator to your website? Check our quick start guide for integration in minutes.',
-		get_started_button: 'Quick Start →',
-	},
-	quick_start: {
-		title: 'Quick Start',
-		subtitle: 'Integrate page-agent in minutes.',
-		installation: 'Installation Steps',
-		step1_title: '1. Import Options',
-		step1_cdn: 'CDN Import',
-		step1_npm: 'NPM Install',
-		step2_title: '2. Initialize Configuration',
-		step3_title: '3. Start Using',
-	},
-	limitations: {
-		title: 'Limitations',
-		subtitle: "Understand page-agent's current capabilities and technical constraints",
-		page_support: 'Page Support Limitations',
-		spa_limit_title: 'Single Page Application Limits',
-		spa_limit_1: '• SPA only: Currently operates within a single page',
-		spa_limit_2: '• Multi-page relay in design: Cannot execute continuous tasks across pages yet',
-		spa_limit_3: '• Requires integration: Cannot operate on sites without page-agent',
-		interaction_limits: 'Interaction Limitations',
-		supported_ops: 'Supported Operations',
-		op_click: 'Click',
-		op_input: 'Text input',
-		op_scroll: 'Scroll',
-		op_submit: 'Form submit',
-		op_select: 'Select',
-		op_focus: 'Focus',
-		unsupported_ops: 'Unsupported Operations',
-		op_hover: 'Mouse hover',
-		op_drag: 'Drag & drop',
-		op_context: 'Right-click menu',
-		op_draw: 'Drawing',
-		op_keyboard: 'Keyboard shortcuts',
-		op_position: 'Position-based control',
-		understanding_limits: 'Understanding Limitations',
-		no_vision_title: 'No Visual Recognition',
-		no_vision_desc:
-			'page-agent operates based on DOM structure with no visual recognition. Cannot understand:',
-		no_vision_1: '• Image content: Cannot recognize text, icons, or visual elements in images',
-		no_vision_2: '• Canvas: Cannot understand graphics drawn on Canvas',
-		no_vision_3: '• WebGL 3D: Cannot operate elements in 3D scenes',
-		no_vision_4: '• SVG graphics: Cannot understand visual content and paths in SVG',
-		website_requirements: 'Website Requirements',
-		req_semantic_title: 'Semantic & Usability',
-		req_semantic_desc:
-			'All operations rely on semantic tags and attributes. Poor semantic structure or lack of accessibility features may affect AI understanding accuracy.',
-		req_ux_title: 'UI/UX',
-		req_ux_desc:
-			'Counter-intuitive interaction rules, visual-only operation hints, complex mouse interactions, or rapidly appearing/disappearing elements can affect AI understanding and operation.',
-		req_env_title: 'Environment',
-		req_env_desc: 'modern browser',
-		future: 'Future Plans',
-		future_title: 'Coming Soon',
-		future_1: '• Multi-page relay capabilities',
-		future_2: '• Richer mouse interaction support',
-		future_3: '• Basic visual understanding',
-		future_4: '• Smarter error recovery',
-	},
-	models: {
-		title: 'Models',
-		subtitle:
-			'Supports models that comply with OpenAI API specification and support tool calls, including public cloud services and private deployments.',
-		recommendation_logic: 'Recommended: Lightweight models with strong ToolCall capabilities.',
-		recommended: 'Recommended Models',
-		available: 'Tested Models',
-		available_verified: 'Verified Working Models',
-		tips: 'Tips',
-		tip_1: 'Reasoning models (like GPT-5) are slower with no advantage',
-		tip_2:
-			'Models with weaker ToolCall capabilities may return incorrect formats. Common errors usually auto-recover. Higher temperature recommended',
-		tip_3:
-			'Small models or those unable to handle complex tool definitions typically perform poorly',
-		security: '🔐 Production Authentication',
-		security_warning: '⚠️ Never commit real LLM API Keys to your frontend code',
-		security_desc:
-			'In production environments, to hide the real LLM API Keys, we recommend the following architecture:',
-		security_backend_proxy: 'Backend Proxy Pattern',
-		security_backend_desc:
-			'Set up a backend LLM proxy endpoint that uses the same authentication method as other APIs in your website, such as:',
-		security_method_1: '• Session/Cookie-based authentication',
-		security_method_2: '• OIDC (OpenID Connect) single sign-on',
-		security_method_3: '• Temporary Access Key or JWT Token',
-		configuration: 'Configuration',
-	},
-	custom_tools: {
-		title: 'Custom Tools',
-		subtitle:
-			'Extend AI Agent capabilities by registering custom tools. Use Zod to define strict input schemas for safe business logic calls.',
-		registration: 'Tool Registration',
-		registration_desc:
-			'Each custom tool requires four core properties: name, description, input schema, and execute function.',
-		page_filter: 'Page Filter',
-		page_filter_desc:
-			'Control tool visibility on specific pages via the pageFilter property to enhance security and UX.',
-		best_practices: 'Best Practices',
-		bp_performance: '⚡ Performance Optimization',
-		bp_1: '• Use pageFilter to reduce unnecessary tool loading',
-		bp_2: '• Implement appropriate caching in execute functions',
-		bp_3: '• Avoid long-running sync operations in tools',
-	},
-}

packages/website/src/i18n/locales/en-US/home.ts

@@ -1,82 +0,0 @@
-export default {
-	hero: {
-		badge: 'GUI Agent in your webpage',
-		title_line1: 'The AI Operator',
-		title_line2: 'Living in Your Web App',
-		subtitle_emoji: '🪄One line of code',
-		subtitle_main: ' adds intelligent GUI Agents to your website.',
-		subtitle_detail: 'Users give natural language commands, AI handles the rest.',
-		tab_try: '🚀 Try It Now',
-		tab_other: '🌐 Try on Other Sites',
-		input_placeholder: 'Describe what you want AI to do...',
-		execute_button: 'Run',
-		default_task:
-			'Goto docs in navigation bar, find Quick-Start section, and summarize in markdown',
-	},
-	try_other: {
-		step1_title: 'Step 1:',
-		step1_content: 'Show your bookmarks bar',
-		step2_title: 'Step 2:',
-		step2_content: 'Drag this button to your bookmarks',
-		cdn_label: 'CDN Source',
-		cdn_international: 'International',
-		cdn_china: 'China Mirror',
-		step3_title: 'Step 3:',
-		step3_content: 'Click the bookmark on any site to activate',
-		notice_title: '⚠️ Heads Up',
-		notice_items: {
-			item1: 'Demo only—link may expire without notice',
-			item2: 'This free demo uses DeepSeek API (see their terms and privacy policy)',
-			item3: 'Some sites block script injection (CSP policies)',
-			item4: 'Works on single-page apps only—reload required after navigation',
-			item5: 'Text-only understanding—no image recognition or drag-and-drop',
-			item6_prefix: 'Full limitations in',
-			item6_link: 'Docs',
-		},
-	},
-	benefits: {
-		no_backend: 'Pure Front-end Solution',
-		private_model: 'Your Own Models',
-		data_masking: 'Built-in Privacy',
-		open_source: 'MIT Open Source',
-	},
-	features: {
-		section_title: 'Why PageAgent',
-		in_page: {
-			title: 'In-page Solution',
-			desc: 'Runs entirely within your page. No browser extensions, no headless browsers, and no backend required.',
-		},
-		secure_integration: {
-			title: 'Secure by Design',
-			desc: 'Control what AI can access with allowlists, data masking, and custom knowledge injection. Your rules, your data.',
-		},
-		zero_backend: {
-			title: 'Zero Backend Setup',
-			desc: 'Just drop in a script. Works with any LLM provider—OpenAI, Anthropic, or your own models.',
-		},
-		accessible: {
-			title: 'Natural Language UI',
-			desc: 'Transform complex admin panels into chat interfaces. Make powerful tools accessible to everyone, not just experts.',
-		},
-	},
-	use_cases: {
-		section_title: 'Where It Shines',
-		section_subtitle: 'From simple forms to complex workflows, AI understands and executes',
-		case1: {
-			title: 'Supercharge Support Bots',
-			desc: 'Stop telling users where to click—let AI do it for them. Turn your chatbot from a guide into an operator that actually completes tasks.',
-		},
-		case2: {
-			title: 'Modernize Legacy Apps',
-			desc: 'Add AI superpowers to old software without rebuilding. One script tag transforms complex enterprise tools into chat-driven interfaces.',
-		},
-		case3: {
-			title: 'Interactive Walkthroughs',
-			desc: "Show, don't tell. Let AI demonstrate workflows in real-time—perfect for onboarding or training new users on complex systems.",
-		},
-		case4: {
-			title: 'Accessibility First',
-			desc: 'Make web apps accessible through natural language. Perfect for screen readers, voice control, or users who find traditional interfaces challenging.',
-		},
-	},
-}

packages/website/src/i18n/locales/zh-CN/common.ts

@@ -1,42 +0,0 @@
-export default {
-	header: {
-		logo_alt: 'page-agent 首页',
-		slogan: 'GUI Agent in your webpage',
-		nav_docs: '文档',
-		nav_source: 'GitHub',
-		mobile_menu: '打开导航栏',
-	},
-	footer: {
-		copyright: '© 2025 page-agent. All rights reserved.',
-		github_label: '访问 GitHub 仓库',
-	},
-	beta_notice: {
-		title: 'Beta 阶段',
-		content: '当前功能未完成，接口可能随时变更。正式版本发布前请勿用于生产环境。',
-	},
-	language: {
-		zh: '中文',
-		en: 'English',
-		switch_label: '切换语言',
-	},
-	nav: {
-		introduction: '介绍',
-		features: '功能特性',
-		integration: '集成指南',
-		advanced: '高级',
-		overview: '概览',
-		quick_start: '快速开始',
-		limitations: '使用限制',
-		models: '模型',
-		custom_tools: '自定义工具',
-		knowledge_injection: '知识注入',
-		data_masking: '数据脱敏',
-		chrome_extension: 'Chrome 扩展',
-		cdn_setup: 'CDN 引入',
-		best_practices: '最佳实践',
-		third_party_agent: '接入第三方 Agent',
-		security_permissions: '安全与权限',
-		page_agent: 'PageAgent',
-		page_agent_core: 'PageAgentCore',
-	},
-}

packages/website/src/i18n/locales/zh-CN/docs.ts

@@ -1,152 +0,0 @@
-export default {
-	overview: {
-		title: 'Overview',
-		subtitle:
-			'page-agent 是一个完全基于 Web 技术的 GUI Agent，简单几步，让你的网站拥有 AI 操作员。',
-		what_is: '什么是 page-agent？',
-		what_is_desc:
-			'page-agent 是一个页面内嵌式 GUI Agent。与传统的浏览器自动化工具不同，page-agent 面向网站开发者，而非爬虫或Agent客户端开发者；将 Agent 集成到你的网站中，让用户可以通过自然语言与页面进行交互。',
-		features_title: '核心特性',
-		feature_dom: {
-			title: '🧠 智能 DOM 理解',
-			desc: '基于 DOM 分析，高强度脱水。无需视觉识别，纯文本实现精准操作。',
-		},
-		feature_secure: {
-			title: '🔒 安全可控',
-			desc: '支持操作黑白名单、数据脱敏保护。注入自定义知识库，让 AI 按你的规则工作。',
-		},
-		feature_backend: {
-			title: '⚡ 零后端部署',
-			desc: 'CDN 或 NPM 引入，自定义 LLM 接入点。',
-		},
-		feature_accessible: {
-			title: '♿ 普惠智能',
-			desc: '为复杂 B端系统、管理后台提供自然语言入口。让每个用户都能轻松上手。',
-		},
-		vs_browser_use: '与 browser-use 的区别',
-		table_feature: '特性',
-		table_deployment: '部署方式',
-		table_deployment_pa: '页面内嵌组件',
-		table_deployment_bu: '外部工具',
-		table_scope: '操作范围',
-		table_scope_pa: '当前页面',
-		table_scope_bu: '整个浏览器',
-		table_user: '目标用户',
-		table_user_pa: '网站开发者',
-		table_user_bu: '爬虫/Agent 开发者',
-		table_scenario: '使用场景',
-		table_scenario_pa: '用户体验增强',
-		table_scenario_bu: '自动化任务',
-		use_cases_title: '应用场景',
-		use_case1_title: '对接答疑机器人：',
-		use_case1_desc:
-			'把你的答疑助手变成全能Agent。客服机器人不再只说「请先点击设置按钮然后点击...」，而是直接帮用户现场操作。',
-		use_case2_title: '交互升级/智能化改造：',
-		use_case2_desc:
-			'一行代码，老应用变身Agent，产品专家帮用户操作复杂 B 端软件。降低人工支持成本，提高用户满意度。',
-		use_case3_title: '产品教学：',
-		use_case3_desc:
-			'向用户演示交互过程，边做边教。例如让AI演示「如何提交报销申请」的完整操作流程。',
-		use_case4_title: '无障碍支持：',
-		use_case4_desc:
-			'为视障用户、老年用户提供自然语言交互，对接屏幕阅读器或语音助理，让软件人人可用。',
-		get_started_title: '🚀 开始使用',
-		get_started_desc:
-			'准备好为你的网站添加 AI 操作员了吗？查看我们的快速开始指南，几分钟内完成集成。',
-		get_started_button: '快速开始 →',
-	},
-	quick_start: {
-		title: 'Quick Start',
-		subtitle: '几分钟内完成 page-agent 的集成。',
-		installation: '安装步骤',
-		step1_title: '1. 引入方式',
-		step1_cdn: 'CDN 引入',
-		step1_npm: 'NPM 安装',
-		step2_title: '2. 初始化配置',
-		step3_title: '3. 开始使用',
-	},
-	limitations: {
-		title: '使用限制',
-		subtitle: '了解 page-agent 当前的功能边界和技术限制',
-		page_support: '页面支持限制',
-		spa_limit_title: '单页应用限制',
-		spa_limit_1: '• 仅支持单页应用（SPA）：目前只能在单个页面内进行操作',
-		spa_limit_2: '• 多页接力功能正在设计中：暂时无法跨页面执行连续任务',
-		spa_limit_3: '• 无法操作未接入该能力的网站：需要目标网站主动集成 page-agent',
-		interaction_limits: '交互行为限制',
-		supported_ops: '支持的操作',
-		op_click: '点击操作',
-		op_input: '文本输入',
-		op_scroll: '页面滚动',
-		op_submit: '表单提交',
-		op_select: '选择操作',
-		op_focus: '焦点切换',
-		unsupported_ops: '不支持的操作',
-		op_hover: '鼠标悬停（hover）',
-		op_drag: '拖拽操作',
-		op_context: '右键菜单',
-		op_draw: '图形绘制',
-		op_keyboard: '键盘快捷键',
-		op_position: '基于点击区域或鼠标位置的控制',
-		understanding_limits: '网页理解限制',
-		no_vision_title: '无视觉能力',
-		no_vision_desc: 'page-agent 基于 DOM 结构进行理解和操作，没有视觉识别能力，无法理解以下内容：',
-		no_vision_1: '• 图片内容：无法识别图片中的文字、图标或视觉元素',
-		no_vision_2: '• Canvas 画布：无法理解 Canvas 中绘制的图形和内容',
-		no_vision_3: '• WebGL 3D 内容：无法操作 3D 场景中的元素',
-		no_vision_4: '• SVG 图形：无法理解 SVG 中的视觉内容和路径',
-		website_requirements: '被操作网站要求',
-		req_semantic_title: '语义化和易用性',
-		req_semantic_desc:
-			'所有操作都基于 DOM 元素的语义化标签和属性。如果页面结构不够语义化，或者没有任何 accessibility 特性，可能影响 AI 的理解准确性。',
-		req_ux_title: 'UI/UX',
-		req_ux_desc:
-			'反常识的交互规则、基于视觉的操作提示、复杂的鼠标交互、快速出现快速消失的元素等，都会影响 AI 的理解和操作。',
-		req_env_title: '环境要求',
-		req_env_desc: 'modern browser',
-		future: '未来规划',
-		future_title: '即将支持',
-		future_1: '• 多页面接力操作能力',
-		future_2: '• 更丰富的鼠标交互支持',
-		future_3: '• 基础的视觉理解能力',
-		future_4: '• 更智能的错误恢复机制',
-	},
-	models: {
-		title: '模型',
-		subtitle: '当前支持符合 OpenAI 接口规范且支持 tool call 的模型,包括公有云服务和私有部署方案。',
-		recommendation_logic: '推荐使用 ToolCall 能力强的轻量级模型。',
-		recommended: '推荐模型',
-		available: '已测试模型',
-		available_verified: '已验证可用模型',
-		tips: '提示',
-		tip_1: 'reasoning 模型(如 GPT-5),速度偏慢,没有必要',
-		tip_2:
-			'ToolCall 能力较弱的模型可能返回错误的格式，常见错误能够自动恢复，建议设置较高的 temperature',
-		tip_3: '小模型或者无法适应复杂 Tool 定义的模型，通常效果不佳',
-		security: '🔐 生产环境鉴权建议',
-		security_warning: '⚠️ 永远不要把真实的 LLM API Key 发布到前端代码',
-		security_desc: '在实际应用中,为了隐藏真实的 LLM API Key，建议采用以下架构:',
-		security_backend_proxy: '后端代理转发',
-		security_backend_desc:
-			'在后端搭建一个 LLM 流量转发接口,该接口使用与你网站上其他接口相同的鉴权方式,例如:',
-		security_method_1: '• Session/Cookie 会话认证',
-		security_method_2: '• OIDC (OpenID Connect) 单点登录',
-		security_method_3: '• 临时 Access Key 或 JWT Token',
-		configuration: '配置方式',
-	},
-	custom_tools: {
-		title: '自定义工具',
-		subtitle:
-			'通过注册自定义工具，扩展 AI Agent 的能力边界。使用 Zod 定义严格的输入接口，让 AI 安全调用你的业务逻辑。',
-		registration: '工具注册',
-		registration_desc:
-			'每个自定义工具需要定义四个核心属性：name、description、input schema 和 execute 函数。',
-		page_filter: '页面过滤器',
-		page_filter_desc: '通过 pageFilter 属性控制工具在哪些页面可见，提升安全性和用户体验。',
-		best_practices: '最佳实践',
-		bp_performance: '⚡ 性能优化',
-		bp_1: '• 使用 pageFilter 减少不必要的工具加载',
-		bp_2: '• 在 execute 函数中实现适当的缓存机制',
-		bp_3: '• 避免在工具中执行耗时的同步操作',
-	},
-}

packages/website/src/i18n/locales/zh-CN/home.ts

@@ -1,81 +0,0 @@
-export default {
-	hero: {
-		badge: 'GUI Agent in your webpage',
-		title_line1: '让你的 Web 应用',
-		title_line2: '拥有 AI 操作员',
-		subtitle_emoji: '🪄一行代码',
-		subtitle_main: '，为你的网站添加 GUI Agent。',
-		subtitle_detail: '用户/答疑机器人给出文字指示，AI 帮你操作页面。',
-		tab_try: '🚀 立即尝试',
-		tab_other: '🌐 其他网页尝试',
-		input_placeholder: '输入您想要 AI 执行的任务...',
-		execute_button: '执行',
-		default_task: '从导航栏中进入文档页，打开“快速开始”相关的文档，帮我总结成 markdown',
-	},
-	try_other: {
-		step1_title: '步骤 1:',
-		step1_content: '显示收藏夹栏',
-		step2_title: '步骤 2:',
-		step2_content: '拖拽下面按钮到收藏夹栏',
-		cdn_label: 'CDN 源',
-		cdn_international: '国际',
-		cdn_china: '国内镜像',
-		step3_title: '步骤 3:',
-		step3_content: '在其他网站点击收藏夹中的按钮即可使用',
-		notice_title: '⚠️ 注意',
-		notice_items: {
-			item1: '仅做技术评估，链接定期失效',
-			item2: '使用 DeepSeek 模型，参考 DeepSeek 用户协议和隐私政策',
-			item3: '部分网站屏蔽了链接嵌入，将无反应',
-			item4: '仅支持单页应用，页面跳转后需要重新注入',
-			item5: '仅识别文本，不识别图像，不支持拖拽等复杂交互',
-			item6_prefix: '详细使用限制参照',
-			item6_link: '《文档》',
-		},
-	},
-	benefits: {
-		no_backend: '纯前端方案',
-		private_model: '支持私有模型',
-		data_masking: '无痛脱敏',
-		open_source: 'MIT 开源',
-	},
-	features: {
-		section_title: '核心特性',
-		in_page: {
-			title: '纯页面内方案',
-			desc: '完全运行在你的页面内。不需要浏览器插件、不需要无头浏览器，不需要后端。',
-		},
-		secure_integration: {
-			title: '安全可控集成',
-			desc: '支持操作黑白名单、数据脱敏保护。注入自定义知识库，让 AI 按你的规则工作。',
-		},
-		zero_backend: {
-			title: '零后端部署',
-			desc: '前端脚本引入，自定义 LLM 接入点。从 OpenAI 到 qwen3，完全由你掌控。',
-		},
-		accessible: {
-			title: '普惠智能交互',
-			desc: '为复杂 B端系统、管理后台提供自然语言入口。让每个用户都能轻松上手。',
-		},
-	},
-	use_cases: {
-		section_title: '应用场景',
-		section_subtitle: '从简单的表单填写到复杂的业务流程，AI 都能理解并执行',
-		case1: {
-			title: '对接答疑机器人',
-			desc: '把你的答疑助手变成全能Agent。客服机器人不再只说「请先点击设置按钮然后点击...」，而是直接帮用户现场操作。',
-		},
-		case2: {
-			title: '交互升级/智能化改造',
-			desc: '一行代码，老应用变身Agent，产品专家帮用户操作复杂 B 端软件。降低人工支持成本，提高用户满意度。',
-		},
-		case3: {
-			title: '产品教学',
-			desc: '向用户演示交互过程，边做边教。例如让AI演示「如何提交报销申请」的完整操作流程。',
-		},
-		case4: {
-			title: '无障碍支持',
-			desc: '为视障用户、老年用户提供自然语言交互，对接屏幕阅读器或语音助理，让软件人人可用。',
-		},
-	},
-}

packages/website/src/i18n/types.ts

@@ -1,16 +0,0 @@
-import 'react-i18next'
-
-import type commonZh from './locales/zh-CN/common'
-import type docsZh from './locales/zh-CN/docs'
-import type homeZh from './locales/zh-CN/home'
-
-declare module 'react-i18next' {
-	interface CustomTypeOptions {
-		defaultNS: 'common'
-		resources: {
-			common: typeof commonZh
-			home: typeof homeZh
-			docs: typeof docsZh
-		}
-	}
-}

packages/website/src/index.css

@@ -71,7 +71,43 @@ html.dark,
 body {
 	background: var(--background);
 	color: var(--foreground);
-	font-family: Arial, Helvetica, sans-serif;
+	font-family:
+		system-ui,
+		-apple-system,
+		BlinkMacSystemFont,
+		'Segoe UI',
+		Roboto,
+		'Noto Sans',
+		'Liberation Sans',
+		sans-serif,
+		'Apple Color Emoji',
+		'Segoe UI Emoji';
+}
+
+/* 文档正文排版优化 */
+.prose {
+	letter-spacing: 0.01em;
+	font-weight: 380;
+}
+
+.prose p {
+	line-height: 1.6;
+}
+
+/* 标题使用中等字重（相对细体更重，但比默认 bold 更轻） */
+.prose h1,
+.prose h2,
+.prose h3,
+.prose h4,
+.prose h5,
+.prose h6 {
+	font-weight: 480;
+}
+
+/* strong/b 也用中等字重 */
+.prose strong,
+.prose b {
+	font-weight: 480;
 }
 
 /* 确保文档页面标题在暗色模式下可见 - 只针对 prose 内的标题 */
@@ -341,6 +377,24 @@ td {
 			background-position: bottom center;
 		}
 	}
+	--animate-marquee: marquee var(--duration) infinite linear;
+	--animate-marquee-vertical: marquee-vertical var(--duration) linear infinite;
+	@keyframes marquee {
+		from {
+			transform: translateX(0);
+		}
+		to {
+			transform: translateX(calc(-100% - var(--gap)));
+		}
+	}
+	@keyframes marquee-vertical {
+		from {
+			transform: translateY(0);
+		}
+		to {
+			transform: translateY(calc(-100% - var(--gap)));
+		}
+	}
 }
 
 /* shadcn dark mode */

packages/website/src/main.tsx

@@ -1,15 +1,22 @@
 import { createRoot } from 'react-dom/client'
 import { Router } from 'wouter'
-import { useHashLocation } from 'wouter/use-hash-location'
 
-import './i18n/config'
-import './i18n/types'
+import { LanguageProvider } from './i18n/context'
 import { default as PagesRouter } from './router'
 
 import './index.css'
 
+// Redirect legacy hash routes (e.g. /#/docs/foo) to clean paths
+const { hash } = window.location
+if (hash.length > 1 && hash.includes('/')) {
+	const path = hash.replace(/^#\/?/, '/')
+	history.replaceState(null, '', '/page-agent' + path)
+}
+
 createRoot(document.getElementById('root')!).render(
-	<Router hook={useHashLocation}>
-		<PagesRouter />
-	</Router>
+	<LanguageProvider>
+		<Router base="/page-agent">
+			<PagesRouter />
+		</Router>
+	</LanguageProvider>
 )